man srec_cat (Commandes) - manipulate eprom load files

NAME

srec_cat - manipulate eprom load files

SYNOPSIS

[ option... ] filename...

-Help

-VERSion

DESCRIPTION

The program is used to assemble the given input files into a single output file. The use of filters (see below) allows significant manipulations to be performed by this command.

A warning will be emitted for each address wich is redundantly se to the same value. A fatal error will be issued if any address is set with contradictory values. To supress this behaviour, use an -exclude -within filter.

INPUT FILE SPECIFICATIONS

Input files may be qualified in a number of ways: you may specify their format and you may specify filters to apply to them. An input file specification looks like this: filename [ format ][ -ignore-checksums ][ filter ... ]

The filename The filename may be specified as a file name, or the special name ``-'' which is understood to mean the standard input.

File Formats

The format is specified by the argument after the file name. The format defaults to Motorola S-Record if not specified. The format specified are:

-Absolute_Object_Module_Format
This option says to use the Intel Absolute Object Module Format (AOMF) to read the file. (See srec_aomf(5) for a description of this file format.)
-Ascii-Hex
This option says to use the Ascii-Hex format to read the file. See srec_ascii_hex(5) for a description of this file format.
-Atmel_Generic
This option says to use the Atmel Generic format to read the file. See srec_atmel_genetic(5) for a description of this file format.
-Binary
This option says the file is a raw binary file, and should be read literally. (May also be written -Raw.)
-COsmac
This option says to use the RCA Cosmac Elf format to read the file. See srec_cosmac(5) for a description of this file format.
-Dec_Binary
This option says to use the DEC Binary (XXDP) format to read the file. See srec_dec_binary(5) for a description of this file format.
-Elektor_Monitor52
This option says to use the EMON52 format to read the file. See srec_emon52(5) for a description of this file format.
-FAIrchild
This option says to use the Fairchild Fairbug format to read the file. See srec_fairchild(5) for a description of this file format.
-Fast_Load
This option says to use the LSI Logic Fast Load format to read the file. See srec_fastload(5) for a description of this file format.
-Formatted_Binary
This option says to use the Formatted Binary format to read the file. See srec_formatted_binary(5) for a description of this file format.
-Four_Packed_Code
This option says to use the FPC format to read the file. See srec_fpc(5) for a description of this file format.
-Guess
This option may be uased to ask to guess the input format. This is slower than specifying an explicit format, as it may open and close the file a number of times.
-Intel
This option says to use the Intel hex format to read the file. See srec_intel(5) for a description of this file format.
-INtel_HeX_16
This option says to use the Intel hex 16 (INHX16) format to read the file. See srec_intel16(5) for a description of this file format.
-MOS_Technologies
This option says to use the Mos Technologies format to read the file. See srec_mos_tech(5) for a description of this file format.
-Motorola [ width ]
This option says to use the Motorola S-Record format to read the file. (May also be written -S-Record.) See srec_motorola(5) for a description of this file format.

The optional width argument describes the number of bytes which form each address multiple. For normal uses the default of one (1) byte is appropriate. Some systems with 16-bit or 32-bit targets mutilate the addresses in the file; this option will correct for that. Unlike most other parameters, this one cannot be guessed.

-Needham_Hexadecimal
This option says to use the Needham Electronics ASCII file format to read the file. See srec_needham(5) for a description of this file format.
-Ohio_Scientific
This option says to use the Ohio Scientific format. See srec_os65v(5) for a description of this file format.
-SIGnetics
This option says to use the Signetics format. See srec_spasm(5) for a description of this file format.
-SPAsm
This option says to use the SPASM assembler output format (commonly used by PIC programmers). See srec_spasm(5) for a description of this file format.
-SPAsm_LittleEndian
This option says to use the SPASM assembler output format (commonly used by PIC programmers). But with the data the other way around.
-STewie
This option says to use the Stewie binary format to read the file. See srec_stewie(5) for a description of this file format.
-Tektronix
This option says to use the Tektronix hex format to read the file. See srec_tektronix(5) for a description of this file format.
-Tektronix_Extended
This option says to use the Tektronix extended hex format to read the file. See srec_tektronix_extended(5) for a description of this file format.
-Texas_Instruments_Tagged
This option says to use the Texas Instruments Tagged format to read the file. See srec_ti_tagged(5) for a description of this file format.
-VMem
This option says to use the Verilog VMEM format to read the file. See srec_vmem(5) for a description of this file format.
-WILson
This option says to use the wilson format to read the file. See srec_wilson(5) for a description of this file format.

