Branching for libisoburn release 0.6.6
This commit is contained in:
85
libisoburn/branches/ZeroSixSix/doc/comments
Normal file
85
libisoburn/branches/ZeroSixSix/doc/comments
Normal file
@ -0,0 +1,85 @@
|
||||
/**
|
||||
@author Mario Danic, Vreixo Formoso, Thomas Schmitt
|
||||
|
||||
@mainpage Libisoburn Documentation Index
|
||||
|
||||
@section intro Introduction
|
||||
|
||||
Libburnia is an open-source project for reading, mastering and writing
|
||||
optical discs. This page is about its capability to read, manipulate, and
|
||||
write ISO 9660 filesystems with Rock Ridge extensions. Media can be optical
|
||||
media or filesystem objects.
|
||||
|
||||
Our scope is currently Linux 2.4 and 2.6, or FreeBSD, or OpenSolaris.
|
||||
|
||||
libisoburn is an add-on to libburn and libisofs which coordinates both and
|
||||
also allows to grow ISO-9660 filesystem images on multi-session media as well
|
||||
as on overwriteable media via the same API.
|
||||
All media peculiarities are handled automatically.
|
||||
|
||||
xorriso is an application of all three libraries which creates, loads,
|
||||
manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions.
|
||||
Manipulation is not only adding or overwriting of files but also deletion,
|
||||
renaming, and attribute changing. An incremental backup feature is provided.
|
||||
The xorriso features are accessible via built-in command interpreters and
|
||||
via a C language API.
|
||||
|
||||
|
||||
SONAME:
|
||||
libisoburn.so.1 (since 0.1.0, February 2008).
|
||||
|
||||
|
||||
@section using Using the libraries
|
||||
|
||||
Our build system is based on autotools.
|
||||
User experience tells us that you will need at least autotools version 1.7.
|
||||
|
||||
To build libisoburn go into its toplevel directory and execute:
|
||||
|
||||
- ./bootstrap (needed if you downloaded from SVN)
|
||||
|
||||
- ./configure
|
||||
|
||||
- make
|
||||
|
||||
To make the library and the xorriso application accessible for running resp.
|
||||
software development:
|
||||
|
||||
- make install
|
||||
|
||||
|
||||
For direct use as command line tool use the xorriso binary which among many
|
||||
other features provides a mkisofs emulation via command "-as mkisofs".
|
||||
See man page xorriso/xorriso.1 or GNU info document xorriso/xorriso.info.
|
||||
|
||||
|
||||
If you want to link an own application with libisoburn, you have
|
||||
two alternative APIs for choice:
|
||||
|
||||
- libisoburn, together with libburn and libisofs.
|
||||
|
||||
- xorriso, a complete representation of xorriso command line options.
|
||||
It encapsulates the three lower level libraries.
|
||||
Calls of both API families shall not be mixed.
|
||||
|
||||
For a description of the lbisoburn API read libisoburn/libisoburn.h
|
||||
See file README for download and installation of a release tarball.
|
||||
You will also have to install and understand the two libraries of the
|
||||
Libburnia project which provide fundamental services:
|
||||
libburn is the library by which preformatted data get onto optical media.
|
||||
See libburn/libburn.h for its API description.
|
||||
libisofs is the library to handle ISO 9660 filesystems with Rock Ridge
|
||||
extensions. Its API is described in libisofs/libisofs.h .
|
||||
|
||||
For xorriso features see its man page xorriso/xorriso.1 or
|
||||
its GNU info document xorriso/xorriso.info.
|
||||
For the corresponding C language API see libisoburn/xorriso.h (resp.
|
||||
xorriso/xorriso.h in the build directory).
|
||||
The implementation this API is part of libisoburn.
|
||||
The xorriso command line tool gets installed as dynamically linked
|
||||
binary together with libisoburn.
|
||||
|
||||
There is also a statically linked release named GNU xorriso.
|
||||
See xorriso/README_gnu_xorriso for its download and installation.
|
||||
|
||||
*/
|
||||
1293
libisoburn/branches/ZeroSixSix/doc/doxygen.conf.in
Normal file
1293
libisoburn/branches/ZeroSixSix/doc/doxygen.conf.in
Normal file
File diff suppressed because it is too large
Load Diff
191
libisoburn/branches/ZeroSixSix/doc/partition_offset.wiki
Normal file
191
libisoburn/branches/ZeroSixSix/doc/partition_offset.wiki
Normal file
@ -0,0 +1,191 @@
|
||||
|
||||
The partition offset feature of libisofs can produce ISO 9660 images which bear
|
||||
a quite conventional partition table if copied onto a USB stick. The first
|
||||
partition marks the size of the ISO image but starts at a non-zero address.
|
||||
Thus it marks a small part of the device as unclaimed by partitions and
|
||||
available for storing boot loader code.
|
||||
|
||||
Nevertheless the USB stick is mountable via its overall device file as well as
|
||||
via the partition device file. E.g. on GNU/Linux: /dev/sdb and /dev/sdb1.
|
||||
This is achieved by two distinct sets of meta-data which refer to the same
|
||||
file content.
|
||||
|
||||
The dual-mount feature supports Rock Ridge and eventually Joliet too.
|
||||
It is capable of multi-session.
|
||||
|
||||
Currently only offset 32 kB seems to make sense. Smaller offsets are prohibited
|
||||
by fundamental assumptions of libisofs and libisoburn. Larger offsets would
|
||||
extend the unclaimed area into vital blocks of the ISO image.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
Example:
|
||||
|
||||
Testing mountability and ISOLINUX bootability from USB stick and CD.
|
||||
|
||||
Overview:
|
||||
|
||||
The test image was derived from one year old RIPLinux-9.3-non-X.iso which
|
||||
has an isohybrid MBR. Syslinux version seems to be 3.82. That MBR and the file
|
||||
tree from the mounted RIPLinux image was used to build a new ISO image
|
||||
with 16 * 2kB partition offset. Isohybrid MBR patching was done by xorriso.
|
||||
|
||||
Details:
|
||||
|
||||
The first 32 kB of an ISO 9660 image are called System Area and may host any
|
||||
byte pattern. In the case of RIPLinux-9.3-non-X.iso only the first 512 bytes
|
||||
are non-zero. But to avoid any assumptions, all 32 kB get copied here.
|
||||
{{{
|
||||
dd if=RIPLinux-9.3-non-X.iso bs=1K count=32 of=RIPLinux-9.3-non-X.sysarea
|
||||
}}}
|
||||
The files of the image are made accessible for reading
|
||||
{{{
|
||||
mount -o loop RIPLinux-9.3-non-X.iso /mnt
|
||||
}}}
|
||||
|
||||
A new ISO image gets composed. The first three lines of arguments are taken
|
||||
from the prescriptions of ISOLINUX wiki and adapted to the names used in
|
||||
RIPLinux-9.3-non-X.iso.
|
||||
Option -isohybrid-mbr imports the copied System Area and patches the MBR
|
||||
according to rules published by hpa on Syslinux mailing list.
|
||||
Option -partition_offset 16 causes the first partition to start at 2 kB block
|
||||
number 16. It also prepares the image to be mountable by this partition, too.
|
||||
{{{
|
||||
xorriso -as mkisofs \
|
||||
-o new_image.iso \
|
||||
-b boot/isolinux/isolinux.bin -c boot/boot.cat \
|
||||
-no-emul-boot -boot-load-size 4 -boot-info-table \
|
||||
-isohybrid-mbr RIPLinux-9.3-non-X.sysarea \
|
||||
-partition_offset 16 \
|
||||
/mnt
|
||||
}}}
|
||||
The image was copied onto a USB stick
|
||||
{{{
|
||||
dd if=new_image.iso of=/dev/sdc
|
||||
}}}
|
||||
and plugged into a Debian system.
|
||||
{{{
|
||||
fdisk -lu /dev/sdb
|
||||
}}}
|
||||
yields
|
||||
{{{
|
||||
Device Boot Start End Blocks Id System
|
||||
/dev/sdb1 * 64 119215 59576 17 Hidden HPFS/NTFS
|
||||
}}}
|
||||
|
||||
I can mount /dev/sdb and /dev/sdb1 alike:
|
||||
{{{
|
||||
mount /dev/sdb1 /mnt1
|
||||
mount -o loop /dev/sdb /mnt
|
||||
}}}
|
||||
-o loop avoids failure with "mount: /dev/sdb already mounted or /mnt busy".
|
||||
A comparison by
|
||||
{{{
|
||||
diff -r /mnt /mnt1
|
||||
}}}
|
||||
reports no difference.
|
||||
Human readable files look ok.
|
||||
Test-reading all content by
|
||||
{{{
|
||||
tar cf - /mnt | wc
|
||||
}}}
|
||||
yields a reasonable byte count of 60743680 and no errors.
|
||||
|
||||
The machine boots RIPLinux from this USB stick with no visible problems.
|
||||
It can then mount /dev/sdb as well as /dev/sdb1.
|
||||
The ISO image boots from CD too.
|
||||
|
||||
Mounting the partition can be simulated with an image file on hard disk by
|
||||
cutting off the first partition_offset blocks of 2 KB:
|
||||
{{{
|
||||
dd if=new_image.iso of=partition_image.iso bs=2048 skip=16
|
||||
mount -o loop partition_image.iso /mnt1
|
||||
}}}
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
Another test was made with GRUB 2 by downloading
|
||||
{{{
|
||||
bzr branch http://bzr.savannah.gnu.org/r/grub/trunk/grub
|
||||
}}}
|
||||
|
||||
Before building GRUB 2, the file
|
||||
{{{
|
||||
util/grub-mkrescue.in
|
||||
}}}
|
||||
was edited to replace in the options of the xorriso command:
|
||||
{{{
|
||||
--protective-msdos-label
|
||||
}}}
|
||||
by
|
||||
{{{
|
||||
-partition_offset 16 -no-pad --no-emul-toc
|
||||
}}}
|
||||
Then GRUB 2 was built and installed.
|
||||
|
||||
The resulting image from
|
||||
{{{
|
||||
./grub-mkrescue -o image.iso
|
||||
}}}
|
||||
was put onto USB stick. It passed the same tests on Debian
|
||||
as above RIPLinux example. It boots to a GRUB prompt.
|
||||
|
||||
Due to options -no-pad --no-emul-toc the image is about 300 kB smaller than
|
||||
the image produced by original grub-mkrescue. Else it would have grown by
|
||||
about 130 kB.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
Open questions:
|
||||
|
||||
- Shall the partition of an isohybrid image be marked bootable ?
|
||||
Currently xorriso keeps the 0x80 mark of an eventually imported MBR
|
||||
resp. the 0x80 mark which xorriso eventually sets by its own MBR
|
||||
preparations.
|
||||
- If not to be marked bootable:
|
||||
What equipment would the partition need to justify having the mark ?
|
||||
|
||||
- I am still puzzled by the cylinder-head-sector ambiguity. How does a reader
|
||||
of the partition table determine the numbers for heads/cylinder and
|
||||
sectors/head ?
|
||||
fdisk tells about my /dev/sdb
|
||||
{{{
|
||||
105 heads, 17 sectors/track, 2193 cylinders, total 3915776 sectors
|
||||
}}}
|
||||
My partiton table rather was computed with 255 heads/cylinder, 63 sectors/head
|
||||
Debian does not mind the difference. (It uses the 32 bit LBAs, i assume.)
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
Application:
|
||||
|
||||
The partition offset feature can be controlled by libisofs API call
|
||||
{{{
|
||||
int iso_write_opts_set_part_offset(IsoWriteOpts *opts,
|
||||
uint32_t block_offset_2k,
|
||||
int secs_512_per_head,
|
||||
int heads_per_cyl);
|
||||
}}}
|
||||
resp. by libisoburn calls
|
||||
{{{
|
||||
int isoburn_igopt_set_part_offset(struct isoburn_imgen_opts *opts,
|
||||
uint32_t block_offset_2k,
|
||||
int secs_512_per_head, int heads_per_cyl);
|
||||
|
||||
int isoburn_igopt_get_part_offset(struct isoburn_imgen_opts *opts,
|
||||
uint32_t *block_offset_2k,
|
||||
int *secs_512_per_head, int *heads_per_cyl);
|
||||
}}}
|
||||
resp. by xorriso options
|
||||
{{{
|
||||
-boot_image any partition_offset=(2kb_block_adr)
|
||||
-boot_image any partition_sec_hd=(number)
|
||||
-boot_image any partition_hd_cyl=(number)
|
||||
-as mkisofs ... -partition_offset (2kb_block_adr) ...
|
||||
}}}
|
||||
|
||||
As stated above, an offset larger than 16 would expose vital parts of the
|
||||
ISO image as unclaimed space. Values smaller than 16 are not accepted.
|
||||
So use either an offset of 16 blocks or keep the feature disabled by
|
||||
offset 0.
|
||||
|
||||
Reference in New Issue
Block a user