» WIT: Wiimms ISO Tools » wit: Wiimms ISO Tool » wit mix

# wit mix

Mix the partitions from different sources into one new Wii or GameCube disc.

## 1. Syntax

    wit MIX SOURCE... --dest|--DEST outfile
      where SOURCE    = infile [QUALIFIER]...
      where QUALIFIER = 'select' part_type
    		  | 'as' [part_table '.'] [part_type]
    		  | 'ignore' ruleset
    		  | 'header'
    		  | 'region'

## 2. Options

Options
Option | Param | Description
--- | --- | ---
`-t` | `--test` |  | Run in test mode, modify nothing. >>> USE THIS OPTION IF UNSURE! <<<
`-d` | `--dest` | path | Define a destination path (directory or file). The destination path is scanned for escape sequences (see option --esc) to allow generic paths.
`-D` | `--DEST` | path | Like --dest, but create the directory path automatically.
`-E` | `--esc` | char | Define an alternative escape character for destination files. The default is '%'. For Windows (CYGWIN) it is a good choice to set '-E$' to avoid conflicts with command shell variables.
`-o` | `--overwrite` |  | Overwrite already existing files without warning.
| `--auto-split` |  | Enable auto split modus: Split only if necessary and determine the split size automatically. THIS OPTION IS EXPERIMENTAL. In future versions it becomes the default.
| `--no-split` |  | Disable output file splitting. This is the default, but in future versions, the new option --auto-split becomes the default.
`-z` | `--split` |  | Enable output file splitting. The default split size is 4 GB.
`-Z` | `--split-size` | sz | Enable output file splitting and define a split size. The parameter 'sz' is a floating point number followed by an optional unit factor (one of 'cb' [=1] or 'kmgtpe' [base=1000] or 'KMGTPE' [base=1024]). The default unit is 'G' (GiB).
| `--disc-size` | size | Define a minimal (virtual) ISO disc size.
| `--prealloc` | [=mode] | This option enables or disables the disc space preallocation. If enabled the tools try to allocate disc space for the new files before writing the data. This reduces the fragmentation but also disables the sparse effect for preallocated areas. The optional parameter decides the preallocation mode: OFF (or 0), SMART (or 1), ALL (or 2). If no parameter is set, ALL is used. Mode 'OFF' disables the preallocation. Mode 'SMART' looks into the source disc to find out the writing areas. SMART is only available for ISO, CISO and WBFS file types. For other file types ALL is used instead. Mode 'ALL' (the default) preallocate the whole destination file. Because of the large holes in plain ISO images, the SMART mode is used for ISOs instead.
| `--trunc` |  | Truncate PLAIN ISO and WBFS images after creating or copying to the minimal needed size with respect to the block size.
| `--chunk-mode` | mode | Defines an operation mode for --chunk-size and --max-chunks. Allowed keywords are 'ANY' to allow any values, '32K' to force chunk sizes with a multiple of 32 KiB, 'POW2' to force chunk sizes >=32K and with a power of 2 or 'ISO' for ISO images (more restrictive as 'POW2', best for USB loaders). The case of the keyword is ignored. The default key is 'ISO'. --chm is a shortcut for --chunk-mode.
| `--chunk-size` | sz | Define the minimal chunk size if creating a CISO or WIA file (for WIA details see option --compression}). The default is to calculate the chunk size from the input file size and find a good value by using a minimal value of 1 MiB for »--chunk-mode ISO« and 32 KiB for modes 32K and POW2. For the modes ISO and POW2 the value is rounded up to the next power of 2. This calculation also depends from option --max-chunks. The parameter 'sz' is a floating point number followed by an optional unit factor (one of 'cb' [=1] or 'kmgtpe' [base=1000] or 'KMGTPE' [base=1024]). The default unit is 'M' (MiB). If the number is prefixed with a '=' then options --chunk-mode and --max-chunks are ignored and the given value is used without any rounding or changing. If the input file size is not known (e.g. reading from pipe), its size is assumed as 12 GiB. --chs is a shortcut for --chunk-size.
| `--max-chunks` | n | Define the maximal number of chunks if creating a CISO file. The default value is 8192 for »--chunk-mode ISO« and 32760 (maximal value) for all other modes. If this value is set than the automatic calculation of --chunk-size will be modified too. --mch is a shortcut for --max-chunks.
| `--compression` | mode | Select one compression method, level and chunk size for new WIA files. The syntax for mode is: [method] [.level] [@factor] 'method' is the name of the method. Possible compressions method are NONE, PURGE, BZIP2, LZMA and LZMA2. There are additional keywords: DEFAULT (=LZMA.5@20), FAST (=BZIP2.3@10), GOOD (=LZMA.5@20) BEST (=LZMA.7@50), and MEM (use best mode in respect to memory limit set by --mem). Additionally the single digit modes 0 (=NONE), 1 (=fast LZMA) .. 9 (=BEST)are defined. These additional keywords may change their meanings if a new compression method is implemented. '.level' is a point followed by one digit. It defines the compression level. The special value .0 means: Use default compression level (=.5). '@factor' is a factor for the chunk size. The base size is 2 MiB. The value @0 is replaced by the default factor @20 (40 MiB). If the factor is not set but option --chunk-size is set, the factor will be calculated by using a rounded value of that option. All three parts are optional. All default values may be changed in the future. --compr is a shortcut for --compression and --wia=mode a shortcut for »--wia --compression mode«. The command »wit COMPR« prints an overview about all compression modes.
| `--mem` | size | This option defines a memory usage limit for compressing files (in MiB if no other unit is entered). When compressing a file with method MEM (see --compression) the the compression method, level and chunk size are selected with respect to this limit. If this option is not set or the value is 0, then the environment WIT_MEM is tried to read instead. If this fails, the tool tries to find out the total memory by reading /proc/meminfo. The limit is set to 80% of the total memory minus 50 MiB.
| `--align-part` | size | The beginning of each partition is set to an offset that is a multiple of the align size. Size must be a power of 2 and at least 32 KiB (=default). If option --overlay is set only the first partition is aligned.
`-W` | `--wdf` | [=param] | Set the image output file type to WDF (Wii Disc Format). The output format is either WDFv1 or WDFv2 (default). It depends of the input file format and of the aligning. --wdf=param is a short cut for »--wdf --align-wdf=param«.
| `--wdf1` | [=param] | Set image output file type to WDF and force version 1. --wdf1=param is a short cut for »--wdf1 --align-wdf=param«.
| `--wdf2` | [=param] | Set image output file type to WDF and force version 2. --wdf2=param is a short cut for »--wdf2 --align-wdf=param«.
| `--align-wdf` | [align][,minhole] | Parameter align defines the aligning factor for new WDF images. It must be a power of 2 and smaller or equal than 1 GiB. The default WDF alignment is 1 for WDF v1 and 4 for WDF v2. Usual values are 1, 512, 4K and 32K. The optional parameter minhole defines the minimal hole size, before a new chunk is created. If NULL, an internal value is used to minimize the total file size. minhole can't be smaller than align.
`-I` | `--iso` |  | Set image output file type to PLAIN ISO.
`-C` | `--ciso` |  | Set image output file type to CISO (Compact ISO, same as WBI).
`-B` | `--wbfs` |  | Set image output file type to WBFS (Wii Backup File System, default).
| `--id` | id | Define an ID for the disc header. The default is 'WIT000'.
| `--name` | name | Define a disc title for the disc header. The default is a generic title based on all sources.
| `--region` | region | This patching option defines the region of the disc. The region is one of JAPAN, USA, EUROPE, KOREA, FILE or AUTO (default). The case of the keywords is ignored. Unsigned numbers are also accepted.
| `--overlay` |  | Most partitions have holes (unused areas) in the data section. If combining multiple partitions into one disc it is possible to overlay the partitions so that the data of one partition resides in the hole of other partitions. This option enables this feature. It also limits the number of input partitions to 12, because the calculation is rated as O(2N). 12 partitions can be combined in 479 millions permutations and all are tested with a back tracking algorithm to find the best one.

