5.5.3. File preprocessing

The stimulus file is converted into a format that can be fed directly into the HDL code using the script fm2conv.pl. This script verifies that the syntax of the input file is correct. This script provides useful error messages when the syntax is not correct. Figure 5.14 shows the process of stimulus file conversion.

Figure 5.14. Stimulus file conversion

Loops

The fm2conv.pl script unfolds loops of S vectors but relies on the FRM functionality for other commands.

Note

Large loops of S vectors can create large stimulus data files.

Data and mask representations

Data and mask values can be specified as either:

  • the bus width

  • with the -buswidth switch to fm2conv.pl

  • the same length as the transfer size with or without a 0x prefix.

The byte lanes are driven according to both the least significant address bits, and the specified endian organization. The default is little-endian.

If the data or mask is represented as fewer bits than the data bus, then the transfer size is implicitly set to be that width. If this value conflicts with an explicit Size field, then an error is generated. The following examples show data and mask representations of with fewer bits than the data bus:

R 00000002 DD

Read transfer with burst type INCR and implied size Byte. The Data mask is 0x0000000000FF0000 in default little-endian mode.

R 0000ABCD 0x0123456789ABCDEF AB

The Data field is 64 bits (bus width), and the Mask field is BYTE, so the transfer size is BYTE.

R 00000004 EEEEEEEE FF

Invalid stimulus on a 64-bit system. The Data field implies a word transfer while the Mask field implies BYTE.

W 000000C0 AB WORD

Invalid stimulus. The Data field implies a byte transfer while the Size field specifies word.

FRM versions

Because the FRM and fm2conv.pl utilities are closely coupled through the stimulus data file, you must take care to ensure the correct versions are used. Table 5.10 lists the compatibility between versions.

Table 5.10. Compatibility between versions of FRM and fm2conv.pl

fm2conv.pl version

ADK1v1

ADK2

File reader version ADK1v1

-

-

File reader version ADK2

Because of enhancements in FRM functionality and stimulus extensions, the stimulus files and data files for the AHB file reader are incompatible with previous versions of the file reader. The versions can be identified by their ADK version keyword:

  • ADK_REL1v for previous versions

  • ADK2v for the FRM described in this document.

Table 5.11 lists the compatibility between versions.

The file preprocessor can translate ADK1v1 stimulus files using the corresponding command-line switch.

Table 5.11. Compatibility between versions of stimulus file and fm2conv.pl

fm2conv.pl version

ADK1v1

ADK2

Stimulus file version ADK1v1

Stimulus file version ADK1v1[1]

-

Stimulus file version ADK2

[1] Using -adk1 command-line switch.

Endianness

The preprocessor script by default assumes little-endian data organization. Therefore, if only a single byte of data is specified for a byte access, it is placed on the byte lane determined by little-endian addressing.

Big-endian mode is supported for AMBA (Rev 2). The type of big-endian is legacy big-endian, also called ARM big-endian or BE-32. The data and mask must be specified in the same way as for little-endian mode. The preprocessor script places the data and mask bytes in the correct lanes.

Stimulus file size

When the file reader simulation begins, the entire stimulus file is read into an array. Ensure that the array size is large enough to store the entire stimulus file. The fm2conv.pl utility reports the array size required and the total number of vectors in a summary of the stimulus file conversion. A warning is generated if the array size is too small for the resulting stimulus file.

If the array size in the RTL file reader bus master is changed from the default value, you can set the array size through a generic parameter in the FRM HDL by using the command line switch -stimarraysize with the fm2conv.pl utility.

File preprocessor usage

Table 5.12 lists the command-line switches accepted by the preprocessor, fm2conv.pl.

Table 5.12. Preprocessor command-line options

SwitchOptionsDefaultDescription
-help--Displays the usage message.
-quiet--Suppresses warning messages.
-adk1--Translates an ADK1v1 stimulus file. This option can also be specified within the stimulus file.
-endian = <endianness>little or biglittleThe endianness determines the byte lanes that are driven for sparsely declared Data and Mask fields. Not supported for v6 stimulus; instead, the full bus width must be specified for big-endian transfers. The big-endian option is implemented as ARM big-endian.
-infile = <filename>-filestim.m2iInput file name.
-outfile = <filename>-filestim.m2dOutput file name. This name must match the definition specified in the file reader bus master HDL.
-buswidth = <width>32 or 6464Specifies the data bus width of the target FRM.
-arch = <arch>ahb2 or V6ahb2

