claunia/libcdio-osx
Archived
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Go over documentation yet again. In particular:

Browse Source 
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
2005-01-28 04:15:15 +00:00
parent 5586d10367
commit df27526f2e
2 changed files with 459 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/glossary.texi
View File

@@ -3,6 +3,7 @@ See also @uref{http://www.dvdrhelp.com/glossary}.
@table @acronym @table @acronym
@item ASPI @item ASPI
@cindex ASPI
See @acronym{Win32 ASPI} See @acronym{Win32 ASPI}
@item ATAPI @item ATAPI
@@ -17,20 +18,22 @@ devices to the IDE/EIDE connections.
A CD-image format developed by Jeff Arnold for CDRWIN software on A CD-image format developed by Jeff Arnold for CDRWIN software on
Microsoft Windows. Many other programs subsequently support using this Microsoft Windows. Many other programs subsequently support using this
format. The .CUE file is a text file which contains CD format and format. The @code{.CUE} file is a text file which contains CD format
track layout information, while the .BIN file holds the actual data of and track layout information, while the @code{.BIN} file holds the
each track. actual data of each track.
@item CD @item CD
Compact Disc Compact Disc
@item CD-DA @item CD-DA
@cindex CD-DA
Compact Disc Digital Audio, described in the ``Red Book'' or ICE Compact Disc Digital Audio, described in the ``Red Book'' or ICE
908. This commonly referred to as an audio @acronym{CD} and what most 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 people think of when you play a @acronym{CD} as it was the first to
use the @acronym{CD} medium. use the @acronym{CD} medium.
@item CD+G @item CD+G
@cindex CD+G
Compact Disc + Graphics. An extension of the CD audio format contains Compact Disc + Graphics. An extension of the CD audio format contains
a limited amount of graphics in subcode channels. This disc works in 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. special CD+G or Karaoke player.
@item CD-i @item CD-i
@cindex CD-i
Compact Disc Interactive. An extension of the CD format designed Compact Disc Interactive. An extension of the CD format designed
around a set-top computer that connects to a TV to provide interactive around a set-top computer that connects to a TV to provide interactive
home entertainment, including digital audio and video, video games, 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. largely (if not totally) been superceded by VCDs.
@item CD-i Bridge @item CD-i Bridge
@cindex CD-i Bridge
A standard allowing CD-ROM XA discs to play on CD-i. Kodak PhotoCDs A standard allowing CD-ROM XA discs to play on CD-i. Kodak PhotoCDs
are CD-XA Bridge discs. are CD-XA Bridge discs.
@item CD-ROM @item CD-ROM
@cindex CD-ROM
Compact Disc Read Only Memory or ``Yellow Book'' describe in Standards 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 ISO/IEC 10149. The data stored on it can be either in the form of
audio, computer or video files. 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. both computer and audio/video to be mixed in the same track.
@item CD Text @item CD Text
@cindex CD Text
CD Text is a technology developed by Sony Corporation and Philips CD Text is a technology developed by Sony Corporation and Philips
Electronics in 1996 that allows storing in an audio CD and its tracks Electronics in 1996 that allows storing in an audio CD and its tracks
information such as artist name, title, songwriter, composer, or information such as artist name, title, songwriter, composer, or
@@ -71,6 +81,8 @@ arranger. Commercially available audio CDs sometimes contain CD Text
information. information.
@item CD XA @item CD XA
@cindex CD XA
CD-ROM EXtended Architecture. A modification to the CD-ROM CD-ROM EXtended Architecture. A modification to the CD-ROM
specification that defines two new types of sectors. CD-ROM XA was specification that defines two new types of sectors. CD-ROM XA was
developed jointly by Sony, Philips, and Microsoft, and announced in 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. fully compatible.
@item FSF @item FSF
@cindex FSF
Free Software Foundation, @uref{http://www.fsf.org/} Free Software Foundation, @uref{http://www.fsf.org/}
@item GNU @item GNU
@cindex GNU
@acronym{GNU} is not @acronym{UNIX}, @uref{http://www.gnu.org/} @acronym{GNU} is not @acronym{UNIX}, @uref{http://www.gnu.org/}
@item ISO @item ISO
@cindex ISO
International Standards Organization. International Standards Organization.
@item ISO 9660 @item ISO 9660
@cindex ISO 9660
The ISO 9660 is an operating-system independent filesystem format for 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 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. ISO 13490 is basically ISO 9660 with multisession support.
@item Joliet extensions @item Joliet extensions
@cindex Joliet extensions
This ISO-9660 upward-compatible standard was developed for Windows 95 This ISO-9660 upward-compatible standard was developed for Windows 95
and Windows NT by Microsoft as an extension of ISO 9600 which allows 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. the Joliet Specification.
@item LBA @item LBA
@cindex LBA
Logical Block Addressing. Mapped integer numbers from CD Red Book Logical Block Addressing. Mapped integer numbers from CD Red Book
Addressing MSF. The starting sector is -150 and ending sector is 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. programming than an MSF.
@item Lead in @item Lead in
@cindex lead in
The area of a CD where the Table Of Contents (TOC) and CDTEXT are 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 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. the ATIP groove on the disk.
@item LSN @item LSN
@cindex LSN
Logical Sector Number. Mapped integer numbers from CD Red Book Logical Sector Number. Mapped integer numbers from CD Red Book
Addressing MSF. The starting sector is 0 and ending sector is 449699, 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. it can be represented as an unsigned value.
@item MCN @item MCN
@cindex MCN
Media Catalog Number. A identification number on an audio CD. Also Media Catalog Number. A identification number on an audio CD. Also
called a UPC. Another identification number is ISRC. called a UPC. Another identification number is ISRC.
@item MMC @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 the SCSI committee T10 organization. They are raw commands for
communicating with CDROM drives, CD-Rewriters, DVD-Rewriters, etc. 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. ATAPI versions of their drives.
@item Mixed Mode CD @item Mixed Mode CD
@cindex Mixed Mode CD
A Mixed Mode is a CD that contains tracks of differing CD-ROM Mode 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 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. video data. Video CD's can be Mixed Mode CDs.
@item Multisession @item Multisession
@cindex Multisession
A way of writing to a CD that allows more data to be A way of writing to a CD that allows more data to be
added to readable discs at a later time. added to readable discs at a later time.
@item Nero NRG format file @item Nero NRG format file
@cindex Nero NRG, CD-Image format
A proprietary CD image file format use by a popular program for A proprietary CD image file format use by a popular program for
Microsoft Windows, Ahead Nero. The specification of this format is Microsoft Windows, Ahead Nero. The specification of this format is
not to our knowlege published. not to our knowlege published.
@item SCSI @item SCSI
@cindex SCSI
Small Computer System Interface. A set of ANSI standard electronic Small Computer System Interface. A set of ANSI standard electronic
interfaces (originally developed at Apple Computer) that allow 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. CD-ROM drives, disk drives, printers, etc.
@item SCSI Pass Through Interface. @item SCSI Pass Through Interface.
@cindex SCSI Pass Through Interface.
Yet another way of issuing MMC commands for accessing a CD-ROM. As 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 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 @item SPTI
@cindex SPTI
SCSI Pass Through Interface. See SCSI Pass Through Interface SCSI Pass Through Interface. See SCSI Pass Through Interface
@item Session @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. of computer data or audio on a CD.
@item SVCD @item SVCD
@cindex Super VCD (SVCD)
Super @acronym{VCD} @uref{http://www.dvdrhelp.com/svcd} Super @acronym{VCD} @uref{http://www.dvdrhelp.com/svcd}
@item TOC @item TOC
@cindex TOC
Table of Contents. The TOC contains the starting track number, last Table of Contents. The TOC contains the starting track number, last
track number individual track starting time, format of track: CDDA or 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. may have several TOCs.
@item Track @item Track
@cindex track
A unit of data of a CD. The size of a track can vary; it can occupy 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 the entire contents of the CD. Most CD standards however require that
tracks have a 150 frame (or ``2 second'') lead-in gap. tracks have a 150 frame (or ``2 second'') lead-in gap.
@item VCD @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 @item Win32 ASPI
@cindex ASPI
The ASPI interface specification was developed by Adaptec for The ASPI interface specification was developed by Adaptec for
sending commands to a SCSI host adapter (such as those controlling CD 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. defined codes and structures.
@item XA @item XA
@cindex XA
See @acronym{CD-ROM XA} See @acronym{CD-ROM XA}
@end table @end table

592
doc/libcdio.texi
View File

@@ -46,7 +46,7 @@ development.''
@titlepage @titlepage
@title GNU libcdio library @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. @author Rocky Bernstein et al.
@page @page
@@ -83,14 +83,15 @@ Copyright (C) 2003, 2004, 2005 Rocky Bernstein and Herbert Valerio Riedel
* Previous Work:: The problem and previous work * Previous Work:: The problem and previous work
* Purpose:: What is in this package (and what's not) * Purpose:: What is in this package (and what's not)
* CD Formats:: A tour through the CD-specification spectrum * 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 * CD Units:: The units that make up a CD
* How to use:: Okay enough babble, lemme at the library! * How to use:: Okay enough babble, lemme at the library!
* Utility Programs:: Diagnostic programs that come with this library * Utility Programs:: Diagnostic programs that come with this library
* OS Considerations:: Operating System Considerations and Drivers * OS Considerations:: Operating System Considerations and Drivers
* Internal Program Organization:: Looking under the hood
Appendices Appendices
* ISO-9660 Character Sets:: * ISO-9660 Character Sets::
* CD Image Formats::
* Glossary:: * Glossary::
* GNU General Public License:: * GNU General Public License::
* GNU Free Documentation License:: * GNU Free Documentation License::
@@ -529,7 +530,7 @@ System semantics.
@node Joliet Extensions @node Joliet Extensions
@subsubsection Joliet Extensions @subsubsection Joliet Extensions
@cindex Joliet Extensions @cindex Joliet extensions
Joliet extensions were an upward-compatible extension to the ISO 9660 Joliet extensions were an upward-compatible extension to the ISO 9660
specification that removes the limitation initially put in to deal 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 sector you call the @code{cdio_read_mode2_sector()} or
@code{cdio_read_mode2_sectors()} setting @code{b_form2} to @code{true}. @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 @node CD Units
@chapter The units that make up a CD @chapter The units that make up a CD
@@ -631,7 +847,8 @@ sector you call the @code{cdio_read_mode2_sector()} or
@node Tracks @node Tracks
@section tracks --- disc subdivisions @section tracks --- disc subdivisions
@cindex tracks @cindex track
In this section we describe CD properties and terms that we make use In this section we describe CD properties and terms that we make use
of in @value{libcdio}. 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 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 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? 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 @node ISO-9660 Character Sets
@appendix ISO-9660 Character Sets @appendix ISO-9660 Character Sets
@@ -1678,199 +2066,7 @@ e | . > N
f | / ? O _ f | / ? O _
@end example @end example
@node CD Image Formats @node Glossary
@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
@appendix Glossary @appendix Glossary
@include glossary.texi @include glossary.texi