From c3b0fa04a663fe233765b83d3be41a42aa08c25d Mon Sep 17 00:00:00 2001 From: "Juan J. Martinez" Date: Mon, 3 May 2021 08:21:10 +0100 Subject: Initial import for public release --- tools/hex2bin-2.0/doc/README | 225 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 tools/hex2bin-2.0/doc/README (limited to 'tools/hex2bin-2.0/doc/README') diff --git a/tools/hex2bin-2.0/doc/README b/tools/hex2bin-2.0/doc/README new file mode 100644 index 0000000..78ee7e7 --- /dev/null +++ b/tools/hex2bin-2.0/doc/README @@ -0,0 +1,225 @@ +Yet Another Hex to bin converter + +It can handle the extended Intel hex format in segmented and linear address +modes. Records need not be sorted and there can be gaps between records. + +Some hex files are produced by compilers. They generate objects files for each +module in a project, and when the linker generates the final hex file, the +object files are stored within the hex files, but modules can appear not +necessary in order of address. + +How does it work? + +Hex2bin/mot2bin allocates a 4 MBytes buffer and just place the converted bytes +in its buffer. At the end, the buffer is written to disk. Using a buffer elimi- +nates the need to sort records. If the option l is used (3), the buffer will be +allocated with the maximum size specified if over 4Mbytes. + +Before reading the hex file, the buffer is filled with a default value. These +padding bytes are all FF by default so an EPROM programmer can skip these bytes +when programming. The padding value can be changed with the -p option. + +1. Compiling on Linux or other unix platforms + + make + + then + + make install + + This will install the program to /usr/local/bin. + +1a. Compiling for Windows on Msys, Cygwin or DOS prompt + + The programs can be compiled as follows: + gcc -O2 -Wall -o hex2bin.exe hex2bin.c common.c libcrc.c binary.c + gcc -O2 -Wall -o mot2bin.exe mot2bin.c common.c libcrc.c binary.c + +2. Using hex2bin + + hex2bin example.hex + + hex2bin will generate a binary file example.bin starting at the + lowest address in the hex file. + +3. Binary file starting address and length + + If the lowest address isn't 0000, + ex: 0100: (the first record begins with :nn010000xxx ) + + there will be problems when using the binary file to program a EPROM + since the first byte supposed to be at 0100 is stored in the binary file + at 0000. + + you can specify a starting address for the binary file on the command line: + + hex2bin -s 0000 start_at_0100.hex + + This start address is not the same thing as the start address record in + the hex file. The start address record is used to specify the starting + address for execution of the binary code. + + The bytes will be stored in the binary file with a padding from 0000 + to the lowest address minus 1 (00FF in this case). + + Similarly, the binary file can be padded up to Length -1 with FF or another byte. + + Here, the space between the last byte and 07FF will be filled with FF. + hex2bin -l 0800 ends_before_07FF.hex + + EPROM, EEPROM and Flash memories contain all FF when erased. + + This program does minimal error checking since many hex files are + generated by known good assemblers. + + When the source file name is + for-example.test.hex + the binary created will have the name + for-example.bin + the ".test" part will be dropped. + + Hex2bin/mot2bin assume the source file doesn't contain overlapping records, + if so, overlaps will be reported. + +4. Checksum of source file + + By default, it ignores record checksum errors, so that someone can change + by hand some bytes allowing quick and dirty changes. + If you want checksum error reporting, specify the option -c. + + hex2bin -c example.hex + + If there is a record checksum error somewhere, the program will continue the + conversion anyway. + + The example file example.hex contains some records with checksum errors. + +5. Check value inserted inside binary file + + A check value can be inserted in the resulting binary file. + + hex2bin -k [0-4] -r [start] [end] -f [address] -C [Poly] [Init] [RefIn] [RefOut] [XorOut] + + -k Select the check method: + 0: Checksum 8-bit + 1: Checksum 16-bit + 2: CRC8 + 3: CRC16 + 4: CRC32 + + -r Range to compute checksum over (default is min and max addresses) + + -f Address of the result to write + + -C Parameters for CRC + Parameters for common CRCs are listed in doc/CRC list.txt. They appear in + the same order. Feed them as is and use t for TRUE, f for FALSE. + + See also the test/Makefile for these common CRCs; since they're tested, + you'll have the command line figured out. + + -E Endian for storing the check result or forcing it + 0: little + 1: big + + Change from previous versions of hex2bin/mot2bin: + Replace former options to this version + -k 1 -> -k 1 -E 0 + -k 2 -> -k 1 -E 1 + +6. Value inserted directly inside binary file + Instead of calculating a value, it can be inserted directly into the file at a specified address. + + hex2bin -k [0|1|2] -F [address] [value] + + -k Select the value format: + + 0 = 8-bit + 1 = 16-bit + 2 = 32-bit + + -F Address and value of checksum to force + + -E Endian for storing the check result or forcing it + 0: little + 1: big + +7. Motorola S files + + mot2bin example.s19 + + Options for mot2bin are the same as hex2bin. Executing the program + without argument will display available options. Some are specific to + Motorola files. + + This program will handle S19 files generated for Motorola micropro- + cessors. Since I use this program for an EPROM programmer, I will + rarely need to have more than 4M, I limited the source program for + 24 bits or 16 bits address records. + + 32 bits records are now supported, but obviously I can't allocate all + the memory for the binary target. What I did is simply assume that the + binary file will occupy less than 4M. For binary files greater than 4M, + see length option (section 3). + +8. Support for byte-swapped hex/S19 files + + -w Wordwise swap: for each pair of bytes, exchange the low and high part. + If a checksum needs to be generated to insert in the binary file, select + one of the 16-bit checksums. + + hex2bin -w test-byte-swap.hex + +9. Goodies + + Description of the file formats is included. + Added examples files for extended addressing. + + Check for overlapping records. The check is rather basic: supposing + that the buffer is filled with pad bytes, when a record overlaps a + previous one, value in the buffer will be different from the pad bytes. + This will not detect the case when the previous value equals the pad byte, + but it's more likely that more than one byte will be overlapped. + + +10. Error messages + + "Can't allocate memory." + + Can't do anything in this case, so the program simply exits. + + "Error occurred while reading from file" + + Problem with fgets. + + "Input/Output file %s cannot be opened. Enter new filename: " + + The user may not have permissions to open the file. + + "0 byte length data record ignored" + + This means that an empty data record was read. Since it's empty, it's simply + ignored and should have no impact on the binary file. + + "Data record skipped at ..." + + This means that the records are falling outside the memory buffer. + + "Overlapped record detected" + + A record is overwritten by a subsequent record. If you're using SDCC, check + if more than one area is specified with a starting address. Checking the map + file generated by the linker can help. + + "Some error occurred when parsing options." + + + +11. History + + See ChangeLog + +12. Other hex tool + + There is a program that supports more formats and has more features. + See SRecord at http://srecord.sourceforge.net/ -- cgit v1.2.3