## 3. Description

With wit MIX you can mix different partitions of different Wii discs into a new Wii disc image. The MIX command copies the partitions 1:1 so that there is no need to fake sign the partitions; the original sign of the source is unchanged.

To copy 2 or more DATA partitions together just type:
»wit MIX image1 image2 image3 --dest result.iso«

The output format can be selected by option or filename. See »Writing an image« for details.

To view what command MIX would to without creating a image use the option --test.

Use the option --id the set the disc id. The default id is WIT000. Use the option --name the set the disc name. The default disc name is a generic name that contains the IDs of all source images. See »Qualifier header« for additional information.

Use the option --region the set the disc region. The default region is generated from the ID. See »Qualifier region« for additional information.

wit MIX warns the user if the filename do not contain a slash ('/') or a point ('.'). This is because words without slash and points are reserved for qualifiers. In the moment 3 qualifiers are supported: 'select', 'psel' and 'as'.

The order of the following qualifiers does not care.

## 4. Qualifier 'select' or 'psel'

    Snytax: select mode
        or: psel   mode

'select' and 'psel' are keywords in any case. mode is a comma separated list of keywords and numbers. It has the same syntax and semantic like the option --psel. Both qualifiers 'select' and 'psel' are identical. The user can select which source partition should be used.

If the parameter list should start with a minus sign ('-'), prefix it with a comma to prevent the detection as an option.

A later 'select' overrides the previous ones. The default is to select only DATA (type=0) partitions.

## Examples

»wit MIX image1 select upd,data image2 --dest outimage.wdf«
This command mix the UPDATE and DATA partition of image1 and the DATA partition of image2. The output is written to the WDF file outimage.wdf.

»wit MIX image1 select ,-upd image2 --dest outimage.iso«
This command mix all non UPDATE partitions of image1 and the DATA partition of image2. The leading comma of the select parameter prevents the detection as an option. The output is written to the PLAIN ISO file outimage.iso.

## 5. Qualifier 'as'

    Snytax: as ptab.
        or: as ptype
        or: as ptab.ptype

