From 64bb2f30c63130d91dd9f7ad4ebc71ebea504eb4 Mon Sep 17 00:00:00 2001 From: Kimmo Kulovesi Date: Wed, 7 Aug 2019 20:33:29 +0300 Subject: [PATCH] Update documentation --- Makefile | 4 +- Makefile.avr | 4 +- README.md | 25 +++++++- bin2ihex.1 | 158 ++++++++++++++++++++++++------------------------ bin2ihex.c | 4 +- ihex2bin.1 | 156 +++++++++++++++++++++++------------------------ kk_ihex.h | 2 +- kk_ihex_read.h | 2 +- kk_ihex_write.h | 2 +- merge16bit.1 | 108 ++++++++++++++++----------------- split16bit.1 | 110 ++++++++++++++++----------------- 11 files changed, 300 insertions(+), 275 deletions(-) diff --git a/Makefile b/Makefile index da6c841..3707708 100644 --- a/Makefile +++ b/Makefile @@ -13,8 +13,6 @@ TESTFILE = $(LIB) TESTER = #TESTER = valgrind -.PHONY: all clean distclean test - all: $(BINS) $(LIB) $(OBJS): kk_ihex.h @@ -41,6 +39,8 @@ $(BINPATH)merge16bit: merge16bit.c $(sort $(BINPATH) $(LIBPATH)): @mkdir -p $@ +.PHONY: all clean distclean test + test: $(BINPATH)bin2ihex $(BINPATH)ihex2bin $(TESTFILE) @$(TESTER) $(BINPATH)bin2ihex -v -a 0x80 -i '$(TESTFILE)' | \ $(TESTER) $(BINPATH)ihex2bin -A -v | \ diff --git a/Makefile.avr b/Makefile.avr index ee50241..fdbea05 100644 --- a/Makefile.avr +++ b/Makefile.avr @@ -12,8 +12,6 @@ OBJS = $(OBJPATH)kk_ihex_write.o $(OBJPATH)kk_ihex_read.o LIBPATH = ./avr/ LIB = $(LIBPATH)libkk_ihex.a -.PHONY: all clean distclean test - all: $(LIB) $(OBJS): kk_ihex.h @@ -29,6 +27,8 @@ $(OBJPATH)%.o: %.c %.h $(sort $(LIBPATH) $(OBJPATH)): @mkdir -p $@ +.PHONY: all clean distclean + clean: rm -f $(OBJS) @rmdir $(OBJPATH) >/dev/null 2>/dev/null || true diff --git a/README.md b/README.md index 6e30d54..9b671f3 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ rather than features, generality, or error handling. See the header file `kk_ihex.h` for documentation, or below for simple examples. -~ [Kimmo Kulovesi](http://arkku.com/), 2013-12-27 +~ [Kimmo Kulovesi](https://arkku.com/), 2013-12-27 Writing ======= @@ -94,6 +94,9 @@ Usage by example: # of the first byte of the input other than zero): bin2ihex -a 0x8000000 -i infile.bin -o outfile.hex + # Encode 64 input bytes per output IHEX line: + bin2ihex -b 64 outfile.hex + # Simple conversion from IHEX to binary: ihex2bin outfile.bin @@ -113,3 +116,23 @@ the address offset. Otherwise the program will simply fill any unused addresses, starting from 0, with zero bytes, which may total mega- or even gigabytes. + +Utilities +========= + +Two additional utilities are provided to help working with ROM images: + +* `split16bit` – splits a 16-bit ROM binary into two 8-bit halves +* `merge16bit` – merges two 8-bit ROM binary halves into a single 16-bit file + +Both of these take the filenames of the high and low halves with the +arguments `-l low.bin` and `-h high.bin`, respectively. For example: + + # Split 16bit.bin into low.bin and high.bin: + split16bit -i 16bit.bin -l low.bin -h high.bin + + # Merge low.bin and high.bin into 16bit.bin: + merge16bit -o 16bit.bin -l low.bin -h high.bin + +These utilities have nothing to with IHEX as such, but they are so small that +it didn't seem worth the bother to release them separately. diff --git a/bin2ihex.1 b/bin2ihex.1 index 700578d..44d8cc8 100644 --- a/bin2ihex.1 +++ b/bin2ihex.1 @@ -1,79 +1,79 @@ -.Dd August 7, 2019 -.Dt bin2ihex 1 -.Os kk_ihex -.Sh NAME -.Nm bin2ihex -.Nd Convert binary data to Intel HEX -.Sh SYNOPSIS -.Nm -.Op Fl a Ar address_offset -.Op Fl i Ar input_file.bin -.Op Fl o Ar output_file.hex -.Op Fl v -.Sh DESCRIPTION -.Nm -reads binary data from standard input and writes the Intel HEX encoded -data to standard output. -.Sh OPTIONS -.Bl -tag -width -indent -.It Fl a Ar address_offset -Set the address of the first input byte to -.Ar address_offset -(default 0) -.It Fl i Ar file -Read the binary input from -.Ar file -instead of standard input -.It Fl o Ar file -Write the Intel HEX output to -.Ar file -instead of standard output -.It Fl b Ar length -Set each output line to be formed by encoding -.Ar length -input bytes into IHEX (default 32) -.It Fl v -Print extra status messages to standard error -.El -.Sh EXAMPLES -Read binary data from -.Ar input.bin -and write the Intel HEX output to -.Ar output.hex -.Pp -.Bd -ragged -offset indent -.Nm -.Fl i -.Ar input.bin -.Fl o -.Ar output.hex -.Ed -.Pp -Read binary data from -.Ar input.bin -and write the Intel HEX output to -.Ar output.hex -such that the first byte of the input will have the address -.Ar 0x8000000 -in the output (e.g., for creating an image with the correct addresses for flashing -to a ROM): -.Bd -ragged -offset indent -.Nm -.Fl a -.Ar 0x8000000 -.Fl i -.Ar input.bin -.Fl o -.Ar output.hex -.Ed -.Pp -Note that the address offset does not make the resulting output significantly -larger, but conversion back to binary with -.Xr ihex2bin 1 -must be done with the same -.Fl a -argument to obtain a binary file identical to the original. -.Sh SEE ALSO -.Xr ihex2bin 1 -.Sh AUTHOR -.An "Kimmo Kulovesi" Aq https://arkku.com +.Dd August 7, 2019 +.Dt bin2ihex 1 +.Os kk_ihex +.Sh NAME +.Nm bin2ihex +.Nd Convert binary data to Intel HEX +.Sh SYNOPSIS +.Nm +.Op Fl a Ar address_offset +.Op Fl i Ar input_file.bin +.Op Fl o Ar output_file.hex +.Op Fl v +.Sh DESCRIPTION +.Nm +reads binary data from standard input and writes the Intel HEX encoded +data to standard output. +.Sh OPTIONS +.Bl -tag -width -indent +.It Fl a Ar address_offset +Set the address of the first input byte to +.Ar address_offset +(default 0) +.It Fl i Ar file +Read the binary input from +.Ar file +instead of standard input +.It Fl o Ar file +Write the Intel HEX output to +.Ar file +instead of standard output +.It Fl b Ar length +Set each output line to be formed by encoding +.Ar length +input bytes into IHEX (default 32) +.It Fl v +Print extra status messages to standard error +.El +.Sh EXAMPLES +Read binary data from +.Ar input.bin +and write the Intel HEX output to +.Ar output.hex +.Pp +.Bd -ragged -offset indent +.Nm +.Fl i +.Ar input.bin +.Fl o +.Ar output.hex +.Ed +.Pp +Read binary data from +.Ar input.bin +and write the Intel HEX output to +.Ar output.hex +such that the first byte of the input will have the address +.Ar 0x8000000 +in the output (e.g., for creating an image with the correct addresses for flashing +to a ROM): +.Bd -ragged -offset indent +.Nm +.Fl a +.Ar 0x8000000 +.Fl i +.Ar input.bin +.Fl o +.Ar output.hex +.Ed +.Pp +Note that the address offset does not make the resulting output significantly +larger, but conversion back to binary with +.Xr ihex2bin 1 +must be done with the same +.Fl a +argument to obtain a binary file identical to the original. +.Sh SEE ALSO +.Xr ihex2bin 1 +.Sh AUTHOR +.An "Kimmo Kulovesi" Aq https://arkku.com diff --git a/bin2ihex.c b/bin2ihex.c index 493e064..2ecf10c 100644 --- a/bin2ihex.c +++ b/bin2ihex.c @@ -5,7 +5,9 @@ * output files can be specified with arguments `-i` and `-o`, * respectively. Initial address offset can be set with option * `-a` (also, `-a 0` forces output of the initial offset even - * though it is the default zero). + * though it is the default zero). The number of bytes to encode + * into a single line of output (which will be more than twice + * that length in bytes) can be given with the argument `-b`. * * Copyright (c) 2013-2019 Kimmo Kulovesi, https://arkku.com * Provided with absolutely no warranty, use at your own risk only. diff --git a/ihex2bin.1 b/ihex2bin.1 index 7a5651d..fcff8aa 100644 --- a/ihex2bin.1 +++ b/ihex2bin.1 @@ -1,78 +1,78 @@ -.Dd February 1, 2014 -.Dt ihex2bin 1 -.Os kk_ihex -.Sh NAME -.Nm ihex2bin -.Nd Convert Intel HEX encoded data to binary -.Sh SYNOPSIS -.Nm -.Op Fl a Ar address_offset | Fl A -.Op Fl i Ar input_file.hex -.Op Fl o Ar output_file.bin -.Op Fl v -.Sh DESCRIPTION -.Nm -reads Intel HEX encoded data from standard input and writes the -decoded binary data to standard output. -.Sh OPTIONS -.Bl -tag -width -indent -.It Fl a Ar address_offset -Set the address of the first byte output to -.Ar address_offset -- by default the beginning of the output is considered to be at address -0, which may cause large amounts of padding to be written if the input -data begins at an offset (e.g., a ROM address for flashing program images) -.It Fl A -Autodetect the address offset (see -.Ar -a -above), i.e., the first output byte written will have the address of the -first byte of input - this option should almost always be used! -.It Fl i Ar file -Read the Intel HEX input from -.Ar file -instead of standard input -.It Fl o Ar file -Write the binary output to -.Ar file -instead of standard output -.It Fl v -Print extra status messages to standard error -.El -.Sh EXAMPLES -Read Intel HEX from -.Ar input.hex -and write the binary output to -.Ar output.bin -such that the first byte of input is written as the first byte -of output (even if the input specifies an address offset): -.Pp -.Bd -ragged -offset indent -.Nm -.Fl A -.Fl i -.Ar input.hex -.Fl o -.Ar output.bin -.Ed -.Pp -Read Intel HEX from -.Ar input.hex -and write the binary output to -.Ar output.bin -such that the first byte of the output has address -.Ar 0x8000000 -(the beginning of the output is padded if the input data begins -at a greater address): -.Bd -ragged -offset indent -.Nm -.Fl a -.Ar 0x8000000 -.Fl i -.Ar input.hex -.Fl o -.Ar output.bin -.Ed -.Sh SEE ALSO -.Xr bin2ihex 1 -.Sh AUTHOR -.An "Kimmo Kulovesi" Aq http://arkku.com +.Dd February 1, 2014 +.Dt ihex2bin 1 +.Os kk_ihex +.Sh NAME +.Nm ihex2bin +.Nd Convert Intel HEX encoded data to binary +.Sh SYNOPSIS +.Nm +.Op Fl a Ar address_offset | Fl A +.Op Fl i Ar input_file.hex +.Op Fl o Ar output_file.bin +.Op Fl v +.Sh DESCRIPTION +.Nm +reads Intel HEX encoded data from standard input and writes the +decoded binary data to standard output. +.Sh OPTIONS +.Bl -tag -width -indent +.It Fl a Ar address_offset +Set the address of the first byte output to +.Ar address_offset +- by default the beginning of the output is considered to be at address +0, which may cause large amounts of padding to be written if the input +data begins at an offset (e.g., a ROM address for flashing program images) +.It Fl A +Autodetect the address offset (see +.Ar -a +above), i.e., the first output byte written will have the address of the +first byte of input - this option should almost always be used! +.It Fl i Ar file +Read the Intel HEX input from +.Ar file +instead of standard input +.It Fl o Ar file +Write the binary output to +.Ar file +instead of standard output +.It Fl v +Print extra status messages to standard error +.El +.Sh EXAMPLES +Read Intel HEX from +.Ar input.hex +and write the binary output to +.Ar output.bin +such that the first byte of input is written as the first byte +of output (even if the input specifies an address offset): +.Pp +.Bd -ragged -offset indent +.Nm +.Fl A +.Fl i +.Ar input.hex +.Fl o +.Ar output.bin +.Ed +.Pp +Read Intel HEX from +.Ar input.hex +and write the binary output to +.Ar output.bin +such that the first byte of the output has address +.Ar 0x8000000 +(the beginning of the output is padded if the input data begins +at a greater address): +.Bd -ragged -offset indent +.Nm +.Fl a +.Ar 0x8000000 +.Fl i +.Ar input.hex +.Fl o +.Ar output.bin +.Ed +.Sh SEE ALSO +.Xr bin2ihex 1 +.Sh AUTHOR +.An "Kimmo Kulovesi" Aq https://arkku.com diff --git a/kk_ihex.h b/kk_ihex.h index a12973a..ad744fe 100644 --- a/kk_ihex.h +++ b/kk_ihex.h @@ -98,7 +98,7 @@ * this is a fairly pointless optimisation. * * - * Copyright (c) 2013-2017 Kimmo Kulovesi, http://arkku.com/ + * Copyright (c) 2013-2019 Kimmo Kulovesi, https://arkku.com/ * Provided with absolutely no warranty, use at your own risk only. * Use and distribute freely, mark modified copies as such. */ diff --git a/kk_ihex_read.h b/kk_ihex_read.h index 047e546..1b776fd 100644 --- a/kk_ihex_read.h +++ b/kk_ihex_read.h @@ -31,7 +31,7 @@ * data bytes per line. * * - * Copyright (c) 2013-2017 Kimmo Kulovesi, http://arkku.com/ + * Copyright (c) 2013-2019 Kimmo Kulovesi, https://arkku.com/ * Provided with absolutely no warranty, use at your own risk only. * Use and distribute freely, mark modified copies as such. */ diff --git a/kk_ihex_write.h b/kk_ihex_write.h index c4e3688..7870661 100644 --- a/kk_ihex_write.h +++ b/kk_ihex_write.h @@ -65,7 +65,7 @@ * reading any IHEX file. * * - * Copyright (c) 2013-2017 Kimmo Kulovesi, http://arkku.com/ + * Copyright (c) 2013-2019 Kimmo Kulovesi, https://arkku.com/ * Provided with absolutely no warranty, use at your own risk only. * Use and distribute freely, mark modified copies as such. */ diff --git a/merge16bit.1 b/merge16bit.1 index 359cb67..8485c26 100644 --- a/merge16bit.1 +++ b/merge16bit.1 @@ -1,54 +1,54 @@ -.Dd August 7, 2019 -.Dt merge16bit 1 -.Os kk_ihex -.Sh NAME -.Nm merge16bit -.Nd Merges two 8-bit halves of a ROM image into one 16-bit file. -.Sh SYNOPSIS -.Nm -.Op Fl o Ar output16bit.bin -.Op Fl h Ar high8bit.bin -.Op Fl l Ar low8bit.bin -.Sh DESCRIPTION -.Nm -reads two raw 8-bit binary files as input, and writes alternating bytes -from the low and high input files to combine them into a single 16-bit -output binary. This is used to merge two 8-bit ROM images into a single -16-bit file. The first byte of the output is taken from the low -input file, i.e., the data is treated as little-endian. -.Sh OPTIONS -.Bl -tag -width -indent -.It Fl l Ar lowfile -Read the low half of the input from -.Ar lowfile -.It Fl h Ar highfile -Read the high half of the input from -.Ar highfile -.It Fl o Ar file -Write the merged output to -.Ar file -instead of standard output -.El -.Sh EXAMPLES -Write -.Ar output.bin -by combining the low and high halves of each 16-bit word from -.Ar low.bin -and -.Ar high.bin -respectively: -.Pp -.Bd -ragged -offset indent -.Nm -.Fl o -.Ar output.bin -.Fl l -.Ar low.bin -.Fl h -.Ar high.bin -.Ed -.Pp -.Sh SEE ALSO -.Xr split16bit 1 -.Sh AUTHOR -.An "Kimmo Kulovesi" Aq https://arkku.com +.Dd August 7, 2019 +.Dt merge16bit 1 +.Os kk_ihex +.Sh NAME +.Nm merge16bit +.Nd Merges two 8-bit halves of a ROM image into one 16-bit file. +.Sh SYNOPSIS +.Nm +.Op Fl o Ar output16bit.bin +.Op Fl h Ar high8bit.bin +.Op Fl l Ar low8bit.bin +.Sh DESCRIPTION +.Nm +reads two raw 8-bit binary files as input, and writes alternating bytes +from the low and high input files to combine them into a single 16-bit +output binary. This is used to merge two 8-bit ROM images into a single +16-bit file. The first byte of the output is taken from the low +input file, i.e., the data is treated as little-endian. +.Sh OPTIONS +.Bl -tag -width -indent +.It Fl l Ar lowfile +Read the low half of the input from +.Ar lowfile +.It Fl h Ar highfile +Read the high half of the input from +.Ar highfile +.It Fl o Ar file +Write the merged output to +.Ar file +instead of standard output +.El +.Sh EXAMPLES +Write +.Ar output.bin +by combining the low and high halves of each 16-bit word from +.Ar low.bin +and +.Ar high.bin +respectively: +.Pp +.Bd -ragged -offset indent +.Nm +.Fl o +.Ar output.bin +.Fl l +.Ar low.bin +.Fl h +.Ar high.bin +.Ed +.Pp +.Sh SEE ALSO +.Xr split16bit 1 +.Sh AUTHOR +.An "Kimmo Kulovesi" Aq https://arkku.com diff --git a/split16bit.1 b/split16bit.1 index 1296a43..8da67bf 100644 --- a/split16bit.1 +++ b/split16bit.1 @@ -1,55 +1,55 @@ -.Dd August 7, 2019 -.Dt split16bit 1 -.Os kk_ihex -.Sh NAME -.Nm split16bit -.Nd Splits a 16-bit ROM image into two 8-bit halves. -.Sh SYNOPSIS -.Nm -.Op Fl i Ar input16bit.bin -.Op Fl h Ar high8bit.bin -.Op Fl l Ar low8bit.bin -.Sh DESCRIPTION -.Nm -reads a raw 16-bit binary file from standard input and writes two -its two 8-bit halves into separate output files. The low half -will contain the first byte of input, since it has the lowest address, -i.e., the input is treated as little-endian. -.Sh OPTIONS -.Bl -tag -width -indent -.It Fl h Ar highfile -Output to -.Ar highfile -the high half of each 16-bit word -.It Fl l Ar lowfile -Output to -.Ar lowfile -the low half of each 16-bit word -.It Fl i Ar file -Read the binary input from -.Ar file -instead of standard input -.El -.Sh EXAMPLES -Read binary data from -.Ar input.bin -and write low and high halves of each input word to -.Ar low.bin -and -.Ar high.bin -respectively: -.Pp -.Bd -ragged -offset indent -.Nm -.Fl i -.Ar input.bin -.Fl l -.Ar low.bin -.Fl h -.Ar high.bin -.Ed -.Pp -.Sh SEE ALSO -.Xr merge16bit 1 -.Sh AUTHOR -.An "Kimmo Kulovesi" Aq https://arkku.com +.Dd August 7, 2019 +.Dt split16bit 1 +.Os kk_ihex +.Sh NAME +.Nm split16bit +.Nd Splits a 16-bit ROM image into two 8-bit halves. +.Sh SYNOPSIS +.Nm +.Op Fl i Ar input16bit.bin +.Op Fl h Ar high8bit.bin +.Op Fl l Ar low8bit.bin +.Sh DESCRIPTION +.Nm +reads a raw 16-bit binary file from standard input and writes two +its two 8-bit halves into separate output files. The low half +will contain the first byte of input, since it has the lowest address, +i.e., the input is treated as little-endian. +.Sh OPTIONS +.Bl -tag -width -indent +.It Fl h Ar highfile +Output to +.Ar highfile +the high half of each 16-bit word +.It Fl l Ar lowfile +Output to +.Ar lowfile +the low half of each 16-bit word +.It Fl i Ar file +Read the binary input from +.Ar file +instead of standard input +.El +.Sh EXAMPLES +Read binary data from +.Ar input.bin +and write low and high halves of each input word to +.Ar low.bin +and +.Ar high.bin +respectively: +.Pp +.Bd -ragged -offset indent +.Nm +.Fl i +.Ar input.bin +.Fl l +.Ar low.bin +.Fl h +.Ar high.bin +.Ed +.Pp +.Sh SEE ALSO +.Xr merge16bit 1 +.Sh AUTHOR +.An "Kimmo Kulovesi" Aq https://arkku.com