Wrappers for specific Multimedia Command (MMC) commands e.g., READ DISC, START/STOP UNIT. More...

#include <cdio/mmc.h>

Macros
#define	mmc_start_stop_media(c, e, i, p, t) mmc_start_stop_unit(c, e, i, p, t, 0)

Functions
driver_return_code_t	mmc_get_configuration (const CdIo_t p_cdio, void p_buf, unsigned int i_size, unsigned int i_return_type, unsigned int i_starting_feature_number, unsigned int i_timeout_ms)

driver_return_code_t	mmc_get_event_status (const CdIo_t *p_cdio, uint8_t out_buf[2])

driver_return_code_t	mmc_mode_select_10 (CdIo_t p_cdio, void p_buf, unsigned int i_size, int page, unsigned int i_timeout_ms)

driver_return_code_t	mmc_mode_sense_10 (CdIo_t p_cdio, void p_buf, unsigned int i_size, unsigned int i_page_code)

driver_return_code_t	mmc_mode_sense_6 (CdIo_t p_cdio, void p_buf, unsigned int i_size, int page)

driver_return_code_t	mmc_prevent_allow_medium_removal (const CdIo_t *p_cdio, bool b_persistent, bool b_prevent, unsigned int i_timeout_ms)

driver_return_code_t	mmc_read_cd (const CdIo_t p_cdio, void p_buf, lsn_t i_lsn, int expected_sector_type, bool b_digital_audio_play, bool b_sync, uint8_t header_codes, bool b_user_data, bool b_edc_ecc, uint8_t c2_error_information, uint8_t subchannel_selection, uint16_t i_blocksize, uint32_t i_blocks)

driver_return_code_t	mmc_read_disc_information (const CdIo_t p_cdio, void p_buf, unsigned int i_size, cdio_mmc_read_disc_info_datatype_t data_type, unsigned int i_timeout_ms)

driver_return_code_t	mmc_set_speed (const CdIo_t *p_cdio, int i_Kbs_speed, unsigned int i_timeout_ms)

driver_return_code_t	mmc_start_stop_unit (const CdIo_t *p_cdio, bool b_eject, bool b_immediate, uint8_t power_condition, unsigned int i_timeout_ms)

driver_return_code_t	mmc_test_unit_ready (const CdIo_t *p_cdio, unsigned int i_timeout_ms)

driver_return_code_t	mmc_read_subchannel (const CdIo_t p_cdio, track_t i_track, unsigned char sub_chan_param, unsigned int i_length, char *p_buf, unsigned int i_timeout_ms)

driver_return_code_t	mmc_read_toc_cdtext (const CdIo_t p_cdio, unsigned int i_length, unsigned char *p_buf, unsigned int i_timeout_ms)

Detailed Description

Wrappers for specific Multimedia Command (MMC) commands e.g., READ DISC, START/STOP UNIT.

The documents we make use of are described in several specifications made by the SCSI committee T10 http://www.t10.org. In particular, SCSI Primary Commands (SPC), SCSI Block Commands (SBC), and Multi-Media Commands (MMC). These documents generally have a numeric level number appended. For example SPC-3 refers to ``SCSI Primary Commands - 3'.

In year 2010 the current versions were SPC-3, SBC-2, MMC-5.

Macro Definition Documentation

◆ mmc_start_stop_media

#define mmc_start_stop_media	(	c,
		e,
		i,
		p,
		t
	)	mmc_start_stop_unit(c, e, i, p, t, 0)

Function Documentation

◆ mmc_get_configuration()

driver_return_code_t mmc_get_configuration	(	const CdIo_t *	p_cdio,
		void *	p_buf,
		unsigned int	i_size,
		unsigned int	i_return_type,
		unsigned int	i_starting_feature_number,
		unsigned int	i_timeout_ms
	)

Get drive capabilities via SCSI-MMC GET CONFIGURATION

Parameters

p_cdio	the CD object to be acted upon.
p_buf	pointer to location to store mode sense information
i_size	number of bytes allocated to p_buf
i_return_type	value in range 0..2 giving what kind of configuration to return:

0 — Full Header and Full Descriptors;
1 — Feature Headers and those with their Current Bit.
2 — One Feature header and zero or one Feature Descriptors.

Parameters

i_starting_feature_number	feature number from which to start getting information.
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in mmc_timeout_ms.

Returns: DRIVER_OP_SUCCESS (0) if we got the status. return codes are the same as driver_return_code_t

◆ mmc_get_event_status()

