diff --git a/doc/glossary.texi b/doc/glossary.texi index ebe967f8..9b7f556b 100644 --- a/doc/glossary.texi +++ b/doc/glossary.texi @@ -33,8 +33,15 @@ 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 Blu-ray Disc (BD) +@cindex Blu-ray Disc (BD) +Optical media with capacity of 25 GB as single layer and 50 GB +as double layer. See also "Media models and profiles". + + @item CD -Compact Disc +@cindex CD +Compact Disc. Capacity up to 900 MB. See also "Media models and profiles". @item CD-DA @cindex CD-DA @@ -114,6 +121,20 @@ translators. But also a CD-I player can read CD-XA discs even if its own `Green Book' file system only resembles ISO 9660 and isn't fully compatible. +@item DVD +@cindex DVD +Digital Versatile Disc. Capacity up to 4.5 GB as single layer and +8.5 GB as double layer media. See also "Media models and profiles". + +@item Defect management +@cindex Defect management +A method to compensate small amounts of bad spots on media by replacing +them out of a pool of reserve blocks and performing address translation. +The necessary checkreading slows down write performance by a factor of 2 or 3. +Defect management applies by default to DVD-RAM and BD-RE. Optionally it +can be formatted onto CD-RW and DVD+RW, where it has the name "Mount Rainier". +Sequential BD-R can be formatted for defect management too. + @item Command Packet @cindex Command Packet @@ -260,6 +281,70 @@ DVD-Rewriters, etc. Many manufacturers have adopted this standard and it also applies to ATAPI versions of their drives. +@item Media models and profiles +@cindex Media models and profiles + +MMC classifies media as models, which describe their logical structure, +and as profiles, which describe the capabilities of the drive with the +particular media. So both are closely related but not identical. + +There are three model families: CD, DVD, Blu-ray. +CD allows special sector formats like audio as well as data +sectors of 2048 bytes. DVD and Blu-ray only record data sectors. +@table @dfn +@item Non-writable media: CD-ROM, DVD-ROM, BD-ROM. +@item Write-once media: CD-R, DVD-R, DVD+R, BD-R. +@item Reusable media: CD-RW, DVD-RW, DVD+RW, DVD-RAM, BD-RE. +@end table + +Profiles depend on drive type and media state. They are expressed as +numbers. It is unfortunate that formatted CD-RW have the same +profile number as unformatted ones. + +ROM drives often announce all media as ROM profiles. +Some writer drives show closed sequential media as ROM profile. +@table @dfn +@item CD-ROM 0x08 +@item DVD-ROM 0x10 +@item BD-ROM 0x40 +@end table + +Sequentially recordable profiles allow multisession in most cases. +Special burn programs are needed for writing to them. +@table @dfn +@item CD-R 0x09 +@item CD-RW 0x0a (unformatted) +@item DVD-R 0x11 +@item DVD-RW 0x14 (unformatted) +@item DVD-R DL 0x15 (double layer) +@item DVD+R 0x1a +@item DVD+R DL 0x2a (double layer) +@item BD-R 0x41 (single or double layer, formatted or not) +@end table +They can assume three states: +@table @dfn +@item "Blank" is not readable but writeable from scratch +@item "Appendable" is readable and after the readable part still writeable +@item "Closed" is only readable +@end table +CD-RW and DVD-RW can be brought back to blank state, +or they can be formatted to become overwriteable. + +Overwriteable profiles allow random read-write access with a +granularity of 2 kB or 32 kB. +One can hope for having read-write access via the normal +POSIX operations lseek(), read(), write() of the operating system. +@table @dfn +@item CD-RW 0x0a (formatted) +@item DVD-RAM 0x12 +@item DVD-RW 0x13 (formatted, 32 kB write granularity) +@item DVD+RW 0x1a +@item BD-R 0x42 (formatted for pseudo-random recording) +@item BD-RE 0x43 (single or double layer) +@end table +BD-R profile 0x42 is defined by MMC but not implemented by the consumer +priced Blu-ray burners as of year 2009. + @item Mixed Mode CD @cindex Mixed Mode CD diff --git a/doc/libcdio.texi b/doc/libcdio.texi index 11aaf215..dd0346d1 100644 --- a/doc/libcdio.texi +++ b/doc/libcdio.texi @@ -12,7 +12,7 @@ @set txicodequotebacktick @copying -This manual documents @code{libcdio}, the GNU CD Input, Output and Control +This manual documents @code{libcdio}, the GNU CD Input, Output, and Control Library. Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008, 2010 Rocky @@ -47,7 +47,7 @@ Texts. A copy of the license is included in the section entitled @titlepage @title GNU @code{libcdio} -@subtitle GNU Compact Disc Input, Output and Control Library +@subtitle GNU Compact Disc Input, Output, and Control Library @subtitle for version @value{VERSION}, @value{UPDATED} @author Rocky Bernstein et al. (@email{bug-libcdio@@gnu.org}) @page @@ -287,7 +287,7 @@ There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. __________________________________ ISO 9660 image: ../test/joliet.iso -Application: K3B THE CD KREATOR VERSION 0.11.12 (C) 2003 SEBASTIAN TRUEG AND THE K3B TEAM +Application: K3B THE CD KREATOR VERSION 0.11.12 (C) 2003 SEBASTIAN TRUEG AND... Preparer : K3b - Version 0.11.12 Publisher : Rocky Bernstein System : LINUX @@ -322,17 +322,13 @@ extracts files from an ISO-9660 image. Historically, @code{libcdio} did not support write access to drives. In conjunction with additional work in a separate project -@code{libburn}, Thomas Schmitt has modified @code{libcdio} to add -write support; @code{libburn} write audio and data CD's and reads data -CD's. It reads and write DVD's and Blu-Ray discs. +@code{libburn}, Thomas Schmitt has modified @code{libcdio} to enable +sending SCSI write commands on some of the drivers. This enables other +programs like @code{libburn} to write to CD's, DVD's and Blu-Ray +discs. -Other writing libraries include (e.g. @code{libdi}, @code{libscg}, or -@code{libdvdread}) may be helpful. - -I'm not theoretically opposed to putting support like this into -libcdio. However at present there are already many gaps in this -package, so narrowing its scope in order to focus on these things I -think is a good idea. +For the OS drivers which are lacking write access, volunteers are +welcome. @node CD Formats @chapter CD Formats @@ -2040,19 +2036,19 @@ MMC (Multimedia commands) is a specification which adds special SCSI commands for CD, DVD, Blu-Ray devices. If your optical drive understands MMC commands as most do nowadays, -this is probably gives the most flexibility in control. SCSI and ATAPI +this probably gives the most flexibility in control. SCSI and ATAPI CD-ROM devices generally support a fairly large set of MMC -commands. Unfortunately on most Operating Systems, one may need to do -additional steps to allow access in this manner. +commands. Unfortunately, on most Operating Systems one may need to do +some additional setup, such as install drivers or modules, to allow +access in this manner. The name ``SCSI MMC'' is often found in the literature in specifications and on the Internet. The ``SCSI'' part is probably a little bit misleading because a drive can understand ``SCSI MMC'' commands but not use a SCSI bus protocol---ATAPI CD-ROMs are one such broad class of examples. In fact there are drivers to ``encapsulate'' -non-SCSI drives on non-MMC-compliant drives and make them act like MMC -drives. I believe that many Operating System SCSI ``pass-through'' -mechanisms do roughly the same thing. +non-SCSI drives to make them act like more like SCSI drives, such as +by adding SCSI address naming. For clarity and precision we will use the term ``MMC'' rather than ``SCSI MMC''. @@ -2067,7 +2063,6 @@ One of the problems with MMC is that there are so many different @item MMC 5 --- @url{ftp://ftp.t10.org/t10/drafts/mmc5/} @end itemize along with the several ``drafts'' of these. -for each standard. Another problem with the MMC commands related to the variations in standards is the variation in the commands themselves and there are @@ -2100,9 +2095,8 @@ find a little bit of this for example via the routine @code{scsi_mmc_get_drive_cap()}. However much more work is needed. Finally, in @code{libcdio} there is a driver access mode (not a -driver) called ``MMC''. It indicates to the specific drivers to in -issue MMC commands instead of other OS-specific or native drive -commands. +driver) called ``MMC''. It tells the specific drivers to use MMC +commands instead of other OS-specific mechanisms. @node Access Modes @section Access Modes @@ -2220,7 +2214,14 @@ More work on this driver is needed. Volunteers? @node Internal Program Organization @chapter Internal Program Organization -@subsection file organization +@menu +* File Organization:: +* Library Organization:: +* Programming Conventions:: +@end menu + +@node File Organization +@section File Organization Here is a list of @value{libcdio} directories. @@ -2296,6 +2297,18 @@ location @code{lib/driver} @end itemize +@node Library Organization +@section Library Organization + +@menu +* libcdio:: +* libcdio_cdda:: Access to CD-DA via the CD Paranoia library +* libcdio_paranoia:: Access to the CD Paranoia library +* libiso9660:: Access to ISO 9660 file systems and structures +* libudf:: Access to UDF file systems and structures +@end menu + +@node libcdio @subsection @samp{libcdio} @value{libcdio} exports one opaque type @code{CdIo_t}. Internally this @@ -2328,6 +2341,7 @@ 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 not parsed. +@node libcdio_cdda @subsection @samp{libcdio_cdda} This library is intended to give access CD-DA disks using Monty's @@ -2335,6 +2349,7 @@ cd-paranoia library underneath. To be completed.... +@node libcdio_paranoia @subsection @samp{libcdio_paranoia} This library is intended to give access Monty's cd-paranoia @@ -2342,6 +2357,8 @@ library. It is the gap detection and jitter correction part without the part dealing with CD-DA reading. To be completed.... + +@node libiso9660 @subsection @samp{libiso9660} This library is intended to give access and manipulate a ISO-9600 file @@ -2352,6 +2369,7 @@ structures and fields that go into such an image. To be completed.... +@node libudf @subsection @samp{libudf} This library is intended to give access and manipulate a UDF file @@ -2359,13 +2377,23 @@ image. To be completed.... +@node Programming Conventions +@section Programming Conventions + +@menu +* Coding Conventions:: +* Namespace Conventions:: +@end menu + +@node Coding Conventions @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 namespace names +@node Namespace Conventions +@subsection Namespace Conventions For the most part, the visible external @value{libcdio} names follow conventions so as not to be confused with other applications or