From 52384030ec2eb167b44d805acaf05b87e30ab593 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Tue, 7 Jul 2020 14:02:30 +0000 Subject: [PATCH] --- FAQ.md | 423 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 423 insertions(+) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..9f87a21 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,423 @@ +### Libburnia Frequently Asked Questions + +Please post your questions to +[GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso). + +---------------------------------------------------------------------------- +### Content: + +Google favorites: + + [xorriso not found](#xorriso_not_found) + + [xorriso tutorial](#xorriso_tutorial) + + [xorriso create ISO image](#xorriso_create_iso) + +Burning: + + [What is the difference between cdrskin and xorriso ?](#diff_cdrskin_xorriso) + + [What does that SCSI error message mean ?](#scsi_error) + + [Why is simultaneous burning with multiple drives so slow ?](#concurrent_burn) + +Imaging: + + [Is there a way to edit files inside the ISO image ?](#edit_files) + + [For which architectures xorriso is able to create bootable images ?](#boot_arch) + + [How to enable booting from USB stick ?](#isohybrid) + + [What is partition offset feature all about?](#partition_offset) + + [Partition offset bad on Apple ?](#partition_offset_apple) + +Development: + + [Where are the APIs of libburnia libraries described ?](#api_specs) + + [I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?](#gui_advise) + +Miscellaneous: + + [Where to see examples ?](#example_links) + + [What personalities are supported by xorriso ?](#xorriso_aliases) + + [What is xorriso dialog mode useful for ?](#xorriso_dialog_mode) + + [Why is every second release missing ?](#version_numbers) + + +------------------------------------------------------------------------ +### Google favorites +------------------------------------------------------------------------ + +##### xorriso not found + +This message is issued by programs which use [xorriso](Xorriso) for +producing ISO 9660 filesystem images. E.g. by GRUB2's grub-mkrescue. + +Executable xorriso binaries are normally contained in software packages +named "libisoburn" or "xorriso". + +If your operating system does not offer such a package, then consider +to get the [GNU xorriso](http://www.gnu.org/software/xorriso#download) +source tarball. For instructions read in its +[README file](http://www.gnu.org/software/xorriso/README_xorriso) +the paragraph "Compilation, First Glimpse, Installation". +With grub-mkrescue it is possible to use the resulting binary without further +installation. Just submit its absolute path with option `--xorriso=`. E.g.: +``` + grub-mkrescue --xorriso=$HOME/xorriso-1.3.8/xorriso/xorriso -o output.iso +``` + +##### xorriso tutorial + +There is not much more than the +[man xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES) + +Volunteers are wanted who make a collection of use cases, ask at bug-xorriso +for xorriso instructions to fulfill the needs, and describe both in a +user-readable manner. + +Up to then, the GUI demo [xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/README-tcltk) +[(screenshot)](http://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif) +may serve as interactive exploration tool. It needs `xorriso` >= 1.2.6, `Tcl`, +`Tk` >= 8.4, optionally Tcl / Tk package `BWidget`. +``` + xorriso-tcltk --script_log_file - +``` +starts the GUI and will log the essential xorriso commands in the start +terminal. I.e. click on "Scan for drives" and learn that this operation +is triggered by xorriso command `-devices`. + +Click the rightmost mouse button while being over any of the GUI elements +in order to get the particular help text for that element. +Have [man xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html) +ready to learn what the particular commands mean. + + +##### xorriso create ISO image + +``` + xorriso -outdev $HOME/result.iso \ + -map /home/me/sounds /sounds \ + -map /home/me/pictures /pictures +``` +This points the output to file `$HOME/result.iso`, which should not yet exist. +Then it maps disk directory `/home/me/sounds` to ISO directory `/sounds`, +and `/home/me/pictures` to `/pictures`. +At program end, the ISO image gets produced and the contents of the +two directory trees gets copied into the ISO. + +If you have experience with program `mkisofs`, you may also use its +emulation by xorriso: +``` + xorriso -as mkisofs \ + -o $HOME/result.iso \ + -graft-points \ + /sounds=/home/me/sounds \ + /pictures=/home/me/pictures +``` + +See [man xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html) +for xorriso native commands. + +See [man xorrisofs](http://www.gnu.org/software/xorriso/man_1_xorrisofs.html) +for its mkisofs emulation. + + + +---------------------------------------------------------------------------- +### Burning +---------------------------------------------------------------------------- + +##### What is the difference between cdrskin and xorriso ? + +[cdrskin](Cdrskin) is a dedicated emulator of program cdrecord, based on +libburn. It tries to be as similar to cdrecord as is possible under that +premise. + +[xorriso](Xorriso) is an integrated tool which creates, loads, manipulates, +and writes ISO 9660 filesystem images with Rock Ridge extensions. +It is based on libburn, libisofs, and libisoburn. One of its features is +the emulation of the corresponding tasks as done by mkisofs and cdrecord. + +##### What does that SCSI error message mean ? + +Error messages labled as "SCSI" stem from the drive. They are codes of +three hexadecimal numbers, like `[3 0C 00]`. The first number gives an overall +classification of the problem. The other two numbers give the particular +error description. + +libburn translates known error codes into text messages. They consist of +two statements: the overall classification and the error description. + +E.g. `[3 0C 00] Medium error. Write error.` + +The classification allows a guess where the problem cause might sit: + +2 `Drive not ready` : This is a well normal drive state and should be handled +by libburn. If you see this outside of DEBUG messages then it happened +at an unexpected occasion. Either libburn did its job wrong, or the hardware +suffers from blackouts. Hardware can be: drive, cable, bus controller. + +Workaround: Check cables. If possible, try the drive at a different +bus controller. + +3 `Medium error` : This indicates a problem between drive and medium. libburn +cannot directly cause such an error by any mistake. If drive and medium +are balancing on the edge of defect, it is possible that optional settings +can cause or prevent such errors. But in many cases of drive-medium conflicts +it is mere incident whether a burn run succeeds or not. + +Workaround: Try other media or another drive. + +4 `Drive error` : The drive or the bus controller accuse themselves of +doing it wrong. As with "Medium error" this might be aggravated or eased by +optional settings. + +Workaround: Check cables. If possible, try the drive at a different +bus controller. + +5 `Illegal request` : The drive did not like a command sent by libburn. +This may be normal. But if you see this outside of DEBUG messages, then +either the drive does not comply to MMC or libburn does not do its job right. + +Workaround: Submit an error report to +[GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso). + +B `Command aborted` : Seems to be generated by some bus controllers or +operating system SCSI drivers. The newest outbreak is said to be due to USB 3 +and drivers which do not prevent power saving. + +Workaround: Plug USB drives to USB 2 sockets or have a recent operating +system kernel. If this does not help, contact +[https://lists.gnu.org/mailman/listinfo/bug-xorriso GNU xorriso mailing list] +and be ready for experiments. + +##### Why is simultaneous burning with multiple drives so slow ? + +It is a known regression of Linux since about 2010 that operating more than +one drive at the same time via SCSI commands shows severe throughput problems. +See [the wiki page about this problem](ConcurrentLinuxSr) which offers two +alternative workarounds in userspace, explanantions of the reason, +and a link to a remedy proposal by courageous kernel modification. + + +---------------------------------------------------------------------------- +### Imaging +---------------------------------------------------------------------------- + +##### Is there a way to edit files inside the ISO image ? + +File content cannot be altered. But files may be replaced by new copies from +the disk filesystem. + +The main method of manipulating an existing ISO image is to append a session +with a new complete directory tree and the file content of the added or +overwritten files. Depending on the media type you get gaps between sessions +of up to 20 MB. So better try to do all foreseeable changes by one add-on +session. + +##### For which architectures xorriso is able to create bootable images ? + +Currently it supports systems with PC-BIOS for booting from CD, DVD, or BD +media, and from memory sticks or hard disks. The same feature range is +supported for systems with EFI firmware with x86 or ARM processor. + +Further it supports machines with MIPS processor from SGI (Big Endian) +and DEC (Little Endian), and SUN SPARC machines. +(See [libisofs/doc/boot_sectors.txt](https://dev.lovelyhq.com/libburnia/libisofs/raw/HEAD/doc/boot_sectors.txt) +for technical details.) + +Examples how to get an impression of the boot equipment of existing ISO 9660 +images are on the wiki page about xorriso +[commands -report_system_area and -report_el_torito](Reportsystemarea). + +##### How to enable booting from USB stick ? + +In most cases, ISOs are prepared for PC-BIOS to boot the ISOLINUX boot loader. +This boot loader is normally started from CD, DVD or BD media via an El Torito +boot record. But if the ISO image resides on an USB stick or another +hard-disk-like device, then PC-BIOS ignores El Torito and rather expects a +Master Boot Record (MBR). Both boot record types can reside in the same ISO +image. Therefore it is possible to create an MBR that starts the boot image +file of ISOLINUX which is already target of the El Torito boot record. +This kind of MBR is called `isohybrid`. ISOLINUX provides +a program named `isohybrid` to patch existing images, but libisofs can create +an MBR already when producing the ISO image. See in +[manual page of xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html) +option `-boot_image` with arguments `isolinux system_area=`, +and `-as mkisofs` option `-isohybrid-mbr`. + +See [Wikipedia on MBR](http://en.wikipedia.org/wiki/Master_boot_record) for +general information about PC-DOS Master Boot Records, and +[ISOLINUX wiki](http://syslinux.zytor.com/wiki/index.php/ISOLINUX) for special +information about ISOLINUX. The wiki example with mkisofs can be performed +as well by help of xorriso option -as mkisofs. + +A similar combination of El Torito and MBR is created by GRUB2 tool +grub-mkrescue. See [homepage of GNU GRUB 2](http://www.gnu.org/software/grub/) +for general information. + +EFI firmware in its native mode boots by El Torito from CD, DVD or BD media, +and by partition table from USB stick or hard disk. Both, El Torito and +partition table, point to a FAT filesystem image, the EFI System Partition. +The partiton table may be either a DOS-style MBR partition table or a +[GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table). +The x86 program program in the MBR is ignored by EFI, which rather starts +a program from the FAT directory "\EFI\BOOT". The name of the program file +depends on the processor architecture: BOOTX64.EFI, BOOTIA32.EFI, BOOTARM.EFI, +BOOTAA64.EFI for x86 64 bit, x86 32 bit, ARM 32 bit, and ARM 64 bit, +respectively. + +The boot equipment for other systems may well work from USB stick too. +But libburnia project has no tangible information about this. + +##### What is partition offset feature all about? + +If an MBR is present, then it contains a partition table with up to four +entries. The MBR is located at the very start of the ISO image. By +tradition the first partition should begin only after the range of MBR and +eventual supporting data blocks. On hard disk one often sees partition 1 +starting at byte `63*512`. Further it is tradition that the payload filesystem +is mountable via one of the partitions. + +The isohybrid MBR has its only partition start at byte 0. Thus it is mountable +but does not obey the tradition to begin only after the MBR. +The `grub-mkrescue` MBR on the other hand has partition 1 start at byte 512,i +which makes it unmountable. Only the unpartitioned base device can be mounted. +(On GNU/Linux +e.g. `/dev/sdb` is the base device whereas `/dev/sdb1` is its partition 1.) + +The compromise offered by libisofs is to create a second superblock at +address `16*2048` and to let start partition 1 at this address. The second +superblock leads to a second directory tree which takes into account the +address difference between partition 1 and the base device. So the image +gets mountable via both devices and reserves 32 kB for boot manager software +where it may manipulate and augment the MBR. +(See [Partition Offset Wiki](PartitionOffset) +for examples.) + +There are reports of machines which will not boot from USB stick if +partition offset is 0. + +##### Partition offset bad on Apple ? + +Apple's "Snow Leopard" operating system refuses to mount Debian CD images +with non-zero partition offset. + +The issue is not yet fully understood. For now one has to choose +between mountability on Apple "Snow Leopard" or bootability from USB stick +on Kontron CG2100 "carrier grade server". + +---------------------------------------------------------------------------- +### Developing +---------------------------------------------------------------------------- + +##### Where are the APIs of libburnia libraries described ? + +The decisive references are the inclusion headers of the libraries +``, ``, ``, +and ``. + +Current git versions of these files: +[libburn/libburn.h](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/libburn/libburn.h) , +[libisofs/libisofs.h](https://dev.lovelyhq.com/libburnia/libisofs/raw/HEAD/libisofs/libisofs.h) , +[libisoburn/libisoburn.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/libisoburn/libisoburn.h) , +[libisoburn/xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/xorriso/xorriso.h) + +##### I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? + +Most appreciated would be a GUI for xorriso which allows to copy files from +a view of the hard disk filesystem to a view of the ISO filesystem, and vice +versa. The xorriso implementation is located inside libisoburn. + +Each option that is described in +[man 1 xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html) +can be performed by a corresponding C function that is defined in +[xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/xorriso/xorriso.h) + +Further there are calls for library startup and shutdown, for problem +handling, and for the interpreters of xorriso's command line interface. +The xorriso API encapsulates calls to libisofs, libburn, and libisoburn. + +An alternative to the xorriso C API is xorriso dialog mode. +[See below](#xorriso_dialog_mode). +The script +[xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/xorriso-tcltk) +demonstrates this approach. It is part of the +libisoburn release tarball and of the GNU xorriso tarball. + +The known existing GUIs +[Xfburn](http://goodies.xfce.org/projects/applications/xfburn), +[Brasero](http://projects.gnome.org/brasero/), +[FlBurn](http://flburn.sourceforge.net/) +rather use libisofs and libburn directly. +(Please submit an URI if you want your libburnia GUI application mentioned +here.) + +---------------------------------------------------------------------------- +### Miscellaneous +---------------------------------------------------------------------------- + +##### Where to see examples ? + +[xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES) , +[cdrskin examples](http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES) , +[libburner.c a minimal but complete burn program](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/test/libburner.c). + + +##### What personalities are supported by xorriso ? + +The name by which xorriso is started may trigger certain features which +normally would need to be enabled by program options. + +xorrisofs starts up in mkisofs emulation mode, which otherwise would have to +be entered by command `-as mkisofs`. + +xorrecord starts up in cdrecord emulation mode, which is normally entered by +command `-as cdrecord`. This emulation is only able to write a single data +track as new session to blank or appendable media. No audio. No multiple +tracks in one session. + +osirrox can copy files from ISO image to disk and to apply option -mount +to one or more of the existing ISO sessions. This is normally enabled by +option `-osirrox on:o_excl_off`. + +##### What is xorriso dialog mode useful for ? + +Dialog mode is initiated if `-dialog on` is among the program arguments. +It can be used to inspect and exploit existing ISO 9660 images or +to explore xorriso's behavior in order to develop the command sequence +for a batch run. + +Frontend programmers may fork xorriso initiating a xorriso dialog session +(`-dialog on -use_readline off -pkt_output on -mark done`), +and interact with it from their own program via pipes connected to +xorriso's stdin and stdout. This is more efficient than forking xorriso +every now and then to perform various commands in order to complete +complex tasks like image size prediction. + +The script +[xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/xorriso-tcltk) +demonstrates this approach. It is part of the +libisoburn release tarball and of the GNU xorriso tarball. + +##### Why is every second release missing ? + +Releases have an even third version number. Like 0.5.6 or 1.0.4. +During development the next higher odd number is used. E.g. 0.5.7 or 1.0.5. + +The content of release tarballs does not get changed without changing +their name. The development tarballs of xorriso and cdrskin may change +their content without notice. + +---------------------------------------------------------------------------- +Site maintainer: Do not edit this wiki directly but rather the git version +of `libisoburn/doc/faq.wiki`. When done, paste it into the wiki editor. +