sigrok-fwextract-kingst-la2016: rephrase resource file writer

[sigrok-util.git] / firmware / kingst-la / sigrok-fwextract-kingst-la2016

diff --git a/firmware/kingst-la/sigrok-fwextract-kingst-la2016 b/firmware/kingst-la/sigrok-fwextract-kingst-la2016
index a5832184577a9f661a559925cb122f19b72cd919..3575b04928a7989523ac69da288aa8e543cae7a2 100755 (executable)
--- a/firmware/kingst-la/sigrok-fwextract-kingst-la2016
+++ b/firmware/kingst-la/sigrok-fwextract-kingst-la2016
@@ -18,14 +18,20 @@
 ## along with this program; if not, see <http://www.gnu.org/licenses/>.
 ##
 
+# This utility extracts FX2 MCU firmware and FPGA bitstream images from
+# the "KingstVIS" vendor software. The blobs are kept in Qt resources
+# sections. The script was tested with several v3.5 software versions.
+
+import argparse
 import os
 import sys
 import re
 import struct
 import codecs
 import importlib.util
+import zlib
 
-# reuse parseelf.py module from saleae-logic16:
+# Reuse the parseelf.py module from saleae-logic16.
 fwdir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 parseelf_py = os.path.join(fwdir, "saleae-logic16", "parseelf.py")
 spec = importlib.util.spec_from_file_location("parseelf", parseelf_py)
@@ -56,7 +62,7 @@ class qt_resources(object):
                 sname, sym["st_size"], len(value)))
         return value
 
-    # qt resource stuff:
+    # Qt resource stuff.
     def _get_resource_name(self, offset):
         length, i = struct.unpack(">HI", self._res_names[offset:offset + 2 + 4])
         offset += 2 + 4
@@ -123,30 +129,34 @@ class res_writer(object):
     def __init__(self, res):
         self.res = res
 
-    def _write_file(self, fn, data, decoder=None, zero_pad_to=None):
+    def _decode_crc(self, data, decoder=None):
         if decoder is not None:
             data = decoder(data)
-        if zero_pad_to is not None:
-            if len(data) > zero_pad_to:
-                raise Exception("can not zero_pad_to %d bytes -- data is already %d bytes" % (zero_pad_to, len(data)))
-            data += b"\0" * (zero_pad_to - len(data))
+        data = bytearray(data)
+        crc = zlib.crc32(data) & 0xffffffff
+        return data, crc
+
+    def _write_file(self, fn, data):
         with open(fn, "wb") as fp:
             fp.write(data)
-        print("saved %d bytes to %s" % (len(data), fn))
-
-    def extract(self, res_fn, out_fn, decoder=None, zero_pad_to=None):
-        self._write_file(out_fn, self.res.get_resource(res_fn), decoder=decoder, zero_pad_to=zero_pad_to)
 
-    def extract_re(self, res_fn_re, out_fn, decoder=None):
-        for res_fn in res.find_resource_names(res_fn_re):
-            fn = re.sub(res_fn_re, out_fn, res_fn).lower()
-            self._write_file(fn, self.res.get_resource(res_fn), decoder=decoder)
+    def extract_re(self, resource_pattern, fname_pattern, decoder=None):
+        resources = sorted(res.find_resource_names(resource_pattern))
+        for resource in resources:
+            fname = re.sub(resource_pattern, fname_pattern, resource)
+            fname = fname.lower()
+            data = self.res.get_resource(resource)
+            data, crc = self._decode_crc(data, decoder=decoder)
+            self._write_file(fname, data)
+            print("resource {rsc}, file {fname}, size {size}, checksum {crc:08x}".format(
+                rsc = resource, fname = fname, size = len(data), crc = crc,
+            ))
 
 def decode_intel_hex(hexdata):
     """ return list of (address, data)
     """
     datas = []
-    # assume \n or \r\n*
+    # Assume LF-only or CR-LF style end-of-line.
     for line in hexdata.split(b"\n"):
         line = line.strip()
         if chr(line[0]) != ":": raise Exception("invalid line: %r" % line)
@@ -182,15 +192,23 @@ def intel_hex_as_blob(hexdata):
 def maybe_intel_hex_as_blob(data):
     if data[0] == ord(":") and max(data) < 127:
           return intel_hex_as_blob(data)
-    return data # keep binary data
+    return data # Keep binary data.
 
 if __name__ == "__main__":
-    if len(sys.argv) != 2:
-        print("sigrok-fwextract-kingst-la2016 <programfile>")
-        sys.exit()
-
-    res = qt_resources(sys.argv[1])
+    parser = argparse.ArgumentParser(description = "KingstVIS firmware extraction")
+    parser.add_argument('executable', help = "KingstVIS executable file")
+    options = parser.parse_args()
+    exe_fn = options.executable
 
+    res = qt_resources(exe_fn)
     writer = res_writer(res)
-    writer.extract("fwfpga/LA2016A", "kingst-la2016a-fpga.bitstream")
+
+    # Extract all MCU firmware and FPGA bitstream images. The sigrok
+    # project may not cover all KingstVIS supported devices. Users can
+    # either just copy those files which are strictly required for their
+    # specific device (diagnostics will identify those). Or just copy a
+    # few more files while some of them remain unused later (their size
+    # is small). Seeing which files would be contained is considered
+    # valuable, to identify device variants or candidate models.
     writer.extract_re(r"fwusb/fw(.*)", r"kingst-la-\1.fw", decoder=maybe_intel_hex_as_blob)
+    writer.extract_re(r"fwfpga/(.*)", r"kingst-\1-fpga.bitstream")