'as' is a keyword in any case. ptab is a number between 0 and 3 to select the destination partition table. It is standard to use partition table #0. ptype is the new partition type. You can use the keywords 'DATA', 'UPDATE' or 'CHANNEL' in any case and as abbreviation, or a number or as an ID with 4 alphanumeric characters.

Without the qualifier 'as' a source partition ist stored in the same partition table and with the same partition type as the source. In other words: An UPDATE partition placed in partition table #2 is stored as UPDATE partition in partition table #2 again. The qualifer 'as' can override this default setting. A later 'as' overrides the previous ones.

## Examples

»wit mix image1 as chan --dest outimage.wdf«
This command will get the DATA partition of image1 and stores it as CHANNEL partition. The output is written to the WDF file outimage.wdf.

»wit mix image1 select udpate as data --dest outimage.ciso«
This command will get the UPDATE partition of image1 and stores it as DATA partition. The output is written to the CISO file outimage.ciso.

## 6. Qualifier 'ignore'

    Snytax: ignore ruleset

'ignore' is a keyword in any case. ruleset is a list of rules described in »File Filters«. The qualifier works in the same way as the option --ignore-files. Each appearence of 'ignore' append more rules to the internal rule list.

When copying in scrubbing mode the system checks which sectors are used by a file. Each system and real file of the FST ('sys/...' and 'files/...') of the first DATA partition, that matches the rule set, is ignored for this sector search.

This means that the partition becomes invalid, because the content of some files is not copied. If such file is accessed the Wii will halt immediately, because the verification of the checksum calculation fails.

The advantage is to reduce the size of the image without a need to fake sign the partition. Use this qualifier in combination with option --overlay to create tricky combinations of partitions. It may help to reduce the size of the output image dramatically.

## Examples

»wit mix image1 ignore .wad --dest outimage.wdf«
Copy the DATA partition of image1 to the WDF file outimage.wdf and ignore all '*.wad' files.

»wit mix image1 ignore "@ignorefile" --dest outimage.wdf«
Copy the DATA partition of image1 to the WDF file outimage.wdf and read file ignorefile for ignore rules.

Use the command »wit dump image1 --show usage --ignore-files ruleset« to test the scrubbing result of the ignore qualifier.

## 7. Qualifier 'header'

    Snytax: header

'header' is a keyword in any case. This qualifier can only used once. Multiple usage results in an error.

If set the disc header (first 256 bytes of the dics) are copyied from the related source image to the destination image. The automatic creation of ID and disc title is disabled. The patching options --id and --name can still override the ID and/or the disc title.

## 8. Qualifier 'region'

    Snytax: region

'region' is a keyword in any case. This qualifier can only used once. Multiple usage results in an error.

If set the region info (32 bytes at disc offset 0x4e000) are copyied from the related source image to the destination image. The automatic creation of the region info is disabled. The patching option --region can still override the region.

## 9. --overlay

Most partitions have holes (unused areas) in the data section. If combining multiple partitions into one disc it is possible to overlay the partitions so that the data of one partition resides in the hole of other partitions. This option enables this feature. It also limits the number of input partitions to 12, because the calculation is rated as O(2N). 12 partitions can be combined in 479 millions permutations and all are tested with a back tracking algorithm to find the best one.
Most partitions have holes (unused areas) in the data section. If copying data in scrubbed mode, these holes are not copied and the destination image is automatically filled with zero (sparse effect).

When mixing partitions, the source partitions are stored one behind the other and the total size of the output image becomes very large and exceeds sometimes the maximum allowed size.

The idea: Use the hole of one partition to store data of the other partitions. Option --overlay enabled this method.

There are two overlay alogithm implemented:

1. The first algorithm works only for two partitions. All holes of both partitions are used to find the optimal overlay. Both partitions are shifted until the smallest total image size is found.
2. The second algorithm works with any number of partitions. It find out the largest hole of each partition. Then it try will try all permutations of all source partitions to find the order with the smallest total image size.

   There are N! (=1*2*3*...*N) permutations for N source partitions. For 5 partitions there are 120 permutations and for 10 partitions there are 3 628 800 permutations. Because this large number of permutations the number of input partitions is limited to 12.

To view the effect of the --overlay option without creating a image use the option --test. If set twice an usage map is printed too.

### Command reference

»wit mix«.

## 10. Verification

Before creating the image a additional verify function is called automatically. This function controls that no sector is used by more than one partition. If the verification fails, wit terminates with an INTERNAL ERROR. This prevents the creation of a buggy Wii disc image.

With verbose level (--verbose) >=3 or test level (--test) >=2 an usage map is printed too.

## 11. Usual error/exit codes:

    0 == OK        : all done without errors.
    WARNING        : a filename without '/' or '.' was used.
    SYNTAX ERROR   : at least one syntax error in command line found.
    SEMANTIC       : error in number of selected partitions.
    READ ERROR     : error while reading a file.
    WRITE ERROR    : error while writing a file.
    CANT CREATE    : Can't create output file. (WBFS output is not supported)
    INTERNAL ERROR : Internal verification test failed.