driver_return_code_t mmc_get_event_status	(	const CdIo_t *	p_cdio,
		uint8_t	out_buf[2]
	)

Return results of media event status via SCSI-MMC GET EVENT STATUS

Parameters

p_cdio	the CD object to be acted upon.
out_buf	media status code from operation

Returns: DRIVER_OP_SUCCESS (0) if we got the status. Return codes are the same as driver_return_code_t

◆ mmc_mode_select_10()

driver_return_code_t mmc_mode_select_10	(	CdIo_t *	p_cdio,
		void *	p_buf,
		unsigned int	i_size,
		int	page,
		unsigned int	i_timeout_ms
	)

Run a SCSI-MMC MODE SELECT (10-byte) command and put the results in p_buf.

Parameters

p_cdio	the CD object to be acted upon.
p_buf	pointer to location to store mode sense information
i_size	number of bytes allocated to p_buf
page	which "page" of the mode sense command we are interested in
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in mmc_timeout_ms.

Returns: DRIVER_OP_SUCCESS if we ran the command ok.

◆ mmc_mode_sense_10()

driver_return_code_t mmc_mode_sense_10	(	CdIo_t *	p_cdio,
		void *	p_buf,
		unsigned int	i_size,
		unsigned int	i_page_code
	)

Run a SCSI-MMC MODE SENSE command (10-byte version) and put the results in p_buf.

Parameters

p_cdio	the CD object to be acted upon.
p_buf	pointer to location to store mode sense information
i_size	number of bytes allocated to p_buf
i_page_code	which "page" of the mode sense command we are interested in

Returns: DRIVER_OP_SUCCESS if we ran the command ok.

◆ mmc_mode_sense_6()

driver_return_code_t mmc_mode_sense_6	(	CdIo_t *	p_cdio,
		void *	p_buf,
		unsigned int	i_size,
		int	page
	)

Run a SCSI-MMC MODE SENSE command (6-byte version) and put the results in p_buf.

Parameters

p_cdio	the CD object to be acted upon.
p_buf	pointer to location to store mode sense information
i_size	number of bytes allocated to p_buf
page	which "page" of the mode sense command we are interested in

Returns: DRIVER_OP_SUCCESS if we ran the command ok.

◆ mmc_prevent_allow_medium_removal()

driver_return_code_t mmc_prevent_allow_medium_removal	(	const CdIo_t *	p_cdio,
		bool	b_persistent,
		bool	b_prevent,
		unsigned int	i_timeout_ms
	)

Request preventing/allowing medium removal on a drive via SCSI-MMC PREVENT/ALLOW MEDIUM REMOVAL.

Parameters

p_cdio	the CD object to be acted upon.
b_persistent	make b_prevent state persistent
b_prevent	true of drive locked and false if unlocked
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in mmc_timeout_ms.

Returns: DRIVER_OP_SUCCESS (0) if we got the status. return codes are the same as driver_return_code_t

◆ mmc_read_cd()

driver_return_code_t mmc_read_cd	(	const CdIo_t *	p_cdio,
		void *	p_buf,
		lsn_t	i_lsn,
		int	expected_sector_type,
		bool	b_digital_audio_play,
		bool	b_sync,
		uint8_t	header_codes,
		bool	b_user_data,
		bool	b_edc_ecc,
		uint8_t	c2_error_information,
		uint8_t	subchannel_selection,
		uint16_t	i_blocksize,
		uint32_t	i_blocks
	)

Issue a MMC READ_CD command.

Parameters

p_cdio	object to read from
p_buf	Place to store data. The caller should ensure that `p_buf` can hold at least `i_blocksize` * `i_blocks` bytes.
i_lsn	sector to read
expected_sector_type	restricts reading to a specific CD sector type. Only 3 bits with values 1-5 are used: 0 — all sector types 1 — CD-DA sectors only 2 — Mode 1 sectors only 3 — Mode 2 formless sectors only. Note in contrast to all other values an MMC CD-ROM is not required to support this mode. 4 — Mode 2 Form 1 sectors only 5 — Mode 2 Form 2 sectors only
b_digital_audio_play	Control error concealment when the data being read is CD-DA. If the data being read is not CD-DA, this parameter is ignored. If the data being read is CD-DA and DAP is false zero, then the user data returned should not be modified by flaw obscuring mechanisms such as audio data mute and interpolate. If the data being read is CD-DA and DAP is true, then the user data returned should be modified by flaw obscuring mechanisms such as audio data mute and interpolate.

