CDROMIO(4S)

NAME
cdromio - CDROM control operations

DESCRIPTION

The Sun CDROM device driver supports a set of ioctl(2) commands for audio operations and CDROM specific operations. It also supports the dkio(4S) operations — generic disk control operation for all Sun disk drivers. See dkio(4S) Basic to these cdromio ioctl() requests are the definitions in <scsi/targets/srdef.h> or <sundev/srreg.h>

/*
 * CDROM I/O controls type definitions
 */
/* definition of play audio msf structure */
struct cdrom_msf {
	unsigned char	cdmsf_min0;	/* starting minute */
	unsigned char	cdmsf_sec0;	/* starting second */
	unsigned char	cdmsf_frame0;	/* starting frame  */
	unsigned char	cdmsf_min1;	/* ending minute   */
	unsigned char	cdmsf_sec1;	/* ending second   */
	unsigned char	cdmsf_frame1;	/* ending frame	   */
};
/* definition of play audio track/index structure */
struct cdrom_ti {
	unsigned char	cdti_trk0;	/* starting track */
	unsigned char	cdti_ind0;	/* starting index */
	unsigned char	cdti_trk1;	/* ending track */
	unsigned char	cdti_ind1;	/* ending index */
};
/* definition of read toc header structure */
struct cdrom_tochdr {
	unsigned char	cdth_trk0;	/* starting track */
	unsigned char	cdth_trk1;	/* ending track */
};
/* definition of read toc entry structure */
struct cdrom_tocentry {
	unsigned char	cdte_track;
	unsigned char	cdte_adr	:4;
	unsigned char	cdte_ctrl	:4;
	unsigned char	cdte_format;
	union {
		struct {
			unsigned char	minute;
			unsigned char	second;
			unsigned char	frame;
		} msf;
		int	lba;
	} cdte_addr;
	unsigned char	cdte_datamode;
};
/*
 * Bitmask for CDROM data track in the cdte_ctrl field
 * A track is either data or audio.
 */
#define CDROM_DATA_TRACK	0x04
/*
 * CDROM address format definition, for use with struct cdrom_tocentry
 */
#define CDROM_LBA	0x01
#define CDROM_MSF	0x02
/*
 * For CDROMREADTOCENTRY, set the cdte_track to CDROM_LEADOUT to get
 * the information for the leadout track.
 */
#define CDROM_LEADOUT	0xAA
struct cdrom_subchnl {
	unsigned char	cdsc_format;
	unsigned char	cdsc_audiostatus;
	unsigned char	cdsc_adr:	4;
	unsigned char	cdsc_ctrl:	4;
	unsigned char	cdsc_trk;
	unsigned char	cdsc_ind;
	union {
		struct {
			unsigned char	minute;
			unsigned char	second;
			unsigned char	frame;
		} msf;
		int	lba;
	} cdsc_absaddr;
	union {
		struct {
			unsigned char	minute;
			unsigned char	second;
			unsigned char	frame;
		} msf;
		int	lba;
	} cdsc_reladdr;
};
/*
 * Definition for audio status returned from Read Sub-channel
 */
#define CDROM_AUDIO_INVALID     0x00    /* audio status not supported */
#define CDROM_AUDIO_PLAY        0x11    /* audio play operation in progress */
#define CDROM_AUDIO_PAUSED      0x12    /* audio play operation paused */
#define CDROM_AUDIO_COMPLETED   0x13    /* audio play successfully completed */
#define CDROM_AUDIO_ERROR       0x14    /* audio play stopped due to error */
#define CDROM_AUDIO_NO_STATUS   0x15    /* no current audio status to return */
/* definition of audio volume control structure */
struct cdrom_volctrl {
	unsigned char	cdvc_chnl0;
	unsigned char	cdvc_chnl1;
	unsigned char	cdvc_chnl2;
	unsigned char	cdvc_chnl3;
};
struct cdrom_read {
        int     cdread_lba;
        caddr_t cdread_bufaddr;
        int     cdread_buflen;
};
#define CDROM_MODE1_SIZE        2048
#define CDROM_MODE2_SIZE        2336
/*
 * CDROM I/O control commands
 */
#define CDROMPAUSE   _IO(c, 10)   /* Pause Audio Operation */
#define CDROMRESUME  _IO(c, 11)	  /* Resume paused Audio Operation */
#define CDROMPLAYMSF _IOW(c, 12, struct cdrom_msf)     /* Play Audio MSF */
#define CDROMPLAYTRKIND  _IOW(c, 13, struct cdrom_ti)  /* Play Audio Trk/ind */
#define CDROMREADTOCHDR  _IOR(c, 103, struct cdrom_tochdr) /* Read TOC hdr */
#define CDROMREADTOCENTRY _IOWR(c, 104, struct cdrom_tocentry) /* Read TOC */
#define CDROMSTOP        _IO(c, 105)               /* Stop the cdrom drive */
#define CDROMSTART       _IO(c, 106)               /* Start the cdrom drive */
#define CDROMEJECT       _IO(c, 107)               /* Ejects the cdrom caddy */
#define CDROMVOLCTRL     _IOW(c, 14, struct cdrom_volctrl) /* volume control */
#define CDROMSUBCHNL  _IOWR(c, 108, struct cdrom_subchnl) /* read subchannel */
#define CDROMREADMODE2          _IOW(c, 110, struct cdrom_read) /* mode 2 */
#define CDROMREADMODE1          _IOW(c, 111, struct cdrom_read) /* mode 1 */