Ignore Checksums

The -ignore-checksums option may be used to disable checksum validation of input files, for those formats which have checksums at all. Note that trhe checksum values are still read in and parse (so it is still an error if they are missing) but their values are not checked. Used after an input file name, the option affects that file alone; used anywhere else on the command line, it applies to all following files.

Input Filters

You may specify zero or more filters to be applied. Filters are applied in the order the user specifies.

-Big_Endian_Checksum_BitNot address [ nbytes [ width ]]
This filter may be used to insert the one's complement checksum of the data into the data, most significant byte first. The data is literaly summed; if there are duplicate bytes, this will produce an incorrect result, if there are holes, it will be as if they were filled with zeros. If the data already contains bytes at the checksum location, you need to use an exclude filter, or this will generate errors. You need to apply and crop or fill filters before this filter. The value will be written with the most significant byte first. The number of bytes of resulting checksum defaults to 4. The width (the width in bytes of the values being summed) defaults to 1.
-Big_Endian_Checksum_Negative address [ nbytes [ width ]]
This filter may be used to insert the two's complement (negative) checksum of the data into the data. Otherwise similar to the above.
-Big_Endian_Checksum_Positive address [ nbytes [ width ]]
This filter may be used to insert the simple checksum of the data into the data. Otherwise similar to the above.
-Little_Endian_Checksum_BitNot address [ nbytes [ width ]]
This filter may be used to insert the one's complement (bitnot) checksum of the data into the data, least significant byte first. Otherwise similar to the above.
-Little_Endian_Checksum_Negative address [ nbytes [ width ]]
This filter may be used to insert the two's complement (negative) checksum of the data into the data. Otherwise similar to the above.
-Little_Endian_Checksum_Negative address [ nbytes [ width ]]
This filter may be used to insert the simple checksum of the data into the data. Otherwise similar to the above.
-Byte_Swap [ width ]
This filter may be used to swap pairs of odd and even bytes. By specifying a width (in bytes) it is possible to reverse the order of 4 and 8 bytes, the default is 2 bytes. (Widths in excess of 8 are assumed to be number of bits.) It is not possuble to swap non-power-of-two addresses. To change the alignment, use the offset filter before and after.
-Big_Endian_CRC16 address
This filter may be used to insert an industry standard 16-bit CRC checksum of the data into the data. Two bytes, big-endian order, are inserted at the address given. Holes in the input data are ignored. Bytes are processed in ascending address order (not in the order they appear in the input).
-Little_Endian_CRC16 address
As above, except little-endian order.
-Big_Endian_CRC32 address
This filter may be used to insert an industry standard 32-bit CRC checksum of the data into the data. Four bytes, big-endian order, are inserted at the address given. Holes in the input data are ignored. Bytes are processed in ascending address order (not in the order they appear in the input).
-Little_Endian_CRC32 address
As above, except little-endian order.
-Crop address-range
This filter may be used to isolate a section of data, and discard the rest.
-Exclude address-range
This filter may be used to exclude a section of data, and keep the rest. The is the logical complement of the -Crop filter.
-Fill value address-range
This filter may be used to fill any gaps in the data with bytes equal to value. The fill will only occur in the address range given.
-UnFill value [ min-run-length ]
This filter may be used to create gaps in the data with bytes equal to value. You can think of it as reversing the effects of the -Fill filter. The gaps will only be created if the are at least min-run-length bytes in a row (defaults to 1).
-Random_Fill address-range
This filter may be used to fill any gaps in the data with random bytes. The fill will only occur in the address range given.
-AND value
This filter may be used to bit-wise AND a value to every data byte. This is useful if you need to clear bits. Only existing data is altered, no holes are filled.
-eXclusive-OR value
This filter may be used to bit-wise XOR a value to every data byte. This is useful if you need to invert bits. Only existing data is altered, no holes are filled.
-OR value
This filter may be used to bit-wise OR a value to every data byte. This is useful if you need to set bits. Only existing data is altered, no holes are filled.
-NOT
This filter may be used to bit-wise NOT the value of every data byte. This is useful if you need to invert the data. Only existing data is altered, no holes are filled.
-Big_Endian_Length address [ nbytes ]
This filter may be used to insert the length of the data (high water minus low water) into the data. This includes the length itself. If the data already contains bytes at the length location, you need to use an exclude filter, or this will generate errors. The value will be written with the most significant byte first. The number of bytes defaults to 4.
-Little_Endian_Length address [ nbytes ]
As above, however the value will be written with the least significant byte first.
-Big_Endian_MAXimum address [ nbytes ]
This filter may be used to insert the maximum address of the data (high water + 1) into the data. This includes the maximum itself. If the data already contains bytes at the given address, you need to use an exclude filter, or this will generate errors. The value will be written with the most significant byte first. The number of bytes defaults to 4.
-Little_Endian_MAXimum address [ nbytes ]
As above, however the value will be written with the least significant byte first.
-Big_Endian_MINimum address [ nbytes ]
This filter may be used to insert the minimum address of the data (low water) into the data. This includes the minimum itself. If the data already contains bytes at the given address, you need to use an exclude filter, or this will generate errors. The value will be written with the most significant byte first. The number of bytes defaults to 4.
-Little_Endian_MINimum address [ nbytes ]
As above, however the value will be written with the least significant byte first.
-OFfset nbytes
This filter may be used to offset the addresses by the given number of bytes. No data is lost, the addresses will wrap around in 32 bits, if necessary.
-SPlit multiple [ offset [ width ] ]
This filter may be used to split the input into a subset of the data, and compress the address range so as to leave no gaps. This useful for wide data buses and memory striping. The multiple is the bytes multiple to split over, the offset is the byte offset into this range (defaults to 0), the width is the number of bytes to extract (defaults to 1) within the multiple. In order to leave no gaps, the output addresses are (width / multiple) times the input addresses.
-Un_SPlit multiple [ offset [ width ] ]
This filter may be used to reverse the effects of the split filter. The arguments are identical. Note that the address range is expanded (multiple / width) times, leaving holes between the stripes.

