home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / cdtv / cdtvtools-20 / cdtv_device / cdtv.device.autodocs next >
Text File  |  1992-02-06  |  43KB  |  1,551 lines
  1. TABLE OF CONTENTS
  2.  
  3. cdtv.device/--Background--
  4. cdtv.device/CDTV_ADDCHANGEINT
  5. cdtv.device/CDTV_CHANGENUM
  6. cdtv.device/CDTV_CHANGESTATE
  7. cdtv.device/CDTV_FADE
  8. cdtv.device/CDTV_FRAMECALL
  9. cdtv.device/CDTV_FRAMECOUNT
  10. cdtv.device/CDTV_FRONTPANEL
  11. cdtv.device/CDTV_GENLOCK
  12. cdtv.device/CDTV_INFO
  13. cdtv.device/CDTV_ISROM
  14. cdtv.device/CDTV_MOTOR
  15. cdtv.device/CDTV_MUTE
  16. cdtv.device/CDTV_PAUSE
  17. cdtv.device/CDTV_PLAYLSN
  18. cdtv.device/CDTV_PLAYMSF
  19. cdtv.device/CDTV_PLAYSEGSLSN
  20. cdtv.device/CDTV_PLAYSEGSMSF
  21. cdtv.device/CDTV_PLAYTRACK
  22. cdtv.device/CDTV_POKEPLAYLSN
  23. cdtv.device/CDTV_POKEPLAYMSF
  24. cdtv.device/CDTV_POKESEGLSN
  25. cdtv.device/CDTV_POKESEGMSF
  26. cdtv.device/CDTV_QUICKSTATUS
  27. cdtv.device/CDTV_READ
  28. cdtv.device/CDTV_READXL
  29. cdtv.device/CDTV_REMCHANGEINT
  30. cdtv.device/CDTV_RESET
  31. cdtv.device/CDTV_SEEK
  32. cdtv.device/CDTV_STOPPLAY
  33. cdtv.device/CDTV_SUBQLSN
  34. cdtv.device/CDTV_SUBQMSF
  35. cdtv.device/CDTV_TOCLSN
  36. cdtv.device/CDTV_TOCMSF
  37. cdtv.device/CDTV_WRITE
  38. cdtv.device/CloseDevice
  39. cdtv.device/OpenDevice
  40. cdtv.device/--Background--                         cdtv.device/--Background--
  41.  
  42.    Background
  43.     This document will describe some common terms and assumptions so
  44.     that it need not be repeated everywhere.
  45.  
  46.    Common IORequest Fields
  47.     Unless otherwise noted, certain fields in the IORequest or IOStdReq
  48.     structure contain values common to all commands.
  49.  
  50.     The io_Device and io_Unit fields are filled by OpenDevice().
  51.     io_Flags can either be NULL or have the IOF_QUICK bit set.  The
  52.     io_Message structure should have the mn_ReplyPort field properly
  53.     initialized to a valid reply port.
  54.  
  55.     Unused fields in the I/O request should be initialized to zero for
  56.     future compatibility.
  57.  
  58.    Errors
  59.     For all commands, if the io_Error field is non-zero, you must assume
  60.     that the command failed, and that the requested action didn't happen
  61.     or the returned data is invalid.  The error codes are defined in
  62.     <devices/cdtv.h>.
  63.  
  64.    Call-Back Environment
  65.     For those commands that can call client routines, the CPU registers
  66.     are initialized as follows (all other registers are undefined):
  67.  
  68.     Command:        Registers:
  69.     --------        ----------
  70.     CDTV_FRAMECALL        A2:  Pointer to I/O request used to invoke
  71.                      the command
  72.  
  73.     CDTV_PLAYSEGS{LSN,MSF}    A2:  Pointer to CDAudioSeg structure just
  74.                      started or completed
  75.  
  76.     CDTV_READXL        A2:  Pointer to CDXL node just completed
  77.  
  78.     D0,D1,A0,A1 may be trashed.  All other registers must be preserved.
  79.     Your code is called in interrupt mode on the supervisor stack (you
  80.     may not take any kind of advantage of this fact).  You are required
  81.     to keep your code very brief.  Your code must return via an RTS
  82.     instruction.  No return values are currently recognized, but put
  83.     zero in D0 for future compatibility.
  84.  
  85.    Bugs
  86.     Bugs are presented here for your convenience.  However, Commodore
  87.     reserves the right to fix any and all bugs.  Do not rely on
  88.     behaviors listed as bugs, as they are subject to change at any time.
  89. cdtv.device/CDTV_ADDCHANGEINT                   cdtv.device/CDTV_ADDCHANGEINT
  90.  
  91.    NAME
  92.     CDTV_ADDCHANGEINT -- Add a disc-change interrupt to the driver.
  93.  
  94.    IO REQUEST
  95.     io_Command    CDTV_ADDCHANGEINT
  96.     io_Data        pointer to Exec Interrupt structure
  97.     io_Length    0
  98.     io_Offset    0
  99.  
  100.    RESULTS
  101.  
  102.    FUNCTION
  103.     This command will install a software interrupt handler which will be
  104.     invoked every time a disc is either removed or inserted into the
  105.     drive.
  106.  
  107.     io_Data points to a properly initialized Exec Interupt structure.
  108.     Once installed, you must be prepared to handle change interrupts
  109.     immediately.  Your handler will be called using standard Exec
  110.     software interrupt conventions.  From within the handler, the only
  111.     commands in cdtv.device you may call are status commands that can
  112.     use IOF_QUICK.  These include CDTV_QUICKSTATUS, CDTV_REMCHANGEINT,
  113.     CDTV_CHANGENUM, and CDTV_CHANGESTATE.
  114.  
  115.     The driver holds on to this command until explicitly released with
  116.     CDTV_REMCHANGEINT using the same I/O request.  Thus, you should use
  117.     SendIO() with this command.
  118.  
  119.    EXAMPLE
  120.  
  121.    NOTES
  122.  
  123.    BUGS
  124.     There is a bug in the hardware that will prevent you from seeing a
  125.     disc change interrupt immediately if you happen to be in the middle
  126.     of a data read when someone ejects the disc.  You should use other
  127.     indicators to detect this condition.
  128.  
  129.    SEE ALSO
  130.     CDTV_REMCHANGEINT
  131. cdtv.device/CDTV_CHANGENUM                         cdtv.device/CDTV_CHANGENUM
  132.  
  133.    NAME
  134.     CDTV_CHANGENUM -- Return the current value of the disc change
  135.               counter.
  136.  
  137.    IO REQUEST
  138.     io_Command    CDTV_CHANGENUM
  139.     io_Data        NULL
  140.     io_Length    0
  141.     io_Offset    0
  142.  
  143.    RESULTS
  144.     io_Actual    the current value of the counter
  145.  
  146.    FUNCTION
  147.     This command reports the current value of the disc change counter.
  148.     The counter is incremented each time a disc is removed or inserted.
  149.  
  150.    EXAMPLE
  151.  
  152.    NOTES
  153.  
  154.    BUGS
  155.  
  156.    SEE ALSO
  157.     CDTV_ADDCHANGEINT, CDTV_REMCHANGEINT
  158. cdtv.device/CDTV_CHANGESTATE                     cdtv.device/CDTV_CHANGESTATE
  159.  
  160.    NAME
  161.     CDTV_CHANGESTATE -- Reports if a disc is present in the drive.
  162.  
  163.    IO REQUEST
  164.     io_Command    CDTV_CHANGESTATE
  165.     io_Data        NULL
  166.     io_Length    0
  167.     io_Offset    0
  168.  
  169.    RESULTS
  170.     io_Actual    current state of the drive (non-zero == drive empty;
  171.             0 == drive not empty (disc present))
  172.  
  173.    FUNCTION
  174.     This command will report whether or not a compact disc (not
  175.     necessarily a CD-ROM) is present in the drive.
  176.  
  177.    EXAMPLE
  178.  
  179.    NOTES
  180.  
  181.    BUGS
  182.  
  183.    SEE ALSO
  184.     CDTV_ISROM
  185. cdtv.device/CDTV_FADE                                   cdtv.device/CDTV_FADE
  186.  
  187.    NAME
  188.     CDTV_FADE -- Fade CD audio volume over time.
  189.  
  190.    IO REQUEST
  191.     io_Command    CDTV_FADE
  192.     io_Data        NULL
  193.     io_Length    fade duration, in frames
  194.     io_Offset    target volume level (0 - 0x7FFF)
  195.  
  196.    RESULTS
  197.  
  198.    FUNCTION
  199.     This command will ramp the CD audio volume up or down from its
  200.     current value to the value contained in io_Offset.  The range is 0
  201.     (silence) to 0x7FFF (full volume).
  202.  
  203.     io_Length contains the duration of the fade.  In seconds, this is:
  204.  
  205.         io_Length / 75
  206.  
  207.     Note that this command returns before the fade has completed.  Thus,
  208.     once started, a fade cannot be aborted.  You can, however, send a
  209.     new CDTV_FADE command, which will immediately override any fade
  210.     currently in progress.  (An io_Length of zero is valid.)
  211.  
  212.     Fades happen in "Mode 1" as described in the CDTV_MUTE document.
  213.     Fades continue to completion even if there is no CD audio operation
  214.     in progress.
  215.  
  216.     It is recommended that you avoid invoking CDTV_MUTE while a fade is
  217.     in progress, since they may interact in unexpected ways.
  218.  
  219.    EXAMPLE
  220.  
  221.    NOTES
  222.     This command has no effect on Amiga audio volume.
  223.  
  224.    BUGS
  225.  
  226.    SEE ALSO
  227.     CDTV_MUTE
  228. cdtv.device/CDTV_FRAMECALL                         cdtv.device/CDTV_FRAMECALL
  229.  
  230.    NAME
  231.     CDTV_FRAMECALL -- Establish a CD frame callback function.
  232.  
  233.    IO REQUEST
  234.     io_Command    CDTV_FRAMECALL
  235.     io_Data        pointer to callback entry point
  236.     io_Length    0
  237.     io_Offset    number of CD frames to wait before invoking callback
  238.  
  239.    RESULTS
  240.  
  241.    FUNCTION
  242.     This command will install a callback function which will be invoked
  243.     when the requested number of CD frames has passed.  Use the
  244.     CDTV_INFO command to discover the prevailing frame rate.
  245.  
  246.     To be more precise, io_Offset is set to the number of frames to skip
  247.     *between* each invocation of the call-back.  For example, if
  248.     io_Offset were set to 1, the driver would skip one frame, then call
  249.     your code on the next, then skip one frame, then call your code on
  250.     the next, etc.  If io_Offset were set to 2, the driver would skip
  251.     two frames, then call your code on the next, etc.  If io_Offset were
  252.     zero, your code would be called every frame (zero frames between
  253.     calls).
  254.  
  255.     When installed, your code must be ready to handle the callback
  256.     immediately.  The callback will continue to be invoked until
  257.     explicitly removed via AbortIO().  Thus, you should use SendIO()
  258.     with this command.
  259.  
  260.    CALL-BACK ENVIRONMENT
  261.     The CPU registers are initialized as follows (all other registers
  262.     are undefined):
  263.  
  264.         A2:  Pointer to I/O request used to invoke the command
  265.         D0,D1,A0,A1 may be trashed.
  266.         All other registers must be preserved.
  267.  
  268.     Your code is called in interrupt mode on the supervisor stack (you
  269.     may not take any kind of advantage of this fact).  You are required
  270.     to keep your code very brief.  Your code must return via an RTS
  271.     instruction.  No return values are currently recognized, but put
  272.     zero in D0 for future compatibility.
  273.  
  274.    EXAMPLE
  275.  
  276.    NOTES
  277.  
  278.    BUGS
  279.  
  280.    SEE ALSO
  281.     CDTV_FRAMECOUNT
  282. cdtv.device/CDTV_FRAMECOUNT                       cdtv.device/CDTV_FRAMECOUNT
  283.  
  284.    NAME
  285.     CDTV_FRAMECOUNT -- Report the frame count since the disc was
  286.                inserted.
  287.  
  288.    IO REQUEST
  289.     io_Command    CDTV_FRAMECOUNT
  290.     io_Data        NULL
  291.     io_Length    0
  292.     io_Offset    0
  293.  
  294.    RESULTS
  295.     io_Actual    number of frames since last insertion
  296.  
  297.    FUNCTION
  298.     This command will return the number of CD frames that have passed
  299.     since the disc was inserted into the drive.  This can be used for
  300.     synchronization purposes.  Use the CDTV_INFO command to discover the
  301.     prevailing frame rate.
  302.  
  303.    EXAMPLE
  304.  
  305.    NOTES
  306.     The frame count will continue to accumulate whether the CD is
  307.     spinning or not.
  308.  
  309.    BUGS
  310.  
  311.    SEE ALSO
  312.     CDTV_FRAMECALL
  313. cdtv.device/CDTV_FRONTPANEL                       cdtv.device/CDTV_FRONTPANEL
  314.  
  315.    NAME
  316.     CDTV_FRONTPANEL -- Enable/disable direct front panel control of the
  317.                CD-ROM drive.
  318.  
  319.    IO REQUEST
  320.     io_Command    CDTV_FRONTPANEL
  321.     io_Data        NULL
  322.     io_Length    desired state (0 == disabled, 1 == enabled)
  323.     io_Offset    0
  324.  
  325.    RESULTS
  326.  
  327.    FUNCTION
  328.     CDTV's front panel and IR remote controls can manipulate the audio
  329.     capabilities of the CD-ROM drive directly, without Amiga
  330.     intervention.
  331.  
  332.     This command enables/disables this capability.  When the front panel
  333.     is "enabled," it operates the drive directly, and no rawkey codes
  334.     for the PLAY, STOP, FF, and REW keys are sent to the Amiga.  When it
  335.     is "disabled," this direct connection is broken, and the Amiga
  336.     receives rawkey codes for those keys.
  337.  
  338.    EXAMPLE
  339.  
  340.    NOTES
  341.     The rawkey codes for the IR buttons are currently:
  342.  
  343.         STOP        0x72
  344.         PLAY/PAUSE    0x73
  345.         FF        0x74
  346.         REW        0x75
  347.  
  348.    BUGS
  349.     There is a bug in the hardware whereby, if the Amiga sends any kind
  350.     of command to the CD-ROM drive (including play commands), the front
  351.     panel controls are disabled, and the drive will ignore all enable
  352.     requests until the command is completed or aborted.
  353.  
  354.    SEE ALSO
  355. cdtv.device/CDTV_GENLOCK                             cdtv.device/CDTV_GENLOCK
  356.  
  357.    NAME
  358.     CDTV_GENLOCK -- Control genlock output mode.
  359.  
  360.    IO REQUEST
  361.     io_Command    CDTV_GENLOCK
  362.     io_Data        NULL
  363.     io_Length    0
  364.     io_Offset    desired genlock mode
  365.  
  366.    RESULTS
  367.  
  368.    FUNCTION
  369.     This command changes the operating mode of the genlock card.  There
  370.     are currently four modes:
  371.  
  372.     CDTV_GENLOCK_REMOTE    permit IR remote to control genlock modes
  373.     CDTV_GENLOCK_AMIGA    display Amiga's video
  374.     CDTV_GENLOCK_EXTERNAL    display external video source
  375.     CDTV_GENLOCK_MIXED    display Amiga video overlayed on external
  376.                 video
  377.  
  378.     It is recommended that you return the genlock to CDTV_GENLOCK_REMOTE
  379.     mode when your title is not using it.
  380.  
  381.    EXAMPLE
  382.  
  383.    NOTES
  384.     There is no way to detect if a genlock card is installed in the
  385.     system.  However, you can detect if the system has booted in genlock
  386.     mode (which strongly suggests the presence of a genlock card) by
  387.     inspecting GfxBase.DisplayFlags to see if the GENLOC bit is set.
  388.  
  389.    BUGS
  390.  
  391.    SEE ALSO
  392. cdtv.device/CDTV_INFO                                   cdtv.device/CDTV_INFO
  393.  
  394.    NAME
  395.     CDTV_INFO -- Report information on CD-ROM drive/disc.
  396.  
  397.    IO REQUEST
  398.     io_Command    CDTV_INFO
  399.     io_Data        NULL
  400.     io_Length    0
  401.     io_Offset    info request code
  402.  
  403.    RESULTS
  404.     io_Actual    the data you requested
  405.  
  406.    FUNCTION
  407.     This command is used to obtain information about the current
  408.     configuration of the CD-ROM drive.  The request code is placed in
  409.     io_Offset.  The requested data may be found in io_Actual.
  410.  
  411.     The available requests are:
  412.  
  413.     CDTV_INFO_BLOCK_SIZE    report size of sectors, in bytes
  414.     CDTV_INFO_FRAME_RATE    report current CD frame rate, in frames per
  415.                 second
  416.  
  417.    EXAMPLE
  418.  
  419.    NOTES
  420.  
  421.    BUGS
  422.  
  423.    SEE ALSO
  424. cdtv.device/CDTV_ISROM                                 cdtv.device/CDTV_ISROM
  425.  
  426.    NAME
  427.     CDTV_ISROM -- Reports type of disc currently in CD-ROM drive.
  428.  
  429.    IO REQUEST
  430.     io_Command    CDTV_ISROM
  431.     io_Data        NULL
  432.     io_Length    0
  433.     io_Offset    0
  434.  
  435.    RESULTS
  436.     io_Actual    type of disc installed (0 == not a CD-ROM;
  437.             non-zero == it's a CD-ROM)
  438.  
  439.    FUNCTION
  440.     This command reports whether or not the disc currently in the drive
  441.     is a CD-ROM (as opposed to an ordinary audio disc).
  442.  
  443.    EXAMPLE
  444.  
  445.    NOTES
  446.  
  447.    BUGS
  448.  
  449.    SEE ALSO
  450.     CDTV_CHANGESTATE
  451. cdtv.device/CDTV_MOTOR                                 cdtv.device/CDTV_MOTOR
  452.  
  453.    NAME
  454.     CDTV_MOTOR -- Turn the CD-ROM drive's motor on/off.
  455.  
  456.    IO REQUEST
  457.     io_Command    CDTV_MOTOR
  458.     io_Data        NULL
  459.     io_Length    requested state of the motor (0 == off, 1 == on)
  460.     io_Offset    0
  461.  
  462.    RESULTS
  463.     io_Actual    previous state of motor
  464.  
  465.    FUNCTION
  466.     This command causes the CD-ROM drive's motor to spin up or spin
  467.     down.  The desired state of the motor is placed in io_Length.  The
  468.     previous state of the motor is returned in io_Actual.  If there is
  469.     no disc in the drive, the motor stays off.
  470.  
  471.     Turning off the motor is discouraged, since it takes several seconds
  472.     for the motor to spin back up.
  473.  
  474.    EXAMPLE
  475.  
  476.    NOTES
  477.     If the drive remains idle for more than eight minutes, it turns the
  478.     motor off.
  479.  
  480.    BUGS
  481.  
  482.    SEE ALSO
  483. cdtv.device/CDTV_MUTE                                   cdtv.device/CDTV_MUTE
  484.  
  485.    NAME
  486.     CDTV_MUTE -- Set CD audio volume.
  487.  
  488.    IO REQUEST
  489.     io_Command    CDTV_MUTE
  490.     io_Data        NULL
  491.     io_Length    mode of operation (0, 1, or 2)
  492.     io_Offset    desired volume level (0 - 0x7FFF)
  493.  
  494.    RESULTS
  495.     io_Actual    previous volume level
  496.  
  497.    FUNCTION
  498.     This command sets the output volume for CD audio.  Both left and
  499.     right channels are affected.
  500.  
  501.     The io_Offset field contains the desired volume level.  0 is
  502.     silence, 0x7FFF is full volume.
  503.  
  504.     The io_Length field specifies the mode of operation:
  505.  
  506.         0:  Do not set the volume.  This is used to inspect the
  507.             current volume level.
  508.         1:  Set volume level to be used when a CD audio play
  509.             operation is initiated.  CD audio volume will be muted
  510.             when the current play command is paused or aborted, or
  511.             when a CDTV_STOPPLAY command is issued.
  512.         2:  Set volume level immediately, regardless of current play
  513.             state.  This is normally used by system software.  Its
  514.             use is discouraged, since it is possible to play CD-ROM
  515.             data by misusing this command.  CD-ROM data sounds
  516.             astonishingly bad.
  517.  
  518.     The previous volume level is returned in io_Actual.
  519.  
  520.    EXAMPLE
  521.  
  522.    NOTES
  523.     This command has no effect on Amiga audio volume.
  524.  
  525.    BUGS
  526.  
  527.    SEE ALSO
  528.     CDTV_FADE
  529. cdtv.device/CDTV_PAUSE                                 cdtv.device/CDTV_PAUSE
  530.  
  531.    NAME
  532.     CDTV_PAUSE -- Pause/un-pause the CD-ROM drive.
  533.  
  534.    IO REQUEST
  535.     io_Command    CDTV_PAUSE
  536.     io_Data        NULL
  537.     io_Length    1 == pause drive; 0 == resume play
  538.     io_Offset    0
  539.  
  540.    RESULTS
  541.  
  542.    FUNCTION
  543.     This command will pause and un-pause the laser on the drive during a
  544.     CD audio play operation.  The desired pause state is placed in
  545.     io_Length.  This command is typically used in CD audio applications.
  546.  
  547.     Audio output is suspended when the drive is paused.  Audio output
  548.     resumes when the drive is un-paused.
  549.  
  550.    EXAMPLE
  551.  
  552.    NOTES
  553.  
  554.    BUGS
  555.     The drive does not latch the current pause state.  That is, if you
  556.     pause the drive, then issue one of the play commands, the drive will
  557.     seek to the new play location and begin playing.  If you wish the
  558.     drive to remain paused in the new location, you must re-issue the
  559.     pause command.
  560.  
  561.     If the drive is in the middle of a seek, it will ignore all attempts
  562.     to pause it.
  563.  
  564.    SEE ALSO
  565. cdtv.device/CDTV_PLAYLSN                             cdtv.device/CDTV_PLAYLSN
  566.  
  567.    NAME
  568.     CDTV_PLAYLSN -- Play CD audio from a specific location, LSN format.
  569.  
  570.    IO REQUEST
  571.     io_Command    CDTV_PLAYLSN
  572.     io_Data        NULL
  573.     io_Length    number of sectors to play
  574.     io_Offset    starting sector
  575.  
  576.    RESULTS
  577.  
  578.    FUNCTION
  579.     This command causes the drive to start playing CD audio from the
  580.     specified position, in LSN format.
  581.  
  582.     io_Offset specifies the starting position in LSN format.  io_Length
  583.     contains the number of sectors to play.
  584.  
  585.     The command will not return until the requested number of sectors
  586.     has been played.  The command may be aborted with AbortIO().  The
  587.     audio will cease, but the laser will continue to track, and the
  588.     drive light will remain on.  Use the CDTV_STOPPLAY command after
  589.     AbortIO() if you wish to halt this action.
  590.  
  591.     Please be sure that you're going to be playing CD audio data before
  592.     issuing this command.  CD-ROM data doesn't sound good.
  593.  
  594.    EXAMPLE
  595.     /*  Play one second of music starting at STARTLSN.  */
  596.     ior->io_Command    = CDTV_PLAYLSN;
  597.     ior->io_Data    = NULL;
  598.     ior->io_Offset    = STARTLSN;
  599.     ior->io_Length    = 75;
  600.     DoIO (ior);
  601.  
  602.    NOTES
  603.  
  604.    BUGS
  605.  
  606.    SEE ALSO
  607.     CDTV_PLAYMSF, CDTV_TOCLSN
  608. cdtv.device/CDTV_PLAYMSF                             cdtv.device/CDTV_PLAYMSF
  609.  
  610.    NAME
  611.     CDTV_PLAYMSF -- Play CD audio from a specific location.
  612.  
  613.    IO REQUEST
  614.     io_Command    CDTV_PLAYMSF
  615.     io_Data        NULL
  616.     io_Length    stopping position, MSF format
  617.     io_Offset    starting position, MSF format
  618.  
  619.    RESULTS
  620.  
  621.    FUNCTION
  622.     This command causes the drive to play CD audio from the location
  623.     specified in MSF format.
  624.  
  625.     io_Offset specifies the starting location in MSF format.  io_Length
  626.     specifies the stopping location in MSF format (NOT the length, as
  627.     in CDTV_PLAYLSN).  The drive will play audio from the starting
  628.     location up to, but not including, the stopping location.
  629.  
  630.     The command will not return until the requested segment has been
  631.     played.  The command may be aborted with AbortIO().  The audio will
  632.     cease, but the laser will continue to track and the drive light will
  633.     remain on.  Use the CDTV_STOPPLAY command after AbortIO() to halt
  634.     this action.
  635.  
  636.    EXAMPLE
  637.     /*  Play 10.333 seconds of music starting five minutes in.  */
  638.     ior->io_Command    = CDTV_PLAYMSF;
  639.     ior->io_Data    = NULL;
  640.     ior->io_Offset    = TOMSF (5, 0, 0);    /*  Start position  */
  641.     ior->io_Length    = TOMSF (5, 10, 25);    /*  End position    */
  642.     DoIO (ior);
  643.  
  644.    NOTES
  645.     You may care to use the TOMSF macro in <devices/cdtv.h> to create an
  646.     MSF number.
  647.  
  648.    BUGS
  649.  
  650.    SEE ALSO
  651.     CDTV_PLAYLSN, CDTV_TOCMSF, <devices/cdtv.h>
  652. cdtv.device/CDTV_PLAYSEGSLSN                     cdtv.device/CDTV_PLAYSEGSLSN
  653.  
  654.    NAME
  655.     CDTV_PLAYSEGSLSN -- Play CD audio segments using a segment list,
  656.                 LSN format.
  657.  
  658.    IO REQUEST
  659.     io_Command    CDTV_PLAYSEGSLSN
  660.     io_Data        pointer to audio segment list header or list node.
  661.     io_Length    0
  662.     io_Offset    0
  663.  
  664.    RESULTS
  665.  
  666.    FUNCTION
  667.     This command will play a sequence of audio "snippets" according to
  668.     the information contained in the nodes of an audio segment list.
  669.     The driver will play all the nodes in turn until it reaches the end
  670.     of the list.
  671.  
  672.     The address of the list header or a CDAudioSeg node is placed into
  673.     io_Data; the list is traversed from this point.  The fields in the
  674.     CDAudioSeg structure are as follows:
  675.  
  676.         Node        Exec MinNode, for linking nodes
  677.         Start        Start position, LSN format
  678.         Stop        Number of logical sectors to play
  679.         StartFunc    Function to call when the audio segment
  680.                 starts playing
  681.         StopFunc    Function to call when the audio segment is
  682.                 completed
  683.  
  684.     This command will not return until all audio segments have been
  685.     played.  The command may be aborted using AbortIO().
  686.  
  687.    CALL-BACK ENVIRONMENT
  688.     If you use the StartFunc or StopFunc fields, your code will be
  689.     called using the call-back environment described below.  For
  690.     StartFunc, your code will be called when the audio for the segment
  691.     has actually commenced.  For StopFunc, your code is called when the
  692.     audio segment has completed.  You may manipulate the segment list
  693.     within both call-backs.
  694.  
  695.     The CPU registers are initialized as follows (all other registers
  696.     are undefined):
  697.  
  698.         A2:  Pointer to CDAudioSeg structure just started or
  699.              completed
  700.         D0,D1,A0,A1 may be trashed.
  701.         All other registers must be preserved.
  702.  
  703.     Your code is called in interrupt mode on the supervisor stack (you
  704.     may not take any kind of advantage of this fact).  You are required
  705.     to keep your code very brief.  Your code must return via an RTS
  706.     instruction.  No return values are currently recognized, but put
  707.     zero in D0 for future compatibility.
  708.  
  709.    EXAMPLE
  710.  
  711.    NOTES
  712.  
  713.    BUGS
  714.  
  715.    SEE ALSO
  716.     CDTV_PLAYSEGSMSF, CDTV_POKESEGMSF
  717. cdtv.device/CDTV_PLAYSEGSMSF                     cdtv.device/CDTV_PLAYSEGSMSF
  718.  
  719.     CDTV_PLAYSEGSMSF -- Play CD audio segments using a segment list,
  720.                 MSF format.
  721.  
  722.    IO REQUEST
  723.     io_Command    CDTV_PLAYSEGSMSF
  724.     io_Data        pointer to audio segment list header or list node.
  725.     io_Length    0
  726.     io_Offset    0
  727.  
  728.    RESULTS
  729.  
  730.    FUNCTION
  731.     This command is identical to CDTV_PLAYSEGSLSN, except that the
  732.     Start and Stop fields in the CDAudioSeg structure are in MSF format.
  733.     In addition, the CDAudioSeg.Stop field specifies the stopping
  734.     location (not the length).
  735.  
  736.     See CDTV_PLAYSEGSLSN for more details.
  737.  
  738.    EXAMPLE
  739.  
  740.    NOTES
  741.  
  742.    BUGS
  743.  
  744.    SEE ALSO
  745.     CDTV_PLAYSEGSLSN, CDTV_POKESEGLSN
  746. cdtv.device/CDTV_PLAYTRACK                         cdtv.device/CDTV_PLAYTRACK
  747.  
  748.    NAME
  749.     CDTV_PLAYTRACK -- Play one or more tracks of CD audio.
  750.  
  751.    IO REQUEST
  752.     io_Command    CDTV_PLAYTRACK
  753.     io_Data        NULL
  754.     io_Length    stopping track, index
  755.     io_Offset    starting track, index
  756.  
  757.    RESULTS
  758.     Music.
  759.  
  760.    FUNCTION
  761.     This command causes the drive to play the specified audio track(s).
  762.     The command will return when the audio has completed.
  763.  
  764.     io_Offset specifies the track number (starting from 1).  It may
  765.     optionally include an index in the upper 16 bits.
  766.  
  767.     io_Length specifies the track at which to stop (NOT the last track
  768.     to be played).  It may also optionally include a stopping index in
  769.     the upper 16 bits.  If io_Length is zero, the stopping position is
  770.     taken to be the next track (no index).
  771.  
  772.     The command may be aborted using AbortIO().  The audio will cease,
  773.     but the laser will continue to track, and the drive light will
  774.     remain on.  The CDTV_STOPPLAY command should be used after AbortIO()
  775.     if you wish to halt this action.
  776.  
  777.    EXAMPLE
  778.     /*  Play three audio tracks starting at STARTTRACK  */
  779.     ior->io_Command    = CDTV_PLAYTRACK;
  780.     ior->io_Data    = NULL;
  781.     ior->io_Offset    = STARTTRACK;
  782.     ior->io_Length    = STARTTRACK + 3;
  783.     DoIO (ior);
  784.  
  785.    NOTES
  786.  
  787.    BUGS
  788.  
  789.    SEE ALSO
  790.     CDTV_PLAYLSN, CDTV_PLAYMSF
  791. cdtv.device/CDTV_POKEPLAYLSN                     cdtv.device/CDTV_POKEPLAYLSN
  792.  
  793.    NAME
  794.     CDTV_POKEPLAYLSN -- Poke a play in progress, LSN format.
  795.  
  796.    IO REQUEST
  797.     io_Command    CDTV_POKEPLAYLSN
  798.     io_Data        NULL
  799.     io_Length    new play duration, in frames
  800.     io_Offset    new play location, LSN format
  801.  
  802.    RESULTS
  803.     Seek to new location and commence audio from that point.
  804.  
  805.    FUNCTION
  806.     This command will cause a play command in progress to seek to and
  807.     commence play at a new location, specified in LSN format.
  808.  
  809.     The drive will start playing at the location contained in io_Offset.
  810.     The new play length is contained in io_Length.
  811.  
  812.     This command eliminates the need to perform an AbortIO() and issue a
  813.     new play command.  It's useful for "fast-forward" type effects.
  814.  
  815.     A CDTV_PLAYLSN command must be in effect before issuing this
  816.     command.
  817.  
  818.    EXAMPLE
  819.  
  820.    NOTES
  821.  
  822.    BUGS
  823.     This command breaks a pause.
  824.  
  825.    SEE ALSO
  826.     CDTV_PLAYLSN
  827. cdtv.device/CDTV_POKEPLAYMSF                     cdtv.device/CDTV_POKEPLAYMSF
  828.  
  829.    NAME
  830.     CDTV_POKEPLAYMSF -- Poke a play in progress, MSF format.
  831.  
  832.    IO REQUEST
  833.     io_Command    CDTV_POKEPLAYMSF
  834.     io_Data        NULL
  835.     io_Length    new stop location, MSF format
  836.     io_Offset    new play location, MSF format
  837.  
  838.    RESULTS
  839.     Seek to new location and commence audio from that point.
  840.  
  841.    FUNCTION
  842.     This command will cause a play command in progress to seek to and
  843.     commence play at a new location, specified in MSF format.
  844.  
  845.     The drive will start playing at the location contained in io_Offset.
  846.     The new stopping location is contained in io_Length.
  847.  
  848.     This command eliminates the need to perform an AbortIO() and issue a
  849.     new play command.  It's useful for "fast-forward" type effects.
  850.  
  851.     A CDTV_PLAYMSF command must be in effect before issuing this
  852.     command.
  853.  
  854.    EXAMPLE
  855.  
  856.    NOTES
  857.  
  858.    BUGS
  859.     This command breaks a pause.
  860.  
  861.    SEE ALSO
  862.     CDTV_PLAYMSF
  863. cdtv.device/CDTV_POKESEGLSN                       cdtv.device/CDTV_POKESEGLSN
  864.  
  865.    NAME
  866.     CDTV_POKESEGLSN -- Jump to an entry in an audio segment list,
  867.                LSN format.
  868.  
  869.    IO REQUEST
  870.     io_Command    CDTV_POKESEGLSN
  871.     io_Data        pointer to CDAudioSeg node
  872.     io_Length    0
  873.     io_Offset    new start position, LSN format
  874.  
  875.    RESULTS
  876.  
  877.    FUNCTION
  878.     This command will cause the device driver to jump to the CDAudioSeg
  879.     node pointed to by io_Data.  The fields in the CDAudioSeg node are
  880.     in LSN format.
  881.  
  882.     The drive will seek and immediately begin playing at the position
  883.     specified by the io_Offset field in the I/O request.  The length is
  884.     taken from the Stop field in the specified node.  The device driver
  885.     will then continue playing the entries in the segment list from this
  886.     point.
  887.  
  888.     A CDTV_PLAYSEGSLSN command must be in effect before invoking this
  889.     command.
  890.  
  891.    EXAMPLE
  892.  
  893.    NOTES
  894.     The target node can be a member of a completely different list.
  895.  
  896.    BUGS
  897.  
  898.    SEE ALSO
  899.     CDTV_POKESEGMSF
  900. cdtv.device/CDTV_POKESEGMSF                       cdtv.device/CDTV_POKESEGMSF
  901.  
  902.    NAME
  903.     CDTV_POKESEGMSF -- Jump to an entry in an audio segment list,
  904.                MSF format.
  905.  
  906.    IO REQUEST
  907.     io_Command    CDTV_POKESEGMSF
  908.     io_Data        pointer to CDAudioSeg node
  909.     io_Length    0
  910.     io_Offset    new start position, MSF format
  911.  
  912.    RESULTS
  913.  
  914.    FUNCTION
  915.     This command will cause the device driver to jump to the CDAudioSeg
  916.     node pointed to by io_Data.  The fields in the CDAudioSeg node are
  917.     in MSF format.
  918.  
  919.     The drive will seek and immediately begin playing at the position
  920.     specified by the io_Offset field in the I/O request.  The stopping
  921.     position is taken from the Stop field in the specified node.  The
  922.     device driver will then continue playing the entries in the segment
  923.     list from this point.
  924.  
  925.     A CDTV_PLAYSEGSMSF command must be in effect before invoking this
  926.     command.
  927.  
  928.    EXAMPLE
  929.  
  930.    NOTES
  931.     The target node can be a member of a completely different list.
  932.  
  933.    BUGS
  934.  
  935.    SEE ALSO
  936.     CDTV_POKESEGLSN
  937. cdtv.device/CDTV_QUICKSTATUS                     cdtv.device/CDTV_QUICKSTATUS
  938.  
  939.    NAME
  940.     CDTV_QUICKSTATUS -- Return current status of the CD-ROM drive.
  941.  
  942.    IO REQUEST
  943.     io_Command    CDTV_QUICKSTATUS
  944.     io_Data        NULL
  945.     io_Length    0
  946.     io_Offset    0
  947.  
  948.    RESULTS
  949.     io_Actual    current status of drive, as a set of bits:
  950.         QSF_READY    drive is ready
  951.         QSF_AUDIO    CD digital audio is playing
  952.         QSF_DONE    last hardware command completed
  953.         QSF_ERROR    error in last hardware command
  954.         QSF_SPIN    disc is spinning
  955.         QSF_DISK    disc is present in drive
  956.         QSF_INFERR    positioning error
  957.  
  958.    FUNCTION
  959.     This command reports the current status of the CD-ROM drive.  This
  960.     command is super-fast, and is always synchronous.  This command may
  961.     safely be used from within interrupts.
  962.  
  963.     The status is returned in io_Actual.  If no status is available,
  964.     io_Actual will contain zero.
  965.  
  966.     The bits QSF_READY, QSF_DONE, QSF_ERROR, and QSF_INFERR should not
  967.     be relied upon to relay any kind of useful information, and should
  968.     be ignored.
  969.  
  970.    EXAMPLE
  971.  
  972.    NOTES
  973.     This command may also be called directly as a function to cut
  974.     overhead in time critical code (A6 must be set to cdtv device base
  975.     and A4 set to point to the I/O request block).
  976.  
  977.    BUGS
  978.  
  979.    SEE ALSO
  980. cdtv.device/CDTV_READ                                   cdtv.device/CDTV_READ
  981.  
  982.    NAME
  983.     CDTV_READ -- Read bytes off a CD-ROM
  984.  
  985.    IO REQUEST
  986.     io_Command    CDTV_READ
  987.     io_Data        pointer to buffer to receive data (word-aligned)
  988.     io_Length    number of bytes to read (must be even)
  989.     io_Offset    offset in bytes from beginning of disc to begin
  990.             reading (must be even)
  991.  
  992.    RESULTS
  993.     io_Actual    actual number of bytes read.  This may differ from
  994.             the amount requested.
  995.  
  996.    FUNCTION
  997.     This command reads bytes from CD-ROM sectors.
  998.  
  999.     CD-ROM transfers are word-oriented, so the destination buffer must
  1000.     be word-aligned and an even number of bytes.  The starting position
  1001.     on the disc must also be an even number.  Unlike other Amiga block
  1002.     devices, the transfer need not be sector aligned.
  1003.  
  1004.     Sectors are DMA'd into the system in 2K bursts.  During this time,
  1005.     bus cycles are stolen from the CPU to move the data.  The bursts
  1006.     take 1.3 milliseconds, and occur at the CD frame rate.
  1007.  
  1008.    EXAMPLE
  1009.  
  1010.    NOTES
  1011.     The io_Offset parameter is not restricted to any particular track;
  1012.     it will read from any position on the disc that contains CD-ROM
  1013.     data.
  1014.  
  1015.     io_Offset's "zero point" is the first byte of the first valid frame
  1016.     on the disc.  This is usually MSF 00:02.00 (LSN 0), but the disc's
  1017.     table of contents will tell you definitely where this is.
  1018.  
  1019.     CD-ROM mode 2, form 2 sector sizes are not supported by this
  1020.     command.  CDTV_READXL must be used for sectors of this type.
  1021.  
  1022.     The time it takes to burst a sector into memory may change in the
  1023.     future.
  1024.  
  1025.     The hardware prohibits all attempts by the Amiga to read CD audio
  1026.     data.
  1027.  
  1028.    BUGS
  1029.     There is a bug in the hardware such that the last few bytes in a
  1030.     given request may not be transferred.  The current workaround is to
  1031.     pad your buffers and your disk data by the value READ_PAD_BYTES, and
  1032.     to request READ_PAD_BYTES more bytes than you would otherwise.
  1033.     Thus, any missing bytes are part of the padding, and ignored.
  1034.     READ_PAD_BYTES is defined in <devices/cdtv.h>.
  1035.  
  1036.    SEE ALSO
  1037.     CDTV_READXL
  1038. cdtv.device/CDTV_READXL                               cdtv.device/CDTV_READXL
  1039.  
  1040.    NAME
  1041.     CDTV_READXL -- Read from CD-ROM into memory via transfer list.
  1042.  
  1043.    IO REQUEST
  1044.     io_Command    CDTV_READXL
  1045.     io_Data        pointer to transfer list header or list node.
  1046.     io_Length    number of sectors to read (-1 == forever)
  1047.     io_Offset    starting sector, from beginning of disc
  1048.  
  1049.    RESULTS
  1050.     Truly amazing.
  1051.  
  1052.    FUNCTION
  1053.     Our Secret Weapon.  (Patent Pending)
  1054.  
  1055.     This command starts reading data off the disc at the specified
  1056.     location and deposits it into memory according to the nodes in the
  1057.     transfer list.  The total number of sectors to transfer is placed in
  1058.     io_Length.  The address of the transfer list header, or one of its
  1059.     nodes, is placed in io_Data.
  1060.  
  1061.     Note that io_Offset and io_Length are specified in sectors rather
  1062.     than bytes.  An io_Length of zero is valid (this has the effect of a
  1063.     seek).  An io_Length of -1 will read sectors forever.
  1064.  
  1065.     The fields in the CDXL node structure are:
  1066.  
  1067.         Node        Exec list MinNode
  1068.         Buffer        address to deposit CD-ROM data
  1069.         Length        number of bytes to transfer
  1070.         DoneFunc    function to call when transfer is complete
  1071.         Actual        filled in with number of bytes actually read
  1072.  
  1073.     The philosophy here is that you set up the buffers you want filled,
  1074.     create CDXL nodes describing the locations and sizes of these
  1075.     buffers, assemble into a list, and invoke the command.  The driver
  1076.     then fills the buffers in a single pass.
  1077.  
  1078.     If you fill in the DoneFunc field with a pointer to a call-back
  1079.     function, your routine will be called when the transfer for the node
  1080.     is complete.  Your code will be called before the driver proceeds to
  1081.     the next node.  You may manipulate the list from within the
  1082.     call-back.
  1083.  
  1084.     This command completes when the specified number of sectors have
  1085.     been read, or the end of the transfer list is reached.  The command
  1086.     can also be aborted via AbortIO().
  1087.  
  1088.    CALL-BACK ENVIRONMENT
  1089.     The CPU registers are initialized as follows (all other registers
  1090.     are undefined):
  1091.  
  1092.         A2:  Pointer to CDXL node just completed
  1093.         D0,D1,A0,A1 may be trashed.
  1094.         All other registers must be preserved.
  1095.  
  1096.     Your code is called in interrupt mode on the supervisor stack (you
  1097.     may not take any kind of advantage of this fact).  You are required
  1098.     to keep your code very brief.  Your code must return via an RTS
  1099.     instruction.  No return values are currently recognized, but put
  1100.     zero in D0 for future compatibility.
  1101.  
  1102.    EXAMPLE
  1103.  
  1104.    NOTES
  1105.     Internally, an interrupt is generated as each node is completed.
  1106.     Thus, if you set up a list with a lot of small buffers (less than 2K
  1107.     each or so), the machine will be saturated with interrupts and will
  1108.     be unable to keep up, and the transfer will abort with an error.
  1109.     Try to avoid this condition.  (The occasional small buffer is okay.)
  1110.  
  1111.     Remember, io_Offset and io_Length are in SECTORS, not bytes.
  1112.  
  1113.    BUGS
  1114.     The bug described in CDTV_READ (missing bytes at the end) applies
  1115.     here, too, with the extra caveat that *all* buffers and request
  1116.     lengths described in the list must be padded by READ_PAD_BYTES.
  1117.  
  1118.    SEE ALSO
  1119.     CDTV_READ, CDTV_SEEK
  1120. cdtv.device/CDTV_REMCHANGEINT                   cdtv.device/CDTV_REMCHANGEINT
  1121.  
  1122.    NAME
  1123.     CDTV_REMCHANGEINT -- Remove a disc-change interrupt.
  1124.  
  1125.    IO REQUEST
  1126.     The *same* IORequest used to invoke the CDTV_ADDCHANGEINT command:
  1127.  
  1128.     io_Command    CDTV_REMCHANGEINT
  1129.     io_Data        pointer to Exec Interrupt structure
  1130.     io_Length    0
  1131.     io_Offset    0
  1132.  
  1133.    RESULTS
  1134.     The specified change interrupt is removed, and the CDTV_ADDCHANGEINT
  1135.     command is returned.
  1136.  
  1137.    FUNCTION
  1138.     This command removes a disc-change interrupt handler previously
  1139.     installed by CDTV_ADDCHANGEINT.  This command must be invoked using
  1140.     the same I/O request used to invoke the CDTV_ADDCHANGEINT command.
  1141.  
  1142.    EXAMPLE
  1143.  
  1144.    NOTES
  1145.  
  1146.    BUGS
  1147.  
  1148.    SEE ALSO
  1149.     CDTV_ADDCHANGEINT
  1150. cdtv.device/CDTV_RESET                                 cdtv.device/CDTV_RESET
  1151.  
  1152.    NAME
  1153.     CDTV_RESET -- Reset drive hardware.
  1154.  
  1155.    IO REQUEST
  1156.     io_Command    CDTV_RESET
  1157.     io_Data        NULL
  1158.     io_Length    0
  1159.     io_Offset    0
  1160.  
  1161.    RESULTS
  1162.  
  1163.    FUNCTION
  1164.     This command issues a reset to the drive, as if the RESET line had
  1165.     been asserted.  The drive then performs its internal initialization
  1166.     sequence before it becomes available.  This can take several
  1167.     seconds.
  1168.  
  1169.    EXAMPLE
  1170.  
  1171.    NOTES
  1172.  
  1173.    BUGS
  1174.  
  1175.    SEE ALSO
  1176. cdtv.device/CDTV_SEEK                                   cdtv.device/CDTV_SEEK
  1177.  
  1178.    NAME
  1179.     CDTV_SEEK -- Seek to a position on the disc.
  1180.  
  1181.    IO REQUEST
  1182.     io_Command    CDTV_SEEK
  1183.     io_Data        NULL
  1184.     io_Length    0
  1185.     io_Offset    number of bytes from beginning of disc
  1186.  
  1187.    RESULTS
  1188.  
  1189.    FUNCTION
  1190.     This command will cause the laser to seek as close as possible to
  1191.     the requested location.
  1192.  
  1193.    EXAMPLE
  1194.  
  1195.    NOTES
  1196.     io_Offset's "zero point" is the first byte of the first valid frame
  1197.     on the disc.  This is usually MSF 00:02.00 (LSN 0), but the disc's
  1198.     table of contents will tell you definitely where this is.
  1199.  
  1200.     This command will span tracks.  However, the target location must
  1201.     contain CD-ROM data.
  1202.  
  1203.    BUGS
  1204.  
  1205.    SEE ALSO
  1206.     CDTV_READ, CDTV_READXL
  1207. cdtv.device/CDTV_STOPPLAY                           cdtv.device/CDTV_STOPPLAY
  1208.  
  1209.    NAME
  1210.     CDTV_STOPPLAY -- Stop CD audio play.
  1211.  
  1212.    IO REQUEST
  1213.     io_Command    CDTV_STOPPLAY
  1214.     io_Data        NULL
  1215.     io_Length    0
  1216.     io_Offset    0
  1217.  
  1218.    RESULTS
  1219.     Silence.
  1220.  
  1221.    FUNCTION
  1222.     This command will halt a play command.  The laser will seek to zero,
  1223.     and the drive activity light will go out.
  1224.  
  1225.     Any running audio commands (CDTV_PLAY#?) must be aborted via
  1226.     AbortIO() before this command is used.
  1227.  
  1228.    EXAMPLE
  1229.  
  1230.    NOTES
  1231.  
  1232.    BUGS
  1233.  
  1234.    SEE ALSO
  1235.     AbortIO()
  1236. cdtv.device/CDTV_SUBQLSN                             cdtv.device/CDTV_SUBQLSN
  1237.  
  1238.    NAME
  1239.     CDTV_SUBQLSN -- Report current disc position and status, LSN format.
  1240.  
  1241.    IO REQUEST
  1242.     io_Command    CDTV_SUBQLSN
  1243.     io_Data        pointer to CDSubQ structure
  1244.     io_Length    0
  1245.     io_Offset    0
  1246.  
  1247.    RESULTS
  1248.  
  1249.    FUNCTION
  1250.     This command reports the current SubQ channel information.  io_Data
  1251.     points to a CDSubQ structure to be filled by the driver.
  1252.  
  1253.     The fields in the CDSubQ structure are:
  1254.  
  1255.     Status        current drive/disc status (see below)
  1256.     AddrCtrl    SubQ bits (see below)
  1257.     Track        current track
  1258.     Index        current index within track
  1259.     DiskPosition    current position relative to start of disc, LSN fmt.
  1260.     TrackPosition    current position relative to start of current track,
  1261.             LSN format
  1262.     ValidUPC    indicates detection of a UPC/ISRC code (see below)
  1263.  
  1264.    STATUS
  1265.     The Status field is numeric, and can have the following values:
  1266.  
  1267.     SQSTAT_NOTVALID    this SubQ report is not valid
  1268.     SQSTAT_PLAYING    drive is currently playing CD audio
  1269.     SQSTAT_PAUSED    drive is currently paused
  1270.     SQSTAT_DONE    most recent play command completed successfully
  1271.     SQSTAT_ERROR    most recent play command generated an error
  1272.     SQSTAT_NOSTAT    no status available; this report is invalid
  1273.  
  1274.     This field must be sanity-checked.
  1275.  
  1276.    ADDRCTRL
  1277.     The lower four bits of the AddrCtrl field are status bits.  Their
  1278.     meanings are:
  1279.  
  1280.     ADRCTLF_PREEMPH    this track has pre-emphasis
  1281.     ADRCTLF_COPY    this track may be digitally copied (we have never
  1282.             observed this bit to be set :-).  In no case is CD
  1283.             digital audio data readable by the Amiga)
  1284.     ADRCTLF_DATA    this track is CD-ROM data (as opposed to audio)
  1285.     ADRCTLF_4CHAN    this track contains 4-channel sound
  1286.  
  1287.     The upper four bits of the AddrCtrl field are numeric.  The possible
  1288.     values are:
  1289.  
  1290.     ADRCTL_NOMODE    no mode info available; this report is invalid
  1291.     ADRCTL_POSITION    this report contains position information
  1292.     ADRCTL_MEDIACAT    this report contains a UPC code
  1293.     ADRCTL_ISRC    this report contains an ISRC number
  1294.  
  1295.     This entire field must be sanity-checked.
  1296.  
  1297.    VALIDUPC
  1298.     The ValidUPC field contains status bits.  They are:
  1299.  
  1300.     SQUPCB_VALID    UPC/ISRC code detected
  1301.     SQUPCB_ISRC    set == ISRC detected; clear == UPC detected
  1302.  
  1303.  
  1304.    EXAMPLE
  1305.  
  1306.    NOTES
  1307.     It is STRONGLY recommended that you perform massive sanity checks on
  1308.     the SubQ information before assuming it is correct.  Check that the
  1309.     Status and AddrCtrl fields both indicate that you have received
  1310.     valid data, and that the DiskPosition field represents a valid
  1311.     position.
  1312.  
  1313.    BUGS
  1314.     Even after passing massive sanity checks, the drive may still hand
  1315.     you bogus SubQ data.  Sigh...
  1316.  
  1317.     The current drive will go severely south if you feed SubQ requests
  1318.     too rapidly.  Try to keep it down below 20 requests per second.
  1319.  
  1320.     The current drive does not report UPC or ISRC codes correctly.
  1321.  
  1322.    SEE ALSO
  1323.     CDTV_SUBQMSF
  1324. cdtv.device/CDTV_SUBQMSF                             cdtv.device/CDTV_SUBQMSF
  1325.  
  1326.    NAME
  1327.     CDTV_SUBQMSF -- Report current disc position and status, MSF format.
  1328.  
  1329.    IO REQUEST
  1330.     io_Command    CDTV_SUBQMSF
  1331.     io_Data        pointer to CDSubQ structure
  1332.     io_Length    0
  1333.     io_Offset    0
  1334.  
  1335.    RESULTS
  1336.  
  1337.    FUNCTION
  1338.     This command reports the current SubQ channel information.  This
  1339.     command is identical to CDTV_SUBQLSN, except that the position
  1340.     information in the CDSubQ structure is expressed in MSF format.
  1341.  
  1342.     For more details, see CDTV_SUBQLSN.
  1343.  
  1344.    SEE ALSO
  1345.     CDTV_SUBQLSN
  1346. cdtv.device/CDTV_TOCLSN                               cdtv.device/CDTV_TOCLSN
  1347.  
  1348.    NAME
  1349.     CDTV_TOCLSN -- Report disc's table of contents, LSN format
  1350.  
  1351.    IO REQUEST
  1352.     io_Command    CDTV_TOCLSN
  1353.     io_Data        pointer to array of CDTOC structures
  1354.     io_Length    number of CDTOC entries to be fetched
  1355.     io_Offset    track number at which to start (0 == volume summary)
  1356.  
  1357.    RESULTS
  1358.     io_Actual    highest track number written to array (does not
  1359.             include volume summary, if requested)
  1360.  
  1361.    FUNCTION
  1362.     This command returns the table of contents of the disc currently in
  1363.     the drive.  The data is expressed in LSN format.
  1364.  
  1365.     The io_Data field points to an array of CDTOC structures to receive
  1366.     the TOC data.
  1367.  
  1368.     The io_Length field specifies the total number of entries to be
  1369.     fetched.  The CDTOC array must be at least this many elements in
  1370.     size.
  1371.  
  1372.     The io_Offset field specifies the track number at which to start
  1373.     gathering TOC data.  If it is set to zero, the first TOC entry will
  1374.     contain a volume summary (see below).
  1375.  
  1376.     It may take the drive up to four seconds to read the TOC upon disc
  1377.     insertion.  If the TOC is not yet available, or there is no disc in
  1378.     the drive, an error will be returned.
  1379.  
  1380.    CDTOC
  1381.     For ordinary tracks, the CDTOC entries will contain the following:
  1382.  
  1383.     AddrCtrl    SubQ flags describing track type
  1384.     Track        track number
  1385.     LastTrack    -na-
  1386.     Position    location of the start of the track, LSN format
  1387.  
  1388.     If a volume summary is requested, then the first entry in the array
  1389.     is interpreted differently.  It will describe the entire disc, and
  1390.     will contain the following:
  1391.  
  1392.     AddrCtrl    -na-
  1393.     Track        first track number
  1394.     LastTrack    last track number
  1395.     Position    location of the lead-out (end of disc), LSN format
  1396.  
  1397.    EXAMPLE
  1398.     /*  Read Table Of Contents with volume summary  */
  1399.     struct CDTOC    tocarray[100];
  1400.  
  1401.     ior->io_Command    = CDTV_TOCLSN;
  1402.     ior->io_Offset    = 0;    /*  Gimme summary  */
  1403.     ior->io_Length    = 100;    /*  Max 99 tracks + summary  */
  1404.     ior->io_Data    = tocarray;
  1405.     DoIO (ior);
  1406.  
  1407.     if (!ior->io_Error) {
  1408.         firsttrack    = tocarray[0].Track;
  1409.         lasttrack    = tocarray[0].LastTrack;
  1410.         /*
  1411.          * Compute total length of disc.  This is the location of
  1412.          * the lead-out, minus the start of the first track (which
  1413.          * is not always zero).
  1414.          */
  1415.         totalsectors    = tocarray[0].Position.LSN -
  1416.                   tocarray[1].Position.LSN;
  1417.     }
  1418.  
  1419.    NOTES
  1420.  
  1421.    BUGS
  1422.  
  1423.    SEE ALSO
  1424.     CDTV_TOCMSF
  1425. cdtv.device/CDTV_TOCMSF                               cdtv.device/CDTV_TOCMSF
  1426.  
  1427.    NAME
  1428.     CDTV_TOCMSF -- Report disc's table of contents, MSF format
  1429.  
  1430.    IO REQUEST
  1431.     io_Command    CDTV_TOCMSF
  1432.     io_Data        pointer to array of CDTOC structures
  1433.     io_Length    number of CDTOC entries to be fetched
  1434.     io_Offset    track number at which to start (0 == volume summary)
  1435.  
  1436.    RESULTS
  1437.     io_Actual    highest track number written to array (does not
  1438.             include volume summary, if requested)
  1439.  
  1440.    FUNCTION
  1441.     This command returns the table of contents of the disc currently in
  1442.     the drive.  This command is identical to CDTV_TOCLSN, except that
  1443.     the position data in the CDTOC structures is expressed in MSF
  1444.     format.
  1445.  
  1446.     For more details, see CDTV_TOCLSN.
  1447.  
  1448.    EXAMPLE
  1449.  
  1450.    NOTES
  1451.  
  1452.    BUGS
  1453.  
  1454.    SEE ALSO
  1455.     CDTV_TOCLSN
  1456. cdtv.device/CDTV_WRITE                                 cdtv.device/CDTV_WRITE
  1457.  
  1458.    NAME
  1459.     CDTV_WRITE -- Writes data to a CD-ROM.
  1460.  
  1461.    FUNCTION
  1462.     This command writes data to the CD-ROM at the current seek position.
  1463.     Note that reading the data back might be difficult...
  1464.  
  1465.    RESULTS
  1466.     The line voltage is switched through to the laser, causing it to go
  1467.     PHWATTTT!!! and burn enormous holes in the CD-ROM, through the
  1468.     top of the case, and through whatever stereo component happens to be
  1469.     on top of the CDTV.
  1470.  
  1471.     We recommend invoking this command if you detect that a CD-I or MPC
  1472.     player has been placed on top of the CDTV.
  1473.  
  1474.     Invoking this command voids the warranty.
  1475.  
  1476.    SERIOUSLY
  1477.     This command always returns CDERR_WRITEPROT (disc is write-
  1478.     protected).
  1479.  
  1480.    SEE ALSO
  1481.     CDTV_READ (much more useful)
  1482. cdtv.device/CloseDevice                               cdtv.device/CloseDevice
  1483.  
  1484.    NAME
  1485.     CloseDevice -- Terminate access to cdtv.device.
  1486.  
  1487.    SYNOPSIS
  1488.     CloseDevice (ior);
  1489.              A1
  1490.  
  1491.     struct IOStdReq    *ior;
  1492.  
  1493.    FUNCTION
  1494.     This function terminates access to the cdtv.device.  'ior' points to
  1495.     a IOStdReq structure that was initialized by OpenDevice().
  1496.  
  1497.     After calling CloseDevice(), 'ior' may no longer be used to send
  1498.     commands to cdtv.device.
  1499.  
  1500.    INPUTS
  1501.     ior    - pointer to an IOStdReq structure
  1502.  
  1503.    RESULT
  1504.     The io_Device and io_Unit fields of the IOStdReq structure are
  1505.     invalidated.
  1506.  
  1507.    NOTES
  1508.  
  1509.    BUGS
  1510.  
  1511.    SEE ALSO
  1512.     OpenDevice()
  1513. cdtv.device/OpenDevice                                 cdtv.device/OpenDevice
  1514.  
  1515.    NAME
  1516.     OpenDevice -- Open the cdtv.device for use.
  1517.  
  1518.    SYNOPSIS
  1519.     error = OpenDevice ("cdtv.device", unit, ior, flags);
  1520.      D0                      A0         D0   A1    D1
  1521.  
  1522.     LONG        error;
  1523.     LONG        unit;
  1524.     struct IOStdReq    *ior;
  1525.     LONG        flags;
  1526.  
  1527.    FUNCTION
  1528.     This call opens the cdtv.device and makes it available for use.
  1529.     The 'unit' and 'flags' parameters to OpenDevice() should be set to
  1530.     zero for future compatibility.
  1531.  
  1532.    INPUTS
  1533.     unit    - 0
  1534.     ior    - pointer to IOStdReq structure
  1535.     flags    - 0
  1536.  
  1537.    RESULT
  1538.     error    - non-zero if error, zero if opened successfully
  1539.  
  1540.     The io_Device and io_Unit fields of the IOStdReq structure are
  1541.     initialized.
  1542.  
  1543.    NOTES
  1544.     io_Device and io_Unit may be safely cloned to create multiple I/O
  1545.     requests.
  1546.  
  1547.    BUGS
  1548.  
  1549.    SEE ALSO
  1550.     CloseDevice()