From b1c218c2803543fe36e0f41228a4ae7dbc33aa86 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Tue, 21 Feb 2012 22:30:29 +0100 Subject: [PATCH] Described the opportunities and constraints of ISO 9660 hybrid fileystems, and the libisofs implementation needs when adding further filesystem types. --- doc/iso_hybrid_fs.txt | 158 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 doc/iso_hybrid_fs.txt diff --git a/doc/iso_hybrid_fs.txt b/doc/iso_hybrid_fs.txt new file mode 100644 index 0000000..5d4d141 --- /dev/null +++ b/doc/iso_hybrid_fs.txt @@ -0,0 +1,158 @@ + + Overview of ISO 9660 hybrid filesystems as libisofs output + + by Thomas Schmitt - mailto:scdbackup@gmx.net + Libburnia project - mailto:libburn-hackers@pykix.org + 21 Feb 2012 + + +The overall framework for the filesystem images produced by libisofs is given +by ECMA-119, which is also known as ISO 9660. The hybrid aspect is the +opportunity to add access structures of other filesystems. + +The framework suggests a logical block size of 2048 and divides the space of +filesystem blocks into several parts: + +- The System Area. Beginning at the image start block. + 32 KiB of arbitrary data, which are not considered to be + part of structure or payload of the ISO image. + +- The Volume Descriptors. Beginning at image start block + 16. + The Primary Volume Descriptor block is the starting point of the ECMA-119 + tree of directories and files. Among other information, it records the size + of the image block space. Other descriptor blocks may lead to boot images + or to the directory trees of add-on filesystems (e.g. Joliet). + +- The area of directory structures and data file content. + libisofs divides it into two sub areas: + + - Directory structures. + They record the file names and attributes of the ECMA-119 tree and + of eventual add-on filesystem. + + - Data file content. + The blocks in this area are referred by zero or more file entries in the + directory trees. They store the data content or regular files. Start block + address of a file and exact byte count are stored in the trees. + + +libisofs may slide-in some data blocks which are neither part of the structure +nor part of file content. See doc/checksums.txt, Checksum Array, Checksum Tags. +In the same way, the superblocks of other filesystems could be inserted into +the image. + +The only block addresses which are fixely occupied are image_start+16 (Primary +Volume Descriptor) and image_start+17 (first possible position of Volume +Descriptor Set Terminator). +Nevertheless, libisofs considers as reserved the blocks image_start+16 to +image_start+31, because add-ons like El Torito, Joliet, or ISO 9660:1999 +need their own volume descriptors stored before the volume descriptor set +terminator block. Only one volume descriptor per add-on filesystem may be +written there, and its exact position will be chosen by libisofs. + + +The System Area in image_start to image_start+15 may be used for a partition +table or the superblock of an additional filesystem structure. +Another place for superblocks is after image_start+31. E.g. UDF stores its +Anchor at block address 256, or at media_size - 1 - 256, or at media_size - 1. + +In both cases the superblocks would point to filesystem-specific data which +are stored in the area of directory structures. These data would then refer to +the same file contents as the ECMA-119 directory structure. + + +----------------------------------------------------------------------- +What libisofs needs to get implemented for a new add-on filesystem: + +The emerging overall image is represented by an Ecma119Image object. +This is an instance of quite fat struct ecma119_image which, among many +others, holds some Joliet specific parameters. Defined in libisofs/ecma119.h. +It gets programmed by applications via API calls for IsoWriteOpts which is +defined as struct iso_write_opts in libisofs/ecma119.h. + + +The content of the System Area may be submitted opaquely via +Ecma119Image.system_area_data or it may get generated underneath +libisofs/system_area.c:iso_write_system_area() by a specific "System area type" +in Ecma119Image.system_area_options. The latter happens when the block adresses +of all components, directories, and files are determined. (One may have to +dig deep in the graph of objects to obtain everything.) + +If a new system area type is needed, then it has to be documented in +libisofs/ecma119.h at struct ecma119_image.system_area_options and in +libisofs/libisofs.h at call iso_write_opts_set_system_area(). See e.g. +"MIPS Big Endian Volume Header". + + +The layout of the areas above image_start+16 is defined in function +libisofs/ecma119.c:ecma119_image_new(). This is done by creating and +registering writer objects. +Writers are instances of typedef struct Iso_Image_Writer IsoImageWriter. +The struct is defined in libisofs/writer.h. + +The Joliet writer is a comprehensive example of an add-on filesystem writer. + +First it gets counted for the allocation of the registration array + if (target->joliet) { + nwriters++; + } + +Later it gets created and registered + if (target->joliet) { + ret = joliet_writer_create(target); + +The function libisofs/joliet.c:joliet_writer_create() accounts for one block +that will hold the Joliet volume descriptor + /* we need the volume descriptor */ + target->curblock++; +Not all add-on filesystems will need a volume descriptor. Joliet does. + +joliet_writer_create() further generates a tree of JolietNode objects by +traversing the image model tree of IsoNode objects. + ret = joliet_tree_create(target); +If a JolietNode represents a regular file then it refers to an IsoFileSrc +object, which represents its data content in the emerging image. +struct Iso_File_Src is defined in libisofs/filesrc.h. + + +libisofs will call the methods of the writer object when it computes the +block addresses of the various image components, when it writes volume +descriptors, when it writes directory trees, and when it finally disposes the +Ecma119Image object. + +The method IsoImageWriter.compute_data_blocks() has to predict the storage +needs in the area of directory trees. +It computes and records Joliet-specific addresses and sizes: + Ecma119Image.joliet_ndirs, Ecma119Image.joliet_l_path_table_pos, + Ecma119Image.joliet_m_path_table_pos , Ecma119Image.joliet_path_table_size + Ecma119Image.j_part_l_path_table_pos, Ecma119Image.j_part_m_path_table_pos +as well as the sizes and block addresses of Joliet directories. +It increases the counter of virtually written blocks: + Ecma119Image.curblock +which is used to determine the start addresses of the image parts and +finally gives the overall image size. + +The method IsoImageWriter.write_vol_desc() composes and writes the Joliet +volume descriptor. (Such writing is not necessarily needed for add-on +filesystems.) + +IsoImageWriter.write_data() writes the records of the Joliet directory tree. +This has to be exactly the same number of blocks by which Ecma119Image.curblock +was increased during IsoImageWriter.compute_data_blocks(). +When it gets called, the number of content data extents, their sizes, and their +addresses are known: JolietNode.IsoFileSrc->nsections, ->sections[].size, +->sections[].block. +struct iso_file_section is defined in libisofs/libisofs.h. + +IsoImageWriter.free_data() disposes the writer and the JolietNode tree. + + +------------------------------------------------------------------------------- + +This text is under +Copyright (c) 2012 Thomas Schmitt +It shall only be modified in sync with libisofs. Please mail change requests to +mailing list or to the copyright holder in private. +f you make use of the license to derive modified versions of libisofs then +you are entitled to modify this text under that same license. +