Address Ranges

There are three ways to specify an address range:

minimum maximum
If you specify two number on the command line (decimal, octal and hexadecimal are understood, using the C conventions) this is an explicit address range. The minimum is inclusive, the maximum is exclusive (one more than the last address). If the maximum is given as zero then the range extends to the end of the address space.
-Within input-specification
This says to use the specified input file as a mask. The range includes all the places the specified input has data, and holes where it has holes. The input specification need not be just a file name, it may be anything any other input specification can be.
-OVER input-specification
This says to use the specified input file as a mask. The range extends from the minimum to the maximum address used by the input, and ignores any holes. The input specification need not be just a file name, it may be anything any other input specification can be.

In addition, all of these methods may be used, and used more than once, and the results will be added together.

Calculated Values

Most of the places above where a number is expected, you may supply one of the following:

-MINimum input-specification
This inserts the minimum address of the specified input file. The input specification need not be just a file name, it may be anything any other input specification can be.
-MAXimum input-specification
This inserts the maximum address of the specified input file, plus one. The input specification need not be just a file name, it may be anything any other input specification can be.
-Length input-specification
This inserts the length of the address range in the specified input file, ignoring any holes. The input specification need not be just a file name, it may be anything any other input specification can be.

For example, the -OVER file option can be thought of a short-hand for ( -min file -max file )i, except that it is much easier to type, and also more efficient.

In addition, calculated values may optionally be rounded in one of three ways:

