The gsrec Utility Program converts an ELF executable file into a Motorola S-record format file. Motorola S-Records are an ASCII representation of binary data. Many simulators, In-Circuit Emulators (ICEs), PROM programmers and debuggers use S-Records as a program download format.
An S-record file contains ASCII text which can be displayed or edited. There are ten kinds of S-records, numbered from S0 to S9:
Not all S-record reader programs behave the same way. Some programs require certain types of data records. Some target environments do not accept S5 data count records and some require certain types of termination records. Options are provided to handle many of these cases.
gsrec [options] input_file [-o srec_file]
options gsrec options, listed below.
input_file Name of ELF executable file to be converted.
-o srec_file -o option and a name for the S-record format file.
Display information about all options.
Determine byte order from the file header. This is the default.
Set the maximum count of unpaired data bytes/records (min 4, max 28). The default is 28.
Set entry point in the termination record to given address.
Tells gsrec to terminate each record with a \r character.
Tells gsrec to terminate each record with a \r\n combination. This is the default in Windows.
Tells gsrec to terminate each record with a \n character. This is the default in UNIX.
Fill memory from address .n1 to address n2 with the one byte value v.
Fill memory from address n1 to address n2 with the two byte value v.
Fill memory from address n1 to address n2 with the four byte value v.
Place only those data bytes from the input file which occur within the specified interval in the output file. Legal values for n are 1 through 8. The default is one, indicating that every byte will be output. If an m value is specified, it tells how many bytes will be output for each interval. For example, 4:2 outputs two consecutive bytes of every four.
Does not produce an S5 block count record.
Specifies the output filename. If this option is not given, the S-record will be sent to standard output.
Start address in ROM to place data. The default is the same address as in the input file.
Produces S1 data records (16-bit addresses).
Produces S2 data records (24-bit addresses).
Produces S3 data records (32-bit addresses). This is the default.
Produces an S5 record. This is the default.
Produces an S5 record with a 16-bit address.
Produces an S7 end record (32-bit entry point. This is the default.
Produces an S8 end record (24-bit entry point).
Produces an S9 end record (16-bit entry point).
Does not output data for section s.
Starts address in object file for outputting when -interval is used.
A data record contains the address where the data is loaded, followed by the data itself. There are 3 varieties of data records: S1, S2, and S3. The only difference between the data records is the size of the load address as follows:
By default an S5 data count record is emitted. If your S-record loader does not understand S5 records, use the option -noS5
to avoid outputting an S5 data count record.
A termination record contains the entry point, the address where program execution begins. There are 3 types of termination records: S7, S8, and S9.
Some S-record readers will only accept data records up to a certain length. The option -bytes
size can be used to set the maximum length of the data records.
If you forget to specify the entry point address when linking, -e
address can be used to set the entry point to the given address.
In some hardware implementations, the width of the bus differs from the width of the PROMs. Depending on how the bus and PROMs are connected, it may be necessary to store even bytes in one PROM and odd bytes in another PROM. The technique of dividing the data into even and odd bytes, or worse, is called data splitting.
Data splitting can be done in gsrec using a few options. The -start option specifies the starting address of the data in the object input file to output to the S-record output file. The -end option specifies the last address of data in the object input file to output. The -interval option specifies the distance between bytes in the input file to output. A value of 2 for -interval outputs every other byte. Sometimes it is necessary to relocate the data to address zero in the S-record output file for programming PROMS. The -romaddr option specifies the start address of the data bytes in the S-record output file. Examples 5 and 6 illustrate separating even and odd bytes into two different S-record files.
All of the examples in this section use the following program file:
1: .text, address: 0x1000, size: 0x100 2: .data, address: 0x2000, size: 0x200 3: .bss, address: 0x3000, size: 0x200 (No Load Section) 4: .data2, address: 0x4000, size: 0x200
The program was linked using the following command:
lx -T0x1000 myprog.o -o prog1
Given a relocatable input file myprog.o, this command causes the linker to create a program file called prog1 with a .text base address of 0x1000.
gsrec prog1
gsrec translates the data in the input file prog1 and writes the S-records to the standard output. Since the contents of section .bss are not loaded, no S-records are output for its data.
gsrec -S1 -S9 prog1 -o prog1.run
gsrec translates the data in the input file prog1 and writes the S-records to the specified output file, prog1.run. Data is output as S1 records which have a 16-bit address space. The start address is output as an S9 record which has 16-bit address space.
gsrec -start 0x1000 -end 0x1080 prog1 -o prog1.run
gsrec translates the data in the input file prog1 starting at address 0x1000 and ending at address 0x1080 to the output file, prog1.run.
gsrec -start 0x1000 -end 0x1080 -romaddr 0 prog1 -o prog1.run
gsrec translates the data in the input file prog1 starting at address 0x1000 and ending at address 0x1080, relocates the data starting at address zero, and copies the resulting S-records to the output file prog1.run.
gsrec -start 0x1000 -end 0x1080 -romaddr 0 -interval 2 prog1
gsrec translates the even data bytes in the input file prog1 starting at address 0x1000 and ending at address 0x1080, relocates the data to start at address zero, and copies the resulting S-records to the standard output.
gsrec -start 0x1001 -end 0x107F -romaddr 0 -interval 2 prog1
gsrec translates the odd data bytes in the input file prog1 starting at address 0x1001 and ending at address 0x107F, relocates the data to start at address zero, and copies the resulting S-records to the standard output.
gsrec -start 0x1002 -end 0x107F -romaddr 0 -interval 4:2 prog1
gsrec translates two out of every four data bytes in the input file prog1 starting at address 0x1002 and ending at address 0x107F, relocates the data to start at address zero, and copies the resulting S-records to the standard output.