The gsrec Utility Program

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.

S-Record Output 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.

Usage

To use gsrec, enter:

gsrec [options] input_file [-o srec_file]

where

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.

The gsrec options include:

-help

Display information about all options.

-auto

Determine byte order from the file header. This is the default.

-B

Input file is Big Endian.

-L

Input file is Little Endian.

-bytes n

Set the maximum count of unpaired data bytes/records (min 4, max 28). The default is 28.

-e addr

Set entry point in the termination record to given address.

-end addr

End address in object file.

-eol cr

Tells gsrec to terminate each record with a \r character.

-eol crlf

Tells gsrec to terminate each record with a \r\n combination. This is the default in Windows.

-eol lf

Tells gsrec to terminate each record with a \n character. This is the default in UNIX.

-fill1 n1 n2 v

Fill memory from address .n1 to address n2 with the one byte value v.

-fill2 n1 n2 v

Fill memory from address n1 to address n2 with the two byte value v.

-fill4 n1 n2 v

Fill memory from address n1 to address n2 with the four byte value v.

-interval n[:m]

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.

-noS5

Does not produce an S5 block count record.

-o filename

Specifies the output filename. If this option is not given, the S-record will be sent to standard output.

-romaddr addr

Start address in ROM to place data. The default is the same address as in the input file.

-S1

Produces S1 data records (16-bit addresses).

-S2

Produces S2 data records (24-bit addresses).

-S3

Produces S3 data records (32-bit addresses). This is the default.

-S5

Produces an S5 record. This is the default.

-S5old

Produces an S5 record with a 16-bit address.

-S7

Produces an S7 end record (32-bit entry point. This is the default.

-S8

Produces an S8 end record (24-bit entry point).

-S9

Produces an S9 end record (16-bit entry point).

-skip s

Does not output data for section s.

-start addr

Starts address in object file for outputting when -interval is used.

Data Record

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.

Termination 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.

Data Splitting

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.

Examples

All of the examples in this section use the following program file:

file: prog1

sections:

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.

Example 1

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.

Example 2

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.

Example 3

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.

Example 4

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.

Example 5

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.

Example 6

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.

Example 7

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.


Previous

Next



Copyright © 1999, Green Hills Software. All rights reserved.