value -Round_Down number
The value is rounded down to the the largest integer smaller than or equal to a whole multiple of the number.
value -Round_Nearest number
The value is rounded to the the nearest whole multiple of the number.
value -Round_Up number
The value is rounded up to the the smallest integer larger than or equal to a whole multiple of the number.

OPTIONS

The following options are understood:

-Output filename [ format ]
This option may be used to specify the output file to be used. The special file name ``-'' is understood to mean the standard output. Output defaults to the standard output if this option is not used.

The format may be specified as:

-Absolute_Object_Module_Format
An Intel Absolute Object Module Format file will be written. (See srec_aomf(5) for a description of this file format.)
-Ascii_Hex
An Ascii-Hex file will be written. (See srec_ascii_hex(5) for a description of this file format.)
-ASM
A series of assembler DB statements will be written.
-Atmel_Generic
An Atmel Generic file will be written. (See srec_atmel_generic(5) for a description of this file format.)
-BASic
A series of BASIC DATA statements will be written.
-Binary
A raw binary file will be written.
-C-Array [ identifier ][ -INClude ][ -No-CONST ]
A C array declaration will be written. The identifier is the name of the variable to be defined. The -INClude options asks for an include file to be generated as well. The -No-CONST options asks for the variables to not use the const keyword (they are declared contant be default, so that they are placed into the read-only segment in embedded systems).
-COsmac
An RCA Cosmac Elf format file will be written. (See srec_cosmac(5) for a description of this file format.)
-Dec_Binary
A DEC Binary (XXDP) format file will be written. (See srec_dec_binary(5) for a description of this file format.)
-Elektor_Monitor52
This option says to use the EMON52 format file when writing the file. (See srec_emon52(5) for a description of this file format.)
-FAIrchild
This option says to use the Fairchild Fairbug format file when writing the file. (See srec_fairchild(5) for a description of this file format.)
-Fast_Load
This option says to use the LSI Logic Fast Load format file when writing the file. (See srec_fastload(5) for a description of this file format.)
-Formatted_Binary
A Formatted Binary format file will be written. (See srec_formatted_binary(5) for a description of this file format.)
-Four_Packed_Code
This option says to use the PFC format file when writing the file. (See srec_fpd(5) for a description of this file format.)
-Intel
An Intel hex format file will be written. (See srec_intel(5) for a description of this file format.) The default is to emit 32-bit linear addressing; if you want 16-bit extended segment addressing use the --address-length=2 option.
-MOS_Technologies
An Mos Technologies format file will be written. (See srec_mos_tech(5) for a description of this file format.)
-Motorola [ width ]
A Motorola S-Record file will be written. (See srec_motorola(5) for a description of this file format.) This is the default output format. By default, the smallest possible address length is emitted, this will be S19 for data in the first 64KB; if you wish to force S28 use the --address-length=3 option; if you wish to force S37 use the --address-length=4 option

The optional width argument describes the number of bytes which form each address multiple. For normal uses the default of one (1) byte is appropriate. Some systems with 16-bit or 32-bit targets mutilate the addresses in the file; this option will imitate that ehaviour. Unlike most other parameters, this one cannot be guessed.