b_sync_header return the sync header (which will probably have the same value as CDIO_SECTOR_SYNC_HEADER of size CDIO_CD_SYNC_SIZE).

Parameters

header_codes Header Codes refer to the sector header and the sub-header that is present in mode 2 formed sectors:

0 — No header information is returned.
1 — The 4-byte sector header of data sectors is be returned,
2 — The 8-byte sector sub-header of mode 2 formed sectors is returned.
3 &mdash Both sector header and sub-header (12 bytes) is returned.

The Header preceeds the rest of the bytes (e.g. user-data bytes) that might get returned.

Parameters

b_user_data Return user data if true.

For CD-DA, the User Data is CDIO_CD_FRAMESIZE_RAW bytes.

For Mode 1, The User Data is ISO_BLOCKSIZE bytes beginning at offset CDIO_CD_HEADER_SIZE+CDIO_CD_SUBHEADER_SIZE.

For Mode 2 formless, The User Data is M2RAW_SECTOR_SIZE bytes beginning at offset CDIO_CD_HEADER_SIZE+CDIO_CD_SUBHEADER_SIZE.

For data Mode 2, form 1, User Data is ISO_BLOCKSIZE bytes beginning at offset CDIO_CD_XA_SYNC_HEADER.

For data Mode 2, form 2, User Data is 2 groups of 324 bytes beginning at offset CDIO_CD_XA_SYNC_HEADER.

Parameters

b_sync
b_edc_ecc	true if we return EDC/ECC error detection/correction bits.

The presence and size of EDC redundancy or ECC parity is defined according to sector type:

CD-DA sectors have neither EDC redundancy nor ECC parity.

Data Mode 1 sectors have 288 bytes of EDC redundancy, Pad, and ECC parity beginning at offset 2064.

Data Mode 2 formless sectors have neither EDC redundancy nor ECC parity

Data Mode 2 form 1 sectors have 280 bytes of EDC redundancy and ECC parity beginning at offset 2072

Data Mode 2 form 2 sectors optionally have 4 bytes of EDC redundancy beginning at offset 2348.

Parameters

c2_error_information	If true associate a bit with each sector for C2 error The resulting bit field is ordered exactly as the main channel bytes. Each 8-bit boundary defines a byte of flag bits.
subchannel_selection	subchannel-selection bits

0 — No Sub-channel data shall be returned. (0 bytes)
1 — RAW P-W Sub-channel data shall be returned. (96 byte)
2 — Formatted Q sub-channel data shall be transferred (16 bytes)
3 — Reserved
4 — Corrected and de-interleaved R-W sub-channel (96 bytes)
5-7 — Reserved

Parameters

i_blocksize	size of the a block expected to be returned
i_blocks	number of blocks expected to be returned.

Returns: DRIVER_OP_SUCCESS if we ran the command ok.

◆ mmc_read_disc_information()

driver_return_code_t mmc_read_disc_information	(	const CdIo_t *	p_cdio,
		void *	p_buf,
		unsigned int	i_size,
		cdio_mmc_read_disc_info_datatype_t	data_type,
		unsigned int	i_timeout_ms
	)

Request information about et drive capabilities via SCSI-MMC READ DISC INFORMATION

Parameters

p_cdio	the CD object to be acted upon.
p_buf	pointer to location to store mode sense information
i_size	number of bytes allocated to p_buf
data_type	kind of information to retrieve.
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in mmc_timeout_ms.

Returns: DRIVER_OP_SUCCESS (0) if we got the status.

◆ mmc_read_subchannel()

driver_return_code_t mmc_read_subchannel	(	const CdIo_t *	p_cdio,
		track_t	i_track,
		unsigned char	sub_chan_param,
		unsigned int *	i_length,
		char *	p_buf,
		unsigned int	i_timeout_ms
	)

Issue a READ SUB-CHANNEL command to read current position, ISRC or MCN from subchannel Q. Note: READ SUB-CHANNEL is deprecated as of MMC-5 but the alternative requires manual parsing of the subchannel.

Parameters

p_cdio	the CD object to be acted upon.
i_track	track number (only for ISRC)
sub_chan_param	1 for CD current position, 2 for `MCN`, 3 for `ISRC`
i_length	pointer to number of bytes to request. Will be overwritten by the number of bytes available.
p_buf	pointer to the location for the returned data
i_timeout_ms	numober of milliseconds to wait for command completion

Returns: DRIVER_OP_SUCCESS on success

◆ mmc_read_toc_cdtext()