The CDROMPAUSE ioctl() pauses the current audio play operation and the CDROMRESUME ioctl() resumes the paused audio play operation. The CDROMSTART ioctl() spins up the disc and seeks to the last address requested, while the CDROMSTOP ioctl() spins down the disc and the CDROMEJECT ioctl() ejects the caddy with the disc. All of the above ioctl() calls only take a file descriptor and a command as arguments. They have the form:
    ioctl(fd, cmd)
    	int	fd;
    	int	cmd;

The rest of the ioctl() calls have the form:
    ioctl(fd, cmd, ptr)
    	int	fd;
    	int	cmd;
    	char	*ptr;
where ptr is a pointer to a struct or an integer.

The CDROMPLAYMSF ioctl() command requests the drive to output the audio signals staring at the specified starting address and continue the audio play until the specified ending address is detected. The address is in MSF (minute, second, frame) format. The third argument of the function call is a pointer to the type struct cdrom_msf.

The CDROMPLAYTRKIND ioctl() command is similar to CDROMPLAYMSF. The starting and ending address is in track/index format. The third argument of the function call is a pointer to the type struct cdrom_ti.

The CDROMREADTOCHDR ioctl() command returns the header of the TOC (table of contents). The header consists of the starting tracking number and the ending track number of the disc. These two numbers are returned through a pointer of struct cdrom_tochdr. While the disc can start at any number, all tracks between the first and last tracks are in contiguous ascending order. A related ioctl() command is CDROMREADTOCENTRY. This command returns the information of a specified track. The third argument of the function call is a pointer to the type struct cdrom_tocentry. The caller need to supply the track number and the address format. This command will return a 4-bit adr field, a 4-bit ctrl field, the starting address in MSF format or LBA format, and the data mode if the track is a data track. The ctrl field specifies whether the track is data or audio. To get information for the lead-out area, supply the ioctl() command with the track field set to CDROM_LEADOUT (0xAA).

The CDROMVOLCTRL ioctl() command controls the audio output level. The SCSI command allows the control of up to 4 channels. The current implementation of the supported CDROM drive only uses channel 0 and channel 1. The valid values of volume control are between 0x00 and 0xFF, with a value of 0xFF indicating maximum volume. The third argument of the function call is a pointer to struct cdrom_volctrl which contains the output volume values.

The CDROMSUBCHNL ioctl() command reads the Q sub-channel data of the current block. The sub-channel data includes track number, index number, absolute CDROM address, track relative CDROM address, control data and audio status. All information is returned through a pointer to struct cdrom_subchnl. The caller needs to supply the address format for the returned address.

The CDROMREADMODE2 and CDROMREADMODE1 ioctl() commands are only available on SPARCstation 1 systems.

Finally, on SPARCstation 1 systems only, the driver supports the user SCSI command interface. By issuing the ioctl() command, USCSICMD, The caller can supply any SCSI-2 commands that the CDROM drive supports. The caller has to provide all the parameters in the SCSI command block, as well as other information such as the user buffer address and buffer length. See the definitions in <scsi/impl/uscsi.h>. The ioctl() call has the form:
    ioctl(fd, cmd, ptr)
    	int	fd;
    	int	cmd;
    	char	*ptr;
where ptr is a pointer to the type:
    struct uscsi_scmd {
    	caddr_t	uscsi_cdb;
    	int	uscsi_cdblen;
    	caddr_t	uscsi_bufaddr;
    	int	uscsi_buflen;
    	unsigned char	uscsi_status;
    	int	uscsi_flags;
    };

uscsi_cdb is a pointer to the SCSI command block. Group 0 cdb's are 6 bytes long while the other groups are 10 bytes or 12 bytes. uscsi_cdblen is the length of the cdb. uscsi_bufaddr is the pointer to the user buffer for parameter passing or data input/output. buflen is the length of the user buffer. uscsi_flags are the execution flags for SCSI input/output. The possible flags are USCSI_SILENT, USCSI_DIAGNOSE, USCSI_ISOLATE, USCSI_READ, and USCSI_WRITE.

FILES
/usr/include/scsi/targets/srdef.h
/usr/include/scsi/impl/uscsi.h
/usr/include/sundev/srreg.h

SEE ALSO
ioctl(2), dkio(4S), sr(4S)

BUGS

The interface to this device is preliminary and subject to change in future releases. You are encouraged to write your programs in a modular fashion so that you can easily incorporate future changes.