-Needham_Hexadecimal
This option says to use the Needham Electronics ASCII file format to write the file. See srec_needham(5) for a description of this file format.
-Ohio_Scientific
This option says to use the Ohio Scientific hexadecimal format. See srec_os65v(5) for a description of this format.
-SIGnetics
This option says to use the Signetics hex format. See srec_signetics(5) for a description of this format.
-SPAsm
This option says to use the SPASM assembler output format (commonly used by PIC programmers). See srec_spasm(5) for a description of this format.
-SPAsm_LittleEndian
This option says to use the SPASM assembler output format (commonly used by PIC programmers). But with the data the other way around.
-STewie
A Stewie binary format file will be written. (See srec_stewie(5) for a description of this file format.)
-Tektronix
A Tektronix hex format file will be written. (See srec_tektronix(5) for a description of this file format.)
-Tektronix_Extended
A Tektronix extended hex format file will be written. (See srec_tektronix_extended(5) for a description of this file format.)
-Texas_Instruments_Tagged
A TI-Tagged format file will be written. (See srec_ti_tagged(5) for a description of this file format.)
-VHdl [ bytes-per-word [ name ]]
A VHDL format file will be written. The bytes-per-word defaaults to one, the name defaults to CW]eprom. The etc/x_defs_pack.vhd file in the source distribution contains an example ROM definitions pack for the type-independent output. You may need to use the -byte-swap filter to get the byte order you want.
-VMem [ memory-width ]
A Verilog VMEM format file will be written. The memory-width may be 8, 16, 32, 64 or 128 bits; defaults to 32 if unspecified. (See srec_vmem(5) for a description of this file format.) You may need to use the -byte-swap filter to get the byte order you want.
-WILson
A wilson format file will be written. (See srec_wilson(5) for a description of this file format.)
-Address_Length number
This option many be used to specify the minimum number of bytes to be used in the output to represent an address (padding with leading zeros if necessary). This helps when talking to brain-dead EPROM programmers which do not fully implement the format specification.
-Data_Only
This option may be used to suppress all output except data fields. This helps when talking to brain-dead EPROM programmers which do not fully implement the format specification.
-IGnore_Checksums
The -ignore-checksums option may be used to disable checksum validation of input files, for those formats which have checksums at all. Note that trhe checksum values are still read in and parse (so it is still an error if they are missing) but their values are not checked. Used after an input file name, the option affects that file alone; used anywhere else on the command line, it applies to all following files.
-CRLF
This option may be used to specify CRLF line termination for text output. For use with brain-dead EPROM programmers which assume all the world uses Evil Bill's operating system's line termination. The default is to use the current operating system's default line termination. Use this option with caution, because it will also introduce extra (i.e. wrong) CR bytes into binary formats.
-Line_Length number
This option may be used to limit the length of the output lines to at most number characters. (Not meaningful for binary file format.) Defaults to something less than 80 characters, depending on the format.
-HEAder string
This option may be used to set the header comment, in those formats which support it.
-Start_Address number
This option may be used to set the start address, in those formats which support it.
-MULTiple
Use this option to permit a file to contain multiple (contradictory) values for some memory locations. A warning will be printed. The last value in the file will be used. The default is for this condition to be a fatal error.

All other options will produce a diagnostic error.

All options may be abbreviated; the abbreviation is documented as the upper case letters, all lower case letters and underscores (_) are optional. You must use consecutive sequences of optional letters.

All options are case insensitive, you may type them in upper case or lower case or a combination of both, case is not important.

For example: the arguments "-help", "-HEL" and "-h" are all interpreted to mean the -Help option. The argument "-hlp" will not be understood, because consecutive optional characters were not supplied.

Options and other command line arguments may be mixed arbitrarily on the command line.

The GNU long option names are understood. Since all option names for are long, this means ignoring the extra leading '-'. The "--option=value" convention is also understood.

EXIT STATUS

The command will exit with a status of 1 on any error. The command will only exit with a status of 0 if there are no errors.

EXAMPLES

The command is very powerful, due to the ability to combine the the input filters in almost unlimited ways.

Converting File Formats

The simplest case is converting files from Intel hex format to Motorola S-Record format: intel-file -intel -o srec-file Converting the other was is just as simple: srec-file -o intel-file -intel In each case, the default format is Motorola S-Record format, so it does not need to be specified.

Cropping the Data

A common activity is to crop your data to match your EPROM location. Your linker may add other junk that you are not interested in, e.g. at the RAM location. In this example, there is a 1MB EPROM at the 2MB boundary: infile -crop 0x200000 0x300000 -o outfile The lower bound is inclusive, the upper bound is exclusive.

Address Offset

Just possibly, you have a moronic EPROM programmer, and it barfs if the eprom doesn't start at zero. Rather than butcher the linker command file, just offset the addresses: infile -crop 0x200000 0x300000 -offset -0x200000 -o outfile This example also demonstrates how the input filters may be chained together.

Joining Files Together

