home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD1.3 / Text_Autodocs / trackdisk.doc < prev    next >
Encoding:
Text File  |  1992-09-12  |  13.0 KB  |  417 lines
  1. TABLE OF CONTENTS
  2.  
  3. trackdisk.device/TD_ADDCHANGEINT
  4. trackdisk.device/TD_CHANGENUM
  5. trackdisk.device/TD_CHANGESTATE
  6. trackdisk.device/TD_FORMAT
  7. trackdisk.device/TD_GETDRIVETYPE
  8. trackdisk.device/TD_GETNUMTRACKS
  9. trackdisk.device/TD_MOTOR
  10. trackdisk.device/TD_PROTSTATUS
  11. trackdisk.device/TD_RAWREAD
  12. trackdisk.device/TD_RAWWRITE
  13. trackdisk.device/TD_REMCHANGEINT
  14. trackdisk.device/TD_SEEK
  15.  
  16.  
  17. trackdisk.device/TD_ADDCHANGEINT               trackdisk.device/TD_ADDCHANGEINT
  18.  
  19.    NAME
  20.        TD_ADDCHANGEINT - add a new change software int
  21.  
  22.    SYNOPSIS
  23.        TDUAddChangeInt( IORequest ), UnitPtr
  24.                          A1           A3
  25.  
  26.    FUNCTION
  27.         Alas, the old TDURemove call was not robust enough.  This routine
  28.     supports an extensible list of software interrupts for use by many
  29.         different supporting drivers.
  30.  
  31.         The call does not "complete" (e.g. TermIO).  The request
  32.         is stashed until TDURemChangeInt is called, when it is
  33.         finally replied.
  34.  
  35.    INPUTS
  36.         IORequest - a standard IO Request block (IO_DATA-> soft int struct).
  37.  
  38.    RESULTS
  39.  
  40.    EXCEPTIONS
  41.  
  42.    SEE ALSO
  43.  
  44.    BUGS
  45.  
  46.  
  47. trackdisk.device/TD_CHANGENUM                     trackdisk.device/TD_CHANGENUM
  48.  
  49.    NAME
  50.        TD_CHANGENUM - return the current disc change number
  51.  
  52.    SYNOPSIS
  53.        TDUChangeNum( IORequest ), UnitPtr
  54.                       A1           A3
  55.  
  56.    FUNCTION
  57.        This routine checks to see if there is a disc in the drive
  58.         of the specified unit.
  59.  
  60.    INPUTS
  61.         IORequest - a standard IO Request block
  62.  
  63.    RESULTS
  64.  
  65.    EXCEPTIONS
  66.  
  67.    SEE ALSO
  68.  
  69.    BUGS
  70.  
  71.  
  72. trackdisk.device/TD_CHANGESTATE                 trackdisk.device/TD_CHANGESTATE
  73.  
  74.    NAME
  75.        TD_CHANGESTATE - Return the current state of the disc
  76.  
  77.    SYNOPSIS
  78.        TDUChangeState( IORequest ), UnitPtr
  79.                         A1           A3
  80.  
  81.    FUNCTION
  82.        This routine checks to see if there is a disc in the drive
  83.         one the specified unit.
  84.  
  85.    INPUTS
  86.         IORequest - a standard IO Request block
  87.  
  88.    RESULTS
  89.         IO_ACTUAL -- nonzero if there is no diskette in the drive
  90.  
  91.    EXCEPTIONS
  92.  
  93.    SEE ALSO
  94.  
  95.    BUGS
  96.  
  97.  
  98. trackdisk.device/TD_FORMAT                           trackdisk.device/TD_FORMAT
  99.  
  100.    NAME
  101.         TD_FORMAT -- format the entire disc
  102.  
  103.    SYNOPSIS
  104.         TDUFormat( iOBlock ), DevNode
  105.         D0         A1         A6
  106.  
  107.    FUNCTION
  108.  
  109.         The function formats the entire disc, destroying all data.
  110.         It fills all the sectors with the contents of the iOBlock.
  111.         The iOBlock must point to (at least) one sector worth of
  112.         information.  Any info greater than one sector is ignored.
  113.         NO ERROR CHECKING is done
  114.  
  115.    INPUTS
  116.  
  117.  
  118.  
  119.    RESULTS
  120.  
  121.  
  122.    SEE ALSO
  123.  
  124.  
  125.  
  126. trackdisk.device/TD_GETDRIVETYPE               trackdisk.device/TD_GETDRIVETYPE
  127.  
  128.    NAME
  129.        TD_GETDRIVETYPE - return the type of the disk drive to the user
  130.  
  131.    FUNCTION
  132.         This routine returns the type of the disk to the user.
  133.         This number will be a small integer.  It will come from
  134.         the set of DRIVE... defines in trackdisk.h
  135.         or trackdisk.i.
  136.  
  137.         The only way you can get to this call is if the trackdisk
  138.         device understands the drive type of the hardware that is
  139.         plugged in.  This is because the OpenDevice call will fail
  140.         if the trackdisk device does not understand the drive type.
  141.         To find raw drive identifiers see the disk resource's
  142.         DR_GETUNITID entry point.
  143.  
  144.    IO REQUEST
  145.         io_Command      TD_GETDRIVETYPE
  146.  
  147.    RESULTS
  148.         io_Actual       the drive type connected to this unit.
  149.  
  150.    SEE ALSO
  151.         TD_GETNUMTRACKS
  152.  
  153.  
  154. trackdisk.device/TD_GETNUMTRACKS               trackdisk.device/TD_GETNUMTRACKS
  155.  
  156.    NAME
  157.        TD_GETNUMTRACKS - return the number of tracks on this type of disk
  158.  
  159.    FUNCTION
  160.         This routine returns the number of tracks that are available
  161.         on this disk unit.  This call obsoletes the older NUMTRACKS
  162.         hard coded constant.
  163.  
  164.    IO REQUEST
  165.         io_Command      TD_GETNUMTRACKS
  166.  
  167.    RESULTS
  168.         io_Actual       number of tracks accessible on this unit
  169.  
  170.    SEE ALSO
  171.         TD_GETDRIVETYPE
  172.  
  173.  
  174. trackdisk.device/TD_MOTOR                             trackdisk.device/TD_MOTOR
  175.  
  176.    NAME
  177.         TD_MOTOR - user visible control for motor
  178.  
  179.    SYNOPSIS
  180.         TDUMotor( IOBlock ), UnitPtr, DevPtr
  181.                   A1         A3       A6
  182.  
  183.    FUNCTION
  184.         This routine allows the user to control the disc motor. He
  185.         may turn it either on or off.  Note that the motor will be
  186.         automatically turned on during an I/O request, but is never
  187.         turned of except by this command.
  188.  
  189.    INPUTS
  190.         IOBlock - the command block for this IO operation.
  191.             IO_ACTUAL -- returns the previous state of the motor
  192.             IO_LENGTH -- the requested state of the motor
  193.                 0 ==> turn motor off
  194.                 1 ==> turn motor on
  195.  
  196.    EXCEPTIONS
  197.  
  198.    SEE ALSO
  199.  
  200.    BUGS
  201.  
  202.  
  203. trackdisk.device/TD_PROTSTATUS                   trackdisk.device/TD_PROTSTATUS
  204.  
  205.    NAME
  206.         TD_PROTSTATUS -- return whether the current disk is write protected
  207.  
  208.    SYNOPSIS
  209.         TDUProtstatus( IOBlock ), UnitPtr, DevPtr
  210.                   A1         A3       A6
  211.  
  212.    FUNCTION
  213.         This routine tells whether the current disk is write protected.
  214.  
  215.    INPUTS
  216.         IOBlock - the command block for this IO operation.
  217.                 IO_ACTUAL - nonzero if the disk is protected, 0 otherwise
  218.                 If there is no disk in the drive, then IO_ERROR is set
  219.                 to TDERR_DiskChanged
  220.  
  221.    EXCEPTIONS
  222.  
  223.    SEE ALSO
  224.  
  225.    BUGS
  226.  
  227.  
  228. trackdisk.device/TD_RAWREAD                         trackdisk.device/TD_RAWREAD
  229.  
  230.    NAME
  231.         TD_RAWREAD - read a raw sector from the disk
  232.  
  233.    FUNCTION
  234.         This routine performs a raw read for the track disk.
  235.         It seeks to the specified track and reads it in to the
  236.         user's buffer.  This buffer MUST be in chip memory.
  237.  
  238.         NO PROCESSING OF THE TRACK IS DONE.  It will appear exactly
  239.         as the bits come out off the disk -- hopefully in some legal MFM
  240.         format (if you don't know what MFM is, you shouldn't be using
  241.         this call...).  Caveat Programmer.
  242.  
  243.         This interface is intended for sophisticated programmers
  244.         only.  Commodore-Amiga may make enhancements to the disk
  245.         format in the future.  We will provide compatibility
  246.         within the trackdisk device.  Anyone who uses this routine
  247.         is bypassing this upwards compatibility.  If your application
  248.         breaks, TOUGH!
  249.  
  250.         If this warning is not enough, then add suitable additional
  251.         harrassment of your choice.
  252.  
  253.  
  254.    IO REQUEST
  255.         io_Flags        if the IOTDB_INDEXSYNC bit is set then the driver
  256.                           will make a best effort attempt to start reading
  257.                           from the index mark.  Note that there
  258.                           will be at least some delay, and perhaps a great
  259.                           deal, of delay (if, for example, interrupts have
  260.                           been Disabled()...).
  261.         io_Command      TD_RAWREAD or ETD_RAWREAD.
  262.         io_Length       Length of buffer (in bytes).  The maximum allowable
  263.                           length is 32K bytes.
  264.         io_Data         Pointer to buffer in chip memory where raw track
  265.                           will be read into.
  266.         io_Offset       The track number to read in (not this is different
  267.                           from a normal trackdisk io call which is given
  268.                           in terms of logical bytes from the beginning of 
  269.                           the disk.  This is because the trackdisk driver
  270.                           has no idea what the format of the disk is).
  271.         iotd_Count      (ETD_RAWREAD only) maximum allowable change counter
  272.                           value
  273.  
  274.    RESULTS
  275.         io_Error        non-zero if there was an error
  276.  
  277.    LIMITATIONS for synced reads and writes
  278.         There is a delay between the index pulse and the start of bits
  279.         coming in from the drive (e.g. dma started).  This delay
  280.         is in the range of 135-200 micro seconds.  This delay breaks
  281.         down as follows: 55 microsecs is software interrupt overhead
  282.         (this is the time from interrupt to the write of the DSKLEN
  283.         register).  66 microsecs is one horizontal line delay (remember
  284.         that disk io is synchronized with agnus' display fetches).
  285.         The last variable (0-65 microsecs) is an additional scan line
  286.         since DSKLEN is poked anywhere in the horizontal line.  This leaves
  287.         15 microsecs unaccounted for...  Sigh.
  288.  
  289.         In short, You will almost never get bits withing the first 135
  290.         microseconds of the index pulse, and may not get it until 200
  291.         microseconds.  At 4 microsecs/bit, this works out to be between
  292.         4 and 7 bytes of user data of delay.
  293.  
  294.    SEE ALSO
  295.         TD_RAWWRITE
  296.  
  297.  
  298. trackdisk.device/TD_RAWWRITE                       trackdisk.device/TD_RAWWRITE
  299.  
  300.    NAME
  301.         TD_RAWWRITE - write a raw sector to the disk
  302.  
  303.    FUNCTION
  304.         NO PROCESSING OF THE TRACK IS DONE.  The disk will appear exactly
  305.         as the bits come out of memory -- hopefully in some legal MFM
  306.         format (if you don't know what MFM is, you shouldn't be using
  307.         this call...).  Caveat Programmer.
  308.  
  309.         NO PROCESSING OF THE TRACK IS DONE.  It will exactly
  310.         as the bits come out off the disk.  Caveat Programmer.
  311.  
  312.         This interface is intended for sophisticated programmers
  313.         only.  Commodore-Amiga may make enhancements to the disk
  314.         format in the future.  We will provide compatibility
  315.         within the trackdisk device.  Anyone who uses this routine
  316.         is bypassing this upwards compatibility.  If your application
  317.         breaks, TOUGH!
  318.  
  319.         If this warning is not enough, then add suitable additional
  320.         harrassment of your choice.
  321.  
  322.  
  323.    IO REQUEST
  324.         io_Flags        if the IOTDB_INDEXSYNC bit is set then the driver
  325.                           will make a best effort attempt to start writing
  326.                           from the index mark.  Note that there
  327.                           will be at least some delay, and perhaps a great
  328.                           deal, of delay (if, for example, interrupts have
  329.                           been Disabled()...).
  330.         io_Command      TD_RAWWRITE or ETD_RAWWRITE.
  331.         io_Length       Length of buffer (in bytes).  The maximum allowable
  332.                           length is 32K bytes.
  333.         io_Data         Pointer to buffer in chip memory where raw track
  334.                           will be read into.
  335.         io_Offset       The track number to read in (not this is different
  336.                           from a normal trackdisk io call which is given
  337.                           in terms of logical bytes from the beginning of 
  338.                           the disk.  This is because the trackdisk driver
  339.                           has no idea what the format of the disk is).
  340.         iotd_Count      (ETD_RAWWRITE only) maximum allowable change counter
  341.                           value
  342.  
  343.    RESULTS
  344.         io_Error        non-zero if there was an error
  345.  
  346.    LIMITATIONS for synced reads and writes
  347.         There is a delay between the index pulse and the start of bits
  348.         going out to the drive (e.g. write gate enabled).  This delay
  349.         is in the range of 135-200 micro seconds.  This delay breaks
  350.         down as follows: 55 microsecs is software interrupt overhead
  351.         (this is the time from interrupt to the write of the DSKLEN
  352.         register).  66 microsecs is one horizontal line delay (remember
  353.         that disk io is synchronized with agnus' display fetches).
  354.         The last variable (0-65 microsecs) is an additional scan line
  355.         since DSKLEN is poked anywhere in the horizontal line.  This leaves
  356.         15 microsecs unaccounted for...  Sigh.
  357.  
  358.         In short, You will almost never get bits withing the first 135
  359.         microseconds of the index pulse, and may not get it until 200
  360.         microseconds.  At 4 microsecs/bit, this works out to be between
  361.         4 and 7 bytes of user data of delay.
  362.  
  363.    SEE ALSO
  364.         TD_RAWREAD
  365.  
  366.  
  367. trackdisk.device/TD_REMCHANGEINT               trackdisk.device/TD_REMCHANGEINT
  368.  
  369.    NAME
  370.        TD_REMCHANGEINT - remove a change software int
  371.  
  372.    SYNOPSIS
  373.        TDURemChangeInt( IORequest ), UnitPtr
  374.                          A1           A3
  375.  
  376.    FUNCTION
  377.         This function unlinks the IOReqest stashed by AddChangeInt.
  378.         It also replies it to the user.
  379.  
  380.    INPUTS
  381.         IORequest - a standard IO Request block
  382.  
  383.    RESULTS
  384.  
  385.    EXCEPTIONS
  386.  
  387.    SEE ALSO
  388.  
  389.    BUGS
  390.  
  391.  
  392. trackdisk.device/TD_SEEK                               trackdisk.device/TD_SEEK
  393.  
  394.    NAME
  395.         TD_SEEK - user visible control for the heads
  396.  
  397.    SYNOPSIS
  398.         TDUSeek( IOBlock ), TDLib
  399.                   A1         A6
  400.  
  401.    FUNCTION
  402.         This routine allows the user to control the seek position.
  403.         Note that the heads will be automatically seeked during an
  404.         I/O request; this command allows the heads to be preseeked
  405.         if the next position is known prior to the I/O being ready.
  406.  
  407.    INPUTS
  408.         IOBlock - the command block for this IO operation.
  409.             IO_OFFSET -- the location to seek to
  410.  
  411.    EXCEPTIONS
  412.  
  413.    SEE ALSO
  414.  
  415.    BUGS
  416.  
  417.