Skip to content

Latest commit

 

History

History
234 lines (162 loc) · 7.58 KB

index.rst

File metadata and controls

234 lines (162 loc) · 7.58 KB
Raw

Binary delta encoding utility

Patch types

Sequential ------

A sequential patch uses two memory regions or files. One contains the from-data and the to-data is written to the other. The patch is accesses sequentially from the beginning to the end when applying the patch.

$ detools create_patch tests/files/foo.old tests/files/foo.new foo.patch

Patch layout:

header diff 1 extra 1 adj. 1 diff 2 extra 2 adj. 2 ...

The first part of the header is not compressed. The rest of the patch is compressed.

HDiffPatch

Patches of this type are slightly smaller than sequential patches.

$ detools create_patch --patch-type hdiffpatch \
    tests/files/foo.old tests/files/foo.new foo.patch

Patch layout:

header covers RLE diff control RLE diff code extra

The header is not compressed. The other four parts are compressed separately.

In-place

The in-place patch type is designed to update an application in place. It is useful when flash operations are faster than the external interface transfer speed.

Use create_patch_in_place to create an in-place patch. The to options --memory-size and --segment-size are required, while --minimum-shift-size is optional.

$ detools create_patch --type in-place --memory-size 131072 --segment-size 32768 \
      tests/files/foo.old tests/files/foo.new foo.patch

Here is an example of an in-place application update from version 1 to version 2. The two applications are represented by the character sequences below for clarity.

Version 1: 0123456789abcdefghijklmnopqr
Version 2: ABCDEFGHIJKLMNOPQRSTUVWXYZstuvwxyz

  1. Before the update application version 1 is found in memory segments 0 to 3.

    0       1       2       3       4       5
    01234567 89abcdef ghijklmn opqr|

  2. The update starts by moving the application two segments to the right to make room for the new version.

    0       1       2       3       4       5
    01234567 89abcdef ghijklmn opqr|

  3. The first part of the patch is received and combined with application version 1. The combined data is written to segment 0.

    0       1       2       3       4       5
    ABCDEFG 01234567 89abcdef ghijklmn opqr|

  4. Same as the previous step, but the combined data is written to segment 1.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNO 01234567 89abcdef ghijklmn opqr|

  5. Segment 2 is erased to make room for the next part of the patch.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNO 89abcdef ghijklmn opqr|

  6. Combined data written to segment 2.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNOP QRSTUVW 89abcdef ghijklmn opqr|

  7. Segment 3 is erased.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNOP QRSTUVW ghijklmn opqr|

  8. Combined data written to segment 3.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNOP QRSTUVWX YZstuvw ghijklmn opqr|

  9. Segment 4 is erased.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNOP QRSTUVWX YZstuvw opqr|

  10. Combined data written to segment 4.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNOP QRSTUVWX YZstuvwx yz| opqr|

  11. Optionally, segment 5 is erased.

    0       1       2       3       4       5
    ABCDEFGH IJKLMNOP QRSTUVWX YZstuvwx yz|
  12. Update to application version 2 complete!

An interrupted in-place update can be resumed by introducing a step state, persistentely stored in a separate memory region. Also store the patch header persistentely. Reject any other patch until the currently active patch has been successfully applied.

0       1       2       3       4       5
01234567 89abcdef ghijklmn opqr|
Step: 0
01234567 89abcdef ghijklmn opqr| opqr| | Step: 1
01234567 89abcdef ghijklmn opqr| ghijklmn opqr| | Step: 2
01234567 89abcdef ghijklm 89abcdef ghijklmn opqr| | Step: 3
01234567 89abcde 01234567 89abcdef ghijklmn opqr| | Step: 4
ABCDEFG7 89abcde 01234567 89abcdef ghijklmn opqr| | Step: 5
ABCDEFGH IJKLMNO 01234567 89abcdef ghijklmn opqr| | Step: 6
ABCDEFGH IJKLMNOP QRSTUVW 89abcdef ghijklmn opqr| | Step: 7
ABCDEFGH IJKLMNOP QRSTUVWX YZstuvw ghijklmn opqr| | Step: 8
ABCDEFGH IJKLMNOP QRSTUVWX YZstuvwx yz| opqr| | Step: 9

Functions and classes

detools.create_patch

detools.apply_patch

detools.apply_patch_in_place

detools.patch_info

detools.create_patch_filenames

detools.apply_patch_filenames

detools.apply_patch_in_place_filenames

detools.patch_info_filename