The command takes its name from the UNIX cat(1) command, which is short for `catenate' or `to join'. Joining files together into a single file is simple, just name as many files on the command line as you need: infile1 infile2 -o outfile However, this assumes that the files don't overlap in any way (you will get an error if they do). If both files start from address zero, you may need to use the offset filter: infile1 infile2 -offset 0x80000 -o outfile Sometimes you want the two files to follow each other exactly, but you don't know the offset in advance: infile1 infile2 -offset -maximum infile1 -o outfile Notice that where the was a number (0x80000) before, there is now a calculation (-maximum infile1). This is possible most places a number may be used (also -minimum and -range).

Filling the Blanks

It is possible to fill the blanks where our data does not lie. The simplest example of this fills the entire EPROM: infile -fill 0x00 0x200000 0x300000 -o outfile This example fills the holes, if any, with zeros. You must specify a range - with a 32-bit address space, filling everything generates huge load files.

If you only want to fill the gaps in your data, and don't want to fill the entire EPROM, try: infile -fill 0x00 -over infile -o outfile This example demonstrates the fact that wherever an address range may be specified, the -over and -within options may be used.

Unfilling the Blanks

It is common to need to ``unfill'' an eprom image after you read it out of a chip. Usually, it will have had all the holes filled with 0xFF (areas of the EPROM you don't program show as 0xFF when you read them back).

To get rid of all the 0xFF bytes in the data, use this filter: infile -unfill 0xFF -o outfile This will get rid of all the 0xFF bytes, including the ones you actually wanted in there. There are two ways to deal with this. First, you can specify a minimum run length to the un-fill: infile -unfill 0xFF 5 -o outfile This says that runs of 1 to 4 bytes of 0xFF are OK, and that a hole should only be created for runs of 5 or more 0xFF bytes in a row. The second method is to re-fill over the intermediate gaps: outile -fill 0xFF -over outfile -o outfile2 Which method you choose depends on your needs, and the shape of the data in your EPROM. You may need to combine both techniques.

Splitting an Image

If you have a 16-bit data bus, but you are using two 8-bit EPROMs to hold your firmware, you can generate the even and odd images by using the -SPlit filter. Assuming your firmware is in the firmware.hex file, use the following:

 firmware.hex -split 2 0 -o firmware.even.hex
 firmware.hex -split 2 1 -o firmware.odd.hex
This will result in the two necessary EPROM images. Note that the output addresses are divided by the split multiple, so if your EPROM images are at a particular offset (say 0x10000, in the following example), you need to remove the offset, and then replace it...
 firmware.hex \
	-offset -0x10000 -split 2 0 \
	-offset 0x10000 -o firmware.even.hex
 firmware.hex \
	-offset -0x10000 -split 2 1 \
	-offset 0x10000 -o firmware.odd.hex
Note how the ability to apply multiple filters simplifies what would otherwise be a much longer script.

A second use for the -SPlit filter is memory striping. In this example, the hardware requires that 512-byte blocks alternate between 4 EPROMs. Generating the 4 images would be done as follows:

 firmware.hex -split 0x800 0x000 0x200 -o firmware.0.hex
 firmware.hex -split 0x800 0x200 0x200 -o firmware.1.hex
 firmware.hex -split 0x800 0x400 0x200 -o firmware.2.hex
 firmware.hex -split 0x800 0x600 0x200 -o firmware.3.hex

The unsplit filter may be used to reverse the effects of the split filter. Note that the address range is expanded leaving holes between the stripes. By using all the stripes, the complete input is reassembled, without any holes. For example, to reverse our previous 16-bit data bus example, use the following command:

 -o firmware.hex \
	firmware.even.hex -unsplit 2 0 \
	firmware.odd.hex  -unsplit 2 1


COPYRIGHT

version

Copyright Peter Miller;

All rights reserved.

The program comes with ABSOLUTELY NO WARRANTY; for details use the ' -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the ' -VERSion License' command.

AUTHOR

tab(;); l r l. Peter Miller;E-Mail:;millerp@canb.auug.org.au /\/\*;WWW:;http://www.canb.auug.org.au/~millerp/