Go over documentation yet again. In particular:
Move section on image formats out of Appendix and expand. Add a chapter on program internals glossary: add item to concept index and regularize index names.
This commit is contained in:
rocky
@@ -3,6 +3,7 @@ See also @uref{http://www.dvdrhelp.com/glossary}.
|
||||
@table @acronym
|
||||
|
||||
@item ASPI
|
||||
@cindex ASPI
|
||||
See @acronym{Win32 ASPI}
|
||||
|
||||
@item ATAPI
|
||||
@@ -17,20 +18,22 @@ devices to the IDE/EIDE connections.
|
||||
|
||||
A CD-image format developed by Jeff Arnold for CDRWIN software on
|
||||
Microsoft Windows. Many other programs subsequently support using this
|
||||
format. The .CUE file is a text file which contains CD format and
|
||||
track layout information, while the .BIN file holds the actual data of
|
||||
each track.
|
||||
format. The @code{.CUE} file is a text file which contains CD format
|
||||
and track layout information, while the @code{.BIN} file holds the
|
||||
actual data of each track.
|
||||
|
||||
@item CD
|
||||
Compact Disc
|
||||
|
||||
@item CD-DA
|
||||
@cindex CD-DA
|
||||
Compact Disc Digital Audio, described in the ``Red Book'' or ICE
|
||||
908. This commonly referred to as an audio @acronym{CD} and what most
|
||||
people think of when you play a @acronym{CD} as it was the first to
|
||||
use the @acronym{CD} medium.
|
||||
|
||||
@item CD+G
|
||||
@cindex CD+G
|
||||
|
||||
Compact Disc + Graphics. An extension of the CD audio format contains
|
||||
a limited amount of graphics in subcode channels. This disc works in
|
||||
@@ -38,6 +41,8 @@ all audio players but the graphics portion is only available in a
|
||||
special CD+G or Karaoke player.
|
||||
|
||||
@item CD-i
|
||||
@cindex CD-i
|
||||
|
||||
Compact Disc Interactive. An extension of the CD format designed
|
||||
around a set-top computer that connects to a TV to provide interactive
|
||||
home entertainment, including digital audio and video, video games,
|
||||
@@ -46,11 +51,14 @@ and software applications. Defined by the ``Green Book'' standard.
|
||||
largely (if not totally) been superceded by VCDs.
|
||||
|
||||
@item CD-i Bridge
|
||||
@cindex CD-i Bridge
|
||||
|
||||
A standard allowing CD-ROM XA discs to play on CD-i. Kodak PhotoCDs
|
||||
are CD-XA Bridge discs.
|
||||
|
||||
@item CD-ROM
|
||||
@cindex CD-ROM
|
||||
|
||||
Compact Disc Read Only Memory or ``Yellow Book'' describe in Standards
|
||||
ISO/IEC 10149. The data stored on it can be either in the form of
|
||||
audio, computer or video files.
|
||||
@@ -64,6 +72,8 @@ layer. CD-ROM/XA An expansion of the CD-ROM Mode 2 format that allows
|
||||
both computer and audio/video to be mixed in the same track.
|
||||
|
||||
@item CD Text
|
||||
@cindex CD Text
|
||||
|
||||
CD Text is a technology developed by Sony Corporation and Philips
|
||||
Electronics in 1996 that allows storing in an audio CD and its tracks
|
||||
information such as artist name, title, songwriter, composer, or
|
||||
@@ -71,6 +81,8 @@ arranger. Commercially available audio CDs sometimes contain CD Text
|
||||
information.
|
||||
|
||||
@item CD XA
|
||||
@cindex CD XA
|
||||
|
||||
CD-ROM EXtended Architecture. A modification to the CD-ROM
|
||||
specification that defines two new types of sectors. CD-ROM XA was
|
||||
developed jointly by Sony, Philips, and Microsoft, and announced in
|
||||
@@ -90,15 +102,22 @@ its own `Green Book' file system only resembles ISO 9660 and isn't
|
||||
fully compatible.
|
||||
|
||||
@item FSF
|
||||
@cindex FSF
|
||||
|
||||
Free Software Foundation, @uref{http://www.fsf.org/}
|
||||
|
||||
@item GNU
|
||||
@cindex GNU
|
||||
|
||||
@acronym{GNU} is not @acronym{UNIX}, @uref{http://www.gnu.org/}
|
||||
|
||||
@item ISO
|
||||
@cindex ISO
|
||||
|
||||
International Standards Organization.
|
||||
|
||||
@item ISO 9660
|
||||
@cindex ISO 9660
|
||||
|
||||
The ISO 9660 is an operating-system independent filesystem format for
|
||||
CD-ROM media and DVD-ROMs. It was standardized in 1988 and replaced the
|
||||
@@ -119,6 +138,7 @@ is the European specification which is identical to ISO 9660.
|
||||
ISO 13490 is basically ISO 9660 with multisession support.
|
||||
|
||||
@item Joliet extensions
|
||||
@cindex Joliet extensions
|
||||
|
||||
This ISO-9660 upward-compatible standard was developed for Windows 95
|
||||
and Windows NT by Microsoft as an extension of ISO 9600 which allows
|
||||
@@ -129,6 +149,7 @@ See @uref{http://bmrc.berkeley.edu/people/chaffee/jolspec.html} for
|
||||
the Joliet Specification.
|
||||
|
||||
@item LBA
|
||||
@cindex LBA
|
||||
|
||||
Logical Block Addressing. Mapped integer numbers from CD Red Book
|
||||
Addressing MSF. The starting sector is -150 and ending sector is
|
||||
@@ -137,6 +158,7 @@ Because an LBA is a single number it is often easier to work with in
|
||||
programming than an MSF.
|
||||
|
||||
@item Lead in
|
||||
@cindex lead in
|
||||
|
||||
The area of a CD where the Table Of Contents (TOC) and CDTEXT are
|
||||
stored. I think it is supposed to be around 4500 (1 min) or more
|
||||
@@ -146,6 +168,7 @@ indicated by the ATIP start of lead-in position that is recorded in
|
||||
the ATIP groove on the disk.
|
||||
|
||||
@item LSN
|
||||
@cindex LSN
|
||||
|
||||
Logical Sector Number. Mapped integer numbers from CD Red Book
|
||||
Addressing MSF. The starting sector is 0 and ending sector is 449699,
|
||||
@@ -155,13 +178,15 @@ MSF. Because it starts at 0 rather than -150 as is the case of an LBA
|
||||
it can be represented as an unsigned value.
|
||||
|
||||
@item MCN
|
||||
@cindex MCN
|
||||
|
||||
Media Catalog Number. A identification number on an audio CD. Also
|
||||
called a UPC. Another identification number is ISRC.
|
||||
|
||||
@item MMC
|
||||
@cindex MMC
|
||||
|
||||
MMC (MultiMedia Commands). A SCSI programming specification made by
|
||||
MMC (Multimedia Commands). A SCSI programming specification made by
|
||||
the SCSI committee T10 organization. They are raw commands for
|
||||
communicating with CDROM drives, CD-Rewriters, DVD-Rewriters, etc.
|
||||
|
||||
@@ -169,6 +194,7 @@ Many manufacturers have adopted this standard and it also applies to
|
||||
ATAPI versions of their drives.
|
||||
|
||||
@item Mixed Mode CD
|
||||
@cindex Mixed Mode CD
|
||||
|
||||
A Mixed Mode is a CD that contains tracks of differing CD-ROM Mode
|
||||
formats. In particular the first track may contain both computer data
|
||||
@@ -176,17 +202,20 @@ formats. In particular the first track may contain both computer data
|
||||
video data. Video CD's can be Mixed Mode CDs.
|
||||
|
||||
@item Multisession
|
||||
@cindex Multisession
|
||||
|
||||
A way of writing to a CD that allows more data to be
|
||||
added to readable discs at a later time.
|
||||
|
||||
@item Nero NRG format file
|
||||
@cindex Nero NRG, CD-Image format
|
||||
|
||||
A proprietary CD image file format use by a popular program for
|
||||
Microsoft Windows, Ahead Nero. The specification of this format is
|
||||
not to our knowlege published.
|
||||
|
||||
@item SCSI
|
||||
@cindex SCSI
|
||||
|
||||
Small Computer System Interface. A set of ANSI standard electronic
|
||||
interfaces (originally developed at Apple Computer) that allow
|
||||
@@ -194,6 +223,7 @@ personal computers to communicate with peripheral hardware such as
|
||||
CD-ROM drives, disk drives, printers, etc.
|
||||
|
||||
@item SCSI Pass Through Interface.
|
||||
@cindex SCSI Pass Through Interface.
|
||||
|
||||
Yet another way of issuing MMC commands for accessing a CD-ROM. As
|
||||
with MMC or ASPI, the CD-ROM doesn't necessarily have to be a
|
||||
@@ -201,6 +231,8 @@ SCSI-attached drive. See also @acronym{MMC} and @acronym{ASPI}.
|
||||
|
||||
|
||||
@item SPTI
|
||||
@cindex SPTI
|
||||
|
||||
SCSI Pass Through Interface. See SCSI Pass Through Interface
|
||||
|
||||
@item Session
|
||||
@@ -209,9 +241,12 @@ A fully readable complete recording that contains one or more tracks
|
||||
of computer data or audio on a CD.
|
||||
|
||||
@item SVCD
|
||||
@cindex Super VCD (SVCD)
|
||||
|
||||
Super @acronym{VCD} @uref{http://www.dvdrhelp.com/svcd}
|
||||
|
||||
@item TOC
|
||||
@cindex TOC
|
||||
|
||||
Table of Contents. The TOC contains the starting track number, last
|
||||
track number individual track starting time, format of track: CDDA or
|
||||
@@ -220,15 +255,38 @@ recorded at the start of the CD (lead-in area). A multi-session CD
|
||||
may have several TOCs.
|
||||
|
||||
@item Track
|
||||
@cindex track
|
||||
|
||||
A unit of data of a CD. The size of a track can vary; it can occupy
|
||||
the entire contents of the CD. Most CD standards however require that
|
||||
tracks have a 150 frame (or ``2 second'') lead-in gap.
|
||||
|
||||
@item VCD
|
||||
Video @acronym{CD} @uref{http://www.dvdrhelp.com/vcd}
|
||||
@cindex Video CD (VCD)
|
||||
|
||||
The Video Compact Disc (@dfn{Video CD} or @dfn{VCD}) is a standardized
|
||||
digital video storage format. It is based on the commonly available
|
||||
Compact Disc technology, which allows for low-cost video authoring.
|
||||
Video CD's can be played in most @acronym{DVD} standalone player,
|
||||
dedicated VCD players and finally, modern Personal Computers with
|
||||
multimedia support.
|
||||
|
||||
A Video CD is made up of @acronym{CD-ROM XA} sectors,
|
||||
i.e. @acronym{CD-ROM} mode 2 form 1 & 2 sectors. Non-@acronym{MPEG} data
|
||||
is stored in mode 2 form 1 sectors with a user data area of 2048 byte,
|
||||
which have a similiar L2 error correction and detection
|
||||
(@acronym{ECC}/@acronym{EDC}) to @acronym{CD-ROM} mode 1 sectors. While
|
||||
realtime @acronym{MPEG} streams is stored in @acronym{CD-ROM} mode 2
|
||||
form 2 sectors, which by have no L2 @acronym{ECC}, yield a ~14% greater
|
||||
user data area consisting of 2324 bytes@footnote{actually raw mode 2
|
||||
sectors have a 2336 byte user data area, but parts of it are used for
|
||||
error codes and headers when using the mode 2 form 1 or form 2
|
||||
configurations.}
|
||||
|
||||
@uref{http://www.dvdrhelp.com/vcd}
|
||||
|
||||
@item Win32 ASPI
|
||||
@cindex ASPI
|
||||
|
||||
The ASPI interface specification was developed by Adaptec for
|
||||
sending commands to a SCSI host adapter (such as those controlling CD
|
||||
@@ -250,6 +308,8 @@ Microsoft Windows. It is used for sending commands to devices using
|
||||
defined codes and structures.
|
||||
|
||||
@item XA
|
||||
@cindex XA
|
||||
|
||||
See @acronym{CD-ROM XA}
|
||||
|
||||
@end table
|
||||
|
||||
592
doc/libcdio.texi
592
doc/libcdio.texi
@@ -46,7 +46,7 @@ development.''
|
||||
|
||||
@titlepage
|
||||
@title GNU libcdio library
|
||||
@subtitle $Id: libcdio.texi,v 1.31 2005/01/24 08:33:57 rocky Exp $
|
||||
@subtitle $Id: libcdio.texi,v 1.32 2005/01/28 04:15:15 rocky Exp $
|
||||
@author Rocky Bernstein et al.
|
||||
@page
|
||||
|
||||
@@ -83,14 +83,15 @@ Copyright (C) 2003, 2004, 2005 Rocky Bernstein and Herbert Valerio Riedel
|
||||
* Previous Work:: The problem and previous work
|
||||
* Purpose:: What is in this package (and what's not)
|
||||
* CD Formats:: A tour through the CD-specification spectrum
|
||||
* CD Image Formats:: A tour through various CD-image formats
|
||||
* CD Units:: The units that make up a CD
|
||||
* How to use:: Okay enough babble, lemme at the library!
|
||||
* Utility Programs:: Diagnostic programs that come with this library
|
||||
* OS Considerations:: Operating System Considerations and Drivers
|
||||
* Internal Program Organization:: Looking under the hood
|
||||
|
||||
Appendices
|
||||
* ISO-9660 Character Sets::
|
||||
* CD Image Formats::
|
||||
* Glossary::
|
||||
* GNU General Public License::
|
||||
* GNU Free Documentation License::
|
||||
@@ -529,7 +530,7 @@ System semantics.
|
||||
|
||||
@node Joliet Extensions
|
||||
@subsubsection Joliet Extensions
|
||||
@cindex Joliet Extensions
|
||||
@cindex Joliet extensions
|
||||
|
||||
Joliet extensions were an upward-compatible extension to the ISO 9660
|
||||
specification that removes the limitation initially put in to deal
|
||||
@@ -621,6 +622,221 @@ In @value{libcdio} when you you want to read a mode2 format 2 audio
|
||||
sector you call the @code{cdio_read_mode2_sector()} or
|
||||
@code{cdio_read_mode2_sectors()} setting @code{b_form2} to @code{true}.
|
||||
|
||||
@node CD Image Formats
|
||||
@chapter CD Image Formats
|
||||
|
||||
@menu
|
||||
* CDRDAO TOC Format::
|
||||
* CDRWIN BIN/CUE Format::
|
||||
* NRG Format::
|
||||
@end menu
|
||||
|
||||
In both the @command{cdrdao} and bin/cue formats there is one meta-file with
|
||||
extensions @code{.toc} or @code{.cue} respectively and one or more
|
||||
files (often with the extension @code{.bin}) which contains the
|
||||
content of tracks. The format of the track data is often
|
||||
interchangeable between the two formats. For example, in
|
||||
@value{libcdio}'s regression tests we make use of this to reduce the
|
||||
size of the test data and just provide alternate meta-data files
|
||||
(@code{.toc} or @code{.cue}).
|
||||
|
||||
In contrast to the first two formats, the NRG format consists of a
|
||||
single file. This has the advantage of being a self-contained
|
||||
units. It is possible in the other two formats for the meta file to
|
||||
refer to a file that can't be found. A disadvantage of the NRG format
|
||||
is that the meta data can't be easily viewed or modified say in a text
|
||||
file as it can be with the first two formats. In conjunction with this
|
||||
disadvantage is another disadvantage that the format is not
|
||||
documented, so how @value{libcdio} interprets an NRG image is based on
|
||||
inference. It is recommended that one of the other forms be used
|
||||
instead of NRG where possible.
|
||||
|
||||
@node CDRDAO TOC Format
|
||||
@section CDRDAO TOC Format
|
||||
|
||||
This is @command{cdrdao}'s CD-image description format. Since this
|
||||
program is GPL and everything about it is in the open, it is the
|
||||
preferred format to use. (Alas, at present it isn't as well supported
|
||||
in @value{libcdio} as the BIN/CUE format.)
|
||||
|
||||
The @emph{toc}-file describes what data is written to the media in the
|
||||
@acronym{CD-ROM}; it allows control over track/index positions,
|
||||
pre-gaps and sub-channel information. It is a text file, so a text
|
||||
editor can be used to create, view or modify it.
|
||||
|
||||
The @cite{cdrdao(1) manual page}, contains more information about this
|
||||
format.
|
||||
|
||||
@subsection CDRDAO Grammar
|
||||
|
||||
Here is a list of lexical tokens taken from the cdrdao grammar.
|
||||
|
||||
@example
|
||||
#lexclass START
|
||||
#token Eof "@@"
|
||||
#token "[\t\r\ ]+"
|
||||
#token Comment "//~[\n@@]*"
|
||||
#token "\n"
|
||||
#token BeginString "\""
|
||||
#token Integer "[0-9]+"
|
||||
#token Index "INDEX"
|
||||
#tokclass AudioFile @{ "AUDIOFILE" "FILE" @}
|
||||
|
||||
#lexclass STRING
|
||||
#token EndString "\""
|
||||
#token StringQuote "\\\""
|
||||
#token StringOctal "\\[0-9][0-9][0-9]"
|
||||
#token String "\\"
|
||||
#token String "[ ]+"
|
||||
#token String "~[\\\n\"\t ]*"
|
||||
@end example
|
||||
|
||||
@example
|
||||
|
||||
toc ::= ( "CATALOG" string | tocType )* @{ cdTextGlobal @} ( track )+ Eof
|
||||
|
||||
track ::= "TRACK" trackMode
|
||||
@{ subChannelMode @}
|
||||
( "ISRC" string | @{ "NO" @} "COPY" | @{ "NO" @} "PRE_EMPHASIS"
|
||||
| "TWO_CHANNEL_AUDIO" | "FOUR_CHANNEL_AUDIO" )*
|
||||
@{ cdTextTrack @}
|
||||
@{ "PREGAP" msf @}
|
||||
( subTrack | "START" | "END" )+
|
||||
( Index msf )*
|
||||
|
||||
subTrack ::=
|
||||
( AudioFile string @{ "SWAP" @} @{ "#" sLong @} samples
|
||||
| "DATAFILE" string @{ "#" sLong @{ dataLength @} @}
|
||||
| "FIFO" string dataLength
|
||||
| "SILENCE" samples
|
||||
| "ZERO" @{ dataMode @} @{ subChannelMode @} dataLength
|
||||
)
|
||||
|
||||
string ::= BeginString ( ( String | StringQuote | StringOctal ) )+
|
||||
EndString
|
||||
|
||||
stringEmpty ::= BeginString ( ( String | StringQuote | StringOctal ) )*
|
||||
EndString
|
||||
|
||||
uLong ::= Integer
|
||||
|
||||
sLong ::= Integer
|
||||
|
||||
msf ::= Integer ":" Integer ":" Integer
|
||||
|
||||
samples ::= ( msf | uLong )
|
||||
|
||||
dataLength ::= ( msf | uLong )
|
||||
|
||||
dataMode ::= ( "AUDIO" | "MODE0" | "MODE1" | "MODE1_RAW" | "MODE2"
|
||||
| "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" )
|
||||
|
||||
trackMode ::= ( "AUDIO" | "MODE1" | "MODE1_RAW" | "MODE2"
|
||||
| "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" )
|
||||
|
||||
subChannelMode ::= ( "RW" | "RW_RAW" )
|
||||
|
||||
tocType ::= ( "CD_DA" | "CD_ROM" | "CD_ROM_XA" | "CD_I" )
|
||||
|
||||
packType ::= ( "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER"
|
||||
| "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2"
|
||||
| "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" | "UPC_EAN" |
|
||||
"ISRC" | "SIZE_INFO" )
|
||||
|
||||
binaryData ::= "\@{"
|
||||
@{ Integer ( "," Integer )* @}
|
||||
"\@}"
|
||||
|
||||
cdTextItem ::= packType ( stringEmpty | binaryData )
|
||||
|
||||
cdTextBlock ::= "LANGUAGE" Integer "\@{" ( cdTextItem )* "\@}"
|
||||
|
||||
|
||||
cdTextLanguageMap ::=
|
||||
LanguageMap "\@{"
|
||||
( Integer ":" ( Integer | "EN" ) )+
|
||||
"\@}"
|
||||
|
||||
cdTextTrack ::= "CD_TEXT" "\@{" ( cdTextBlock )* "\@}"
|
||||
|
||||
cdTextGlobal ::= "CD_TEXT" "\@{" @{ cdTextLanguageMap @} ( cdTextBlock )* "\@}"
|
||||
@end example
|
||||
|
||||
|
||||
|
||||
@node CDRWIN BIN/CUE Format
|
||||
@section CDRWIN BIN/CUE Format
|
||||
@cindex BIN/CUE, CD Image Format
|
||||
|
||||
The format referred to as @emph{CDRWIN BIN/CUE Format} in this manual
|
||||
is a popular CD image format used in the @acronym{PC} world. Not
|
||||
unlike @command{cdrdao}'s toc file, the @emph{cue} file describes the
|
||||
track layout, i.e. how the sectors are to be placed on the CD
|
||||
media. The @emph{cue} file usually contains a reference to a file
|
||||
traditionally having the @file{.bin} extension in its filename, the
|
||||
@emph{bin} file. This @emph{bin} file contains the sector data payload
|
||||
which is to be written to the CD medium according to the description
|
||||
in the @emph{cue} file.
|
||||
|
||||
The following is an attempt to describe the subset of the @file{.cue}
|
||||
file syntax used in @value{libcdio} and vcdimager in an EBNF-like
|
||||
notation:
|
||||
|
||||
@subsection BIN/CUE Grammar
|
||||
|
||||
@example
|
||||
@cartouche
|
||||
<cue-document> ::= +( <file-line> +<track-expr> )
|
||||
|
||||
<digit> ::= "0" | "1" ... "8" | "9"
|
||||
<number> ::= +<digit>
|
||||
<msf> ::= <digit><digit> ":" <digit><digit> ":" <digit><digit>
|
||||
|
||||
<file-line> ::= "FILE" <pathname-expr> <file-type> <EOL>
|
||||
|
||||
<pathname-expr> ::= [ "\"" ] <pathname-str-without-spaces> [ "\"" ]
|
||||
| "\"" <pathname-str> "\""
|
||||
|
||||
<file-type> ::= "BINARY"
|
||||
|
||||
<track-expr> ::= <track-line> [ <flag-line> ]
|
||||
[ <pregap-line> ] *<index-line> [ <postgap-line> ]
|
||||
|
||||
<flag-line> ::= "FLAGS" *<flag-type> <EOL>
|
||||
<flag-type> ::= "DCP"
|
||||
|
||||
<track-line> ::= "TRACK" <number> <track-type> <EOL>
|
||||
|
||||
<pregap-line> ::= "PREGAP" <msf> <EOL>
|
||||
|
||||
<index-line> ::= "INDEX" <number> <msf> <EOL>
|
||||
|
||||
<postgap-line> ::= "POSTGAP" <msf> <EOL>
|
||||
|
||||
<track-type> ::= "AUDIO" | "MODE1/2048" | "MODE1/2352"
|
||||
| "MODE2/2336" | "MODE2/2352"
|
||||
|
||||
<comment-line> ::= "REM" *<char> <EOL>
|
||||
@end cartouche
|
||||
@end example
|
||||
|
||||
@node NRG Format
|
||||
@section NRG Format
|
||||
@cindex Nero NRG, CD-Image format
|
||||
|
||||
The format referred to as @emph{NRG Format} in this manual is another
|
||||
popular CD image format. It is available only on Nero software
|
||||
on a Microsoft Windows Operating System. It is proprietary and not
|
||||
generally published, so the information we have comes from guessing
|
||||
based on sample CD images. So support for this is incomplete and using
|
||||
this format is not recommended.
|
||||
|
||||
Unlike @command{cdrdao}'s TOC file the BIN/CUE format everything is
|
||||
contained in one file. that one can edit Meta information such as the
|
||||
number of tracks and track format is contained at the end of the
|
||||
file. This information is not inteded to be edited through a text
|
||||
editor.
|
||||
|
||||
@node CD Units
|
||||
@chapter The units that make up a CD
|
||||
|
||||
@@ -631,7 +847,8 @@ sector you call the @code{cdio_read_mode2_sector()} or
|
||||
|
||||
@node Tracks
|
||||
@section tracks --- disc subdivisions
|
||||
@cindex tracks
|
||||
@cindex track
|
||||
|
||||
In this section we describe CD properties and terms that we make use
|
||||
of in @value{libcdio}.
|
||||
|
||||
@@ -1616,10 +1833,181 @@ More work on this driver is needed. Volunteers?
|
||||
|
||||
A problem with OS/X is that if the OS thinks it understands the drive
|
||||
it gains exclusive access to it and thus prevents a library like this
|
||||
to get non-exclusive access.
|
||||
to get non-exclusive access.
|
||||
|
||||
Currently @value{libcdio} access the CD-ROM non-exclusively. However
|
||||
in order to be able to issue SCSI-MMC, the current belief is that
|
||||
exclusive access is needed. Probably in a future @value{libcdio},
|
||||
there will be some way to specify which kind of access is desired
|
||||
(with the inherent consequences of each).
|
||||
|
||||
More work on this driver is needed. Volunteers?
|
||||
|
||||
@node Internal Program Organization
|
||||
@chapter Internal Program Organization
|
||||
|
||||
@subsection file organization
|
||||
|
||||
Here is a list of @value{libcdio} directories.
|
||||
|
||||
@itemize
|
||||
|
||||
@item @code{include/cdio}
|
||||
|
||||
This contains the headers that are public. One that will probably be
|
||||
used quite a bit is @code{<cdio/cdio.h>}.
|
||||
|
||||
@item @code{lib}
|
||||
|
||||
Code for installed libraries. See below for further breakout
|
||||
|
||||
@item @code{lib/driver}
|
||||
|
||||
Code for various OS-specific CD-ROM drivers, image drivers, and
|
||||
common SCSI-MMC routines.
|
||||
|
||||
This code comprises @code{libcdio.a} (or the shared version of it).
|
||||
|
||||
@item @code{lib/iso9660}
|
||||
|
||||
Code for to extract or query ISO-9660 images.
|
||||
|
||||
This code comprises @code{libiso9660.a} (or the shared version of it).
|
||||
|
||||
@item @code{lib/paranoia}
|
||||
|
||||
This is from cdparanoia. It is the OS- and hardware- dependent code to
|
||||
detect and correct jitter for CD-DA CDs.
|
||||
|
||||
@item @code{lib/cdda_interface}
|
||||
|
||||
This is also from cdparanoia. It is the OS- and hardware- independent
|
||||
code to detect and correct jitter for CD-DA CDs.
|
||||
|
||||
@item @code{doc}
|
||||
|
||||
A home for fine documentation such as this masterpiece.
|
||||
|
||||
@item @code{example}
|
||||
|
||||
Here you will find various small example programs using
|
||||
@value{libcdio} which are largely for pedagogical purposes. You might
|
||||
be able to find one that is similar to what you want to do that could
|
||||
be extended. In fact some these are contain the kernel ideas behind of
|
||||
some of the larger programs in @file{src}.
|
||||
|
||||
@item @code{src}
|
||||
|
||||
Various stand-alone utility programs. See below.
|
||||
|
||||
@item @code{src/paranoia}
|
||||
|
||||
@value{libcdio}'s version of @code{cdparanoia}. Except for the fact
|
||||
that the back-end CD-reading code has been replaced by
|
||||
@value{libcdio}'s routines the code is pretty much identical.
|
||||
|
||||
@item @code{test}
|
||||
|
||||
Regression tests
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection libcdio
|
||||
|
||||
@value{libcdio} exports one opaque type @code{CdIo_t}. Internally this
|
||||
an enumeration for the driver, a structure containing function
|
||||
pointers and a generic ``environment'' pointer which is passed as a
|
||||
parameter on a function call. See
|
||||
@file{lib/driver/cdio_private.h}. The initialization routine for each
|
||||
driver sets up the function pointers and allocates memory for the
|
||||
environment. When a particular user-level cdio routine is called (e.g
|
||||
@code{cdio_get_first_track_num} for lib/driver/track.c), the
|
||||
environment pointer is passed to a device-specific routine which will
|
||||
then cast this pointer into something of the appropriate type.
|
||||
|
||||
Because function pointers are used, there can be and is quite a bit
|
||||
of sharing of common routines. Some of the common routines are found
|
||||
in the file @file{lib/driver/_cdio_generic.c}.
|
||||
|
||||
Another set of routines that one is likely to find shared amongst
|
||||
drivers are the SCSI-MMC commands. These are located in
|
||||
@file{lib/driver/scsi_mmc.c}.
|
||||
|
||||
There not only an attempt to share functions but we've tried to create
|
||||
a generic CD structure @code{generic_img_private_t} of file
|
||||
@file{lib/driver/generic.h}. By putting information into a common
|
||||
structure, we increase the likelihood of being able to have a common
|
||||
routine to perform some sort of function.
|
||||
|
||||
The generic CD structure would also be useful in a utility to convert
|
||||
one CD-image format to another. Basically the first image format is
|
||||
``parsed'' into the common internal format and then from this
|
||||
structure it is unparsed.
|
||||
|
||||
@subsection libiso9660
|
||||
|
||||
To be completed....
|
||||
|
||||
@subsection Coding Conventions
|
||||
|
||||
In @value{libcdio} there are a number of conventions used. If you
|
||||
understand some of these conventions it may facilitate understanding
|
||||
the code a little.
|
||||
|
||||
@subsubsection variable names
|
||||
|
||||
A number of prefixes are used in variable names here's what they mean
|
||||
|
||||
@itemize
|
||||
@item @code{i_}
|
||||
|
||||
An integer type of some sort. A variable of this ilk one might find
|
||||
being iterated over in @code{for} loops or used as the index of an
|
||||
array for example.
|
||||
|
||||
@item @code{b_}
|
||||
|
||||
A boolean type of some sort. A variable of this ilk one might find
|
||||
being in an @code{if} condition for example.
|
||||
|
||||
@item @code{p_}
|
||||
|
||||
A pointer of some sort. A variable of this ilk, say
|
||||
@code{p_foo} one is like likely to see @code{*p_foo} or
|
||||
@code{p_foo->...}.
|
||||
|
||||
@item @code{pp_}
|
||||
|
||||
A pointer to a pointer of some sort. A variable of this ilk, say
|
||||
@code{pp_foo} one is like likely to see @code{**p_foo} or
|
||||
@code{p_foo[x][y]} for example
|
||||
|
||||
@item @code{psz_}
|
||||
|
||||
A @code{char *} pointer of some sort. A variable of this ilk, say
|
||||
@code{psz_foo} may be used in a string operation. For example
|
||||
@code{printf(%s\n", psz_foo)} or @code{strdup(psz_foo)}.
|
||||
|
||||
@item @code{ppsz_}
|
||||
|
||||
A pointer to a @code{char *} pointer of some sort. A variable of this
|
||||
ilk, say @code{ppsz_foo} is used for example to return a list of
|
||||
CD-ROM device names
|
||||
|
||||
@end itemize
|
||||
|
||||
A couple other name conventions. Generally if a routine name starts
|
||||
@code{cdio_}, e.g. @code{cdio_open}, then it is an externally
|
||||
visable routine in @code{libcdio}. If a name starts @code{iso9660_},
|
||||
e.g. @code{iso9660_isdchar} then it is an externally visable routine
|
||||
in @code{libiso9660}. If a name starts @code{scsi_mmc_},
|
||||
e.g. @code{scsi_mmc_get_discmode}, then it is an externally visable
|
||||
SCSI-MMC routine. (We don't have a separate library for this yet.
|
||||
|
||||
Names in captal letters only that start @code{CDIO_} are externally
|
||||
visable @code{#defines}.
|
||||
|
||||
|
||||
@node ISO-9660 Character Sets
|
||||
@appendix ISO-9660 Character Sets
|
||||
|
||||
@@ -1678,199 +2066,7 @@ e | . > N
|
||||
f | / ? O _
|
||||
@end example
|
||||
|
||||
@node CD Image Formats
|
||||
@appendix CD Image Formats
|
||||
|
||||
@menu
|
||||
* CDRDAO TOC Format::
|
||||
* CDRWIN BIN/CUE Format::
|
||||
* NRG Format::
|
||||
@end menu
|
||||
|
||||
@node CDRDAO TOC Format
|
||||
@appendixsec CDRDAO TOC Format
|
||||
|
||||
This is @command{cdrdao}'s own cd image description format. Since this
|
||||
program is GPL and everything about it is in the open, it is the
|
||||
preferred format to use. (Alas, at present it isn't as well supported
|
||||
in @value{libcdio} as the BIN/CUE format.)
|
||||
|
||||
A snippet from the @cite{cdrdao(1) manual page}, which you should
|
||||
refer to for more information about this format:
|
||||
|
||||
@quotation
|
||||
The @emph{toc}-file describes what data is written to the
|
||||
@acronym{CD-R} and allows control over track/index positions, pre-gaps
|
||||
and sub-channel information. It is a simple text file, use your
|
||||
favorite text editor to create it.
|
||||
@end quotation
|
||||
|
||||
Here is a list of lexical tokens taken from the cdrdao grammar.
|
||||
|
||||
@example
|
||||
#lexclass START
|
||||
#token Eof "@@"
|
||||
#token "[\t\r\ ]+"
|
||||
#token Comment "//~[\n@@]*"
|
||||
#token "\n"
|
||||
#token BeginString "\""
|
||||
#token Integer "[0-9]+"
|
||||
#token Index "INDEX"
|
||||
#tokclass AudioFile @{ "AUDIOFILE" "FILE" @}
|
||||
|
||||
#lexclass STRING
|
||||
#token EndString "\""
|
||||
#token StringQuote "\\\""
|
||||
#token StringOctal "\\[0-9][0-9][0-9]"
|
||||
#token String "\\"
|
||||
#token String "[ ]+"
|
||||
#token String "~[\\\n\"\t ]*"
|
||||
@end example
|
||||
|
||||
@example
|
||||
|
||||
toc ::= ( "CATALOG" string | tocType )* @{ cdTextGlobal @} ( track )+ Eof
|
||||
|
||||
track ::= "TRACK" trackMode
|
||||
@{ subChannelMode @}
|
||||
( "ISRC" string | @{ "NO" @} "COPY" | @{ "NO" @} "PRE_EMPHASIS"
|
||||
| "TWO_CHANNEL_AUDIO" | "FOUR_CHANNEL_AUDIO" )*
|
||||
@{ cdTextTrack @}
|
||||
@{ "PREGAP" msf @}
|
||||
( subTrack | "START" | "END" )+
|
||||
( Index msf )*
|
||||
|
||||
subTrack ::=
|
||||
( AudioFile string @{ "SWAP" @} @{ "#" sLong @} samples
|
||||
| "DATAFILE" string @{ "#" sLong @{ dataLength @} @}
|
||||
| "FIFO" string dataLength
|
||||
| "SILENCE" samples
|
||||
| "ZERO" @{ dataMode @} @{ subChannelMode @} dataLength
|
||||
)
|
||||
|
||||
string ::= BeginString ( ( String | StringQuote | StringOctal ) )+
|
||||
EndString
|
||||
|
||||
stringEmpty ::= BeginString ( ( String | StringQuote | StringOctal ) )*
|
||||
EndString
|
||||
|
||||
uLong ::= Integer
|
||||
|
||||
sLong ::= Integer
|
||||
|
||||
msf ::= Integer ":" Integer ":" Integer
|
||||
|
||||
samples ::= ( msf | uLong )
|
||||
|
||||
dataLength ::= ( msf | uLong )
|
||||
|
||||
dataMode ::= ( "AUDIO" | "MODE0" | "MODE1" | "MODE1_RAW" | "MODE2"
|
||||
| "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" )
|
||||
|
||||
trackMode ::= ( "AUDIO" | "MODE1" | "MODE1_RAW" | "MODE2"
|
||||
| "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" )
|
||||
|
||||
subChannelMode ::= ( "RW" | "RW_RAW" )
|
||||
|
||||
tocType ::= ( "CD_DA" | "CD_ROM" | "CD_ROM_XA" | "CD_I" )
|
||||
|
||||
packType ::= ( "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER"
|
||||
| "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2"
|
||||
| "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" | "UPC_EAN" |
|
||||
"ISRC" | "SIZE_INFO" )
|
||||
|
||||
binaryData ::= "\@{"
|
||||
@{ Integer ( "," Integer )* @}
|
||||
"\@}"
|
||||
|
||||
cdTextItem ::= packType ( stringEmpty | binaryData )
|
||||
|
||||
cdTextBlock ::= "LANGUAGE" Integer "\@{" ( cdTextItem )* "\@}"
|
||||
|
||||
|
||||
cdTextLanguageMap ::=
|
||||
LanguageMap "\@{"
|
||||
( Integer ":" ( Integer | "EN" ) )+
|
||||
"\@}"
|
||||
|
||||
cdTextTrack ::= "CD_TEXT" "\@{" ( cdTextBlock )* "\@}"
|
||||
|
||||
cdTextGlobal ::= "CD_TEXT" "\@{" @{ cdTextLanguageMap @} ( cdTextBlock )* "\@}"
|
||||
@end example
|
||||
|
||||
|
||||
|
||||
@node CDRWIN BIN/CUE Format
|
||||
@appendixsec CDRWIN BIN/CUE Format
|
||||
@cindex BIN/CUE, CD Image Format
|
||||
|
||||
The format referred to as @emph{CDRWIN BIN/CUE Format} in this manual
|
||||
is a popular CD image format used in the @acronym{PC} world. Not
|
||||
unlike @command{cdrdao}'s toc file, the @emph{cue} file describes the
|
||||
track layout, i.e. how the sectors are to be placed on the CD
|
||||
media. The @emph{cue} file usually contains a reference to a file
|
||||
traditionally having the @file{.bin} extension in its filename, the
|
||||
@emph{bin} file. This @emph{bin} file contains the sector data payload
|
||||
which is to be written to the CD medium according to the description
|
||||
in the @emph{cue} file.
|
||||
|
||||
The following is an attempt to describe the subset of the @file{.cue}
|
||||
file syntax as used in vcdimager in an EBNF-like notation:
|
||||
|
||||
@example
|
||||
@cartouche
|
||||
<cue-document> ::= +( <file-line> +<track-expr> )
|
||||
|
||||
<digit> ::= "0" | "1" ... "8" | "9"
|
||||
<number> ::= +<digit>
|
||||
<msf> ::= <digit><digit> ":" <digit><digit> ":" <digit><digit>
|
||||
|
||||
<file-line> ::= "FILE" <pathname-expr> <file-type> <EOL>
|
||||
|
||||
<pathname-expr> ::= [ "\"" ] <pathname-str-without-spaces> [ "\"" ]
|
||||
| "\"" <pathname-str> "\""
|
||||
|
||||
<file-type> ::= "BINARY"
|
||||
|
||||
<track-expr> ::= <track-line> [ <flag-line> ]
|
||||
[ <pregap-line> ] *<index-line> [ <postgap-line> ]
|
||||
|
||||
<flag-line> ::= "FLAGS" *<flag-type> <EOL>
|
||||
<flag-type> ::= "DCP"
|
||||
|
||||
<track-line> ::= "TRACK" <number> <track-type> <EOL>
|
||||
|
||||
<pregap-line> ::= "PREGAP" <msf> <EOL>
|
||||
|
||||
<index-line> ::= "INDEX" <number> <msf> <EOL>
|
||||
|
||||
<postgap-line> ::= "POSTGAP" <msf> <EOL>
|
||||
|
||||
<track-type> ::= "AUDIO" | "MODE1/2048" | "MODE1/2352"
|
||||
| "MODE2/2336" | "MODE2/2352"
|
||||
|
||||
<comment-line> ::= "REM" *<char> <EOL>
|
||||
@end cartouche
|
||||
@end example
|
||||
|
||||
@node NRG Format
|
||||
@appendixsec NRG Format
|
||||
@cindex NRG, CD Image Format
|
||||
|
||||
The format referred to as @emph{NRG Format} in this manual is another
|
||||
popular CD image format. It is available only on Nero software
|
||||
on a Microsoft Windows Operating System. It is proprietary and not
|
||||
generally published, so the information we have comes from guessing
|
||||
based on sample CD images. So support for this is incomplete and using
|
||||
this format is not recommended.
|
||||
|
||||
Unlike @command{cdrdao}'s TOC file the BIN/CUE format everything is
|
||||
contained in one file. that one can edit Meta information such as the
|
||||
number of tracks and track format is contained at the end of the
|
||||
file. This information is not inteded to be edited through a text
|
||||
editor.
|
||||
|
||||
@node Glossary, GNU General Public License, CD Image Formats, Top
|
||||
@node Glossary
|
||||
@appendix Glossary
|
||||
|
||||
@include glossary.texi
|
||||
|
||||
Reference in New Issue
Block a user