driver_return_code_t mmc_read_toc_cdtext	(	const CdIo_t *	p_cdio,
		unsigned int *	i_length,
		unsigned char *	p_buf,
		unsigned int	i_timeout_ms
	)

Issue a READ TOC/PMA/ATIP command to read the CD-TEXT from R-W sub-channel.

On a successful return (when DRIVER_OP_SUCCESS is returned), pbuf contains the raw SCSI/MMC reply as retrieved by mmc_read_toc_cdtext().

The first two bytes of the header, a Big-Endian number, specifies the number of following bytes. The count also includes the next two header bytes which should be 0. See also Table 495, of the MMC-5 specification.

Here is code that can be used to get the number of text packs:

#include <cdio/mmc.h>

CDIO_MMC_GET_LEN16(p_buf) - 2

and start of the text packs is at:

p_buf + 4

The number of bytes returned is limited by the value in parameter *i_length. which should tell the byte capacity of p_buf. The maximum size according to specification is 4 + 8 * 256 * 18 = 36,864 bytes.

Instead of retrieving everything in one go by allocating the maximum possible value in the passed-in *p_buf, another approach is to first get the header bytes in a small p_buf, then re-allocate the buffer using the length given by CDIO_MMC_GET_LEN16(p_buf) + 2 (bytes), and then to call mmc_read_toc_cdtext() again with *i_length set to this size.

Parameters

p_cdio	the CD object to be acted upon.
i_length	pointer to number of bytes to request. Will be overwritten by the number of bytes available.
p_buf	pointer to the location for the returned data
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in `mmc_timeout_ms`.

Returns: DRIVER_OP_SUCCESS on success

◆ mmc_set_speed()

driver_return_code_t mmc_set_speed	(	const CdIo_t *	p_cdio,
		int	i_Kbs_speed,
		unsigned int	i_timeout_ms
	)

Set the drive speed in K bytes per second using SCSI-MMC SET SPEED.

Parameters

p_cdio	CD structure set by cdio_open().
i_Kbs_speed	speed in K bytes per second. Note this is not in standard CD-ROM speed units, e.g. 1x, 4x, 16x as it is in cdio_set_speed. To convert CD-ROM speed units to Kbs, multiply the number by 176 (for raw data) and by 150 (for filesystem data). Also note that ATAPI specs say that a value less than 176 will result in an error. On many CD-ROM drives, specifying a value too large will result in using the fastest speed.
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in mmc_timeout_ms.

Returns: the drive speed if greater than 0. -1 if we had an error. is -2 returned if this is not implemented for the current driver.

See also: cdio_set_speed and mmc_set_drive_speed

◆ mmc_start_stop_unit()

driver_return_code_t mmc_start_stop_unit	(	const CdIo_t *	p_cdio,
		bool	b_eject,
		bool	b_immediate,
		uint8_t	power_condition,
		unsigned int	i_timeout_ms
	)

Load or Unload media using a MMC START STOP UNIT command.

Parameters

p_cdio	the CD object to be acted upon.
b_eject	eject if true and close tray if false
b_immediate	wait or don't wait for operation to complete
power_condition	Set CD-ROM to idle/standby/sleep. If nonzero, eject/load is ignored, so set to 0 if you want to eject or load.
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in mmc_timeout_ms.

Returns: DRIVER_OP_SUCCESS if we ran the command ok.

See also: mmc_eject_media or mmc_close_tray

◆ mmc_test_unit_ready()

driver_return_code_t mmc_test_unit_ready	(	const CdIo_t *	p_cdio,
		unsigned int	i_timeout_ms
	)

Check if drive is ready using SCSI-MMC TEST UNIT READY command.

Parameters

p_cdio	the CD object to be acted upon.
i_timeout_ms	value in milliseconds to use on timeout. Setting to 0 uses the default time-out value stored in `mmc_timeout_ms`.

Returns: DRIVER_OP_SUCCESS if we ran the command ok.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ mmc_start_stop_media

Function Documentation

◆ mmc_get_configuration()

◆ mmc_get_event_status()

◆ mmc_mode_select_10()

◆ mmc_mode_sense_10()

◆ mmc_mode_sense_6()

◆ mmc_prevent_allow_medium_removal()

◆ mmc_read_cd()

◆ mmc_read_disc_information()

◆ mmc_read_subchannel()

◆ mmc_read_toc_cdtext()

◆ mmc_set_speed()

◆ mmc_start_stop_unit()

◆ mmc_test_unit_ready()