Specifies the ARM processor architecture version of the target FRM.

Note

V6 is not supported by this version of the FRM.

-StimArraySize = <size><size>5000The size of the file reader bus master file array. This size must match the value set in the FRM HDL.

Error reporting during file preprocessing

The script performs additional checks to ensure correct FRM operation. Table 5.13 lists the error checks. File conversion is aborted if an error with the command-line options is found. File conversion continues if any other error is found, so that you can generate non-AMBA compliant stimulus for test purposes, if required.

Table 5.13. fm2conv.pl error messages

Error

number

Description

17

Input file is unreadable, does not exist or has incorrect permissions.

20

Input file has same name as output file.

21

Cannot create output file.

32

Unrecognized commands within the file.

36

Required fields are missing or in the wrong format.

37

Loop command has Number field missing.

38

Comment command requires a string within double quotes.

40

Size value exceeds the data bus width. Maximum value is dword | size64 for the ADK2 64-bit version FRM, and word | size32 for the ADK2 32-bit version FRM.

43

Loop Number field out of range.

44

Poll TimeOut field out of range.

48

Data field length exceeds FRM data bus width.

49

Data field has invalid length.

52

Mask field length exceeds FRM data bus width.

53

Mask field has invalid length.

56

Mismatch between transfer size, whether specified or implicitly set by Data or Mask width, and Data or Mask field.

64

Address is not aligned with the size of the transfer.

80

For Poll commands, burst types are not the valid incr or single.

84

S or B vectors before a defined-length or undefined-length burst has started.

88

Burst exceeds 1kB address boundary, for both defined and undefined-length bursts.

89

Loop number exceeds number of remaining transfers, for each defined-length burst type.

Most common AMBA protocol violations are detected by the file preprocessor script, but the absence of errors and warnings does not guarantee that the stimulus are compliant with the AMBA protocol.

Table 5.14 lists the warnings. File conversion continues when a warning is issued.

Table 5.14. fm2conv.pl warnings

Warning

number

Description

128

Perl version older than 5.005. Command line switches not supported

132

Invalid data bus width selected.

133

Invalid architecture selected.

134

Adk1 architecture selected and data bus width not specified as 32-bits.

136

Output file length exceeds specified size of stimarraysize.

144

EOF found during burst: expected further transfers.

164

An optional field has an invalid value.

165

Invalid character in comment string.

168

Comment command has a string of length greater than 80 characters.

169

Consecutive blank or commented lines exceeds 63 for line number reporting to work.

216

Number of S vectors following a W | R command is incorrect for a fixed length burst (a burst is terminated early). This enables the simulation of early-terminated bursts.

240

Unsupported command is encountered, Memory.

241

Unsupported field is encountered, AltMaster, and entire line is ignored.

242

Unsupported field is encountered, DeGrant, and is ignored.

248

A feature in development status.

254

Currently unsupported value in field, for example, size > 64.

255

Internal or debug error. Not expected to occur in normal usage.

Errors and warnings have the following numbering scheme:

[7]

Severity.

[6:4]

Error or warning type.

[3:2]

Error or warning subtype.

[1:0]

Enumerator.

Table 5.15 to Table 5.17 list the numbering scheme for errors and warnings.

Table 5.15. Numbering scheme for bit 7, severity

Value

Meaning

0

Error

1

Warning

Table 5.16. Numbering scheme for bits [6:4] and [3:2], error and warning type and subtype

Value bits [6:4]

Meaning

Value bits [3:2]

Meaning

000

Command line

00

Environment

01

Options

10

-

11

-

001

File input/output

00

Input file

01

Output file

10

-

11

-

010

Syntax

00

Command

01

Field

10

Range

11

-

011

Transfer size

00

Data

01

Mask

10

Mismatch

11

-

100

Alignment

00

Address

01

-

10

-

11

-

101

Burst

00

Within burst

01

Outside burst

10

Length

11

-

110

Reserved

-

-

111

Reserved

-

-

Table 5.17. Numbering scheme for bits [1:0], enumerator

Value

Meaning

(any)

Creates unique identifier in conjunction with bits [7:2]

Copyright © 2003, 2007 ARM Limited. All rights reserved.ARM DDI 0243C
Non-Confidential