DK4

Handel-C Language Reference Manual

For DK version 4
Handel-C Language Reference Manual

Celoxica, the Celoxica logo and Handel-C are trademarks of Celoxica Limited.

All other products or services mentioned herein may be trademarks of their respective
owners.

Neither the whole nor any part of the information contained in, or the product described
in, this document may be adapted or reproduced in any material form except with the
prior written permission of the copyright holder.

The product described in this document is subject to continuous development and

improvement. All particulars of the product and its use contained in this document are
given by Celoxica Limited in good faith. However, all warranties implied or express,
including but not limited to implied warranties of merchantability, or fitness for purpose,
are excluded.

This document is intended only to assist the reader in the use of the product. Celoxica
Limited shall not be liable for any loss or damage arising from the use of any information
in this document, or any incorrect use of the product.

The information contained herein is subject to change without notice and is for general
guidance only.

Copyright © 2005 Celoxica Limited. All rights reserved.

Authors: RG

Document number: RM-1003-4.2

Customer Support at http://www.celoxica.com/support/

Celoxica in Europe Celoxica in Japan Celoxica in the Americas

T: +44 (0) 1235 863 656 T: +81 (0) 45 331 0218 T: +1 800 570 7004

E: sales.emea@celoxica.com E: sales.japan@celoxica.com E: sales.america@celoxica.com

www.celoxica.com
Handel-C Language Reference Manual

Contents
1 INTRODUCTION ............................................................................. 11
1.1 REFERENCES............................................................................ 11

2 GETTING STARTED WITH HANDEL-C ................................................... 12

2.1 BASIC CONCEPTS ...................................................................... 12
2.1.1 Handel-C programs ............................................................................... 12
2.1.2 Parallel programs .................................................................................. 12
2.1.3 Channel communication ......................................................................... 13
2.1.4 Scope and variable sharing..................................................................... 15

3 LANGUAGE BASICS ......................................................................... 16

3.1 PROGRAM STRUCTURE................................................................ 16
3.2 COMMENTS ............................................................................. 17
3.3 STATEMENT SUMMARY ............................................................... 17
3.4 OPERATOR SUMMARY................................................................. 19
3.5 TYPE SUMMARY ........................................................................ 21
3.6 COMPARISON OF HANDEL-C AND ANSI-C ..................................... 22
3.6.1 Handel-C v C: types and type operators ................................................... 23
3.6.2 Handel-C v C: floating-point variables ...................................................... 23
3.6.3 Handel-C v C: variable widths and casting ................................................ 24
3.6.4 Handel-C v C: side effects ...................................................................... 25
3.6.5 Handel-C v C: functions ......................................................................... 26
3.6.6 Handel-C v C: loop statements ............................................................... 27
3.6.7 Handel-C v C: unions............................................................................. 28
3.6.8 Handel-C v C: data input and output........................................................ 29
3.6.9 Handel-C v C: memory allocation ............................................................ 29
3.6.10 Handel-C v C: standard library .............................................................. 29
3.6.11 C and Handel-C types and objects ......................................................... 29
3.6.12 Expressions in C and Handel-C .............................................................. 30
3.6.13 Statements in C and Handel-C .............................................................. 32
3.7 HANDEL-C CONSTRUCTS NOT FOUND IN ANSI-C ............................. 32

4 DECLARATIONS ............................................................................. 36
4.1 INTRODUCTION TO TYPES ........................................................... 36
4.1.1 Handel-C values and widths.................................................................... 36
4.1.2 String constants ................................................................................... 37
4.1.3 Constants ............................................................................................ 37
4.2 LOGIC TYPES ........................................................................... 38
4.2.1 int ...................................................................................................... 38
4.2.2 Signed | unsigned syntax ....................................................................... 39
4.2.3 Supported types for porting.................................................................... 39
4.2.4 Inferring widths .................................................................................... 40

www.celoxica.com Page 1
Handel-C Language Reference Manual

4.2.5 Arrays ................................................................................................. 41

4.2.6 Array indices ........................................................................................ 43
4.2.7 struct .................................................................................................. 43
4.2.8 enum .................................................................................................. 44
4.2.9 Bit fields .............................................................................................. 45
4.3 POINTERS ............................................................................... 46
4.3.1 Pointers and addresses .......................................................................... 48
4.3.2 Pointers to functions.............................................................................. 48
4.3.3 Pointers to interfaces............................................................................. 49
4.3.4 Structure pointers ................................................................................. 49
4.3.5 address and indirection operators............................................................ 50
4.4 ARCHITECTURAL TYPES .............................................................. 51
4.5 CHANNELS .............................................................................. 51
4.5.1 FIFO code example ............................................................................... 53
4.5.2 Arrays of channels ................................................................................ 53
4.5.3 Restrictions on channel accesses ............................................................. 53
4.5.4 Timing and latency in FIFOs ................................................................... 55
4.6 INTERFACES: OVERVIEW ............................................................ 56
4.6.1 Interface declaration ............................................................................. 56
4.6.2 Interface definition................................................................................ 57
4.6.3 Example interface to external code .......................................................... 58
4.6.4 Interface specifications .......................................................................... 59
4.7 RAMS AND ROMS .................................................................... 61
4.7.1 Initialization ......................................................................................... 61
4.7.2 Inferring size from use........................................................................... 62
4.7.3 Accessing RAMs and ROMs ..................................................................... 62
4.7.4 Differences between RAMs and arrays ...................................................... 62
4.7.5 RAM and ROM support on different devices ............................................... 63
4.7.6 Multidimensional memory arrays ............................................................. 63
4.8 MPRAM (MULTI-PORTED RAMS) .................................................. 64
4.8.1 Initialization of mprams ......................................................................... 66
4.8.2 Mapping of different width mpram ports ................................................... 66
4.8.3 mprams example .................................................................................. 68
4.9 WOM (WRITE-ONLY MEMORY) .................................................... 69
4.10 SEMA ................................................................................... 69
4.11 SIGNAL ................................................................................ 70
4.12 STORAGE CLASS SPECIFIERS ...................................................... 71
4.12.1 auto .................................................................................................. 71
4.12.2 extern (external variables) ................................................................... 72
4.13 EXTERN LANGUAGE CONSTRUCT .................................................. 72
4.14 REGISTER ............................................................................. 75
4.15 INLINE FUNCTIONS ................................................................. 75
4.16 STATIC ................................................................................. 76
4.17 TYPEDEF ............................................................................... 76
4.18 TYPEOF ................................................................................ 77
4.19 CONST.................................................................................. 78

www.celoxica.com Page 2
Handel-C Language Reference Manual

4.20 VOLATILE .............................................................................. 78

4.21 COMPLEX DECLARATIONS.......................................................... 78
4.21.1 Macro expressions in widths.................................................................. 78
4.21.2 <> (type clarifier) ............................................................................... 79
4.21.3 Using signals to split up complex expressions .......................................... 79
4.22 VARIABLE INITIALIZATION ....................................................... 80

5 STATEMENTS ................................................................................. 82
5.1 SEQUENTIAL AND PARALLEL EXECUTION ......................................... 82
5.2 SEQ 83
5.3 REPLICATED PAR AND SEQ .......................................................... 83
5.4 PRIALT ................................................................................... 85
5.5 USING PRIALT: EXAMPLES .......................................................... 86
5.6 ASSIGNMENTS ......................................................................... 88
5.6.1 continue .............................................................................................. 89
5.6.2 goto.................................................................................................... 90
5.6.3 return [expression] ............................................................................... 91
5.6.4 Conditional execution (if ... else) ............................................................. 91
5.6.5 while loops........................................................................................... 92
5.6.6 do ... while loops .................................................................................. 93
5.6.7 for loops .............................................................................................. 93
5.6.8 switch ................................................................................................. 95
5.6.9 break .................................................................................................. 96
5.6.10 delay ................................................................................................. 97
5.6.11 try... reset ......................................................................................... 97
5.6.12 trysema() .......................................................................................... 99
5.6.13 releasesema() .................................................................................. 100

6 EXPRESSIONS ..............................................................................102
6.1 INTRODUCTION TO EXPRESSIONS ................................................102
6.1.1 Clock cycles required ........................................................................... 102
6.1.2 Breaking down complex expressions ...................................................... 102
6.1.3 Prefix and postfix operators .................................................................. 102
6.2 CASTING OF EXPRESSION TYPES ..................................................103
6.2.1 Restrictions on casting ......................................................................... 104
6.3 RESTRICTIONS ON RAMS AND ROMS ..........................................104
6.4 ASSERT .................................................................................106
6.5 BIT MANIPULATION OPERATORS ..................................................108
6.5.1 Shift operators ................................................................................... 109
6.5.2 Take / drop operators .......................................................................... 109
6.5.3 Concatenation operator........................................................................ 109
6.5.4 Bit selection ....................................................................................... 110
6.5.5 Width operator ................................................................................... 111
6.6 ARITHMETIC OPERATORS ...........................................................111
6.7 RELATIONAL OPERATORS ...........................................................113
6.7.1 Signed/unsigned compares................................................................... 114

www.celoxica.com Page 3
Handel-C Language Reference Manual

6.7.2 Implicit compares ............................................................................... 114

6.8 LOGICAL OPERATORS ................................................................114
6.8.1 Bitwise logical operators ...................................................................... 115
6.9 CONDITIONAL OPERATOR ..........................................................116
6.10 MEMBER OPERATORS (. / ->) ..................................................116

7 FUNCTIONS AND MACROS ................................................................118

7.1 FUNCTIONS AND MACROS: OVERVIEW ...........................................118
7.1.1 Functions and macros: language issues.................................................. 118
7.1.2 Functions and macros: sharing hardware................................................ 120
7.1.3 Functions and macros: clock cycles........................................................ 121
7.1.4 Functions and macros: examples........................................................... 121
7.1.5 Accessing external names .................................................................... 123
7.1.6 Recursion in macros and functions......................................................... 124
7.2 INTRODUCTION TO FUNCTIONS ...................................................124
7.2.1 Function definitions and declarations...................................................... 125
7.2.2 Functions: scope................................................................................. 126
7.2.3 Arrays of functions .............................................................................. 126
7.2.4 Function arrays: example..................................................................... 127
7.2.5 Function arrays example with static variables.......................................... 128
7.2.6 Function pointers ................................................................................ 129
7.2.7 Function pointers example.................................................................... 130
7.2.8 Simultaneous function calls .................................................................. 134
7.2.9 Multiple functions in a statement ........................................................... 136
7.3 INTRODUCTION TO MACROS .......................................................137
7.3.1 Non-parameterized macro expressions................................................... 137
7.3.2 Parameterized macro expressions ......................................................... 138
7.3.3 select operator ................................................................................... 138
7.3.4 ifselect .............................................................................................. 139
7.3.5 Recursive macro expressions ................................................................ 140
7.3.6 Recursive macro expressions example ................................................... 142
7.3.7 Shared expressions ............................................................................. 142
7.3.8 Using recursion to generate shared expressions ...................................... 143
7.3.9 Restrictions on shared expressions ........................................................ 143
7.3.10 let ... in ........................................................................................... 144
7.3.11 Macro procedures.............................................................................. 145
7.3.12 Macro procedures compared to pre-processor macros............................. 146

8 INTRODUCTION TO TIMING ..............................................................148

8.1 STATEMENT TIMING .................................................................148
8.1.1 Example timings ................................................................................. 148
8.1.2 Statement timing summary .................................................................. 154
8.2 AVOIDING COMBINATIONAL LOOPS ..............................................156
8.3 PARALLEL ACCESS TO VARIABLES .................................................158
8.4 DETAILED TIMING EXAMPLE .......................................................159
8.5 TIME EFFICIENCY OF HANDEL-C HARDWARE ..................................161
8.5.1 Reducing logic depth ........................................................................... 161

www.celoxica.com Page 4
Handel-C Language Reference Manual

8.5.2 Pipelining........................................................................................... 164

9 CLOCKS OVERVIEW ........................................................................167

9.1 LOCATING THE CLOCK ...............................................................167
9.1.1 External clocks ................................................................................... 168
9.1.2 Internal clocks fed from expressions ...................................................... 168
9.2 CURRENT CLOCK ......................................................................169
9.3 MULTIPLE CLOCK DOMAINS ........................................................169
9.3.1 Channels communicating between clock domains..................................... 169
9.3.2 Simulating multiple clock domains ......................................................... 183

10 TARGETING HARDWARE AND SIMULATION .........................................184

10.1 INTERFACING WITH THE SIMULATOR ..........................................184
10.1.1 Simulator input file format.................................................................. 185
10.1.2 Block data transfers........................................................................... 185
10.2 TARGETING FPGA AND PLD DEVICES ........................................186
10.2.1 Summary of supported devices ........................................................... 187
10.2.2 Detecting the current device family...................................................... 189
10.2.3 Targeting specific devices via source code............................................. 190
10.2.4 Specifying a global reset .................................................................... 193
10.3 USE OF RAMS AND ROMS WITH HANDEL-C ................................193
10.3.1 Asynchronous RAMs........................................................................... 194
10.3.2 Synchronous RAMs ............................................................................ 200
10.3.3 Targeting Stratix and Cyclone memory blocks ....................................... 216
10.3.4 Using on-chip RAMs in Actel devices..................................................... 217
10.3.5 Using on-chip RAMs in Altera devices ................................................... 218
10.3.6 Using on-chip RAMs in Xilinx devices .................................................... 219
10.3.7 Using external ROMs.......................................................................... 219
10.3.8 Connecting to RAMs in foreign code ..................................................... 220
10.3.9 Using other RAMs .............................................................................. 224

11 INTERFACING WITH EXTERNAL HARDWARE ........................................225

11.1 INTERFACE SORTS ..................................................................225
11.1.1 Reading from external pins bus_in ....................................................... 226
11.1.2 Registered reading from external pins: bus_latch_in .............................. 227
11.1.3 Clocked reading from external pins: bus_clock_in .................................. 228
11.1.4 Writing to external pins: bus_out......................................................... 228
11.1.5 Bidirectional data transfer: bus_ts ....................................................... 228
11.1.6 Bidirectional data transfer with registered input: bus_ts_latch_in ............. 229
11.1.7 Bidirectional data transfer with clocked input: bus_ts_clock_in................. 231
11.1.8 Example hardware interface................................................................ 232
11.2 SIMULATING INTERFACES ........................................................235
11.3 BUSES AND THE SIMULATOR .....................................................237
11.4 MERGING PINS .....................................................................238
11.4.1 Merging clock pins............................................................................. 238
11.4.2 Merging input pins............................................................................. 239
11.4.3 Merging tri-state pins......................................................................... 239

www.celoxica.com Page 5
Handel-C Language Reference Manual

11.5 TIMING CONSIDERATIONS FOR BUSES .........................................240

11.5.1 Example timing considerations for input buses....................................... 240
11.5.2 Example timing considerations for output buses..................................... 242
11.6 METASTABILITY ....................................................................242
11.6.1 Techniques to minimize the problem .................................................... 243
11.6.2 Using interfaces: External resynchronizing example ............................... 246
11.7 PORTS: INTERFACING WITH EXTERNAL LOGIC ...............................248
11.8 SPECIFYING THE INTERFACE .....................................................249
11.9 TARGETING PORTS TO SPECIFIC TOOLS .......................................250

12 OBJECT SPECIFICATIONS ..............................................................252

12.1 SUMMARY OF SPECIFICATIONS ..................................................252
12.1.1 Compiler atttributes........................................................................... 252
12.1.2 Simulator attributes........................................................................... 253
12.1.3 Clock attributes................................................................................. 254
12.1.4 Channel attributes ............................................................................. 256
12.1.5 Channel and memory attributes .......................................................... 256
12.1.6 Memory attributes ............................................................................. 256
12.1.7 Interface and memory attributes ......................................................... 258
12.1.8 Interface attributes............................................................................ 259
12.1.9 Examples ......................................................................................... 260
12.2 BASE SPECIFICATION ..............................................................261
12.3 BIND SPECIFICATION ..............................................................261
12.4 BLOCK SPECIFICATION ............................................................263
12.5 BUFFER SPECIFICATION ...........................................................266
12.6 BUSFORMAT SPECIFICATION .....................................................266
12.7 SPECIFYING THE CLOCK PIN FOR SSRAM ....................................268
12.8 CLOCKPORT SPECIFICATION .....................................................269
12.9 DATA SPECIFICATION (PIN CONSTRAINTS) ..................................271
12.10 DCI SPECIFICATION ..............................................................272
12.11 EXTINST, EXTLIB, EXTFUNC SPECIFICATIONS ..............................273
12.12 EXTPATH SPECIFICATION .......................................................275
12.13 FIFOLENGTH SPECIFICATION...................................................275
12.14 INFILE AND OUTFILE SPECIFICATIONS .......................................276
12.15 INTIME AND OUTTIME SPECIFICATIONS .....................................276
12.16 TIMING CONSTRAINTS EXAMPLE ..............................................277
12.17 MINPERIOD SPECIFICATION ...................................................280
12.18 OFFCHIP SPECIFICATION .......................................................281
12.19 PARANOIA SPECIFICATION .....................................................282
12.20 PIN SPECIFICATIONS ............................................................283
12.21 PORTS SPECIFICATION ..........................................................284
12.22 PROPERTIES SPECIFICATION...................................................285
12.23 PULL SPECIFICATION ............................................................287

www.celoxica.com Page 6
Handel-C Language Reference Manual

12.24 QUARTUS_PROJ_ASSIGN SPECIFICATION ..................................288

12.25 RATE SPECIFICATION ............................................................288
12.26 RCLKPOS, WCLKPOS AND CLKPULSELEN SPECIFICATIONS (SSRAM
TIMING) .........................................................................289
12.27 RESOLUTIONTIME SPECIFICATION ............................................291
12.28 RETIME SPECIFICATION .........................................................291
12.29 SC_TYPE SPECIFICATION .......................................................292
12.30 SHOW SPECIFICATION ...........................................................293
12.31 SPEED SPECIFICATION ..........................................................293
12.32 STANDARD SPECIFICATION .....................................................293
12.32.1 Available I/O standards .................................................................... 294
12.32.2 I/O standards supported by different chips .......................................... 296
12.32.3 I/O standard details ......................................................................... 297
12.32.4 Differential I/O standards ................................................................. 301
12.33 STD_LOGIC_VECTOR SPECIFICATION ........................................302
12.34 STRENGTH SPECIFICATION .....................................................303
12.35 SYNCHRONOUS SPECIFICATION ...............................................304
12.36 UNCONSTRAINEDPERIOD SPECIFICATION ...................................304
12.37 VHDL_TYPE SPECIFICATION ...................................................305
12.38 WARN SPECIFICATION ...........................................................307
12.39 WEGATE SPECIFICATION ........................................................307
12.40 WESTART AND WELENGTH SPECIFICATIONS ................................307

13 HANDEL-C PREPROCESSOR ............................................................310

13.1 PREPROCESSOR MACROS .........................................................310
13.2 FILE INCLUSION ....................................................................311
13.3 CONDITIONAL COMPILATION ....................................................312
13.4 LINE CONTROL ......................................................................313
13.5 CONCATENATION IN MACROS ....................................................313
13.6 ERROR GENERATION ...............................................................314
13.7 PREDEFINED MACRO SUBSTITUTION ...........................................314
13.8 LINE SPLICING ......................................................................314

14 LANGUAGE SYNTAX ......................................................................316

14.1 LANGUAGE SYNTAX CONVENTIONS .............................................316
14.2 KEYWORD SUMMARY ..............................................................316
14.3 CONSTANT EXPRESSIONS .........................................................321
14.3.1 Identifiers: syntax ............................................................................. 321
14.3.2 Integer constants: syntax................................................................... 322
14.3.3 Character constants: syntax ............................................................... 322
14.3.4 Strings: syntax ................................................................................. 322
14.3.5 Floating-point constants: syntax.......................................................... 322
14.4 FUNCTIONS AND DECLARATIONS: SYNTAX ....................................323

www.celoxica.com Page 7
Handel-C Language Reference Manual

14.5 MACRO/SHARED EXPRS/PROCS: SYNTAX ....................................324

14.6 INTERFACES: SYNTAX .............................................................325
14.7 STRUCTURES AND UNIONS: SYNTAX ...........................................326
14.8 ENUMERATED TYPES: SYNTAX ...................................................326
14.9 SIGNAL SPECIFIERS: SYNTAX....................................................326
14.10 CHANNEL SYNTAX ................................................................326
14.11 RAM SPECIFIERS: SYNTAX......................................................327
14.12 DECLARATORS: SYNTAX.........................................................327
14.13 FUNCTION PARAMETERS: SYNTAX ............................................327
14.14 TYPE NAMES AND ABSTRACT DECLARATORS: SYNTAX ....................328
14.15 STATEMENTS: SYNTAX ..........................................................328
14.15.1 Compound statements with replicators ............................................... 331
14.16 REPLICATORS: SYNTAX .........................................................331
14.17 EXPRESSIONS: SYNTAX .........................................................332

15 INDEX ......................................................................................335

www.celoxica.com Page 8
Handel-C Language Reference Manual

Conventions
A number of conventions are used in this document. These conventions are detailed
below.

2 Warning Message. These messages warn you that actions may damage your
hardware.

Ï Handy Note. These messages draw your attention to crucial pieces of

information.

Hexadecimal numbers will appear throughout this document. The convention used is
that of prefixing the number with '0x' in common with standard C syntax.

Sections of code or commands that you must type are given in typewriter font like this:
void main();

Information about a type of object you must specify is given in italics like this:
copy SourceFileName DestinationFileName

Optional elements are enclosed in square brackets like this:

struct [type_Name]

Curly brackets around an element show that it is optional but it may be repeated any
number of times.
string ::= "{character}"

www.celoxica.com
Handel-C Language Reference Manual

Assumptions & Omissions

This manual assumes that you:

• have used Handel-C or have the Handel-C Language Reference Manual

• are familiar with common programming terms (e.g. functions)
• are familiar with MS Windows

This manual does not include:

• instruction in VHDL or Verilog

• instruction in the use of place and route tools
• tutorial example programs. These are provided in the Handel-C User Manual

www.celoxica.com
Handel-C Language Reference Manual

1 Introduction

1.1 References
• The C Programming Language 2nd Edition
Kernighan, B. and Ritchie, D.
Prentice-Hall, 1988
• Altera Databook
Altera 2004
www.altera.com/literature/lit-index.html
• Xilinx Data Book
Xilinx 2004
www.xilinx.com/literature/index.htm
• VHDL for logic synthesis
Author: Andrew Rushton
Publisher: John Wiley and Sons
ISBN: 0-471-98325-X
Published: May 1998
• IEEE standard 1364 -1995
IEEE Standard Hardware Description Language Based on the Verilog®
Hardware Description Language.
http://standards.ieee.org/

www.celoxica.com Page 11
Handel-C Language Reference Manual

2 Getting started with Handel-C

2.1 Basic concepts

Handel-C uses much of the syntax of conventional C with the addition of inherent
parallelism. You can write sequential programs in Handel-C, but to gain maximum benefit
in performance from the target hardware you must use its parallel constructs. These may
be new to some users. If you are familiar with conventional C you will recognize nearly
all the other features.

Handel-C programs

• Parallel programs
• Channel communications
• Scope and variable sharing

2.1.1 Handel-C programs

Since Handel-C is based on the syntax of conventional C, programs written in Handel-C

are implicitly sequential. Writing one command after another indicates that those
instructions should be executed in that exact order. To execute instructions in parallel,
you must use the par keyword.

Handel-C provides constructs to control the flow of a program. For example, code can be
executed conditionally depending on the value of some expression, or a block of code can
be repeated a number of times using a loop construct.

You can express your algorithm in Handel-C without worrying about how the underlying
computation engine works. This philosophy makes Handel-C a programming language
rather than a hardware description language. In some senses, Handel-C is to hardware
what a conventional high-level language is to microprocessor assembly language.

The hardware design that DK produces is generated directly from the Handel-C source
program. There is no intermediate 'interpreting' layer as exists in assembly language
when targeting general-purpose microprocessors. The logic gates that make up the final
Handel-C circuit are the assembly instructions of the Handel-C system.

2.1.2 Parallel programs

The target of the Handel-C compiler is low-level hardware. This means that you get
massive performance benefits by using parallelism. It is essential for writing efficient
programs to instruct the compiler to build hardware to execute statements in parallel.
Handel-C parallelism is true parallelism, not the time-sliced parallelism familiar from
general-purpose computers. When instructed to execute two instructions in parallel,

www.celoxica.com Page 12
Handel-C Language Reference Manual

those two instructions will be executed at exactly the same instant in time by two
separate pieces of hardware.

When a parallel block is encountered, execution flow splits at the start of the parallel
block and each branch of the block executes simultaneously. Execution flow then re-joins
at the end of the block when all branches have completed. Any branches that complete
early are forced to wait for the slowest branch before continuing.

This diagram illustrates the branching and re-joining of the execution flow. The left hand
and middle branches must wait to ensure that all branches have completed before the
instruction following the parallel construct can be executed.

2.1.3 Channel communication

Channels provide a link between branches executing in parallel. One parallel branch
outputs data onto the channel and the other branch reads data from the channel.

Channels can be constructed with and without FIFO capacities

• Channels constructed as FIFOs

A channel can be constructed as a FIFO queue. In this case, the data is written
to the head of the FIFO and is read from the tail. If the FIFO is full, a write
blocks until an element is read from the FIFO. If the FIFO is empty, a read
blocks until there is data ready to be read.
• Channels constructed without FIFO capacity
These channels provide synchronization between parallel branches because
the data transfer can only complete when both the transmitter and the
receiver are ready. If one side is not ready, the other must wait.

www.celoxica.com Page 13
Handel-C Language Reference Manual

Channel synchronization

SYNCHRONIZATION OF NORMAL CHANNELS

Here, the channel is shown transferring data from the left branch to the right branch. If
the left branch reaches point a before the right branch reaches point b, the left branch
waits at point a until the right branch reaches point b.

Communication without synchronization

If you are using a channel FIFO, the left branch will not have to wait at point a if there is
space in the FIFO. Instead, it can write to the FIFO once per clock tick until the FIFO is
full. Only then will it have to wait. Each time the right branch reads from the FIFO at
point b, the data at the head of the FIFO is read, and the next piece of data becomes the
head. The right branch must wait if the FIFO is empty.

In this case, the two branches will not be synchronized after every read and write.

www.celoxica.com Page 14
Handel-C Language Reference Manual

2.1.4 Scope and variable sharing

The scope of declarations is based around code blocks. A code block is denoted with {...}
brackets. This means that:

• Global variables must be declared outside all code blocks

• An identifier is in scope within a code block and any sub-blocks of that block.

The scope of variables is illustrated below:

Since parallel constructs are simply code blocks, variables can be in scope in two parallel
branches of code. This can lead to resource conflicts if the variable is written to
simultaneously by more than one of the branches. Handel-C states that a single variable
must not be written to by more than one parallel branch but may be read from by
several parallel branches.

If you wish to write to the same variable from several processes, the correct way to do
so is by using channels which are read from in a single process. This process can use a
prialt statement to select which channel is ready to be read from first, and that channel
is the only one which will be allowed to write to the variable.

www.celoxica.com Page 15
Handel-C Language Reference Manual

while(1)
prialt
{
case chan1 ? y:
break;
case chan2 ? y:
break;
case chan3 ? y:
break;
}

In this case, three separate processes can attempt to change the value of y by sending
data down the channels, chan1, chan2 and chan3. y will be changed by whichever
process sends the data first.

Ï A single variable should not be written to by more than one parallel branch.

3 Language basics

3.1 Program structure

Sequential structure
As in a conventional C program, a Handel-C program consists of a series of statements
which execute sequentially. These statements are contained within a main() function
that tells the compiler where the program begins. The body of the main function may be
split into a number of blocks using {...} brackets to break the program into readable
chunks and restrict the scope of variables and identifiers.

Handel-C also has functions, variables and expressions similar to conventional C. There
are restrictions where operations are not appropriate to hardware implementation and
extensions where hardware implementation allows additional functionality.

Parallel structure
Unlike conventional C, Handel-C programs can also have statements or functions that
execute in parallel. This feature is crucial when targeting hardware because parallelism is
the main way to increase performance by using hardware. Parallel processes can
communicate using channels. A channel is a point-to-point link between two processes.

www.celoxica.com Page 16
Handel-C Language Reference Manual

Overall structure
The overall program structure consists of one or more main functions, each associated
with a clock. This is unlike conventional C, where only one main function is permitted.
You would only use more than one main function if you needed parts of your program to
run at different speeds (and so use different clocks). A main function is defined as
follows:

Global Declarations

Clock Definition
void main(void)
{
Local Declarations

Body Code
}

The main() function takes no arguments and returns no value. This is in line with a
hardware implementation where there are no command line arguments and no
environment to return values to. The argc, argv and envp parameters and the return
value familiar from conventional C can be replaced with explicit communications with an
external system (e.g. a host microprocessor) within the body of the program.

3.2 Comments
Handel-C uses the standard /* ... */ delimiters for comments. These comments may not
be nested. For example:

/* Valid comment */

/* This is /* NOT */ valid */

Handel-C also provides the C++ style // comment marker which tells the compiler to
ignore everything up to the next new line. For example

x = x + 1; // This is a comment

3.3 Statement summary

www.celoxica.com Page 17
Handel-C Language Reference Manual

Statement Meaning

par {...} Parallel execution

seq {...} Sequential execution
par (Init ; Test ; Iter){...} Parallel replication
seq (Init ; Test ; Iter){...} Sequential replication
Variable = Expression; Assignment
Variable ++; Increment
Variable --; Decrement
++ Variable; Increment
-- Variable; Decrement
Variable += Expression; Add and assign
Variable -= Expression; Subtract and assign
Variable *= Expression; Multiply and assign
Variable /= Expression; Divide and assign
Variable %= Expression; Modulo and assign
Variable <<= Expression; Shift left and assign
Variable >>= Expression; Shift right and assign
Variable &= Expression; Bitwise AND and assign
Variable |= Expression; Bitwise OR and assign
Variable ^= Expression; Bitwise XOR and assign
Channel ? Variable; Channel input
Channel ! Expression; Channel output
if (Expression) {statement} [else Conditional execution
{statement}]
ifselect (Expression) {statement} Conditional compilation
[else {statement}]
while (Expression) {statement} Iteration
do {...} while (Expression); Iteration
for (Init ; Test ; Iter) {...} Iteration
break; Loop, switch and prialt termination
continue; Resume execution
return[([Expression])]; Return from function
goto label; Jump to label
switch (Expression) {statement} Selection
prialt {statement} Channel alternation

www.celoxica.com Page 18
Handel-C Language Reference Manual

releasesema() Make semaphore available after use of

trysema expression
try{...} Perform statements on reset condition
reset(Condition){statement}
delay; Single cycle delay

Note: RAM and ROM elements, signals and array elements are included in the set of
variables above. However,

ram x [3];

x[0]++;
is invalid.

Ï The assignment group of operations and the increment and decrement

operations are included as statements to reflect the fact that Handel-C
expressions cannot contain side effects.

3.4 Operator summary

The following table lists all operators. Entries at the top have the highest precedence and
entries at the bottom have the lowest precedence. Entries within the same group have
the same precedence. Precedence of operators is as expected from conventional C. For
example:

x = x + y * z;

This performs the multiplication before the addition. Brackets may be used to ensure the
correct calculation order as in conventional C.

Note that assignments are not true operators in Handel-C.

www.celoxica.com Page 19
Handel-C Language Reference Manual

Operator Meaning

trysema Test if semaphore owned. Take if not

select(Constant, Expr, Expr) Compile-time selection
Expression [Expression] Array or memory subscripting
Expression [Constant ] Bit selection
Expression [Constant: Bit range extraction. One of the two constants may
Constant] be omitted (but not both).
functionName (Arguments ) Function call
pointerToStructure->member Structure reference
structureName.member Structure reference
! Expression Logical NOT
~ Expression Bitwise NOT
- Expression Unary minus
+ Expression Unary plus
& object Yields pointer to operand
* pointer Yields object or function that the operand points to
width(Expression) Width of expression
(Type) Expression Type casting
Expression <- Constant Take LSBs
Expression \\ Constant Drop LSBs
Expression * Expression Multiplication
Expression / Expression Division
Expression % Expression Modulo arithmetic
Expression + Expression Addition
Expression - Expression Subtraction
Expression << Expression Shift left
Expression >> Expression Shift right
Expression @ Expression Concatenation
Expression < Expression Less than
Expression > Expression Greater than
Expression <= Expression Less than or equal
Expression >= Expression Greater than or equal
Expression == Expression Equal
Expression != Expression Not equal
Expression & Expression Bitwise AND
Expression ^ Expression Bitwise XOR

www.celoxica.com Page 20
Handel-C Language Reference Manual

Expression | Expression Bitwise OR

Expression && Expression Logical AND
Expression || Expression Logical OR
Expression ? Expr : Expr Conditional selection
assert diagnostic macro to print to stderr

3.5 Type summary

The most common types that may be associated with a variable, and the prefixes for
architectural and compound types are listed below.

Common logic types

Type Width

int See *Note 1

[signed | unsigned] int n n bits
[signed | unsigned] int Compiler infers width
undefined
[signed | unsigned] char 8 bits
[signed | unsigned] short 16 bits
[signed | unsigned] long 32 bits
[signed | unsigned] int32 32 bits
[signed | unsigned] int64 64 bits
typeof (Expression) Yields type of object
*Note 1: Width will be inferred by compiler unless the 'set intwidth = n' command
appears before the declaration.

Architectural types
Prefixes to the above types for different architectural object types are:

www.celoxica.com Page 21
Handel-C Language Reference Manual

Prefix Object

chan Channel
chanin Simulator channel
chanout Simulator channel
ram Internal or external RAM
rom Internal or external ROM
signal Wire
wom WOM within multi-port memory

Compound types
The compound types are:

Prefix Object

struct Structure
mpram Multi-port memory

Special types

Type Object

interface Interface to external logic or device

sema Semaphore. Has no width or logic type

Interfaces connect to logic beyond the Handel-C design, whether on the same or a
different device.

3.6 Comparison of Handel-C and ANSI-C

Handel-C has many similarities to ANSI-C (ISO-C). However, Handel-C is a language for
digital logic design, which means that the way in which DK interprets it may different to
the way in which compilers interpret ANSI-C for software design. Handel-C has some
extensions to ANSI-C, to allow additional functionality for hardware design. It also lacks
some ANSI-C constructs which are not appropriate to hardware implementation.

This section summarizes the differences between Handel-C and ANSI-C. It is not a
definitive list. Refer to specific sections to see how DK implements each of the language
constructs.

www.celoxica.com Page 22
Handel-C Language Reference Manual

3.6.1 Handel-C v C: types and type operators

Handel-C supports all ANSI-C types apart from float, double and long double. You can
still perform floating-point arithmetic.

char, short and long are supported to help the porting of code from ANSI-C. However,
it can be better (more efficient in hardware terms) to re-express these as a signed or
unsigned int of a specific width. In Handel-C, ints are not limited to 64 bits.

Handel-C has a range of additional types for creating channels and interfaces between
different hardware blocks, and for specifying memories and signals. The Celoxica wide
number library provides signed and unsigned compiler-independent implementations of
int32 and int64.

Handel-C also allows all ANSI-C storage class specifiers and type qualifiers, but volatile
and register have no meaning in hardware terms, and are accepted for compatibility
only.

You have to specify the size of an array in Handel-C. For example, you couldn't write:

int ai[SIZE]

and then # define SIZE.

Handel-C variables can only be initialized if they are static, const or global. Otherwise,
you must assign a value to them in a statement.

int a = 8 //not allowed

int a;
a = 8; // OK

static int a = 8; // OK

The Handel-C typeof operator allows you to determine the type of an object at compile
time.

3.6.2 Handel-C v C: floating-point variables

There are no floating-point types (float, double or long double) in Handel-C.

Floating-point arithmetic is more complex than integer or fixed-point arithmetic and

tends to require more hardware. If you are porting C code to Handel-C, check if there is
a way to avoid using floating-points. For example, you might be able to use fixed-point
values (which have a binary point), or to change the units to remove the decimal places
(e.g. use pence or cents instead of pounds or dollars).

If you do need to use floating-point arithmetic, use the Celoxica floating-point library.
This allows you to specify the exact width of the mantissa and exponent. You can
download the floating-point library from the downloads section of the Celoxica support
web site. If you can use fixed-point arithmetic, use the Celoxica fixed-point library. This
is provided in the Platform Developer's Kit.

www.celoxica.com Page 23
Handel-C Language Reference Manual

3.6.3 Handel-C v C: variable widths and casting

Handel-C widths
Handel-C types are not limited to specific widths. When you define a Handel-C variable,
you should specify the minimum width required, to minimize hardware usage. For
example, if you have a variable, x, that can hold a value between 1 and 20, use a 5-bit
int:

int 5 x;

Casting
There is no automatic conversion between signed and unsigned values in Handel-C, you
have to explicitly cast them:

int 12 x;
unsigned int 12 y;
y = x; //not allowed
y = (unsigned) x; //OK

Similarly, there is no automatic type conversion. If you wanted to add an int 5 and a
long together, you would need to pad the int to 32 bits by using the concatenation
operator. However, it would be more usual to perform arithmetic on ints of specific
widths.

Pointers can be cast to void and back, to another pointer of the same type except for the
addition or removal of a type qualifier, between signed and unsigned, and between
similar structs (e.g. a struct with identical elements except for the width of the types).

You cannot perform the following casts in Handel-C:

• from a pointer of one type to a pointer of another type (except for those listed
above)
• from a pointer to an integral type
• from an integral type to a pointer
• from a pointer to a function to a pointer to another function type

Arithmetic and comparisons on variables of different width

In Handel-C you need to use the concatenation operator or the take operator when
performing arithmetic or comparisons on variables of different width. For example:

www.celoxica.com Page 24
Handel-C Language Reference Manual

int 12 x;
int 8 y;

x = y; // not allowed
y = x; //not allowed
x = y[7] @ y[7] @ y[7] @ y[7] @ y // OK
y = x <-8; // OK; preserves the sign and copies the 7 LSBs

Alternatively you can use the width adjustment macros in the Celoxica standard macro
library, stdlib.hcl. The adju() macro adjusts the width of unsigned numbers and the
adjs() macro adjusts the widths of signed numbers. The standard library is now
provided as part of the Platform Developer's Kit (PDK). If you do not already have a copy
of PDK, you can download it from the support section of the Celoxica web site.

sizeof
There is no sizeof in Handel-C. For simple types (signed and unsigned char, int, long
and short), you can use the width operator. For example, sizeof long in C is
equivalent to width long in Handel-C, except that the number of bytes is returned in C
and the number of bits is returned in Handel-C.

3.6.4 Handel-C v C: side effects

There are restrictions on how you can use side-effects in Handel-C, because each
statement must only take one clock cycle. Each statement can only contain a single
assignment, or an increment or a decrement.

This means that:

• Shortcut assignments (e.g. +=) must appear as standalone statements.

• The initialization and iteration phases of for loops must be statements, not
expressions.

If you are porting ANSI-C code, complex statements have to be re-written as multiple
single statements. It is often more efficient to run these statements in parallel. You
cannot use comma operators in Handel-C.

If you had the following expression written in ANSI-C:

a = b = ++c, d+e;

this could be separated into single statements in Handel-C:

www.celoxica.com Page 25
Handel-C Language Reference Manual

seq
{
++c;
b = d + e;
a = b;
}

However, you could rewrite the same code to run all the statements in parallel:

par
{
++c;
a = d + e;
b = d + e;
}

3.6.5 Handel-C v C: functions

There are a number of differences in the way in which functions can be used in ANSI-C
and Handel-C.

In Handel-C:

• Functions may not be called recursively, since all logic must be expanded at
compile-time to generate hardware.
• You can only call functions in expression statements. These statements must
not contain any other calls or assignments.
• Variable length parameter lists are not supported.
• Old-style ANSI-C function declarations (where the type of the parameters is
not specified) are not supported.
• main() functions take no arguments and return no values.
• You can have more than one main() function. Each main() function is
associated with a clock. If you have more than one main() function in the
same source file, they must all use the same clock.
• You can have arrays of functions and inline functions. These are useful when
you are writing parallel code.

Re-writing recursive functions

If you want to port code that uses recursive functions to Handel-C, the options for
rewriting it include:

• Using recursive macro expressions or recursive macro procedures. (It must be

possible to determine the depth of recursion at compile-time.)
• Creating multiple copies of a function.

www.celoxica.com Page 26
Handel-C Language Reference Manual

• Re-writing the function to create iterative code. This is relatively easy if the
function is calling itself (simple recursion), and the recursive call is the last
item within the function definition (tail recursion).

The following ANSI-C function has simple tail recursion:

unsigned long Factorial (unsigned long n)

{
if (n==0)
return 1;
else
return n * Factorial (n-1);
}

It can be re-written in Handel-C as:

unsigned int 32 Factorial (unsigned int 32 n)

{
unsigned int 32 nfact;
nfact = 1;
if (n == 0)
delay;
else
{
while (n != 0)
{
nfact *= n;
--n;
}
}
return nfact;
}

Note that the if...else is required to prevent the possibility of a combinatorial loop if
the while loop is not executed.

3.6.6 Handel-C v C: loop statements

for loops in Handel-C are slightly different to those in ANSI-C: the initialization and
iteration steps are written as statements rather than expressions. This is because of
restrictions on side effects in expressions in Handel-C.

You need to ensure that loop statements take at least one clock cycle in Handel-C. This
means that:

• you cannot have empty loops in Handel-C

www.celoxica.com Page 27
Handel-C Language Reference Manual

• you need to ensure that the body of a loop will always execute at least once,
or else provide an alternative execution point using an if...else.

For example, if you had the following ANSI-C code:

while ((--i) != 0)
{
MyFunction (i);
}

The while loop would not be executed if i was equal to 0. You could re-write this in
Handel-C as:

--i;
if (i != 0)
while (i != 0)
{
MyFunction (i);
--i;
}
else
delay;

Note that you need to decrement i before you enter the while body to preserve the order
dependency of the ANSI-C code.

3.6.7 Handel-C v C: unions

If there is no relationship between members of the union, you can use a struct instead.

If the members of the union are of related types (e.g. int, long and char), you can
"reuse" a single variable which is the width of the widest variable in the union. For
example, if you have the following union in your C code:

union
{
unsigned long ul;
unsigned char uc;
short ss;
} u;

you could use a single variable of the same width as the long:

unsigned int 32 i;

You could then get values equivalent to ul, ss and ul by casting and using the take
operator:

www.celoxica.com Page 28
Handel-C Language Reference Manual

u.ul would be written as i

u.uc would be written as i <-8

u.ss would be written as (signed) (i<-16)

Note that in ANSI-C there is no guarantee about whether ul, uc and ss would share
storage, and so the Handel-C code above might not exactly reproduce the behaviour of
the ANSI-C code in your C compiler.

3.6.8 Handel-C v C: data input and output

Handel-C does not have functions equivalent to scanf() and printf(). You can use
scanf() and printf() when you are simulating a design, as Handel-C allows you to
make calls to Handel-C functions. Alternatively, you can use the Handel-C infile and
outfile specifications. Both these methods allow you to debug an algorithm before you
build it in hardware.

When you are targeting hardware, data is passed between different parts of your Handel-
C design using channels. If your Handel-C design will receive data from or send data to
external components, you need to specify an interface. These external components
might be written in EDIF, Verilog or VHDL, or they could be an additional component
specified in Handel-C.

3.6.9 Handel-C v C: memory allocation

Memory allocation is not relevant when you are targeting hardware, so Handel-C has no
equivalent of malloc and free.

You can use Handel-C to create RAM or ROM blocks on an FPGA or PLD, or interface to
off-chip memory.

3.6.10 Handel-C v C: standard library

The standard library in Handel-C is called stdlib.hcl. This has no relationship to the C
library, stdlib.lib or to stdio.lib.

stdlib.hcl contains bit manipulation and arithmetic macros.

The standard library is now provided as part of the Platform Developer's Kit (PDK). If you
do not already have a copy of PDK, you can download it from the support section of the
Celoxica web site.

3.6.11 C and Handel-C types and objects

www.celoxica.com Page 29
Handel-C Language Reference Manual

In both Conventional Handel-C

C only only
int double chan
unsigned float ram
char union rom
long wom
short mpram
enum signal
register chanin
static chanout
extern undefined
struct interface
volatile <>
void inline
const typeof
auto
signed
typedef

3.6.12 Expressions in C and Handel-C

www.celoxica.com Page 30
Handel-C Language Reference Manual

In both Conventional Handel-C

C only only

* (pointer sizeof select(…)

indirection)
& (address of) width(…)
- @
+ \\
* <-
(multiplication)
/ [:]
let…in

<<

>>

>

<

>=

<=

==

!=

& (bitwise and)

? :

[]

&&

||

->

www.celoxica.com Page 31
Handel-C Language Reference Manual

3.6.13 Statements in C and Handel-C

In both Handel-C only

{;} par
switch delay
do … while ?
while !
if … else prialt
for (;;) seq
break ifselect
continue
return
goto
assert assert is an expression in Handel-C and not the
same as in ANSI-C

3.7 Handel-C constructs not found in ANSI-C

Handel-C is designed to target hardware. It allows you to specify timing and to target
components such as memory, ports, buses and wires. One of the most important
differences to ANSI-C is the ability to create code that executes in parallel.

Handel-C constructs that are not found in ANSI-C are listed below.

Parallelism
The par keyword specifies that a block of code should execute in parallel. Each statement
within the block is executed in the same clock cycle. If the par keyword is not used,
statements within a code block are executed sequentially. You can use the seq keyword
to make this more explicit.

Channels allow communication between parallel branches of code. They are specified
using the chan keyword, or by chanin and chanout when you are simulating code. You
can read from and write to channels using statements of the form

Channel ? Variable; //reads from a channel

Channel ! Expression; //writes to a channel

prialt statements are used with multiple channels, to select the first one that is ready
for a read or write.

Semaphores (sema) allow you to coordinate the use of resources that are shared between
parallel branches of code. The trysema() construct tests to see if the sema is owned.

www.celoxica.com Page 32
Handel-C Language Reference Manual

The releasesema() construct frees a semaphore once it is no longer needed by a

resource.

inline functions, arrays of functions, macro procedures and macro expressions help you
to create multiple copies of functions. You need copies of a function if it is to be accessed
by parallel branches of code.

Timing
The set clock construct specifies the clock source for each main() function. You can
have more than one clock interfacing with your design by specifying more than one
main() function. If you want to simulate code, you can set a "dummy" clock. You can
specify the frequency of a clock using the rate specification. The clockport specification
can be used to assign a dedicated clock input resource on your target device. You can
also use it to specify that a port on an interface is used to drive the Handel-C clock.

Assignments and delay take one clock cycle in Handel-C. Everything else is "free". The
delay statement does nothing, but takes one clock cycle. This can be used to avoid
timing conflicts, such as combinational loops.

The intime and outtime specifications can be used to specify the maximum delay
between an interface and an element interacting with an interface, (e.g. the port reading
data into a RAM).

Compile-time selection and expansion and generic code

When you write code to target hardware, all logic needs to be expanded at compile time.
This means that you cannot use recursive functions. However, macro procedures, macro
expressions and shared expressions allow compile-time recursion in combination with the
select, ifselect and let...in constructs.

The select operator allows you to select between expressions at compile time. It is
similar to the conditional operator (cond ? expr1: expr2), but no hardware is
generated for the conditional.

The ifselect construct is similar to an if...else, but selects between alternative

blocks of code at compile time.

The typeof operator allows the type of an object to be determined at compile time. The
undefined keyword specifies that the compiler should infer the width of a variable. These
constructs allow you to create parameterizable code. For example, the Celoxica fixed-
point library uses macros to pass the integer width and fraction width of a fixed-point
number into code that creates a struct to hold the number.

Targeting hardware; FPGAs and PLDs

The set family and set part constructs allow you to specify the device you want to
target in your source code. You can also set the device using the DK GUI.

Targeting hardware; memory

The ram and rom keywords allow you to create on-chip RAM and ROM, and to interface to
external RAM and ROM. If you want to create a block RAM, use the block specification.

www.celoxica.com Page 33
Handel-C Language Reference Manual

To interface to off-chip RAMs or ROMs, use the offchip specification. The addr, data,
we, cs, oe and clk specifications define the pins used between the FPGA/PLD and
external RAM or ROM.

An mpram is a multi-ported RAM. This allows you to read from and write to a RAM within
the same clock cycle, or to make two read or two write accesses. Individual ports can be
specified as read/write, read-only and write-only using the ram, rom and wom keywords.

If you want to interface to a dedicated memory resource on the FPGA/PLD, use the ports
specification.

The clkpulselen, rclkpos and wclkpos specifications allow you to synchronize a RAM
clock with the Handel-C clock. The westart, welength and wegate specifications allow
you to specify timing of a RAM clock that is asynchronous to the Handel-C clock.

Targeting hardware; wires

If you specify a signal in Handel-C, this creates a wire in hardware. A signal takes on
the value assigned to it but only for that clock cycle. The value assigned to it can be read
back during the same clock cycle.

Targeting hardware; resets

set reset allows you to reset your device into a known state. It can also be used to
configure devices that are not in a known state at start up.

try...reset allows you to specify some actions that occur if a particular condition
becomes true within a particular block of hardware.

Interfacing to existing modules and to peripherals

Handel-C interfaces can be used to connect to external devices or to external logic on
your target FPGA/PLD, such as other programs written in Handel-C, VHDL or Verilog.

Port-type interfaces allow you connect to external logic. The bind, properties and
std_logic_vector specifications allow you to parameterize interfaces connecting to
external code.

Bus-type interfaces connect to pins connected to peripheral devices. The standard

specification selects the I/O standard for interface pins and the strength specification
determines the drive current. You can use the dci specification if you want to use digital
controlled impedance. The pull specification allows you to create a pull up or pull down
resistor for bus pins. The speed specification allows you to specify the slew rate for the
output buffer on pins.

The extern "language" construct is the same as that found in C++. It allows you to
connect to blocks of ANSI-C or C++ code for co-simulation.

Bit manipulation
Handel-C types are not constrained to a specific width, so you can specify the exact
width needed for a variable to minimize hardware usage. Bit manipulation is required to
connect objects of different widths. In addition to the ANSI-C bit manipulation operators,

www.celoxica.com Page 34
Handel-C Language Reference Manual

Handel-C provides the take and drop operators, which take and drop the least significant
bits of a variable, and the concatenation operator, to extend variable width. The bit
selection operator, allows you to select individual bits of a variable.

www.celoxica.com Page 35
Handel-C Language Reference Manual

4 Declarations

4.1 Introduction to types

Handel-C uses two kinds of objects: logic types and architecture types. The logic types
specify variables. The architecture types specify variables that require a particular sort of
hardware architecture (e.g., ROMs, RAMs and channels).

Both kinds are specified by their scope (static or extern), their size and their type.
Architectural types are also specified by the logic type that uses them.

Both types can be used in derived types (such as structures, arrays or functions) but
there may be some restrictions on the use of architectural types.

Specifiers
The type specifiers signed, unsigned and undefined define whether the variable is
signed and whether it takes a default defined width.

You can use the storage class specifiers extern and static to define the scope of any
variable.

Functions can have the storage class inline to show that they are expanded in line,
rather than being shared.

Type qualifiers
Handel-C supports the type qualifiers const and volatile to increase compatibility with
ANSI-C. These can be used to further qualify logic types.

Disambiguator
Handel-C supports the extension < >. This can be used to clarify complex declarations of
architectural types.

4.1.1 Handel-C values and widths

A crucial difference between Handel-C and conventional C is Handel-C’s ability to handle

values of arbitrary width. Since conventional C is targeted at general-purpose
microprocessors it handles 8, 16 and 32 bit values well but cannot easily handle other
widths. When targeting hardware, there is no reason to be tied to these data widths and
so Handel-C has been extended to allow types of any number of bits.

Handel-C has also been extended to cope with extracting bits from values and joining
values together to form wider values. These operations require no hardware and can
provide great performance improvements over software.

www.celoxica.com Page 36
Handel-C Language Reference Manual

When writing programs in Handel-C, care should be taken that data paths are no wider
than necessary to minimize hardware usage. While it may be valid to use 32-bit values
for all items, a large amount of unnecessary hardware is produced if none of these values
exceed 4 bits.

Care must also be taken that values do not overflow their width. This is more of an issue
with Handel-C than with conventional C because variables should be just wide enough to
contain the largest value required (and no wider).

You cannot cast a variable or expression to a type with a different width. Use the
concatenation operator to zero pad or sign extend a variable to a given width.

4.1.2 String constants

String constants are allowed in Handel-C. A string constant consists of a string of

characters delimited by double quotes ("). They will be stored as a null-terminated array
of characters (as in ANSI-C). String constants can contain any of the special characters
listed below. Arrays and pointers can be initialized with string constants, and string
constants can be assigned to pointers. If a string constant is assigned to a pointer, the
storage for the string will be created implicitly.

Special characters:

\a alert
\b backspace
\f formfeed
\n newline
\r carriage return
\t tab
\v vertical tab
\\ backslash
\? question mark
\' single quote
\" double quote
\onumber octal number e.g. \o77
\xnumber hexadecimal number e.g. \xf3

4.1.3 Constants

Constants may be used in expressions. Decimal constants are written as simply the
number while hexadecimal constants must be prefixed with 0x or 0X, octal constants

www.celoxica.com Page 37
Handel-C Language Reference Manual

must be prefixed with a zero and binary constants must be prefixed with 0b or 0B. For
example:

w = 1234; /* Decimal */

x = 0x1234; /* Hexadecimal */

y = 01234; /* Octal */

z = 0b00100110; /* Binary */

The width of a constant may be explicitly given by 'casting'. For example:

x = (unsigned int 3) 1;

Casting may be necessary where the compiler is unable to infer the width of the constant
from its usage.

4.2 Logic types

The basic logic type is an int. It may be qualified as signed or unsigned. Integers can
be manually assigned a width by the programmer or the compiler will attempt to infer a
width from use.

Enumeration types (enums) allow you to define a specified set of values that a variable of
this type may hold.

There are derived types (types that are derived from the basic types). These are arrays,
pointers, structs bit fields, and functions. The non-type void enables you to declare
empty parameter lists or functions that do not return a value. The typeof type operator
allows you to reference the type of a variable.

4.2.1 int

There is only one fundamental type for variables: int. By default, integers are signed.
The int type may be qualified with the unsigned keyword to indicate that the variable
only contains positive integers or 0. For example:

int 5 x;
unsigned int 13 y;

These two lines declare two variables: a 5-bit signed integer x and a 13-bit non-negative
integer y. In the second example here, the int keyword is optional. Thus, the following
two declarations are equivalent.

unsigned int 6 x;
unsigned 6 x;

You may use the signed keyword to make it clear that the default type is used. The
following declarations are equivalent.

www.celoxica.com Page 38
Handel-C Language Reference Manual

int 5 x;
signed int 5 x;
signed 5 x;

The range of an 8-bit signed integer is -128 to 127 while the range of an 8-bit unsigned
integer is 0 to 255 inclusive. This is because signed integers use 2's complement
representation.

You may declare a number of variables of the same type and width simultaneously. For
example:

int 17 x, y, z;

This declares three 17-bit wide signed integers x, y and z.

4.2.2 Signed | unsigned syntax

Signed | unsigned is declared in the same way as in ANSI-C except that Handel-C
allows the width to be declared. The width may be undefined, an expression, or nothing.

For example:

• int a;
• long b;
• unsigned int 7 c;
• signed undefined d;
• long signed int e;

4.2.3 Supported types for porting

Handel-C provides support for porting from conventional C by allowing the types char,
short and long. For example:

unsigned char w;
short y;
unsigned long z;

Note that these are fixed-widths in Handel-C, and implementation dependent in ANSI-C.
The widths used for each of these types in Handel-C is as follows:

www.celoxica.com Page 39
Handel-C Language Reference Manual

Type Width

char 8 bits (signed)

short 16 bits
long 32 bits

Ï Smaller and more efficient hardware will be produced by using variables of the
smallest possible width.

4.2.4 Inferring widths

The Handel-C compiler can infer the width of variables from their usage. It is therefore
not always necessary to explicitly define the width of all variables and the undefined
keyword can be used to tell the compiler to try to infer the width of a variable. For
example:

int 6 x;
int undefined y;

x = y;

In this example the variable x has been declared to be 6 bits wide and the variable y has
been declared with no explicit width. The compiler can infer that y must be 6 bits wide
from the assignment operation later in the program and sets the width of y to this value.

If the compiler cannot infer all the undefined widths, it will generate errors detailing
which widths it could not infer.

The undefined keyword is optional, so the two definitions below are equivalent:

int x;
int undefined x;

Handel-C provides an extension to allow you to override this behaviour to ease porting
from conventional C. This allows you to set a width for all variables that have not been
assigned a specific width or declared as undefined.

This is done as follows:

set intwidth = 16;

int x;
unsigned int y;

www.celoxica.com Page 40
Handel-C Language Reference Manual

This declares a 16-bit wide signed integer x and a 16-bit wide unsigned integer y. Any
width may be used in the set intwidth instruction, including undefined.

You can still declare variables that must have their width inferred by using the undefined
keyword. For example:

set clock = external "p1";

set intwidth = 27;

void main(void)
{
unsigned x;
unsigned undefined y;
}

This example declares a variable x with a width of 27 bits and a variable y that has its
width inferred by the compiler. This example also illustrates that the int keyword may
be omitted when declaring unsigned integers.

You may also set the default width to be undefined:

set intwidth = undefined;

4.2.5 Arrays

You can declare arrays of variables in the same way that arrays are declared in
conventional C. For example:

int 6 x[7];

This declares 7 registers each of which is 6 bits wide. Accessing the variables is exactly
as in conventional C. For example, to access the fifth variable in the array:

x[4] = 1;

Note that as in conventional C, the first variable has an index of 0 and the last has an
index of n-1 where n is the total number of variables in the array.

When a variable is used as an array index, as is often done when using a for loop, the
variable must be declared unsigned.

Example
This loop initializes all the elements in array ax to the value of index.

www.celoxica.com Page 41
Handel-C Language Reference Manual

unsigned int 6 ax[7];

unsigned index;

index=0;
do
{
ax[index] = (0 @ index);
index++;
}
while(index <= 6);

Note that the width of index has to be adjusted in the assignment. This is because its
width will be inferred to be 3, from the array dimension (the array has 7 elements, so
"index" will only ever need to count as far as 6).

Multidimensional arrays
You can declare multi-dimensional arrays of variables. For example:

unsigned int 6 x[4][5][6];

This declares 4 * 5 * 6 = 120 variables each of which is 6 bits wide. Accessing the
variables is as expected from conventional C. For example:

y = x[2][3][1];

Pointers to arrays
If you want to declare a pointer to the whole of an array, rather than an individual
element, you must enclose the variable name and the "*" in brackets. You must also use
brackets when initializing a pointer to an entire array:

// Declare an array
unsigned 4 MyArray [2];

// Declare a pointer to an array element

unsigned 4 *pointer_to_array_element;

// Declare a pointer to the entire array - brackets are required

unsigned 4 (*pointer_to_array) [2];

void main(void)
{
// Initialize pointer to point to an individual array element
pointer_to_array_element = &MyArray[0];

www.celoxica.com Page 42
Handel-C Language Reference Manual

// Initialize pointer to point to the entire array - brackets are

required
(pointer_to_array) = &(MyArray);
...
}

If you wanted to view all the referenced values MyArray in the Watch window during
simulation, you would need to type in "(*pointer_to_array)".

4.2.6 Array indices

When an array is declared, the index has the smallest width possible. For instance, in
array[8], the index need only go up to seven and will therefore be a three bit number. If
a variable is declared to represent the index, it too will be three bits.

4.2.7 struct

struct defines a data structure; a grouping together of variables under a single name.
The format of the structure can be identified by a type name. The variable members of
the structure may be of the same or different types. Once a structure has been declared,
its type name can be used to define other structures of the same type. Structure
members may be accessed individually using the construct

struct_Name.member_Name

Syntax
A structure type is declared using the format

struct [type_Name]
{
member-list
} [instance_Name {,instance_Name}];

member-list is a list of variable definitions terminated by semi-colons.

The use of instance_Names declares variables of that structure type. Alternatively, you
may declare variables as follows:

struct type_Name instance_Name;

Storage
• Structures may be passed through channels and signals.
• Structures may be stored in internal memory elements.
• Structures cannot be stored in off-chip RAMs.

www.celoxica.com Page 43
Handel-C Language Reference Manual

If a structure contains a memory element, a channel, or a signal, it cannot be stored in

another memory element, it cannot be passed to a function "by value", it cannot be
assigned to and it cannot be passed through a channel or a signal.

If a structure contains a memory element, it cannot be assigned (or assigned to) another
structure, as the assignment cannot be performed in a single clock cycle.

Whole structures may not be sent directly to interfaces.

Example
struct human // Declare human struct type
{
unsigned int 8 age; // Declare member types
int 1 sex;
char name[25];
}; // Define human type

struct human sister;

sister.age = 25;

Initialization
You can use a list initializer to initialize static or const structures or structures with global
scope. List initializers may be flat or structured.

struct Boris
{
int 12 v[3];
int 8 a, b;
};
static struct Boris b = {{1, 2, 3}, 4, 5};

4.2.8 enum

enum specifies a list of constant integer values, for example:

enum weekdays {MON, TUES, WED, THURS, FRI};

The first name (in this case MON) has a value of 0, the next 1, and so on, unless explicit
values are specified. If not all values are specified, values increment from the last
specified value.

If you do not specify a width for the enum, the program must contain information from
which the compiler can infer the width.

You can declare variables of a specified enum type. They are effectively equivalent to int
undefined or unsigned undefined. The signedness is inferred from use.

To specify enum values

www.celoxica.com Page 44
Handel-C Language Reference Manual

enum weekdays {MON = 9, TUES, WED, THURS, FRI};

To specify the width of an enum

enum weekdays {MON = (unsigned 4)9, TUES, WED, THURS, FRI};

To declare a variable of type enum

enum weekdays x;

To assign enum values to a variable

static int x = MON;

Example
The example below illustrates how to infer the width of an enum. The cast ensures the
enumerated variable has a width associated with it.

set clock = external "P1";

typedef enum
{
A,
B,
C = 43,
D
} En;

void main(void)
{
En num;
int undefined result;

num = (int 7)D;

result = num;
}

4.2.9 Bit fields

A bit field is a type of structure member consisting of a specified number of bits. The
length of each field is separated from the field name by a colon (:). Each element can be
accessed independently. Since Handel-C allows you to specify the width of integers in
bits, a bit field is merely another way of specifying a standard structure. In ANSI-C, bit
fields are made up of words, and only the specified bits are accessed, the rest are
padded. Padding in ANSI-C is implementation dependent. There is no padding in Handel-
C, so nothing can be assumed about it.

www.celoxica.com Page 45
Handel-C Language Reference Manual

Syntax
struct [tag_name]
{
field_Type field_Name: field_Width
...
} [instance_names] ;

Example
This example defines an identical array of flags as a structure and as a bit field.

struct structure
{
unsigned int 1 LED;
unsigned int 1 value;
unsigned int 1 state;
}outputs;

struct bitfield
{
unsigned int LED : 1;
unsigned int value : 1;
unsigned int state : 1;
}signals;

4.3 Pointers
A pointer declaration consists of *, the name of the pointer and the type of the variable
that it points to.

type *Name

Pointers are used to point to variables in conjunction with the unary operator &, which
gives the address of an object. To set a pointer to point to a variable, you assign the
address of the variable to the pointer. For example

int 8 *ptr; //declare a pointer to an int 8

int 8 object, x;
object = 6;
x = 10;
ptr = &object; //assigns address of object to ptr
x = *ptr; // x is now 6
*ptr = 12; //object is now 12

www.celoxica.com Page 46
Handel-C Language Reference Manual

Ï The behaviour of uninitialized pointers is undefined. De-referencing an

uninitialized pointer during simulation will result in a run-time error, after
which the simulator will terminate.

Casting pointers
In Handel-C, you may only cast void pointers (void * pointerName) to a different type.
All other pointers may only be cast to change the sign of an object pointed to, and
whether it is const or volatile. These restrictions are the standard casting restrictions in
Handel-C.

You can change a void pointer's type by casting, assignment or comparison. Void * must
have a consistent type so:

void *p;
int 6 *s;
int 7 *t;
p = s;
p = t; //invalid

Pointer arithmetic
You cannot perform arithmetic on a void pointer because the size of the object being
pointed to is not known.

• Valid pointer operations are:

• Assign a pointer to another pointer of the same type
• Add a pointer and an integer
• Subtract an integer from a pointer
• Subtract or compare (using <, <=, > or >=) a pointer to an array or memory
member with another pointer to a member of the same array or memory
• Compare two pointers for equality (using != or ==)
• Assign or compare a pointer to NULL

The result of subtracting or comparing pointers to members of different arrays or

memories or to other objects is undefined.

The behaviour of arithmetic on pointers that moves the pointer beyond the extent of the
object is undefined. An exception is that an address one element beyond an array or
memory (at the high end) is valid, but it is not valid to dereference a pointer at such an
address (the behaviour of the dereference would be undefined). This "one-beyond"
address is useful for loops.

www.celoxica.com Page 47
Handel-C Language Reference Manual

Examples
In the examples below, p and q can point to any part of Single or an element of Array,
AnotherArray or Memory.

int undefined i;
int 4 Single, Array [10], AnotherArray [20];
ram int 4 Memory [10];
int 4 * p, * q;
unsigned int 1 test;

p = & Single;
p += 2; // undefined behaviour (invalid address)
p = & Single; ++ p; // defined (valid address), but ...
* p = 0; // ... undefined behaviour
p = & (Array [4]);
p += 2; // now, p = & (Array [6])
p = Array; q = & (Array [4]);
i = q - p; // meaningful; now, i = 4;
test = (p < q); // meaningful (true in this case)
test = (p == q); // meaningful (false in this case)
p = Array; q = AnotherArray;
i = q - p; // undefined behaviour
test = (p < q); // undefined behaviour
test = (p == q); // meaningful (false for pointers into different objects)

4.3.1 Pointers and addresses

Pointers in Handel-C are similar to those in conventional C. They provide the address of a
variable or a piece of code. This enables you to access variables by reference rather than
by value.

The indirection operator (*) is the same as it is in ANSI-C. It is used to de-reference

pointers (i.e. to access objects pointed to by pointers).

The "address of" operator (&) works as it does in ANSI-C.

4.3.2 Pointers to functions

If you point to code (a function), the address operator is optional. The syntax is

returnType (*pointerName)(parameter list);

The parentheses at the end of the declaration declare the pointer to be a pointer to a
function. The * before the pointerName declares it to be a pointer declaration.

www.celoxica.com Page 48
Handel-C Language Reference Manual

There is the standard C type ambiguity between the declaration of a function returning a
pointer and a pointer to a function. To ensure that * is associated with the pointer name
rather than the return type, you need to use parentheses

int 8 * functionName(); //function returning pointer

and

int 8 (* pointerName)(); //pointer to function

4.3.3 Pointers to interfaces

When declaring pointers to interfaces, you must ensure that you declare a pointer to an
interface sort and then assign a defined interface to it (much as when you declare a
pointer to a function). You cannot combine the definition of an object with the declaration
of a pointer to it.

The members of the interface must have the same name in the declaration of the pointer
type as in the definition of the interface object which you assign the pointer to.

Example
//declaration of pointer to interface of sort bus_out
interface bus_out() *p(int 2 x);
interface bus_out() b(int 2 x=y); //interface definition
p=&b; // p now points to b

4.3.4 Structure pointers

The structure pointer operator (->) can be used, as in ANSI-C. It is used to access the
members of a structure, when the structure is referenced through a pointer.

struct S
{
int 18 a, b;
} s, *sp;
sp = &s;
s.a = 26;
sp->b = sp->a;

The last line accesses the member variables of structure s through pointer sp. Because
the pointer is being used to access the structure, the -> operator is used to refer to the
member variables.

sp->a = (*sp).q

You can cast structure pointers between structures with the same member types and
names. For example:

www.celoxica.com Page 49
Handel-C Language Reference Manual

struct S1
{
int 6 x;
} st1;

struct S2
{
int 6 x;
} st2;

set clock = external;

void main (void)
{
int r;
struct S1 *structPtr1;
struct S2 *structPtr2;
structPtr1 = &st1;
structPtr2 = (struct S2 *)structPtr1;
structPtr2->x = 7;
r = st1.x; //r = 7
}

4.3.5 address and indirection operators

The indirection operator * is the same as it is in ANSI-C. It is used to de-reference

pointers (i.e. to access objects pointed to by pointers).

The address operator (&) works as it does in ANSI-C.

The following can also be used: pointers to arrays, pointers to channels, pointers to
signals, pointers to memory elements, pointers to structures, pointers to pointers, arrays
of pointers.

Example: pointer assignment

unsigned char cha, chb, *chp;

chp = &cha;
cha = 90;

chb = *chp;
chp = &chb;

The first line declares two unsigned variables (cha and chb), and a pointer to an
unsigned (chp). The second line assigns the address of cha to pointer chp. In other
words, pointer chp now points to variable cha. The third line simply assigns a value to

www.celoxica.com Page 50
Handel-C Language Reference Manual

cha. The fourth line dereferences pointer chp, to access what it's pointing to, which is
cha. In other words, chb is assigned the value of the object pointed to by chp. The last
line assigns the address of chb to pointer chp. In other words, pointer chp now points to
variable chb.

Example: pointer to pointer assignment

struct S
{
int 6 a, b;
} s1, s2, *sp, **spp;

sp = &s1;
spp = &sp;
s2 = **spp;

This declares two variables of type struct S (s1 and s2), a pointer to a variable of this
type (sp), and a pointer to a pointer to a variable of this type (spp). The next line
assigns the address of structure s1 to pointer sp (pointer sp to point to structure s1).
The following line assigns the address of pointer sp to pointer spp (pointer spp to point to
pointer sp). The last line dereferences pointer spp twice, and it assigns the dereferenced
value, which is s1, to structure s2 (i.e. s2 now equals s1).

4.4 Architectural types

The architectural types are:

• channels (used to communicate between parallel processes)

• interfaces (used to connect to pins or provide signals to communicate with
external code)
• memories (rom, ram, wom and mpram)
• signal (declares a wire).

The type clarifier < > has been provided to help clarify the definitions of memories,
channels and signals.

4.5 Channels
Handel-C provides channels for communicating between branches of code executing in
parallel. One branch writes to a channel and a second branch reads from it.

Channels are declared with the chan keyword. For example:

chan int 7 link;

www.celoxica.com Page 51
Handel-C Language Reference Manual

The width and type of data sent down the channel must be of the same width and type
as the channel. The width and type of a channel can sometimes be inferred by the
Handel-C compiler, if they are not explicitly declared. The channel can be an entry in an
array of channels, or be pointed to by a channel pointer.

If you want to select the first channel that is ready to communicate from a list of
channels, use the prialt statement.

If you wish to convert the channel into a FIFO, use the fifolength specification. This
creates a FIFO with the specified number of data stores of the same width as the
channel.

If you are simulating code, you may use chanin and chanout to specify interfaces to the
simulator. These do not represent architectural channels but can be addressed in a
similar way.

Syntax
chan [ logicType ] Name [with specifications];

Reading from a channel

Channel ? Variable;

This assigns the value read from the channel to the variable. It may also be read to a
signal, an array element, RAM element or WOM element.

Writing to a channel
Channel ! Expression;

This writes the value of the expression to the channel. Expression may be any
expression of the correct type.

Example
set clock = external;
void main(void)
{
unsigned 8 Res;
chan Bill;

par
{
Bill ! 23;
Bill ? Res;
}
}

www.celoxica.com Page 52
Handel-C Language Reference Manual

4.5.1 FIFO code example

chan unsigned 8 ch with { fifolength=2 };

{
unsigned 8 a,b,c,d ;

ch!1; // FIFO becomes <1>

ch!2; // FIFO becomes <1,2>
ch?a; // FIFO becomes <2>, a becomes 1
ch!3; // FIFO becomes <2,3>
ch?b; // FIFO becomes <3>, b becomes 2
ch?c; // FIFO becomes empty, c becomes 3
ch!4; // FIFO becomes <4>
ch!5; // FIFO becomes <4,5>
ch?d; // FIFO becomes <5>, d becomes 4
ch!6; // FIFO becomes <5,6>
}

4.5.2 Arrays of channels

Handel-C allows arrays of channels to be declared. For example:

chan unsigned int 5 x[6];

This is equivalent to declaring 6 channels each of which is 5 bits wide. A channel can be
accessed by specifying its index. As with variable arrays, the index for the nth element is
n-1. For example:

x[4] ! 3; // Output 3 on channel x[4]

x[3] ? y; // Input to y from channel x[3]

It is also possible to declare multi-dimensional arrays of channels. For example:

chan unsigned int 6 x[4][5][6];

This declares 4 * 5 * 6 = 120 channels each of which is 6 bits wide. Accessing the
channels is similar to accessing arrays in conventional C. For example:

x[2][3][1] ! 4; // Output 4 on channel

4.5.3 Restrictions on channel accesses

No two statements may simultaneously write to or simultaneously read from a single

channel.

www.celoxica.com Page 53
Handel-C Language Reference Manual

par
{
out ! 3 // Undefined: simultaneous send to a channel
out ! 4
}

This code will give an undefined result, as it attempts to write simultaneously to a single
channel. Similarly, the following code will not work because an attempt is made to read
simultaneously from the same channel:

par
{
in ? x; // Undefined: simultaneous receive from a channel
in ? y;
}

Ï Your code should not rely on the perceived behaviour of multiple simultaneous
reads and writes, in either simulation or hardware.

You can detect parallel accesses to channel during simulation using the Detection of
simultaneous channel reads/writes option on the Compiler tab in Project Settings, or by using the
-S+parchan option in the command line compiler.

Simultaneous channel access concealed within prialt

The prialt construct negotiates the readiness of the remote (i.e. non-prialt) end of
channel. It does not resolve conflicts at the local (i.e. prialt) end of the channel. The
programmer must still avoid simultaneous channel accesses, even if the send or receive
statements are inside a prialt statement.

www.celoxica.com Page 54
Handel-C Language Reference Manual

Examples:
int 4 x, y, z;
chan <int 4> ch1, ch2;
unsigned int 1 thing;

// Code that affects thing

par {
ch2 ! x;
prialt
{
case ch1 ! y:
break;
case ch2 ! y:
// Undefined: simultaneous send
break;
}
if (thing)
ch1 ? z;
else
ch2 ? z;
}

If thing is false, then channel ch2 is the only channel that becomes ready to receive, so
the prialt tries to send y over ch2 simultaneously with the statement sending x over ch2,
resulting in an illegal simultaneous access.

There is a conflict even when thing is true, as ch2 undergoes readiness negotiations
within the prialt statement and this also requires access to the channel.

Restrictions on channels accesses between clock domains

If you have channels communicating between clock domains, all writes to a channel must
take place within a single clock domain, and all reads must take place within a single
clock domain.

For more information on using channels to communicate between clock domains, see
Channels communicating between clock domains (see page 169)

4.5.4 Timing and latency in FIFOs

Note that if fifolength is a power of 2, the channel will be implemented in a different

way to when it is not, in order to save memory.

Channels with FIFO sizes of a power of 2 may have greater latency.

www.celoxica.com Page 55
Handel-C Language Reference Manual

The latency of channels is dependent on the target architecture and the way the code has
been implemented within it.

4.6 Interfaces: overview

All interfaces, except for external (foreign code or off-chip) RAMs are declared with the
interface keyword in Handel-C. Interfaces are used to communicate with:

• external devices
• external logic, such as other Handel-C programs, programs written in VHDL
etc.

You can communicate between blocks of internal logic using channels

The interface definition is in two parts:

• an interface sort: the name of the black box or primitive that the interface
connects to
• an instance name: the name of the instance of the interface sort in Handel-C

Interface definitions may be split into declarations and definitions. You must use a
declaration if you want to define multiple instances of the same interface sort, or to use
forward references.

The declaration gives the sort name and port names and types associated with that
interface sort.

The definition gives the instance name, object specifications and the data transmitted for
a single instance of the interface sort.

Only signed and unsigned types may be passed over interfaces.

Ï Your license may not allow you to use interfaces. If this is the case you can
only interface to external devices using macros provided in any Celoxica
libraries you have licenses for, such as PAL.

4.6.1 Interface declaration

You need to use an interface declaration if you want to define multiple instances of an
interface sort, or to use forward references. If you only want a single instance of an
interface sort, you only need to use an interface definition.

Interfaces of pre-defined sorts do not need to be declared.

The general format of the interface declaration is:

www.celoxica.com Page 56
Handel-C Language Reference Manual

interface Sort (ports_in_to_Handel-C)

(ports_out_from_Handel-C);

Sort user-defined name or predefined interface sort

ports_in_to_Handel-C Optional. One or more prototypes of ports bringing data
into the Handel-C code.
ports_out_from_Handel-C Optional. One or more prototypes of ports sending data
from the Handel-C code.

A port prototype consists of the port type, and the port name. At least one port (whether
to Handel-C or from Handel-C) must be declared. Port declarations are delimited by
commas. For example:

interface MyInterface (int 5 InPort)

(int 4 OutPort1, int 4 OutPort2);

Ï The name of each port in a port_in or port_out interface must be different,

as they will all be built to the top level of the design.

Once you have declared an interface sort, you can define multiple instances of that sort.
The interface definition creates a named instance of the interface sort, assigns data to be
transmitted to the output ports, and may also specify properties using interface
specifications. You cannot use interface specifications in interface declarations, only in
interface definitions.

You can declare pointers to an interface declaration and then assign a defined interface
to the pointer.

4.6.2 Interface definition

A Handel-C interface definition consists of an interface sort, an instance name and data
ports, together with information about each port.

The definition defines a single instance of an interface sort. If you want to define multiple
instances, or use forward references to the interface, declare the interface, and then
make multiple definitions of that interface sort. (You do not need to declare interfaces of
predefined sorts.)

The general format of an interface definition is:

interface Sort (ports_in_to_Handel-C)

InstanceName (ports_out_from_Handel-C )
with {GeneralSpecs};

www.celoxica.com Page 57
Handel-C Language Reference Manual

Sort Pre-defined interface sort, or used-defined sort. (This

should match the sort in the interface declaration, if you
are using one.)
ports_in_to_Handel-C Definitions of one or more ports bringing data into the
Handel-C code. (Port definitions are described below.)
InstanceName User-defined identifier for that instance of the interface.
(You can define any number of instances of an interface
sort, if you make a declaration of the interface sort.)
ports_out_from_Handel-C Definitions of one or more ports sending data from the
Handel-C code.
Each output port should be assigned an expression. The
value of the expression will be connected to that port.
GeneralSpecs Handel-C interface specifications.
These specify hardware details of the interface, such as
chip pin numbers or are used to specify an external
simulator using the extlib directive.
Interface specifications apply to all ports in the interface.
You can also assign specifications to individual ports.

Port definitions
If the interface has been previously declared, the port definitions must be prototyped in
their interface declaration, and must have the same types as those in the prototype. The
declaration must have at least one port into Handel-C or from Handel-C. Port definitions
are delimited by commas. Each port definition consists of:

• the data type that uses it (either defined or inferred from its first use). Only
signed and unsigned types may be passed over interfaces.
• a port name
• port specifications (optional). The port specifications are enclosed in a set of
braces {...} and delimited by commas.

Example
interface Sort_A (int 4 inPort1, int 4 inPort2)
interfaceName (unsigned outPort = x)

4.6.3 Example interface to external code

This example shows an interface declaration used to connect to a piece of foreign code,
and the definition that uses this declaration.

www.celoxica.com Page 58
Handel-C Language Reference Manual

set clock = external "D17";

set family = XilinxVirtex;
set part = "V1000BG560-4";

// Interface declaration
interface ttl7446(unsigned 7 segments, unsigned 1 rbon)
(unsigned 1 ltn, unsigned 1 rbin, unsigned 4 digit,
unsigned 1 bin);

unsigned 1 ltnVal;
unsigned 1 rbinVal;
unsigned 1 binVal;
unsigned 4 digitVal;

// Interface definition
interface ttl7446(unsigned 7 segments, unsigned 1 rbon)
decode(unsigned 1 ltn=ltnVal, unsigned 1 rbin=rbinVal,
unsigned 4 digit=digitVal, unsigned 1 bin=binVal)
with {extlib="PluginModelSim.dll",
extinst="decode; model=ttl7446_wrapper; delay=1"};

This declares an interface of sort tt17446. The inputs from the interface to the Handel-C
design are segments and rbon. The interface would therefore connect to a black box
named tt17746 with ports segments, rbon, ltn, rbin, digit, and bin.

The instance of the interface is decode. The instance specifies the data going into the
ports ltn, rbin, digit, and bin and connects to a plugin, PluginModelSim.dll, for
simulation.

If you did not want to use forward references to the interface, and only wanted to define
a single instance of the interface sort tt17446, you would not need to declare the
interface. (The interface definition would be exactly the same as that shown above.)

4.6.4 Interface specifications

Predefined bus interface specs: Default:

data list the pins used for transferring data, MSB to LSB None

www.celoxica.com Page 59
Handel-C Language Reference Manual

speed set buffer speed (output) 2: Actel

ProASIC/
ProASIC+
1: others
pull set pull-up or pull-down for bus pins None
infile set file source for input bus data None
outfile set file destination for output bus data None

All interface specs: Default:

base specify display base for variables in debugger 10
bind bind component to work library 0
busformat text format of exported wires in EDIF netlist "B_I"

data list the pins used for transferring data, MSB to LSB None
dci apply Digital Controlled Impedance to buses (Xilinx 0 (No)
only)
extlib specify external plugin for simulator None
extfunc specify external simulator function for this port PlugInSet or
PlugInGet
extpath specify any direct logic (combinational logic) None
connections to another port
extinst specify connection to external code None
intime maximum allowable time between a port and the None
sequential elements it drives (in ns)
outtime maximum allowable time between a port and the None
sequential elements it is driven from (in ns)
properties parameterize instantiations of external black boxes None
sc_type specify type of port in port_in, port_out or bool for 1 bit
generic interface for SystemC ports, sc_uint
otherwise
standard specify I/O standard (electrical characteristics) to LVCMOS33 for
use on port(s) in question Actel
ProASIC/ProAS
IC+,
LVTTL for
others
strength specify drive strength (in mA) for output buses Standard
dependent

www.celoxica.com Page 60
Handel-C Language Reference Manual

vhdl_type specify type of port in port_in, port_out or std_logic for

generic interface in VHDL 1 bit ports,
unsigned
otherwise
warn disable some compiler warnings 1 (No)

4.7 RAMs and ROMs

RAMs and ROMs may be built from the logic provided in the FPGA/PLD using the ram and
rom keywords.

For example:

ram int 6 a[43];

static rom int 16 b[4] = { 23, 46, 69, 92 };

This example constructs a RAM consisting of 43 entries each of which is 6 bits wide and a
ROM consisting of 4 entries each of which is 16 bits wide.

ROMs must be declared as static or global. If you declare a static ROM in a macro
procedure, each call to the macro creates a separate version of the ROM. RAMs can be
declared as static, global or auto (i.e. non-static).

All RAMs and ROMs must be declared as arrays, so to declare a RAM that holds one 4 bit
integer, you must declare it as an array with a dimension of 1.

ram int 4 ramname[1];

Ï RAMs and ROMs may only have one entry accessed in any clock cycle.

4.7.1 Initialization

You can only initialize ROMs or RAMs if they are static, or have global scope. For
example, a global ROM could be initialized as shown below:

rom int 16 b[4] = { 23, 46, 69, 92 } with {block = 1};

The ROM is initialized with the constants given in the following list in the same way as an
array would be initialized in C. In this example, the ROM entries are given the following
values:

www.celoxica.com Page 61
Handel-C Language Reference Manual

ROM entry Value

b[0] 23
b[1] 46
b[2] 69
b[3] 92

4.7.2 Inferring size from use

The Handel-C compiler can also infer the widths, types and the number of entries in
RAMs and ROMs from their usage. Thus, it is not always necessary to explicitly declare
these attributes. For example:

ram int undefined a[123];

ram int 6 b[];
ram c[43];
ram d[];

4.7.3 Accessing RAMs and ROMs

RAMs and ROMs are accessed in the same way as arrays. For example:

ram int 6 b[56];

b[7] = 4;

This sets the eighth entry of the RAM to the value 4. Note that as in conventional C, the
first entry in the memory has an index of 0 and the last has an index of n-1 where n is
the total number of entries in the memory.

4.7.4 Differences between RAMs and arrays

RAMs differ from arrays in that an array is equivalent to declaring a number of variables.
Each entry in an array may be used exactly like an individual variable, with as many
reads, and as many writes to a different element in the array as required within a clock
cycle. RAMs, however, are normally more efficient to implement in terms of hardware
resources than arrays, but they only allow one location to be accessed in any one clock
cycle. Therefore, you should use an array when you wish to access the elements more
than once in parallel and you should use a RAM when you need efficiency.

www.celoxica.com Page 62
Handel-C Language Reference Manual

4.7.5 RAM and ROM support on different devices

Creating internal RAMs can only be done if the target device supports on-chip RAMs. Most
devices currently targeted by Handel-C do so (e.g. Altera Flex 10K, APEX, APEXII,
Mercury, Stratix and Cyclone, Xilinx Spartan series devices and Virtex series devices).

No Actel families support ROMs. ProASIC and ProASIC+ devices support RAMs, but these
may not be initialized.

4.7.6 Multidimensional memory arrays

You can create simple multi-dimensional arrays of memory using the ram, rom and wom
keywords. The definitions can be made clearer by using the optional disambiguator <>.

Syntax
ram | rom | wom logicType entry_width
Name[[const_expression]] {[[const_expression]]}
[= {initialization}];

Possible logic types are ints, structs, pointers and arrays.

The last constant expression is the index for the RAM. The other indices give the number
of copies of that type of RAM.

Example
ram <int 6> a[15][43];
static rom <int 16> b[4][2][2] =
{{{1, 2},
{3, 4}
},
{{5, 6},
{7, 8}
},
{{9, 10},
{11, 12}
},
{{13, 14},
{15, 16}
}
};

This example constructs 15 RAMs, each consisting of 43 entries of 6 bits wide and 4 * 2
ROMs, each consisting of 2 entries of 16 bits wide. The ROM is initialized with the
constants in the following list in the same way as a multidimensional array would be

www.celoxica.com Page 63
Handel-C Language Reference Manual

initialized in C. The last index (that of the RAM entry) changes fastest. In this example,
the ROM entries are given the following values:

ROM entry Value ROM entry Value

b[0][0][0] 1 b[0][0][1] 2
b[0][1][0] 3 b[0][1][1] 4
b[1][0][0] 5 b[1][0][1] 6
b[1][1][0] 7 b[1][1][1] 8
b[2][0][0] 9 b[2][0][1] 10
b[2][1][0] 11 b[2][1][1] 12
b[3][0][0] 13 b[3][0][1] 14
b[3][1][0] 15 b[3][1][1] 16
Because of their architecture, RAMs and ROMs are restricted to performing operations
sequentially. Only one element of a RAM or ROM may be addressed in any given clock
cycle and, as a result, familiar looking statements are often disallowed. For example:

ram <unsigned int 8> x[4];

x[1] = x[3] + 1;

This code is inadvisable because the assignment attempts to read from the third element
of x in the same cycle as it writes to the first element.

In a multi-dimensional array, you can access separate elements of the arrays, so long as
you are not accessing the same RAM. For example:

x[2][1]=x[3][0] is valid

x[2][1]=x[2][0] is invalid

Note that arrays of variables do not have these restrictions but may require substantially
more hardware to implement than RAMs depending on the target architecture.

4.8 mpram (multi-ported RAMs)

You can create multiple-ported RAMs (MPRAMs) by constructing something similar to an
ANSI-C union. You must use the mpram keyword.

mprams can be used to connect two independent code blocks. The clock of the mpram port
is taken from the function in which it is used.

The normal declaration of a MPRAM would be to create a dual-ported RAM by declaring

two ports of equal width:

• for Actel devices, one port must be read-only, and one write-only.

www.celoxica.com Page 64
Handel-C Language Reference Manual

• for Altera ApexII and Mercury devices, both ports can be bi-directional. For
Cyclone and Stratix devices this depends on the type of memory used. For
other Altera families, one port would be read-only and one write-only
• Altera Mercury devices can have up to four ports. You can have (one or two
write ports AND one or two read ports) OR two read/write ports. Depending on
how you have configured the port, you can have up to four simultaneous
accesses of the same block of memory.
• for Virtex and SpartanII devices, both ports would be read/write for block
RAM, and for LUT RAM, one port would be read/write and one read-only.
Spartan and SpartanXL devices only have distributed (LUT) RAM.

You can use mpram ports of different widths for certain devices.

The mpram construct allows the declaration of any number of ports. Your only restriction
is the target hardware.

You can apply clock specifications to the whole MPRAM, or to individual ports. MPRAM
write ports will be synchronous and read ports will be asynchronous by default, if the
target hardware allows it. For example, Stratix memories are fully synchronous and do
not allow an asynchronous read port.

You can create synchronous read ports explicitly by using clock position specifications
(rclkpos and clkpulselen), and asynchronous write ports by using write-enable
specifications (westart, welength or wegate). However, you cannot have an
asynchronous write port and a synchronous read port, since this would violate Handel-C's
timing semantics.

Syntax
mpram MPRAM_name
{
ram_Type variable_Type RAM_Name[size]
[with {ClockPosition/WriteEnableSpecs = value}];
ram_Type variable_Type RAM_Name[size]
[with {ClockPosition/WriteEnableSpecs = value}];
};

Examples
In the example below, the first MPRAM is a bi-directional dual-port RAM, with clock
specifications applied to the whole MPRAM. The second is a simple dual-port RAM, with
different clock specifications applied to each port.

www.celoxica.com Page 65
Handel-C Language Reference Manual

set clock = external_divide "C1" 4;

mpram
{
ram unsigned 4 Port1[4];
ram unsigned 4 Port2[4];
} TMax with {wclkpos = {2}, rclkpos = {2.5}, clkpulselen = 1};

mpram
{
wom unsigned 4 WritePort[4] with {wclkpos = {2}, clkpulselen = 1};
rom unsigned 4 ReadPort[4] with {rclkpos = {2.5}, clkpulselen = 1};
} SMax;

4.8.1 Initialization of mprams

The first member of the mpram can be initialized.

static mpram Fred

{
ram <unsigned 8> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
} Mary ={10,11,12,13};

This would have the same effect as

Mary.ReadWrite[0]=10;
Mary.ReadWrite[1]=11;
Mary.ReadWrite[2]=12;
Mary.ReadWrite[3]=13;

The other elements of Fred.ReadWrite will be initialized as zero (since Mary is static).
In this case, since Fred.Read is the same size as Fred.ReadWrite, elements 0 – 3 of
Fred.Read would be initialized with the same values.

4.8.2 Mapping of different width mpram ports

If the ports of the mpram are of different widths, they will be mapped onto each other
according to the specifications of the chip you are using. If the ports used are of different
widths, the widths should have values of 2n.

Different width ports are available for Xilinx Virtex and Spartan-II, Spartan-IIE and
Spartan-3 devices and Altera Apex II, Stratix and Cyclone devices. They are not available
with other Altera devices or Actel devices.

www.celoxica.com Page 66
Handel-C Language Reference Manual

Xilinx bit mapping

To find the bits that an array element occupies in a Xilinx Virtex or Spartan RAM, you can
use the formula
RAM array ram y Name[a] will have a start bit of (y * (a+1)) - 1 and an end bit of y * a.

Xilinx mapping is little-endian. This means that the address points to the LSB.

The bits between the declarations of RAM are mapped directly across, so that bit 27 in
one declaration will have the same value as bit 27 in another declaration, even though
the bits may be in different array elements in the different declarations.

mpram Joan
{
ram <unsigned 4> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
};

Joan.ReadWrite[100] will run from 400 to 403.

Joan.Read[100] will run from 800 to 807.

Joan.Read[50] will run from 400 to 407.

Joan.ReadWrite[100] is equivalent to Joan.Read[50][0:3].

ApexII bit mapping

To find the bits that an array element occupies in an ApexII RAM, you can use the
formula
RAM array ram y Name[a] will have a start bit of (y * (a+1)) - 1 and an end bit of y * a.

ApexII mapping is little-endian. This means that the address points to the LSB.

The bits between the declarations of RAM are mapped directly across, so that bit 27 in
one declaration will have the same value as bit 27 in another declaration, even though
the bits may be in different array elements in the different declarations.

mpram Joan
{
ram <unsigned 4> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
};

Joan.ReadWrite[100] will run from 400 to 403.

Joan.Read[100] will run from 800 to 807.

Joan.Read[50] will run from 400 to 407.

Joan.ReadWrite[100] is equivalent to Joan.Read[50][0:3].

www.celoxica.com Page 67
Handel-C Language Reference Manual

4.8.3 mprams example

Using an mpram to communicate between two independent logic blocks:

File 1:
mpram Fred
{
ram <unsigned 8> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
};

mpram Fred Joan ; // Declare Joan as an mpram like Fred

set clock = internal "F8M";

void main(void)
{
unsigned 8 data;

Joan.ReadWrite[7] = data;
}

File 2:
mpram Fred
{
ram <unsigned 8> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
};

extern mpram Fred Joan;

set clock = external "P2";

void main(void)
{
unsigned 8 data;
data= Joan.Read[7];
}

www.celoxica.com Page 68
Handel-C Language Reference Manual

4.9 WOM (write-only memory)

You can declare a write-only memory using the keyword wom. The only use of a write-
only memory would be to declare an element within a multi-ported RAM. Since woms only
exist inside multi-port rams, it is illegal to declare one outside an mpram declaration.

Syntax
wom variable_Type variable_Size WOM_Name[dimension] =
initialize_Values [ with {specs}]
Example
mpram connect
{
wom <unsigned 8> Writeonly[256]; // Write only port
rom <unsigned 8> Read[256]; // Read only port
}

4.10 sema
Handel-C provides semaphores for protecting critical areas of code. Semaphores are
declared with the sema keyword. For example:

sema RAMguard;

Semaphores have no type or width associated with them. They cannot be assigned to or
have their value assigned to anything else. You can only access semaphores through the
trysema(semaphore) expression and releasesema(semaphore) statement. trysema
tests to see if the semaphore is currently taken. If it is not, it takes the semaphore and
returns one. If it is taken, it returns zero. releasesema releases the semaphore. After
you have taken a semaphore, you should ensure that you release it cleanly once you
have left the critical area.

Semaphores may be included in structures. They cannot be passed to directly to

functions, over channels or interfaces. They may be passed to functions or channels by
reference.

Syntax
sema Name

www.celoxica.com Page 69
Handel-C Language Reference Manual

Example
inline void critRAMaccess(sema *RAMsema, ram int 8
(*danger)[4], unsigned count)
{
int 8 x;
// wait till you've got the // RAM
while(trysema(*RAMsema)==0) delay;
x= (*danger)[count];
releasesema(*RAMsema);
}

4.11 signal
A signal is an object that takes on the value assigned to it but only for that clock cycle.
The value is assigned at the start of the clock cycle and can be read back during the
same clock cycle. At all other times the signal takes on its initialization value. The
optional disambiguator <> can be used to clarify complex signal definitions.

If a signal is assigned to when you are debugging code, values shown in the Watch and
Variables windows are updated immediately, rather than at the end of the clock cycle
(step).

Signals represent wires in hardware.

Syntax
signal [<type data-width>] signal_Name;

Example
int 15 a, b;
signal <int> sig;

a = 7;
par
{
sig = a;
b = sig;
}

sig is assigned to and read from in the same clock cycle, so b is assigned the value of a.

Since the signal only holds the value assigned to it for a single clock cycle, if it is read
from just before or just after it is assigned to, you get its initial value. For example:

www.celoxica.com Page 70
Handel-C Language Reference Manual

int 15 a, b;
static signal <int> sig = 690;

a = 7;
par
{
sig = a;
b = sig;
}
a = sig;

Here, b is assigned the value of a through the signal, as before. Since there is a clock
cycle before the last line, a is finally assigned the signal's initial value of 690.

4.12 Storage class specifiers

Storage class specifiers define how variables are accessed.

extern and static are used within functions to allocate storage. static gives the
declared objects static storage class, and extern specifies that the variable is defined
elsewhere. For compatibility with ANSI-C, the specifiers auto and register can be used
but have no effect.

The expansion of a function is defined by the specifier inline.

The typedef specifier does not reserve storage, but allows you to declare new names for
existing types.

4.12.1 auto

auto defines a local automatic variable. In Handel-C, all local variables default to auto.
You cannot initialize an auto variable, but must assign it a value. The initialization status
of auto variables is undefined.

Example
set clock = external "P1";

void main (void)

{
auto 8 pig;
pig = 15;
}

www.celoxica.com Page 71
Handel-C Language Reference Manual

4.12.2 extern (external variables)

extern declares a variable that is external to all functions; the variable may be accessed
by name from any function.

External variables must be defined exactly once outside any function, and declared in
each function that wants to access them. The declaration may be an explicit extern , or
else be implicit from the context (if the variable has been defined outside a function
without static).

If the variable is used in multiple source files, it is good practice to collect all the extern
declarations in a header file, included at the top of each source file using the #include
headerFileName directive.

You may use extern "language" to access variables in C or C++ files.

Ï You cannot access the same variable from different clock domains.

Example
extern int 16 global_fish;
int global_frog = 1234;

main()
{
global_fish = global_frog;
…
}

Syntax
extern variable declaration;

4.13 extern language construct

The extern "language" construct allows you to declare that names used in Handel-C
code have ANSI-C or C++ linkage.

• For ANSI-C functions, use extern "C"

• For C++ functions, use extern "C++"

These functions can only be compiled for simulations targeting the simulator. They may
not be used in targeting devices.

www.celoxica.com Page 72
Handel-C Language Reference Manual

extern "C" and extern "C++" functions have the same timing as Handel-C functions.
For example, a printf() function would take at least one clock cycle, even if the return
value is ignored, and a C function with a body that takes 0 clock cycles and a void return
type would not take any clock cycles.

Examples
extern "C" int printf(const char *format, ...);
declares printf() with C linkage.

extern "C++"
{
int 14 x;
}

declares a variable, x, with C++ linkage.

extern "C"
{
//remove Microsoft-specific extensions from the header file
#define __cdecl
#include <stdio.h>
}

causes everything in stdio.h to have C linkage.

Mapping of types to C/C++

Handel-C types will be mapped to C/C++ types in the following way when inside an
extern "language" construct:

www.celoxica.com Page 73
Handel-C Language Reference Manual

Handel-C type C/C++ type

char char
short short
long long
int int (only valid within an extern "language" construct)
int width Int<width> (C++ only)
unsigned int width UInt<width> (C++ only)
struct struct
type ram[n] convertedType[n]
type rom[n] convertedType[n]
Others Generate an error
Mapping of types outside extern
Mapping of types outside the extern "language" construct is the same, except signed
and unsigned ints must have a specified width.

Ï When outside an extern "language" construct, an int without a specified

width will generate an error.

For example, the following Handel-C:

extern "C" int printf(const char *format, ...);

extern "C++"
{
int 14 x;
long y;
}
char f(long y); //outside extern construct

will map to this C++:

int printf(const char *format, ...);

Int<14> x;
long y;
char f(long y);

www.celoxica.com Page 74
Handel-C Language Reference Manual

4.14 register
register has been implemented for reasons of compatibility with ANSI-C. register
defines a variable that has local scope. Its initial value is undefined.

Example
register int 16 fish;
fish = f(plop);

4.15 inline functions

inline causes a function to be expanded where it is called. The logic will be generated
every time it is invoked. This ensures that the function is not accessed at the same time
by parallel branches of code.

Ï If you have a local static variable in an inline function there is one copy of the
variable per function instantiation.

By default, functions are assumed to be shared (not inline).

Example
inline int 4 knit(int needle, int stitch)
{
needle = needle + stitch;
return(needle);
}

int 4 jumper[100];
par(needle = 1; needle < 100; needle = needle+2)
{
jumper[needle] = knit(needle, 1);
}

Syntax
inline function_Declaration

www.celoxica.com Page 75
Handel-C Language Reference Manual

4.16 static
static gives a variable static storage (its values are kept at all times). This ensures that
the value of a variable is preserved across function calls. It also affects the scope of a
variable or a function. static functions and static variables declared outside functions can
only be used in the file in which they appear. static variables declared within an inline
function or an array of functions can only be used in the copy of the function in which
they appear. Handel-C uses static in a different way to C++. In C++, if you have an
inline function and a local static variable, one copy of the variable is shared across each
function instantiation. In Handel-C, there is one copy of the variable per function
instantiation.

static variables are the only local variables (excluding consts) that can be initialized. To
get a default value, initialize the variable.

Example
static int 16 local_function (int water, int weed);
static int 16 local_fish = 1234;

void main(void)
{
int fresh, pondweed;
local_fish = local_function(fresh, pondweed);
...
}

Syntax
static variable_declaration;
static functionName(parameter-type-list);

Static variables in arrays of functions

If a static variable is declared in an arrayed function, each instance of the function will
have its own independent copy of the variable.

4.17 typedef
typedef defines another name for a variable type. This allows you to clarify your code.
The new name is a synonym for the variable type.

typedef int 4 SMALL_FISH;

If the typedef is used in multiple source files, it is good practice to collect all the type
definitions in a header file, included at the top of each source file using the #include
headerFileName directive. It is conventional to differentiate typedef names from
standard variable names, so that they are easily recognizable.

www.celoxica.com Page 76
Handel-C Language Reference Manual

Example
typedef int 4 SMALL_FISH;

extern SMALL_FISH stickleback;

4.18 typeof
The typeof type operator allows the type of an object to be determined at compile time.
The argument to typeof must be an expression. Using typeof ensures that related
variables maintain their relationship. It makes it easy to modify code by simplifying the
process of sorting out type and width conflicts.

A typeof construct can be used anywhere a type name could be used. For example, you
can use it in a declaration, in casts.

Syntax
typeof ( expression )

Example
unsigned 9 ch;
typeof(ch @ ch) q;
struct
{
typeof(ch) cha, chb;
} s1;
typeof(s1) s2;

ch = s1.cha + s2.chb;
q = s1.chb @ s2.cha;

If the width of variable ch were changed in this example, there would be no need to
modify any other code.

This is also useful for passing parameters to macro procedures. The code below shows
how to use a typeof definition to deal with multiple parameter types.

macro proc swap (a, b)

{
typeof(a) t;
t=a;
a=b;
b=t;
}

www.celoxica.com Page 77
Handel-C Language Reference Manual

4.19 const
const defines a variable or pointer or an array of variables or pointers that cannot be
assigned to. This means that they keep the initialization value throughout. They may be
initialized in the declaration statement. The const keyword can be used instead of
#define to declare constant values. It can also be used to define function parameters
which are never modified. The compiler will perform type-checking on const variables
and prevent the programmer from modifying it.

Example 1
const int i = 5;

i = 10; // Error
i++; // Error

Example 2
const int *const p;

p = p + 1; // Error
*p = 3; // Error

4.20 volatile
In ANSI-C, volatile is used to declare a variable that can be modified by something
other than the program.

It is mostly used for hard-wired registers. volatile controls optimization by forcing a re-
read of the variable. It is only a guide, and may be ignored. The initial value of volatile
variables is undefined.

Handel-C does nothing with volatile. It is accepted for compatibility purposes.

4.21 Complex declarations

It is possible to have extremely complex declarations in Handel-C. You can combine
arrays of functions, structs, arrays, and pointers with architectural types. To clarify such
expressions, it is wise to use typedef.

4.21.1 Macro expressions in widths

If you use a macro expression to provide the width in a type declaration, you must
enclose it in parentheses. This ensures that it will be correctly parsed as a macro.

www.celoxica.com Page 78
Handel-C Language Reference Manual

int (mac(x)) y;

To declare a pointer to a function returning that type, you get

int (mac(x)) (*f)();

4.21.2 <> (type clarifier)

< > is a Handel-C extension used to disambiguate complex declarations of architectural

types. You cannot use it on logic types. It is good practice to use it whenever you declare
channels, memories or signals, to clarify the format of data passed or stored in these
variables.

It is required to disambiguate a declaration such as:

chan int *x; //pointer to channel or

//channel of pointers?

This should be declared as

chan <int *> x; //channel of pointers

or

chan <int> *x; //pointer to channel

Example
struct fishtank
{
int 4 koi;
int 8 carp;
int 2 guppy;
} bowl;

signal <struct fishtank> drip;

chan <int 8 (*runwater)()> tap;

4.21.3 Using signals to split up complex expressions

You can use signals to split up complex expressions. E.g.,

b = (((a * 2) - 55) << 2) + 100;

could also be written

www.celoxica.com Page 79
Handel-C Language Reference Manual

int 17 a, b;
signal s1, s2, s3, s4;

par
{
s1 = a;
s2 = s1 * 2;
s3 = s2 - 55;
s4 = s3 << 2;
b = s4 + 100;
}

Breaking up expressions also enables you to re-use sub-expressions:

unsigned 15 a, b;
signal sig1;

par
{
sig1 = x + 2;
a = sig1 * 3;
b = sig1 / 2;
}

4.22 Variable initialization

Global, static and const variables
Global variables (i.e. those declared outside all code blocks) may be initialized with their
declaration. For example:

static int 15 x = 1234;

static int 7 y = 45 with {outfile = "out.dat"};

Variables declared within functions or macros can only be initialized if they have static
storage or are consts.

Global and static variables may only be initialized with constants. If you do not initialize
them, they will have a default value of zero.

If you use the set reset construct, variables will be reset to their initial values. If you
use the try...reset construct, variables will not be re-initialized.

www.celoxica.com Page 80
Handel-C Language Reference Manual

All other variables

Local non-static variables have no default initial value. You cannot initialize them.
Instead, you must use an explicit sequential or parallel list of assignments following your
declarations to achieve the same effect. For example:

{
int 4 x;
unsigned 5 y;

x = 5;
y = 4;
}

Simulation
In simulation, variables (including static variables inside functions) are initialized before
the simulation run begins (i.e. before the first clock cycle is simulated).

www.celoxica.com Page 81
Handel-C Language Reference Manual

5 Statements

5.1 Sequential and parallel execution

Handel-C implicitly executes instructions sequentially. When targeting hardware it is
extremely important to use parallelism. For this reason, Handel-C has a parallel
composition keyword par to allow statements in a block to be executed in parallel.

Three assignments that execute in parallel and in the same clock cycle:

par
{
x = 1;
y = 2;
z = 3;
}

Three assignments that execute sequentially, requiring three clock cycles:

x = 1;
y = 2;
z = 3;

The par example executes all assignments literally in parallel. Three specific pieces of
hardware are built to perform these three assignments. This is about the same amount
as is needed to execute the assignments sequentially.

Sequential branches
Within parallel blocks of code, sequential branches can be added by using a code block
denoted with the {...} brackets instead of a single statement. For example:

par
{
x = 1;
{
y = 2;
z = 3;
}
}

In this example, the first branch of the parallel statement executes the assignment to x
while the second branch sequentially executes the assignments to y and z. The
assignments to x and y occur in the same clock cycle, the assignment to z occurs in the
next clock cycle.

www.celoxica.com Page 82
Handel-C Language Reference Manual

Ï The instruction following the par {...} will not be executed until all branches
of the parallel block complete.

5.2 seq
To allow replication, the seq keyword exists. Sequential statements can be written with
or without the keyword.

The following example executes three assignments sequentially:

x = 1;
y = 2;
z = 3;

as does this:

seq
{
x = 1;
y = 2;
z = 3;
}

5.3 Replicated par and seq

You can replicate par and seq blocks by using a counted loop (a similar construct to a
for loop). The count is defined with a start point (index_Base below), an end point
(index_Limit) and a step size (index_Count). The body of the loop is replicated as
many times as there are steps between the start and end points. If it is a par loop, the
replicated processes will run in parallel, if a seq, they will run sequentially.

Syntax
par | seq (index_Base; index_Limit; index_Count)
{
Body
}

The apparent variables used in index_Base, index_Limit and index_Count are macro
exprs that are implicitly declared. index_Base, index_Limit and index_Count do not
need to be single expressions, for example, you could declare par (i=0, j=23; i !=
76; i++, j--). In this case i and j are implicit macro exprs

www.celoxica.com Page 83
Handel-C Language Reference Manual

Example
par (i=0; i<3; i++)
{
a[i] = b[i];
}

expands to:

par
{
a[0] = b[0];
a[1] = b[1];
a[2] = b[2];
}

Replicated pipeline example

unsigned init;
unsigned q[149];
unsigned 31 out;

init = 57;
par (r = 0; r < 16; r++)
{
ifselect(r == 0)
q[r] = init;
else ifselect(r == 15)
out = q[r-1];
else
q[r] = q[r-1];
}

ifselect checks for the start of the pipeline, the replicator rules create the middle
sections and ifselect checks the end. The replicated code expands to:

par
{
q[0] = init;
q[1] = q[0];
q[2] = q[1];
etc...

q[14] = q[13];
out = q[14];
}

www.celoxica.com Page 84
Handel-C Language Reference Manual

5.4 prialt
The prialt statement selects the first channel ready to communicate from a list of
channel cases. The syntax is similar to a conventional C switch statement.

prialt
{
case CommsStatement:
Statement
break;
......
case CommsStatement:
Statement
break;
......
[default:
Statement
break;]
}

prialt selects between the communications on several channels depending on the

readiness of the other end of the channel. CommsStatement must be one of the following:

Channel ? Variable

Channel ! Expression

The case whose communication statement is the first to be ready to transfer data will
execute and data will be transferred over the channel. The statements up to the next
break statement will then be executed. If no channel is ready within a given clock tick,
the default clause will be executed (if one is present)

Priority
If two channels are ready simultaneously, then the first one listed in the code takes
priority.

Default
prialt with no default case:
execution halts until one of the channels becomes ready to communicate.

prialt statement with default case:

if none of the channels is ready to communicate immediately then the default branch
statements executes and the prialt statement terminates.

www.celoxica.com Page 85
Handel-C Language Reference Manual

Restrictions
Fall through of cases in a prialt construct is prohibited. This means that each case
must have its own break statement. If the same channel is listed twice in its cases, only
the first occurrence will ever be accessed. You would only wish to do this if the channel
within the prialt is the result of an expression (e.g., a pointer to a channel or a
reference to an array of channels). The compiler cannot reliably check this condition, so it
will not cause a warning.

If a channel between clock domains has fifolength=0 (default) and has a prialt on
both sides, the compiler will convert it to have a fifolength=1. This is also true if a
channel within a prialt has the other side within a try reset in a different clock
domain.

5.5 Using prialt: examples

The prialt statement selects the first channel ready to communicate from a list of
channel cases.

int 4 x, y, z;
chan <int 4> first, second;

par
{
prialt
{
case first ! x:
break;
case second ! y:
break;
}

seq
{
delay;
second ? z;
}

Send and receive statements can be mixed within a prialt. For example:

www.celoxica.com Page 86
Handel-C Language Reference Manual

int 4 num, even, odd;

chan <int 4> ch1, ch2;

par
{
if (num[0] != 0)
ch1 ? odd;
else
ch2 ! num;

prialt
{
case ch1 ! num:
break;
case ch2 ? even:
break;
}
}

Restrictions on using prialt

int 4 x, y;
chan <int 4> ch;

prialt
{
case ch ! x:
break;
case ch ! y: //illegal: ch already used
break;
}

int 4 x, y;
chan <int 4> ch;

prialt
{
case ch ! x:
break;
case ch ? y: //illegal: ch already used
break;
}

www.celoxica.com Page 87
Handel-C Language Reference Manual

5.6 Assignments
Handel-C assignments are of the form:

Variable = Expression;

For example:

x = 3;
y = a + b;

The expression on the right hand side must be of the same width and type (signed or
unsigned) as the variable on the left hand side. The compiler generates an error if this is
not the case.

The left hand side of the assignment may be any variable, array element or RAM
element. The right hand side of the assignment may be any expression.

Short cuts
The following short cut assignment statements cannot be used in expressions as they can
in conventional C but only in stand-alone statements. See Introduction: Expressions for
more information.

Shortcuts cannot be used with RAM variables, as they contravene the RAM access
restrictions

www.celoxica.com Page 88
Handel-C Language Reference Manual

Statement Expansion

Variable ++; Variable = Variable + 1;

Variable --; Variable = Variable - 1;
++ Variable; Variable = Variable + 1;
-- Variable; Variable = Variable - 1;
Variable += Variable = Variable + Expression;
Expression;
Variable -= Variable = Variable – Expression;
Expression;
Variable *= Variable = Variable * Expression;
Expression;
Variable /= Variable = Variable / Expression;
Expression;
Variable %= Variable = Variable % Expression;
Expression;
Variable <<= Variable = Variable << Expression;
Expression;
Variable >>= Variable = Variable >> Expression;
Expression;
Variable &= Variable = Variable & Expression;
Expression;
Variable |= Variable = Variable | Expression;
Expression;
Variable ^= Variable = Variable ^ Expression;
Expression;

5.6.1 continue

continue moves straight to the next iteration of a for, while or do loop. For do or while,
this means that the test is executed immediately. In a for statement, the increment step
is executed. This allows you to avoid deeply nested if ... else statements within
loops.

www.celoxica.com Page 89
Handel-C Language Reference Manual

Example
for (i = 100; i > 0; i--)
{
x = f( i );
if ( x == 1 )
continue;
y += x * x;
}

Ï You cannot use continue to jump out of or into par blocks.

5.6.2 goto

goto label moves straight to the statement specified by label. label has the same
format as a variable name, and must be in the same function as the goto. Labels are
local to the whole function, even if placed within an inner block. Formally, goto is never
necessary. It may be useful for extracting yourself from deeply nested levels of code in
case of error.

Example
for(… )
{
for(… )
{
if(disaster)
goto Error;
}
}

Error:
output ! error_code;

Ï You cannot use goto to jump out of or into par blocks.

www.celoxica.com Page 90
Handel-C Language Reference Manual

5.6.3 return [expression]

The return statement is used to return from a function to its caller. return terminates
the function and returns control to the calling function. Execution resumes at the line
immediately following the function call. return can return a value to the calling function.
The value returned is of the type declared in the function declaration. Functions that do
not return a value should be declared to be of type void.

Example
int power(int base, int n)
{
int i, p;

p = 1;
for (i = 1; i <= n; ++i)
p = p * base;
return(p);
}

Ï You cannot use return to jump out of par blocks.

5.6.4 Conditional execution (if ... else)

Handel-C provides the standard C conditional execution construct as follows:

if (Expression)
Statement
else
Statement

As in conventional C, the else portion may be omitted if not required. For example:

if (x == 1)
x = x + 1;

Statement may be replaced with a block of statements by enclosing the block in {...}
brackets. For example:

www.celoxica.com Page 91
Handel-C Language Reference Manual

if (x>y)
{
a = b;
c = d;
}
else
{
a = d;
c = b;
}

The first branch of the conditional is executed if the expression is true and the second
branch is executed if the expression is false. Handel-C treats zero values as false and
non-zero values as true. Relational and logical operators return values to match this
meaning but it is also possible to use variables as conditions. For example:

if (x)
a = b;
else
c = d;

This is expanded by the compiler to:

if (x!=0)
a = b;
else
c = d;

When executed, if x is not equal to 0 then b is assigned to a. If x is 0 then d is assigned

to c.

5.6.5 while loops

Handel-C provides while loops exactly as in conventional C:

while (Expression)
Statement

The contents of the while loop may be executed zero or more times depending on the
value of Expression. While Expression is true then Statement is executed repeatedly.
Statement may be replaced with a block of statements. For example:

www.celoxica.com Page 92
Handel-C Language Reference Manual

x = 0;
while (x != 45)
{
y = y + 5;
x = x + 1;
}

This code adds 5 to y 45 times (equivalent to adding 225 to y).

5.6.6 do ... while loops

Handel-C provides do ... while loops exactly as in conventional C:

do
Statement
while (Expression);

The contents of the do ... while loop is executed at least once because the conditional
expression is evaluated at the end of the loop rather than at the beginning as is the case
with while loops. Statement may be replaced with a block of statements. For example:

do
{
a = a + b;
x = x - 1;
} while (x>y);

5.6.7 for loops

Handel-C provides for loops similar to those in conventional C.

for (Initialization ; Test ; Iteration)

Statement

The body of the for loop may be executed zero or more times according to the results of
the condition test. There is a direct correspondence between for loops and while loops.
Because of the benefits of parallelism, it is nearly always preferable to implement a
while loop instead.

for (Init; Test; Inc)

Body;

is directly equivalent to:

www.celoxica.com Page 93
Handel-C Language Reference Manual

{
Init;
while (Test)
{
Body;
Inc;
}
}

unless the Body includes a continue statement. In a for loop continue jumps to before
the increment, in a while loop continue jumps to after the increment.

Unless a specific continue statement is needed, it is always faster to implement the for
loop as a while loop with the Body and Inc steps in parallel rather than in sequence
when this is possible.

Each of the initialization, test and iteration statements is optional and may be omitted if
not required. Note that for loops with no iteration step can cause combinational loops.
As with all other Handel-C constructs, Statement may be replaced with a block of
statements. For example:

for ( ; x>y ; x++ )

{
a = b;
c = d;
}

The difference between a conventional C for loop and the Handel-C version is in the
initialization and iteration phases. In conventional C, these two fields contain
expressions and by using expression side effects (such as ++ and --) and the sequential
operator ',' conventional C allows complex operations to be performed. Since Handel-C
does not allow side effects in expressions the initialization and iteration expressions have
been replaced with statements. For example:

for (x = 0; x < 20; x = x+1)

{
y = y + 2;
}

Here, the assignment of 0 to x and adding one to x are both statements and not
expressions. These initialization and iteration statements can be replaced with blocks of
statements by enclosing the block in {...} brackets. For example:

for ({ x=0; y=23;} ; x < 20; {x+=1; x*=2;} )

{
y = y + 2;
}

www.celoxica.com Page 94
Handel-C Language Reference Manual

5.6.8 switch

Handel-C provides switch statements similar to those in conventional C.

switch (Expression)
{
case Constant:
Statement
break;
......
default:
Statement
break;
}

The switch expression is evaluated and checked against each of the case compile time
constants. The statement(s) guarded by the matching constant is executed until a break
statement is encountered.

If no matches are found, the default statement is executed. If no default option is

provided, no statements are executed.

Each of the Statement lines above may be replaced with a block of statements by
enclosing the block in {...} brackets.

As with conventional C, it is possible to make execution drop through case branches by

omitting a break statement. For example:

switch (x)
{
case 10:
a = b;
case 11:
c = d;
break;

case 12:
e = f;
break;
}

Here, if x is 10, b is assigned to a and d is assigned to c, if x is 11, d is assigned to c and

if x is 12, f is assigned to e.

Ï The values following each case branch must be compile time constants.

www.celoxica.com Page 95
Handel-C Language Reference Manual

5.6.9 break

Handel-C provides the normal C break statement for:

• terminating loops
• separation of case branches in switch and prialt statements.

break cannot be used to jump into or out of par blocks.

Loops
When used within a while, do...while or for loop, the loop is terminated and execution
continues from the statement following the loop. For example:

for (x=0; x<32; x++)

{
if (a[x]==0)
break;
b[x]=a[x];
}
// Execution continues here

switch
When used within a switch statement, execution of the case branch terminates and the
statement following the switch is executed. For example:

switch (x)
{
case 1:
case 2:
y++;
break;
case 3:
z++;
break;
}
// Execution continues here

prialt
When used within a prialt statement, execution of the case branch terminates and the
statement following the prialt is executed. For example:

www.celoxica.com Page 96
Handel-C Language Reference Manual

prialt
{
case a ? x:
x++;
break;
case b ! y:
y++;
break;
}
// Execution continues here

5.6.10 delay

Handel-C provides a delay statement, not found in conventional C, which does nothing
but takes one clock cycle to do it. This may be useful to avoid resource conflicts (for
example to prevent two accesses to one RAM in a single clock cycle) or to adjust
execution timing.

delay can also be used to break combinational logic cycles.

5.6.11 try... reset

try...reset allows you to perform actions on receipt of a reset signal within a specified
section of code. You can form the same kind of construct with other control statements,
but this requires more complex code and therefore more hardware.

Syntax
try
{
statements
}
reset(condition)
{
statements
}

During the execution of statements within the try block, if condition is true, the reset
statement block will be executed immediately, else it will not. The condition expression is
continually checked. If it occurs in the middle of a function, execution will immediately go
to the reset thread. Static variables within the function will remain in the state they were
in when the reset condition occurred. Variables and RAMs will not be re-initialized.

www.celoxica.com Page 97
Handel-C Language Reference Manual

Examples
void main(void)
{
interface bus_in(int 1 input) resetbus();
try
{
someFunction();
}
reset(resetbus.input == 1)
{
cleanUpSomeFunction();
}
}

If you have nested try…reset statements, and more than one try condition is true, only
the outermost reset statement is executed. For example:

www.celoxica.com Page 98
Handel-C Language Reference Manual

unsigned 4 a, s, t, x, y;
static unsigned 1 condition = 0;

par
{
while(1)
{
condition = (a == 1);
}

try
{
try
{
a = 1;
a = 2;
a = 3;
}
reset(condition)
{
s = 1;
t = 1;
}
}
reset (condition)
{
x = 1;
y = 1;
}
}

will execute the second reset statement only.

5.6.12 trysema()

trysema(semaphore) tests to see if the semaphore is owned. If not, it returns one and
takes ownership of the semaphore. If it is, it returns zero. A semaphore may be freed by
using the statement releasesema(semaphore).

www.celoxica.com Page 99
Handel-C Language Reference Manual

Example
inline void critRAMaccess(sema *RAMsema, ram int 8
(*danger)[4], unsigned count)
{
int 8 x;
// wait till you've got the RAM
while(trysema(*RAMsema)==0) delay;
x= (*danger)[count];
releasesema(*RAMsema);
}

Ï Note that you can no longer take the semaphore twice without releasing it.

while(1)
{
// always succeeds because its the same 'trysema' expression
if (trysema(s)) {...}
}

In DK version 1, this worked. In DK version 1.1 and subsequent versions, the second and
subsequent trysema() will always fail. Instead, use

while(1)
{
if (trysema(s))
{
...
releasesema(s)
}
}

5.6.13 releasesema()

releasesema(semaphore) releases a semaphore that was previously taken by

trysema(semaphore).

www.celoxica.com Page 100

Handel-C Language Reference Manual

Example
inline void critRAMaccess(sema *RAMsema, ram int 8
(*danger)[4], unsigned count)
{
int 8 x;
while(trysema(*RAMsema)==0) delay; // wait till you've got the RAM
x= (*danger)[count];
releasesema(*RAMsema);
}

www.celoxica.com Page 101

Handel-C Language Reference Manual

6 Expressions

6.1 Introduction to expressions

6.1.1 Clock cycles required

Expressions in Handel-C take no clock cycles to be evaluated, and so have no bearing on

the number of clock cycles a given program takes to execute.

They affect the maximum possible clock rate for a program: the more complex an
expression, the more hardware is involved in its evaluation and the longer it is likely to
take because of combinational delays in the hardware. The clock period for the entire
hardware program is limited by the longest such evaluation in the whole program.

Because expressions are not allowed to take any clock cycles, expressions with side
effects are not permitted in Handel-C. For example;

if (a<b++) /* NOT PERMITTED */

This is not permitted because the ++ operator has the side effect of assigning b+1 to b
which requires one clock cycle.

6.1.2 Breaking down complex expressions

The longest and most complex C statement with many side effects can be written in
terms of a larger number of simpler expressions and assignments. The resulting code is
normally easier to read. For example:

a = (b++) + (((c-- ? d++ : e--)) , f);

can be rewritten as:

a = b + f;
b = b + 1;
if (c)
d = d + 1;
else
e = e - 1;
c = c - 1;

6.1.3 Prefix and postfix operators

Handel-C provides the prefix and postfix ++ and -- operations as statements rather than
expressions. For example:

www.celoxica.com Page 102

Handel-C Language Reference Manual

a++;
b--;
++c;
--d;

is directly equivalent to:

a = a + 1;
b = b - 1;
c = c + 1;
d = d - 1;

6.2 Casting of expression types

Automatic conversions between signed and unsigned values are not allowed. Values must
be cast between types to ensure that the programmer is aware that a conversion is
occurring that may alter the meaning of a value.

You can cast to a type of undefined width. For example:

int 4 x;
unsigned int undefined y;

x = (int undefined)y;

The compiler will infer that y must be 4 bits wide.

Explanation of signed/unsigned casting

The following piece of Handel-C is invalid:

int 4 x; // Range of x: -8...7

unsigned int 4 y; // Range of y: 0...15

x = y; // Not allowed

This is because x is a signed integer while y is an unsigned integer. When generating

hardware, it is not clear what the compiler should do here. It could simply assign the 4
bits of y to the 4 bits of x or it could extend y with an extra zero as its most significant
bit to preserve its value and then assign these 5 bits to x assuming x was declared to be
5 bits wide.

To see the difference, consider the case when y is 10. By simply assigning these 4 bits
to a signed integer, a result of -6 would be placed in x. A better solution might be to
extend y to a five bit value by adding a 0 bit as its MSB to preserve the value of 10.

A programmer must explicitly cast the variables to the same type. Assuming that they
wish to use the 4-bit value as a signed integer, the above example then becomes:

www.celoxica.com Page 103

Handel-C Language Reference Manual

int 4 x;
unsigned int 4 y;

x = (int 4)y;

It is now clear that the value of x is the result of treating the 4 bits extracted from y as a
signed integer.

6.2.1 Restrictions on casting

Casting cannot be used to change the width of values. For example, this is not allowed:

unsigned int 7 x;
int 12 y;

y = (int 12)x; // Not allowed

The conversion should be done explicitly:

y = (int 12)(0 @ x);

Here, the concatenation operation produces a 12-bit unsigned value. The casting then
changes this to a 12-bit signed integer for assignment to y.

This is to ensure that the programmer is aware of such conversions.

Explanation
int 7 x;
unsigned int 12 y;

x = -5;
y = (unsigned int 12)x;

The Handel-C compiler could take two routes. One would be to sign extend the value of x
and produce the result 4091. The second would be to zero pad the value of x and
produce the value of 123. Since neither method can preserve the value of x in y Handel-
C performs neither automatically. Rather, it is left up to the programmer to decide which
approach is correct in a particular situation and to write the expression accordingly. You
may sign extend using the adjs macro and zero-pad using the adju macro. These
macros are provided in the standard macro library within the Celoxica Platform
Developer's Kit.

6.3 Restrictions on RAMs and ROMs

Because of their architecture, RAMs and ROMs are restricted to performing operations
sequentially. Only one element of a RAM or ROM may be addressed in a single clock

www.celoxica.com Page 104

Handel-C Language Reference Manual

cycle. In hardware, this means you can only write one value to the address port of a
memory, allowing one read access or one write access. You can detect simultaneous
memory accesses when you are debugging your code by using the Detection of simultaneous
memory accesses option on the Debug tab in Project Settings, or the -S+parmem option in the
command line compiler.

If you want to make more than one access to a memory at a time, use an MPRAM (multi-
ported RAM). You can access more than one port at a time, but you can only make a
single access to any one mpram port in a single clock cycle.

Example of disallowed assignment

Only one element of a RAM or ROM may be addressed in any given clock cycle and, as a
result, familiar looking statements will often produce unexpected results. For example:

ram <unsigned int 8> x[4];

x[1] = x[3] + 1;

This code should not be used because the assignment attempts to read from the third
element of x in the same cycle as it writes to the first element, and the memory may
produce undefined results.

Example of disallowed condition evaluation

ram unsigned int 8 x[4];

if (x[0]==0)
x[1] = 1; //double access, disallowed

This code is illegal because the condition evaluation must read from element 0 of the
RAM in the same clock cycle as the assignment writes to element 1. Similar restrictions
apply to while loops, do ... while loops, for loops and switch statements.

Incorrect execution with conditional operator

This code will not execute correctly because of the double access.

x = y>z ? RamA[1] : RamA[2];

The solution is to re-write the code as follows:

x = RamA[y>z ? 1 : 2];

Here, there is only a single access to the RAM so the problem does not occur.

Ï Arrays of variables do not have these restrictions but may require

substantially more hardware to implement than RAMs (depending on the
target architecture).

www.celoxica.com Page 105

Handel-C Language Reference Manual

6.4 assert
assert allows you to generate messages at compile-time if a condition is met. The
messages can be used to check compile-time constants and help guard against possible
problematic code alterations. The user uses an expression to check the value of a
compile-time constant, and if the expression evaluates to false, an error message is sent
to the standard error channel in the format

filename:line number, start column - end column::Assertion failed: user-

defined error string

The default error message is:

"Error : User assertion failed"

If the expression evaluates to true, the whole assert expression is replaced by a constant
expression.

assert can be used as a statement by passing 0 as the trueValue. If the condition is

true, the whole assert statement is replaced by 0 (a null statement). This is shown in the
example below. If the width of x is 3 (the condition is true), the whole statement is
replaced by the trueValue of 0, so nothing happens.

assert (width(x)==3, 0, "Width of x is not 3 (it is %d)", width(x));

A more detailed example is given below. assert can also be used as an expression,
where its return value is assigned to something. This is illustrated in the second example
below, where the return value is assigned to ReturnVal.

Syntax
assert(condition,trueValue [string with format specification(s)
{,argument(s)}]);

If condition is true, the whole expression reduces to trueValue. If condition is false,

string will be sent to the standard error channel, with each format specification
replaced by an argument. When assert encounters the first format specification (if any),
it converts the value of the first argument into that format and outputs it. The second
argument is formatted according to the second format specification and so on. If there
are more expressions than format specifications, the extra expressions are ignored. The
results are undefined if there are not enough arguments for all the format specifications.

The format specification is one of:

%c Display as a character %s Display as a string

%d Display as a decimal %f Display as a floating-point

%o Display as an octal %x Display as a hexadecimal

www.celoxica.com Page 106

Handel-C Language Reference Manual

Ï An assert evaluates to an empty statement and can only appear after all
declarations in a macro or function

Using assert as a statement

In the example below assert is used as a statement.

set clock = external "C1";

int f(int x)
{
assert(width(x)==3, 0, "Width of x is not 3 (it is %d)", width(x));
return x+1;
}

void main(void)
{
int 4 y;
y = f(y);
}

x will be inferred to have a width of 4, so the following message will be displayed.

F:\proj\test.hcc(4)(2) : Assertion failed : Width of x is not 3 (it is 4)

Using assert as an expression

In the example below, assert is used as an expression.

www.celoxica.com Page 107

Handel-C Language Reference Manual

set clock = external "C1";

unsigned func(unsigned p, unsigned q)
{
macro expr WidthSum(a, b) = width(a) + width(b);
macro expr CheckWidths(a, b) = assert((WidthSum(a, b)==32
|| WidthSum(a, b)==16), WidthSum(a, b),
"Sum of widths of function parameters is not 16 or 32 (it is %d)",
WidthSum(a, b));
unsigned 16 ReturnVal;

ReturnVal = CheckWidths(p, q);

return ReturnVal;
}

void main(void)
{
static unsigned 9 x;
static unsigned 7 y;
unsigned result;

result = func(x, y);

}

6.5 Bit manipulation operators

The following bit manipulation operators are provided in Handel-C:

<< Shift left

>> Shift right
<- Take least significant bits
\\ Drop least significant bits
@ Concatenate bits
[] Bit selection
width(Expression) Width of expression

www.celoxica.com Page 108

Handel-C Language Reference Manual

6.5.1 Shift operators

The shift operators shift a value left or right by a variable number of bits resulting in a
value of the same width as the value being shifted. Any bits shifted outside this width are
lost.

When shifting unsigned values, the right shift pads the upper bits with zeros. When right
shifting signed values, the upper bits are copies of the top bit of the original value. Thus,
a shift right by 1 divides the value by 2 and preserves the sign. For example:

static unsigned 4 a = 0b1101;

static unsigned (log2ceil(width(a)+1)) b = 2;

a = a >> b; //a becomes 0b0011

b--;
a = a >> b; //a becomes 0b0001

The width of b needs to have a width equal to log2(width(a)+1) rounded up to the

nearest whole number. This can be calculated using the log2ceil macro which is
provided as part of the standard library in the Platform Developer's Kit.

6.5.2 Take / drop operators

The take operator, <-, returns the n least significant bits of a value. The drop operator,
\\, returns all but the n least significant bits of a value. n must be a compile-time
constant. For example:

macro expr four = 8 / 2;

unsigned int 8 x;
unsigned int 4 y;
unsigned int 4 z;

x = 0xC7;
y = x <- four;
z = x \\ 4;

This results in y being set to 7 and z being set to 12 (or 0xC in hexadecimal).

6.5.3 Concatenation operator

The concatenation operator, @, joins two sets of bits together into a result whose width is
the sum of the widths of the two operands. For example:

www.celoxica.com Page 109

Handel-C Language Reference Manual

unsigned int 8 x;
unsigned int 4 y;
unsigned int 4 z;

y = 0xC;
z = 0x7;
x = y @ z;

This results in x being set to 0xC7. The left operand of the concatenation operator forms
the most significant bits of the result.

You may also use the concatenation operator to zero pad a variable to a given width.

unsigned int 8 x;
unsigned int 8 y;
unsigned int 16 z;

//width of zero constant inferred to be 8 bits

z = (0 @ x) * (0 @ y);

If you want to use sign extension, you need to copy the 1 or the 0 from the most
significant bit into the new bits. For example:

signed int 8 i;
signed int 12 j;
j = i[7] @ i[7] @ i[7] @ i[7] @ i;

6.5.4 Bit selection

Individual bits or a range of bits may be selected from a value by using the [] operator.
Bit 0 is the least significant bit and bit n-1 is the most significant bit where n is the width
of the value. For example:

unsigned int 8 x;
unsigned int 1 y;
unsigned int 5 z;

x = 0b01001001;
y = x[4];
z = x[7:3];

This results in y being set to 0 and z being set to 9. Note that the range of bits is of the
form MSB:LSB and is inclusive. Thus, the range 7:3 is 5 bits wide.

The bit selection values must be fixed at compile time.

www.celoxica.com Page 110

Handel-C Language Reference Manual

The value before or after ':' can be omitted. If you omit the value after the semi-colon,
then zero is assumed, so the LSBs are taken. If you omit the value before the semi-
colon, then n–1 is assumed, so the MSBs are taken.

Bit selection is allowed in RAM, ROM and array elements. For example:

ram int 7 w[23];

int 5 x[4];
int 3 y;
unsigned int 1 z;

y = w[10][4:2];
z = (unsigned 1)x[2][0];

The 10 specifies the RAM entry and the 4:2 selects three bits from the middle of the
value in the RAM w is set to the value of the selected bits.

Similarly, z is set to the least significant bit in the x[2] variable.

Ï You cannot assign to bit ranges, only read from them.

6.5.5 Width operator

The width() operator returns the width of an expression. It is a compile time constant.
For example:

x = y <- width(x);

This takes the least significant bits of y and assigns them to x. The width() operator
ensures that the correct number of bits is taken from y to match the width of x.

6.6 Arithmetic operators

The following arithmetic operators are provided in Handel-C:

www.celoxica.com Page 111

Handel-C Language Reference Manual

Operator Meaning

+ Addition
- Subtraction
* Multiplication
/ Division
% Modulo arithmetic

Any attempt to perform one of these operations on two expressions of differing widths or
types results in a compiler error. For example:

int 4 w;
int 3 x;
int 4 y;
unsigned 4 z;

y = w + x; // ILLEGAL
z = w + y; // ILLEGAL

The first statement is illegal because w and x have different widths. The second
statement is illegal because w and y are signed integers and z is an unsigned integer.

Width of results
All operators return results of the same width as their operands. Thus, all overflow bits
are lost. For example:

unsigned int 8 x;
unsigned int 8 y;
unsigned int 8 z;

x = 128;
y = 192;
z = 2;

x = x + y;
z = z * y;

This example results in x being set to 64 and z being set to 128.

By using the bit manipulation operators to expand the operands, it is possible to obtain
extra information from the arithmetic operations. For instance, the carry bit of an
addition or the overflow bits of a multiplication may be obtained by first expanding the
operands to the maximum width required to contain this extra information. For example:

www.celoxica.com Page 112

Handel-C Language Reference Manual

unsigned int 8 u;
unsigned int 8 v;
unsigned int 9 w;
unsigned int 8 x;
unsigned int 8 y;
unsigned int 16 z;

w = (0 @ u) + (0 @ v);
z = (0 @ x) * (0 @ y);

In this example, w and z contain all the information obtainable from the addition and
multiplication operations. Note that the constant zeros do not require a width
specification because the compiler can infer their widths from the usage. The zeros in
the first assignment must be 1 bit wide because the destination is 9 bits wide while the
source operands are only 8 bits wide. In the second assignment, the zero constants
must be 8 bits wide because the destination is 16 bits wide while the source operands are
only 8 bits wide.

6.7 Relational operators

Operator Meaning

== Equal to
!= Not equal to
< Less than
> Greater than
<= Less than or equal
>= Greater than or equal
These operators compare values of the same width and return a single bit wide unsigned
int value of 0 for false or 1 for true. This means that this conventional C code is invalid:

unsigned 8 w, x, y, z;

w = x + (y >z); // NOT ALLOWED

Instead, you should write:

w = x + (0 @ (y > z));

www.celoxica.com Page 113

Handel-C Language Reference Manual

6.7.1 Signed/unsigned compares

Signed/signed compares and unsigned/unsigned compares are handled automatically.

Mixed signed and unsigned compares are not handled automatically. For example:

unsigned 8 x;
int 8 y;

if (x>y) // Not allowed

...

To compare signed and unsigned values you must sign extend each of the parameters.
The above code can be rewritten as:

unsigned 8 x;
int 8 y;

if ((int)(0@x) > (y[7]@y))

...

6.7.2 Implicit compares

The Handel-C compiler inserts implicit compares with zero if a value is used as a
condition on its own. For example:

while (1)
{
...
}

Is directly expanded to:

while (1 != 0)
{
...
}

6.8 Logical operators

www.celoxica.com Page 114

Handel-C Language Reference Manual

Operator Meaning

&& Logical and

|| Logical or
! Logical not
These operators are provided to combine conditions as in conventional C. Each operator
takes 1-bit unsigned operands and returns a 1-bit unsigned result.

Note that the operands of these operators need not be the results of relational operators.
This feature allows some familiar looking conventional C constructs.

Example
if (x || y > z)
w = 0;

In this example, the variable x need not be 1 bit wide. If it is wider, the Handel-C
compiler inserts a compare with 0.

if (x != 0 || y > z)
w = 0;

The condition of the if statement is true if x is not equal to 0 or y is greater than z.

C-like example
while (x || y)
{
...
}

Again, if the variables are wider than 1-bit, the Handel-C compiler inserts compares with
0.

6.8.1 Bitwise logical operators

Operator Meaning

& Bitwise and

| Bitwise or
^ Bitwise exclusive or
~ Bitwise not
These operators perform bitwise logical operations on values. Both operands must be of
the same type and width: the resulting value will also be this type and width. For
example:

www.celoxica.com Page 115

Handel-C Language Reference Manual

unsigned int 6 w;
unsigned int 6 x;
unsigned int 6 y;
unsigned int 6 z;

w = 0b101010;
x = 0b011100;
y = w & x;
z = w | x;
w = w ^ ~x;

This example results in y having the value 0b001000, z having the value 0b111110 and
w having the value 0b001001.

6.9 Conditional operator

Handel-C provides the conditional expression construct familiar from conventional C. Its
format is:

Expression ? Expression : Expression

The first expression is evaluated and if true, the whole expression evaluates to the result
of the second expression. If the first expression is false, the whole expression evaluates
to the result of the third expression. For example:

x = (y > z) ? y : z;

This sets x to the maximum of y and z. This code is directly equivalent to:

if (y > z)
x = y;
else
x = z;

The advantage of using this construct is that the result is an expression so it can be
embedded in a more complex expression. For example:

x = ((w==0) ? y : z) + 4;

In this case, the signedness and widths of x, y and z must match (as the value of y or z
may be assigned to x), but those of w need not.

6.10 Member operators (. / ->)

The structure member operator (.) is used to access members of a structure or mpram, or
to access a port within an interface.

www.celoxica.com Page 116

Handel-C Language Reference Manual

The structure pointer operator (->) can be used, as in ANSI-C. It is used to access the
members of a structure or mpram, when the structure/mpram is referenced through a
pointer.

mpram Fred
{
ram <unsigned 8> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
} Joan;

mpram Fred *mpramPtr;

mpramPtr = &Joan;
x = mpramPtr->Read[56];

If a memory is made up of structures, the structure member operator can be used to

reference structure members within the memory.

ram struct S compRAM[100];

ram struct S (*ramStructPtr)[];
ramStructPtr = &compRAM;
x = (*ramStructPtr)[10].a;

www.celoxica.com Page 117

Handel-C Language Reference Manual

7 Functions and macros

7.1 Functions and macros: overview

Handel-C includes and extends the range of functions and macros offered by ANSI-C.

Return Typed Called by Shared

value? return reference? hardware?
values and
parameters
?

Functions Can have Yes No Yes

Arrays of functions Can have Yes No Yes
Inline functions Can have Yes No No
Preprocessor macros Can have No Yes No
Macro expressions Must have No Yes No
Shared expressions Must have No Yes Yes
Macro procedures None No Yes No

7.1.1 Functions and macros: language issues

Called by reference or value

Functions employ call-by-value on their parameters, whereas macros effectively employ
call-by-reference. Consider the code:

void inline f_pseudoswap (int 12 x, int 12 y)

{
par
{
x = y;
y = x;
}
}

www.celoxica.com Page 118

Handel-C Language Reference Manual

macro proc mp_swap (x, y)

{
par
{
x = y;
y = x;
}
}

If you call mp_swap(a,b) the values of a and b will be swapped.

If you call call f_pseudoswap(a,b) the values a and b are copied to the formal
parameters x and y of f_pseudoswap. x and y are swapped, but a and b are
unaffected. The swap function with the same behaviour as the macro procedure is
therefore

void inline f_swap (int 12 * x, int 12 * y)

{
par
{
* x = * y;
* y = * x;
}
}

with a call of the form f_swap(&a,&b).

Typed or untyped parameters

Function parameters must have a type, although the width can sometimes be inferred by
the compiler.

Macro expressions and procedures are un-typed in the sense that their formal
parameters can’t be given types. The type of macro parameters is inferred from the type
in the call statement.

This means that it is better to use macros for parameterizable code. For example, macro
procedures can be used in libraries if you want to create multiple instances of hardware,
but leave them untyped to make the code more generic.

Recursion
In Handel-C, functions may not be recursive. Macro procedure and macro expressions
can be used to capture compile-time recursion.

If you use recursive macro procedures you need to use ifselect to guard the base case
(the condition where the recursion terminates). If you use recursive macro expressions,
you need to use select to guard the base case.

Macro procedure example:

www.celoxica.com Page 119

Handel-C Language Reference Manual

unsigned 4 g;
macro proc p(x)
{
ifselect(width(x) != 0)
{
g = 0@x;
p(x\\1);
}
else
delay;
}

set clock = external;

void main()
{
unsigned 4 i;
p(i);
}

Macro expression example:

macro expr copycat (copies, bits) =

select (copies <= 0, (unsigned 0) 0,
bits @ copycat (copies - 1, bits));

7.1.2 Functions and macros: sharing hardware

Calls to functions and shared expressions result in a single shared piece of hardware.
This is equivalent to an ANSI-C function resulting in a single shared section of machine
code.

Shared hardware will reduce the size of your design, but care is needed if you have
parallel code where multiple branches access the shared hardware. Shared hardware
may also compromise the speed of your design as it tends to lead to an increase in logic
depth.

Each call to an inline function, macro procedure or macro expression results in a separate
piece of hardware.

Arrays of functions allow a specified number of copies to be created.

www.celoxica.com Page 120

Handel-C Language Reference Manual

7.1.3 Functions and macros: clock cycles

Macro expressions and shared expressions are evaluated in a single clock cycle, where
the expression is assigned to a variable. Functions and macro procedures may involve
control logic, and may take many cycles.

7.1.4 Functions and macros: examples

There are many ways in which a much-used code fragment can be expressed. The
examples below all multiply a value by 1.5. For hints on when to use the different types
of macros and functions, see:

• Functions and macros: overview

• Comparison of macros and functions

Preprocessor macro
#define de_sesqui(s) ((s) + ((s) >> 1))
#define dp_sesqui(d,s) ((d) = (s) + ((s) >> 1))

Macro expression
macro expr me_sesqui (s) = s + (s >> 1);

Shared expression
shared expr se_sesqui (s) = s + (s >> 1);

Macro procedure
macro proc mp_sesqui (d, s)
{
d = s;
d += (d >> 1);
}

Function
void f_sesqui (int * d, int s) //"shared" function without return
{
* d = s;
* d += ((* d) >> 1);
}

www.celoxica.com Page 121

Handel-C Language Reference Manual

int rf_sesqui (int s) //"shared" function with return

{
int ret;
ret = s;
ret += (ret >> 1);
return ret;
}

Array of functions
void af_sesqui [5] (int * d, int s) //function array without return
{
* d = s;
* d += ((* d) >> 1);
}

int arf_sesqui [5] (int s) // function array with return

{
int ret;
ret = s;
ret += (ret >> 1);
return ret;
}

Inline function
void inline if_sesqui (int * d, int s) // inline function without return
{
* d = s;
* d += ((* d) >> 1);
}

// inline function with return

int inline irf_sesqui (int s)
{
int ret;
ret = s;
ret += (ret >> 1);
return ret;
}

How to call the example macros and functions

The example macros and functions above can be called using code such as:

www.celoxica.com Page 122

Handel-C Language Reference Manual

{
int 5 x, y;
x = 10;

y = de_sesqui (x);
dp_sesqui (y, x);

y = me_sesqui (x);

y = se_sesqui (x);

mp_sesqui (y, x);

f_sesqui (& y, x);

y = rf_sesqui (x);

af_sesqui[2] (& y, x);

y = arf_sesqui[2] (x);

if_sesqui (& y, x);

y = irf_sesqui (x);
}

7.1.5 Accessing external names

You can refer to functions, macros and shared expressions that have been defined in
another file by prototyping them. You prototype by declaring an object at the top of the
file in which it is used.

Function prototypes are in the following format:

returnType functionName(parameterTypeList);

Macro prototypes are of the form:

macro expr Name(parameterList);

macro proc Name(parameterList);

Functions and macros may be static or extern. static functions and macros may only
be used in the file where they are defined.

You can collect all the prototypes into a single header file and then #include it within
your code files.

You can access variables declared in other files by using the extern keyword.

www.celoxica.com Page 123

Handel-C Language Reference Manual

Ï You cannot use variables to communicate between clock domains. Variables

are restricted to a single clock domain. The only items that can connect across
separate clock domains are channels and mprams.

7.1.6 Recursion in macros and functions

Macros can be recursive in Handel-C, but due to the absence of a stack in Handel-C,
functions cannot be recursive.

The depth of recursion, though unbounded, must be determinable at compile-time.

7.2 Introduction to functions

Functions are similar to functions in ANSI-C. A function is compiled to be a single shared
piece of hardware, much as a C compiler generates a single shared block of machine
code.

Handel-C has been extended to provide arrays of functions and inline functions.

Arrays of functions provide multiple copies of a function. You can select which copy is
used at any time.

Inline functions are similar to macros in that they are expanded wherever they are used.

You may also use a macro proc (a parameterized macro procedure).

Functions take arguments and return values. A function that does not return a value is of
type void. Valid return types are integers and structs. The default return type is int
undefined. Functions that do not take arguments have void as their parameter list, for
example:

void main(void)

As in ANSI-C, function arguments are passed by value. This means that a local copy is
created that is only in scope within the function. Changes take place on this copy.

To access a variable outside the function, you must pass the function a pointer to that
variable. A local copy will be made of the pointer, but it will still point to the same
variable. This is known as passing by reference.

Architectural types (hardware constructs) must be passed by reference (a pointer to or

address of the construct). The only architectural type that can be passed to or returned
by a function by value is a signal. All others (and structures containing them) must be
passed by reference. Arrays and functions can also only be passed by reference.

www.celoxica.com Page 124

Handel-C Language Reference Manual

7.2.1 Function definitions and declarations

Function definitions and declarations are defined as in ANSI-C. Functions must be

declared in every file that they are used in, though they should only be defined once. It is
common to put function declarations into a header file and #include that in every file
where they are used.

Function definition
The definition of a function consists of its name and parameters followed by the function
body (the block of code that it performs when it is called).

The syntax is:

returnType Name(parameterList)
{
declarations
statements
}

For example:

int 4 add (int 4 left, int 4 right)

{
int 4 sum;
sum = left + right;
return sum;
}

If there is nothing returned from the function, a void return type must be specified.

Old-style ANSI-C function definitions, where the types of the parameters are specified
between the parameter list and the function body, are not supported. For example:

int 4 add (left, right) //old-style not supported

int 4 left, right;
{
return left + right;
}
Function declaration
A function declaration lists the function name, return type and the types of the
parameters. The syntax is:

returnType Name(parameterType_1 parameter_1, parameterType_n parameter_n);

Note the semicolon following the parameter list.

www.celoxica.com Page 125

Handel-C Language Reference Manual

You may omit the parameter names in a declaration. The parameter types are used by
the compiler to check that the correct types are used for the function arguments within
the rest of the file.

Old-style ANSI-C declarations, where the names but not the type of the parameters are
given, are not supported.

7.2.2 Functions: scope

Functions cannot be defined within other functions. By default, functions are extern
(they can be used anywhere). Functions can also be defined as static (they can only be
used in the file in which they are defined).

7.2.3 Arrays of functions

An array of functions is a collection of identical functions. It is not the same as an array

of function pointers (each of whose elements can point to a different function). A function
array allows you to run different copies of the same function in parallel. Without this
construct, the only safe way to run a function in parallel with itself would be to explicitly
declare two functions with different names.

Function arrays allow functions to be copied and shared neatly. For example:

unsigned func[2](unsigned x, unsigned y)

{
return (x + y);
}

Syntax
The syntax is a normal function declaration, with square brackets added to specify that
this is an array declaration as well as a function declaration. The general form of a
function array declaration is:

returnType Name[Size](parameterList);

www.celoxica.com Page 126

Handel-C Language Reference Manual

7.2.4 Function arrays: example

set clock = external "P1";

// Function array prototype

unsigned func[2](unsigned x, unsigned y);

// Main program
void main(void)
{
unsigned a, b, c, d, e, f;
unsigned short r1, r2, r3, r4;
unsigned result;

par
{
a = 12;
b = 22;
c = 32;
d = 42;
e = 52;
f = 62;
}

par
{
r1 = func[0](a, b);
r2 = func[1](c, d);
}

par
{
r3 = func[0](e, f);
r4 = func[1](r1, r2);
}

result = func[0](r3, r4);

}

www.celoxica.com Page 127

Handel-C Language Reference Manual

// Function array definition

unsigned func[2](unsigned x, unsigned y)
{
return (x + y);
}

7.2.5 Function arrays example with static variables

In the example below each function in the array has its own copy of the static variable
‘t’. Thus, if func[0]’s copy of ‘t’ is modified, func[1]’s copy remains unaffected.

www.celoxica.com Page 128

Handel-C Language Reference Manual

set clock = external "C1";

unsigned func[2](unsigned a, unsigned b)

{
static unsigned t = 0;
t++;
return a + b + t;
}

void main(void)
{
unsigned 7 p, q, r, s, t, u, v, w, x, y, z;

par
{
p = 1;
q = 1;
r = 1;
s = 1;
t = 1;
u = 1;
}

par
{
v = func[0](p, q); // v = 3 (t in func[0] is 1)
w = func[1](r, s); // w = 3 (t in func[1] is 1)
}

x = func[0](t, u); // x = 4 (t in func[0] is 2)

y = func[0](v, w); // y = 9 (t in func[0] is 3)

z = func[1](x, y); // z = 15 (t in func[1] is 2)

}

7.2.6 Function pointers

These are a very powerful, yet potentially confusing feature. In situations where any one
of a number of functions can be called at a particular point, it is neater and more concise
to use a function pointer, where the alternative might be a long if-else chain, or a long
switch statement (see example).

www.celoxica.com Page 129

Handel-C Language Reference Manual

Function pointers can be assigned with or without the address operator & (similar to
assigning array addresses). Functions pointed to can be called with or without the
indirection operator.

A function name can be assigned to a pointer without the &

p = addeven;

although the & format is clearer:

p = &addeven;

A function pointed to can be called by writing

(*chk)(a, b);

This can also be written in the shorthand form:

chk(a, b);

The first form is preferable, as it tips off anyone reading the code that a function pointer
is being used.

7.2.7 Function pointers example

Consider the following program:

www.celoxica.com Page 130

Handel-C Language Reference Manual

set clock = external "P1";

unsigned 1 check(short int *a, short int *b,

unsigned 1 (*chk)(const short int *,
const short int *));

unsigned 1 addeven(const short int *x, const short int *y);

unsigned 1 minuseven(const short int *x, const short int *y);
unsigned 1 diveven(const short int *x, const short int *y);
unsigned 1 modeven(const short int *x, const short int *y);

void main(void)
{
short int m, n;
unsigned 2 choice;
unsigned 1 result;
unsigned 1 (*p)(const short *, const short *);

par
{
m = 19;
n = 47;
}

do
{
switch (choice)
{
case 0:
p = addeven;
break;
case 1:
p = minuseven;
break;
case 2:
p = diveven;
break;
case 3:
p = modeven;
break;
default:
delay;

www.celoxica.com Page 131

Handel-C Language Reference Manual

break;
}

par
{
result = check(&m, &n, p);
choice++;
}
}
while(choice);
}

unsigned 1 check(short int *a, short int *b,

unsigned 1 (*chk)(const short int *,
const short int *))
{
return (*chk)(a, b);
}

unsigned 1 addeven(const short int *x, const short int *y)

{
return (unsigned)(*x + *y)[0];
}

unsigned 1 minuseven(const short int *x, const short int *y)

{
return (unsigned) (*x - *y)[0];
}

unsigned 1 diveven(const short int *x, const short int *y)

{
return (unsigned) (*x / *y)[0];
}

unsigned 1 modeven(const short int *x, const short int *y)

{
return (unsigned) (*x % *y)[0];
}

The function addeven checks whether the sum of two numbers is even. Similar checks
are carried out by minuseven (difference of two numbers), diveven (division) and
modeven (modulus). The function check simply calls the function whose pointer it
receives, with the arguments it receives. This gives a consistent interface to the xxxeven

www.celoxica.com Page 132

Handel-C Language Reference Manual

functions. Pay close attention to the declaration of check, and of function pointer p. The
parentheses around *p (and *chk in the declaration of check) are necessary for the
compiler to make the correct interpretation.

Possible code optimization

Inside the main program body, check was called like this:

check(&m, &n, p);

It could have been written like this:

check(&m, &n, xxxeven);

eliminating the need for an additional pointer variable.

Here is the main section written using this form of expression:

www.celoxica.com Page 133

Handel-C Language Reference Manual

void main(void)
{
short int m, n;
unsigned 2 choice;
unsigned 1 result;

par
{
m = 19;
n = 47;
}

do
{
switch (choice)
case 0:
result = check(&m, &n, &addeven);
break;
case 1:
result = check(&m, &n, &multeven);
break;
case 2:
result = check(&m, &n, &diveven);
break;
case 3:
result = check(&m, &n, &modeven);
break;
default:
break;
choice++;
}
while(choice);
}

7.2.8 Simultaneous function calls

In Handel-C, a function corresponds to a shared piece of hardware, which may only be

used by one thread at a time. Simultaneous calls to a function, or even overlapping
execution of a function, will cause problems.

www.celoxica.com Page 134

Handel-C Language Reference Manual

You can check for simultaneous accesses to a function when you are debugging your
code by using the Detection of simultaneous function calls option on the Debug tab in Project
Settings, or the -S+parfunc option in the command line compiler.

You can ensure that the function usage does not overlap by declaring functions to be
inline (so they are expanded whenever they are used) or by declaring an array of
functions, one to be used in each parallel branch. This is illustrated in the example below.

Example
int func(int x, int y);

void main(void)
{
int a, b, c, d, e, f, foo;
// etc ...

par
{
a = func(b, c);
{
b = foo;
d = func(e, f); // NOT ALLOWED
}
}
// etc ...
}

int func(int x, int y)

{
if (x == y)
delay;
else
{
x = x % y;
}
x *= 10;

return(x);
}
This is not allowed because part of the single function is used twice in the same clock
cycle.

The code can be re-written to use inline functions, or an array of functions:

www.celoxica.com Page 135

Handel-C Language Reference Manual

inline int func(x, y);

par
{
a = func(b, c);
{
b = foo;
d = func(e, f);
}
}

or

int func[2](x, y);

par
{
a = func[0](b, c);
{
b = foo;
d = func[1](e, f);
}
}

7.2.9 Multiple functions in a statement

Because each statement in Handel-C must take a single clock cycle, you cannot have
multiple functions in a single statement.

Instead of

y = f(g(x));// illegal

you can write

z=g(x);
y=f(z);

Instead of

y = f(x) + g(z); // illegal

you can write:

www.celoxica.com Page 136

Handel-C Language Reference Manual

par
{
a = f(x);
b = g(z);
}
y = a+b;

7.3 Introduction to macros

The Handel-C compiler passes source code through a standard C preprocessor before
compilation allowing the use of #define to define constants and macros in the usual
manner. Since the preprocessor can only perform textual substitution, some useful
macro constructs cannot be expressed. For example, there is no way to create recursive
macros using the preprocessor.

Handel-C provides additional macro support to allow more powerful macros to be defined
(for example, recursive macro expressions). In addition, Handel-C supports shared
macro expressions to generate one piece of hardware which is shared by a number of
parts of the overall program similar to the way that procedures allow conventional C to
share one piece of code between many parts of a conventional program.

7.3.1 Non-parameterized macro expressions

Non-parameterized macro expressions are of two types:

• simple constant equivalent to #define

• a constant expression

Constant
This first form of the macro is a simple expression. For example:

macro expr DATA_WIDTH = 15;

int DATA_WIDTH x;

This form of the macro is similar to the #define macro. Whenever DATA_WIDTH appears
in the program, the constant 15 is inserted in its place.

Constant expression
To provide a more general solution, you can use a real expression. For example:

macro expr sum = (x + y) @ (y + z);

v = sum;
w = sum;

www.celoxica.com Page 137

Handel-C Language Reference Manual

7.3.2 Parameterized macro expressions

Handel-C allows macros with parameters. For example:

macro expr add3(x) = x+3;

y = add3(z);

This is equivalent to the following code:

y = z + 3;

This form of the macro is similar to the #define macro in that every time the add3()
macro is referenced, it is expanded in the manner shown above. In this example, an
adder is generated in hardware every time the add3() macro is used.

7.3.3 select operator

The select(...) operator is used to mean ‘select at compile time’. Its general usage is:

select(Expression1, Expression2, Expression3)

Expression1 must be a compile time constant. If Expression1 evaluates to true then

the Handel-C compiler replaces the whole expression with Expression2. If Expression1
evaluates to false then the Handel-C compiler replaces the whole expression with
Expression3.

Comparison with conditional operator

The difference between select and the conditional operator is seen in this example:

w = (width(x)==4 ? y : z);

The example generates hardware to compare the width of the variable x with 4 and set w
to the value of y or z depending on whether this value is equal to 4 or not.

This is probably not what was intended because both width(x) and 4 are constants.
What was probably intended was for the compiler to check whether the width of x was 4
and then simply replace the whole expression above with y or z according to the value.
This can be written as follows:

w = select(width(x)==4 , y , z);

In this example, the compiler evaluates the first expression and replaces the whole line
with either w=y; or w=z;. No hardware for the conditional is generated.

Combining with macros

This is more useful when macros are combined with this feature.

www.celoxica.com Page 138

Handel-C Language Reference Manual

macro expr adjust(x, n) =

select(width(x) < n, (0 @ x), (x <- n));

unsigned 4 a;
unsigned 5 b;
unsigned 6 c;

b = adjust(a, width(b));
b = adjust(c, width(b));

This example is for a macro that equalizes widths of variables in an assignment. If the
right hand side of an assignment is narrower than the left hand side then the right hand
side must be padded with zeros in its most significant bits. If the right hand side is wider
than the left hand side, the least significant bits of the right hand side must be taken and
assigned to the left hand side.

The select(...) operator is used here to tell the compiler to generate different
expressions depending on the width of one of the parameters to the macro. The last two
lines of the example could have been written by hand as follows:

b = 0 @ a;
b = c <- 5;

The macro comes into its own if the width of one of the variables changes. Suppose that
during debugging, it is discovered that the variable a is not wide enough and needs to be
8 bits wide to hold some values used during the calculation. Using the macro, the only
change required would be to alter the declaration of the variable a. The compiler would
then replace the statement b = 0 @ a; with b = a <- 5; automatically.

This form of macro also comes in useful when variables of undefined width are used. If
the compiler is used to infer widths of variables, it may be tedious to work out by hand
which form of the assignment is required. By using the select(...) operator in this way,
the correct expression is generated without you having to know the widths of variables at
any stage.

7.3.4 ifselect

ifselect checks the result of a compile-time constant expression at compile time. If the
condition is true, the following statement or code block is compiled. If false, it is dropped
and an else condition can be compiled if it exists. Thus, whole statements can be selected
or discarded at compile time, depending on the evaluation of the expression.

The ifselect construct allows you to build recursive macros, in a similar way to select.
It is also useful inside replicated blocks of code as the replicator index is a compile-time
constant. Hence, you can use ifselect to detect the first and last items in a replicated
block of code and build pipelines.

www.celoxica.com Page 139

Handel-C Language Reference Manual

Syntax
ifselect (condition)
statement 1
[else
statement 2]

Example
int 12 a;
int 13 b;
int undefined c;

ifselect(width(a) >= width(b))

c = a;
else
c = b;

c is assigned to by either a or b, depending on their width relationship.

Pipeline example
unsigned init;
unsigned q[15];
unsigned 31 out;

init = 57;
par (r = 0; r < 16; r++)
{
ifselect(r == 0)
q[r] = init;
else ifselect(r == 15)
out = q[r-1];
else
q[r] = q[r-1];
}

7.3.5 Recursive macro expressions

Preprocessor macros (those defined with #define) cannot generate recursive

expressions. By combining Handel-C macros (those defined with macro expr) and the
select(...) operator, recursive macros can express complex hardware simply. This
type of macro is particularly important in Handel-C where the exact form of the macro
may depend on the width of a parameter to the macro.

www.celoxica.com Page 140

Handel-C Language Reference Manual

Variable sign extension example

When assigning a narrow signed variable to a wider variable, the most significant bits of
the wide variable should be padded with the sign bit (MSB) of the narrow variable.

Value 4-bit Conversion to 8-

representation bit representation
-2 0b1110 0b11111110
6 0b0110 0b00000110
The following code suffices for a 4-bit to 8-bit conversion

int 8 x;
int 4 y;

x = y[3] @ y[3] @ y[3] @ y[3] @ y;

but it is tedious for variables that differ by a significant number of bits. It also does not
deal with the case when the exact widths of the variables are not known. What is needed
is a macro to sign extend a variable. For example:

macro expr copy(x, n) =

select(n==1, x, (x @ copy(x, n-1)));

macro expr extend(y, m) =

copy(y[width(y)-1], m-width(y)) @ y;

int a;
int b; // Where b is known to be wider than a

b = extend(a, width(b));

The copy macro generates n copies of the expression x concatenated together. The
macro is recursive and uses the select(...) operator to evaluate whether it is on its last
iteration (in which case it just evaluates to the expression) or whether it should continue
to recurse by a further level.

The extend macro concatenates the sign bit of its parameter m-k times onto the most
significant bits of the parameter. Here, m is the required width of the expression y and k
is the actual width of the expression y.

The final assignment correctly sign extends a to the width of b for any variable widths
where width(b) is greater than width(a).

www.celoxica.com Page 141

Handel-C Language Reference Manual

7.3.6 Recursive macro expressions example

This example illustrates the generation of large quantities of hardware from simple
macros. The example is a multiplier whose width depends on the parameters of the
macro. Although Handel-C includes a multiplication operator as part of the language, this
example serves as a starting point for generating large regular hardware structures using
macros.

The multiplier generates the hardware for a single cycle long multiplication operation
from a single macro. The source code is:

macro expr multiply(x, y) = select(width(x) == 0, 0,

multiply(x \\ 1, y << 1) +
(x[0] == 1 ? y : 0));
a = multiply (b , c);

At each stage of recursion, the multiplier tests whether the bottom bit of the x parameter
is 1. If it is then y is added to the ‘running total’. The multiplier then recurses by
dropping the LSB of x and multiplying y by 2 until there are no bits left in x. The overall
result is an expression that is the sum of each bit in x multiplied by y. This is the familiar
long multiplication structure. For example, if both parameters are 4 bits wide, the macro
expands to:

a = ((b \\ 3)[0]==1 ? c<<3 : 0) +

((b \\ 2)[0]==1 ? c<<2 : 0) +
((b \\ 1)[0]==1 ? c<<1 : 0) +
(b[0]==1 ? c : 0);

This code is equivalent to:

a = ((b & 8)==8 ? c*8 : 0) +

((b & 4)==4 ? c*4 : 0) +
((b & 2)==2 ? c*2 : 0) +
((b & 1)==1 ? c : 0);

which is a standard long multiplication calculation.

7.3.7 Shared expressions

By default, Handel-C generates all the hardware required for every expression in the
whole program. This can mean that large parts of the hardware are idle for long periods.
Shared expressions allow hardware to be shared between different parts of the program
to decrease hardware usage.

The shared expression has the same format as a macro expression but does not allow
recursion. You can use recursive macro expressions or let...in to generate recursive
shared expressions.

www.celoxica.com Page 142

Handel-C Language Reference Manual

Example
a = b * c;
d = e * f;
g = h * i;

This code generates three multipliers. Each one will only be used once and none of them
simultaneously. This is a massive waste of hardware. You can improve the hardware
efficiency with a shared expression:

shared expr mult(x, y) = x * y;

a = mult(b, c);
d = mult(e, f);
g = mult(h, i);

In this example, only one multiplier is built and it is used on every clock cycle. If speed is
required, you can build three multipliers executing in parallel.

Warning
It is not always the case that less hardware is generated by using shared expressions
because multiplexors may need to be built to route the data paths. Some expressions
use less hardware than the multiplexors associated with the shared expression.

7.3.8 Using recursion to generate shared expressions

Although shared expressions cannot use recursion directly, macro expressions can be
used to generate hardware which can then be shared using a shared expression. For
example, to share a recursive multiplier you could write:

macro expr multiply(x, y) = select(width(x) == 0, 0,

multiply(x \\ 1, y << 1) +
(x[0] == 1 ? y : 0));

shared expr mult(x, y) = multiply(x, y);

a = mult(b, c);
d = mult(e, f);

The macro expression builds a multiplier and the shared expression allows that hardware
to be shared between the two assignments.

7.3.9 Restrictions on shared expressions

Shared expressions must not be shared by two different parts of the program on the
same clock cycle. For example:

www.celoxica.com Page 143

Handel-C Language Reference Manual

shared expr mult(x, y) = x * y;

par
{
a = mult(b, c);
d = mult(e, f); // NOT ALLOWED
}

This is not allowed because the single multiplier is used twice in the same clock cycle.

You need to ensure that shared expressions in parallel branches are not shared on the
same clock cycle.

7.3.10 let ... in

let and in allow you to declare macro expressions within macro expressions. In this
way, complex macros may be broken down into simple ones, whilst still being grouped
together in a single block of code. They also provide easy sharing of recursive macros.

The let keyword starts the declaration of a local macro; the in keyword ends the
declaration and defines its scope.

Example
macro expr Fred(x) =
let macro expr y = x*2; in
y+3; // Returns x*2+3

The top line defines the macro name and parameters. The second line defines y within
the macro definition. The last line expresses the value of the macro in full.

Independent let …in definitions

macro expr op(a, b) =
let macro expr t2(x) = x * 2; in
let macro expr d3(x) = x / 3; in
let macro expr t4(x) = x * 4; in
t2(a) + d3(b) + t4(a - b) + t2(b - a);

is equivalent to writing

macro expr op(a, b) = (a * 2) + (b / 3) + ((a-b) * 4) + ((b-a) * 2);

Related let …in definitions

macro expr op(a, b) =
let macro expr sum(x, y) = x + y; in
let macro expr mult(x, y) = x * sum(x, y); in
mult(a, b) - (b * b);

www.celoxica.com Page 144

Handel-C Language Reference Manual

sum is defined within the macro definition, then mult is defined using sum. This example
is equivalent to:

macro expr op(a, b) = (a * (a + b)) - (b * b);

Shared recursive macro

A recursive multiplier illustrating the way in which let…in can be used to share recursive
macros.

shared expr mult(p, q) =

let macro expr multiply(x, y) =
select(width(x) == 0, 0, multiply(x \\ 1, y << 1)
+ (x[0] == 1 ? y : 0)); in
multiply(p, q)

Scope of definitions
The inner macros are not accessible outside the outer macro

{
chanout <unsigned 16> och;
int 16 i, j, k;
{
macro expr Cube(x) =
let macro expr Sqr(x) = x*x; in
x * Sqr(x)
i = Cube(3) // Correct use
j = Sqr(3) // Error - out of scope
}
k = Cube(2); //Error - out of scope
}

7.3.11 Macro procedures

Macro procedures may be used to replace complete statements to avoid tedious

repetition while coding. A single macro procedure can be expanded into a complex block
of code. It generates the hardware for the statement each time it is referenced.

The general syntax of macro procedures is:

macro proc Name(Params) Statement

Macros may be prototyped (like functions). This allows you to declare them in one file
and use them in another. A macro prototype consists of the name of the macro plus a list
of the names of its parameters. E.g.

macro proc work(x, y);

www.celoxica.com Page 145

Handel-C Language Reference Manual

If you have local or static declarations within the macro procedure, a copy of the variable
will be created for each copy of the macro.

Macro procedures that don't take any parameters require an empty parameter list. For
example:

macro proc MyMacro ();

Example
macro proc output(x, y)
{
out ! x;
out ! y;
}

output(a + b, c * d);
output(a + b, c * d);

This example writes the two expressions a+b and c*d twice to the channel out. This
example also illustrates that the statement may be a code block - in this case two
instructions executed sequentially.

It expands to 4 channel output statements.

7.3.12 Macro procedures compared to pre-processor macros

Macro procedures differ from preprocessor macros in that they are not simple text
replacements. The statement section of the definition must be a valid Handel-C
statement.

The following code is valid as a #define pre-processor macro but not as a macro
procedure:

#define test(x,y) if (x!=(y<<2)) // not valid as a macro procedure as not a

complete statement

test(a,b)
{
a++;
}
else
{
b++;
}

Incomplete statements will not compile as macro procedures:

www.celoxica.com Page 146

Handel-C Language Reference Manual

macro proc test(x,y) if (x!=(y<<2)) // Incomplete statement, will not

compile

A complete statement will not successfully replace an incomplete one:

macro proc test(x,y) if (x!=(y<<2)); // Complete statement will compile

test(a,b) // will expand to if (x!=(y<<2));

{
a++;
}
else // this else has no associated if
{
b++;
}

Here, the macro procedure is not defined to be a complete statement so the Handel-C
compiler generates an error. This restriction provides protection against writing code
which is generally unreadable and difficult to maintain.

www.celoxica.com Page 147

Handel-C Language Reference Manual

8 Introduction to timing
A Handel-C program executes with one clock source for each main statement. It is
important to be aware exactly which parts of the code execute on which clock cycles.
This is not only important for writing code that executes in fewer clock cycles but may
mean the difference between correct and incorrect code when using Handel-C’s
parallelism. Experienced programmers can immediately tell which instructions execute on
which clock cycles. This information becomes very important when your program
contains multiple interacting parallel processes.

Knowing about clock cycles also becomes important when considering interfaces to
external hardware. It is important to understand timing issues before moving on to
implementing such interfaces because it is likely that the external device will place
constraints on when signals should change.

Avoiding certain constructs has a dramatic influence on the maximum clock rate that
your Handel-C program can run at.

8.1 Statement timing

The basic rule for working out the number of cycles used in a Handel-C program is:

Ï Assignment and delay take 1 clock cycle. Everything else is free.

• One clock cycle is used every time you write an assignment statement or a
delay statement. releasesema also uses one clock cycle.
A special case statement is supported of the form:
a = f(x);
to allow function calls which take multiple clock cycles.
• Channel communications use one clock cycle in the same clock domain if both
ends are ready to communicate. If one of the branches is not ready for the
data transfer then execution of the other branch waits until both branches
become ready.
• You can write any other piece of code and not use any clock cycles to execute
it.

8.1.1 Example timings

Statements
x = y;
x = (((y * z) + (w * v))<<2)<-7;

www.celoxica.com Page 148

Handel-C Language Reference Manual

Each of these statements takes one clock cycle.

Notice that even the most complex expression can be evaluated in a single clock cycle.
Handel-C builds the combinational hardware to evaluate such expressions; they do not
need to be broken down into simpler assembly instructions as would be the case for
conventional C.

Parallel statements
par
{
x = y;
a = b * c;
}

This code executes in a single cycle because each branch of the parallel statement takes
only one clock cycle. This example illustrates the benefits of parallelism. You can have as
many non-interdependent instructions as you wish in the branches of a parallel
statement. The total time for execution is the length of time that the longest branch
takes to execute. For example:

par
{
x = y;
{
a = b;
c = d;
}
}

This code takes two clock cycles to execute. On the first cycle, x = y and a = b take
place. On the second clock cycle, c = d takes place. Since both branches of the par
statement must complete before the par block can complete, the first branch delays for
one clock cycle while the second instruction in the second branch is executed.

While loop
x = 5;
while (x>0)
{
x--;
}

This code takes a total of 6 clock cycles to execute. One cycle is taken by the assignment
of 5 to x. Each iteration of the while loop takes 1 clock cycle for the assignment of x-1
to x and the loop body is executed 5 times. The condition of the while loop takes no
clock cycles as no assignment is involved.

www.celoxica.com Page 149

Handel-C Language Reference Manual

For loop
for (x = 0; x < 5; x ++)
{
a += b;
b *= 2;
}

This code has an almost direct equivalent:

{
x = 0;
while (x<5)
{
a += b;
b *= 2;
x ++;
}
}

This code takes 16 clock cycles to execute. One is required for the initialization of x and
three for each execution of the body. Since the body is executed 5 times, this gives a
total of 16 clock cycles.

Decision
if (a>b)
{
x = a;
}
else
{
x = b;
}

This code takes exactly one clock cycle to execute. Only one of the branches of the if
statement is executed, either x = a or x = b. Each of these assignments takes one
clock cycle. Notice again that no time is taken for the test because no assignment is
made. A slightly different example is:

if (a>b)
{
x = a;
}

Here, if a is not greater than b, there is no else branch. This code therefore takes either
1 clock cycle if a is greater than b or no clock cycles if a is not greater than b.

www.celoxica.com Page 150

Handel-C Language Reference Manual

Channels
Channel timings can be complex. The simplest example is with a channel link of
fifolength 0 (default):

chan unsigned 8 link;

par
{
link ! x; // Transmit
link ? y; // Receive
}

This code takes a single clock cycle to execute because both the transmitting and
receiving branches are ready to transfer at the same time. All that is required is the
assignment of x to y which, like all assignments, takes 1 clock cycle. A more complex
example is:

chan unsigned 8 link;

par
{
{ // Parallel branch 1
a = b;
c = d;
link ! x;
}

link ? y; // Parallel branch 2

}

Here, the first branch of the par statement takes three clock cycles to execute.
However, the second branch of the par statement also takes three clock cycles to
execute because it must wait for two cycles before the transmitting branch is ready. The
usage of clock cycles is as follows:

Cycle Branch 1 Branch 2

1 a = b; delay

2 c = d; delay
3 Channel output Channel input

FIFOs
FIFOs add another layer of complexity.

www.celoxica.com Page 151

Handel-C Language Reference Manual

chan unsigned link_FIFO with {fifolength=4};

int i = 0;

par
{
while(1)
{
i++; //Cannot be in parallel to channel write
//Do not change a variable in parallel with sending
it
link_FIFO ! i; // Parallel branch 1
}
// Parallel branch 2
a = b; //Parallel code: used here instead of delay
c = d;
link_FIFO ? y;
}
}

Here, the write branch of the par statement takes two clock cycles to execute and the
read branch takes three clock cycles to execute. If it were a simple channel, the write
branch would have to wait until the channel had been read, before it could write the next
value of i. However, because it is a FIFO, the write branch can keep writing until the
FIFO is full. On the third clock cycle, the read branch reads the first value from the FIFO.

When the FIFO is full the first branch must wait until the FIFO is read from before it can
write to it again.

Ï The precise timing of FIFOs depends on many different factors. The

throughput will be close to one word per cycle for sufficiently large FIFOs.

FIFO: channel and FIFO comparison code

This example shows a loop using a channel to communicate between two processes.

www.celoxica.com Page 152

Handel-C Language Reference Manual

Process A:
static unsigned 4 Val = 1;
while(1)
{
Val = Val[2:0]@Val[3];
MyChan ! Val; // Send
delay;
}

Process B:
static unsigned 4 Count;
while(1)
{ // wait 0 or more cycles
while (Count != 0)
{
Count--;
}
MyChan ? Count; // Receive
delay;
}
The delay statements in each process always take place on the same clock cycle in the
same clock domain.

Example with FIFO

This shows the same process, but using a FIFO with fifolength 4. The loop in process A
would execute 4 times without pausing and then run after each time process B reads
from the FIFO.

www.celoxica.com Page 153

Handel-C Language Reference Manual

chan myFIFO with {fifolength = 4};

Process B:
static unsigned 4 Count;
while(1)
{ // wait 0 or more cycles
while (Count != 1)
{
Count--;
}
MyFIFO ? Count; // Receive
delay;
}

Process A:
static unsigned 4 Val = 1;
while(1)
{
Val = Val[2:0]@Val[3];
MyFIFO ! Val; // Send
delay;
}
See the summary of statement timings for more detail.

8.1.2 Statement timing summary

www.celoxica.com Page 154

Handel-C Language Reference Manual

Statement Timing

{...} Sum of all statements in sequential block

par {...} Length of longest branch in block
Function(), break, goto, No clock cycles
continue
return(Expression); 1 clock cycle if Expression is assigned on return,
otherwise none.
Variable = Expression; 1 clock cycle

Variable ++; 1 clock cycle

Variable --; 1 clock cycle
++ Variable; 1 clock cycle
-- Variable; 1 clock cycle
Variable += Expression; 1 clock cycle
Variable -= Expression; 1 clock cycle
Variable *= Expression; 1 clock cycle
Variable /= Expression; 1 clock cycle
Variable %= Expression; 1 clock cycle
Variable <<= Constant; 1 clock cycle

Variable >>= Constant; 1 clock cycle

Variable &= Expression; 1 clock cycle
Variable |= Expression; 1 clock cycle
Variable ^= Expression; 1 clock cycle
Channel ? Variable; 1 clock cycle when transmitter is ready (in same clock
domain)
Channel ! Expression; 1 clock cycle when receiver is ready (in same clock
domain)
if (Expression) {...} Length of executed branch
else {...}
while (Expression) {...} Length of loop body * number of iterations
do {...} while Length of loop body * number of iterations
(Expression);
for (Init; Test; Iter) Length of Init + (Length of body + length of Iter) *
{...} number of iterations
switch (Expression) {...} Length of executed case branch

www.celoxica.com Page 155

Handel-C Language Reference Manual

prialt {...} 1 clock cycle for case communication when other party
is ready plus length of executed case branch
or length of default branch if present and no
communication case is ready
or infinite if no default branch and no communication
case is ready
releasesema(); 1 clock cycle
delay; 1 clock cycle

Ï The Handel-C compiler may insert delay statements to break combinational

loops.

8.2 Avoiding combinational loops

If you wish to wait for a variable to be modified in a parallel process before continuing,
you might write:

while (x!=3); // WARNING!!

This is bad Handel-C code because it generates a combinational loop in the logic (This is
because of the way that Handel-C expressions are built to evaluate in zero clock cycles.)

This is easier to see if it is written as

while (x!=3)
{
// wait until x == 3
}

This empty loop must be broken by changing the code to:

while (x!=3)
{
delay;
}

This code takes no longer to execute but does not contain a combinational loop because
of the clock cycle delay in the loop body.

The Handel-C compiler spots this form of error, inserts the delay statement, and
generates a warning. It is considered better practice to include the delay statement in
the code to make it explicit

Similar problems occur with do ... while loops and switch statements in similar
circumstances. for loops with no iteration step can also cause combinational loops.

www.celoxica.com Page 156

Handel-C Language Reference Manual

Further combinational loop code example

Code may look correct but still include an empty loop. For example:

while (x!=3)
{
if (y>z)
{
a++;
}
}

This if statement may take zero clock cycles to execute if y is not greater than z so
even though this loop body does not look empty a combinational loop is still generated.
This is more obvious written as

while (x!=3)
{
if (y>z)
{
a++;
}
else
{
// do nothing
}
}

The solution is to add the else part of the if construct as follows:

while (x!=3)
{
if (y>z)
{
a++;
}
else
{
delay;
}
}

www.celoxica.com Page 157

Handel-C Language Reference Manual

8.3 Parallel access to variables

The rules of parallelism state that the same variable must not be accessed from two
separate parallel branches. This avoids resource conflicts on the variables.

The rule may be relaxed to state that the same variable must not be assigned to more
than once on the same clock cycle but may be read as many times as required. This
gives powerful programming techniques. For example:

par
{
a = b;
b = a;
}

This code swaps the values of a and b in a single clock cycle.

Since exact execution time may be run-time dependent, the Handel-C compiler cannot
determine when two assignments are made to the same variable on the same clock
cycle. You should therefore check your code to ensure that the relaxed rule of parallelism
is still obeyed.

Example
Using this technique, a four-place queue can be written:

while(1)
{
par
{
int x[3];

x[0] = in;
x[1] = x[0];
x[2] = x[1];
out = x[2];
}
}

The value of out is the value of in delayed by 4 clock cycles. On each clock cycle, values
will move one place through the x array. For example:

www.celoxica.com Page 158

Handel-C Language Reference Manual

Clock in x[0] x[1] x[2] out

1 5 0 0 0 0
2 6 5 0 0 0
3 7 6 5 0 0
4 8 7 6 5 0
5 9 8 7 6 5
6 10 9 8 7 6
7 11 10 9 8 7
8 12 11 10 9 8
9 13 12 11 10 9

8.4 Detailed timing example

This is an analyzed example that generates signals tied to real-world constraints. It
shows the generation of signals for a real time clock. The signals required are for
microseconds, seconds, minutes and hours.

The hardware generated will eventually be driven from an external clock. In order to
write the program, the rate of this clock must be known. It has been assumed to be 5
MHz on pin P1.

The loop body takes one clock cycle to execute. The Count variable is used to divide the
clock by 5 to generate microsecond increments. As each variable wraps round to zero,
the next time step up is incremented.

www.celoxica.com Page 159

Handel-C Language Reference Manual

set clock = external "P1";

void main(void)
{
unsigned 20 MicroSeconds;
unsigned 6 Seconds;
unsigned 6 Minutes;
unsigned 16 Hours;
unsigned 3 Count;

par
{
Count = 0;
MicroSeconds = 0;
Seconds = 0;
Minutes = 0;
Hours = 0;
}
while (1)
{
if (Count!=4)
Count++;
else
par
{
Count = 0;
if (MicroSeconds!=999999)
MicroSeconds++;
else
par
{
MicroSeconds = 0;
if (Seconds!=59)
Seconds++;
else
par
{
Seconds = 0;
if (Minutes!=59)
Minutes++;
else
par
{

www.celoxica.com Page 160

Handel-C Language Reference Manual

Minutes = 0;
Hours++;
}
}
}
}
}
}

8.5 Time efficiency of Handel-C hardware

Handel-C requires that the clock period for a program is longer than the longest path
through combinational logic in the whole program. This means that, for example, once
FPGA or PLD place and route has been completed, the maximum clock rate for the
system can be calculated from the reciprocal of the longest path delay in the circuit.

For example, suppose the FPGA place and route tools calculate that the longest path
delay between flip-flops in a design is 70ns. The maximum clock rate that that circuit
should be run at is then 1/70ns = 14.3MHz.

If this calculated rate is not fast enough for the system performance or real time
constraints you can optimize your program to reduce the longest path delay and increase
the maximum possible clock rate. You can also use the retiming option to try and match
your target clock rate.

One standard technique for optimizing efficiency is to use pipelining.

8.5.1 Reducing logic depth

Certain operations in Handel-C combine to produce deep logic. Deep logic results in long
path delays in the final circuit so reducing logic depth should increase clock speed.

Guidelines for reducing logic depth

• Division and modulo operators produce the deepest logic. Multiplication also
produces deep logic. A single cycle divide, mod or multiplier produces a large
amount of hardware and long delays through deep logic so you should avoid
using them wherever possible.
• Most common division and multiplications can be done with the shift
operators. Also consider using a long multiplication with a loop, shift and add
routine or a pipelined multiplier.
• Most common modulo operations can be done with the AND operator.
• Wide adders require deep logic for the carry ripple. Consider using more clock
cycles with shorter adders.
• Avoid greater than and less than comparisons - they produce deep logic.

www.celoxica.com Page 161

Handel-C Language Reference Manual

• Reduce complex expressions into a number of stages.

• Avoid long strings of empty statements. Empty statements result from, for
example, missing else conditions from if statements.

Adder example
To reduce a single, 8-bit wide adder to 3, narrower adders:

unsigned 8 x;
unsigned 8 y;
unsigned 5 temp1;
unsigned 4 temp2;

par
{
temp1 = (0@(x<-4)) + (0@(y<-4));
temp2 = (x \\ 4) + (y \\ 4);
}
x = (temp2+(0@temp1[4])) @ temp1[3:0];

Comparison example
while (x<y)
{
......
x++;
}

can be replaced with:

while (x!=y)
{
......
x++;
}

The == and != comparisons produce much shallower logic although in some cases it is
possible to remove the comparison altogether. Consider the following code:

www.celoxica.com Page 162

Handel-C Language Reference Manual

unsigned 8 x;

x = 0;
do
{
......
x = x + 1;
} while (x != 0);

This code iterates the loop body 256 times but it can be re-written as follows:

unsigned 9 x;

x = 0;
do
{
......
x = x + 1;
} while (!x[8]);

By widening x by a single bit and just checking the top bit, we have removed an 8-bit
comparison.

Complex expression example

x = a + b + c + d + e + f + g + h;

reduces to:

par
{
temp1 = a + b;
temp2 = c + d;
temp3 = e + f;
temp4 = g + h;
}
par
{
temp1 = temp1 + temp2;
temp3 = temp3 + temp4;
}
x = temp1 + temp3;

This code takes three clocks cycles as opposed to one but each clock cycle is much
shorter and so the rest of the circuit should be speeded up by the faster clock rate
permitted.

www.celoxica.com Page 163

Handel-C Language Reference Manual

Empty statement example

if (a>b)
x++;
if (b>c)
x++;
if (c>d)
x++;
if (d>e)
x++;
if (e>f)
x++;

If none of these conditions is met then all the comparisons must be made in one clock
cycle. By filling in the else statements with delays, the long path through all these if
statements can be split at the expense of having each if statement take one clock cycle
whether the condition is true or not.

8.5.2 Pipelining

A classic way to increase clock rates in hardware is to pipeline. A pipelined circuit takes
more than one clock cycle to calculate any result but can produce one result every clock
cycle. The trade off is an increased latency for a higher throughput so pipelining is only
effective if there is a large quantity of data to be processed: it is not practical for single
calculations.

www.celoxica.com Page 164

Handel-C Language Reference Manual

Pipelined multiplier example

unsigned 8 sum[8];
unsigned 8 a[8];
unsigned 8 b[8];
//ina.dat is a data file. You must provide your own
chanin inputa with {infile = "ina.dat"};
chanin inputb with {infile = "ina.dat"};
chanout output with {outfile = "out.dat"};

par
{
while(1)
inputa ? a[0];

while(1)
inputb ? b[0];

while(1)
output ! sum[7];

while(1)
{
par
{
macro proc level(x)
par
{
sum[x] = sum[x - 1] +
((a[x][0] == 0) ? 0 : b[x]);
a[x] = a[x - 1] >> 1;
b[x] = b[x - 1] << 1;
}

sum[0] = ((a[0][0] == 0) ? 0 : b[0]);

par ( i=1; i <=7; i++)
{
level (i);
}
}
}
}

www.celoxica.com Page 165

Handel-C Language Reference Manual

This multiplier calculates the 8 LSBs of the result of an 8-bit by 8-bit multiply using long
multiplication. The multiplier produces one result per clock cycle with a latency of 8 clock
cycles. This means that although any one result takes 8 clock cycles, you get a
throughput of 1 multiply per clock cycle. Since each pipeline stage is very simple,
combinational logic is shallow and a much higher clock rate is achieved than would be
possible with a complete single cycle multiplier.

At each clock cycle, partial results pass through each stage of the multiplier in the sum
array. Each stage adds on 2n multiplied by the b operand if required. The LSB of the a
operand at each stage tells the multiply stage whether to add this value or not. Stages
are generated with a macro procedure instantiated several times using a replicator

Operands are fed in on every clock cycle through a[0] and b[0]. Results appear 8 clock
cycles later on every clock cycle through sum[7].

www.celoxica.com Page 166

Handel-C Language Reference Manual

9 Clocks overview
You can have multiple clocks interfacing with your design. Each main() function must be
associated with a single clock. If you have more than one main function in the same
source file, they must all use the same clock.

Clocks may be fed from expressions (internal clocks) or fed from a pin (external clocks).

The current clock may be referred to using the keyword _ _clock

You can specify the maximum delay in MHz allowed between components fed from a
clock by using the rate specification.

The general syntax of the clock specification is:

set clock = Location with {Rate_spec, periodSpec};

If you are communicating between clock domains, you also need to set timing
specifications (resolutiontime or minperiod). These control the synchronization
hardware generated.

You must specify a clock. When generating simulation output, a dummy clock such as
'set clock = external "P1";' is valid.

9.1 Locating the clock

Since each Handel-C main() code block generates synchronous hardware, a single clock
source is required for each one.

The general syntax of the clock specification is:

set clock = Location;

Location may be any of the following:

Location Meaning

internal Expression Clock from expression

internal_divide Clock from expression with integer division
Expression Factor
external [Pin] Clock from device pin
external_divide Clock from device pin with integer division
[Pin] Factor

www.celoxica.com Page 167

Handel-C Language Reference Manual

9.1.1 External clocks

External clocks may be accessed by associating the clock with a specific pin using set
clock external = "pin_Name" or set clock external_divide = "pin_Name" factor,
where the external_divide keyword is a constant integer. For example:

set clock = external "P35";

set clock = external_divide "P35" 3;
set clock = external_divide 3;

The first of these examples specifies a clock taken from pin P35. The second specifies a
clock taken from pin P35 which is divided on the FPGA/PLD by a factor of 3. The third
option shows a clock divided by 3 with no pin number specified.

When the pin number is omitted, the place and route tools will choose an appropriate
pin. Omitting pin specifications can speed up the clock rate of the design.

You can also define an interface that reads an external clock. If the clock is associated
with a specific pin, you can use the interface sort bus_in. You would only need to do
this if the external clock has been divided, otherwise you can use the intrinsic __clock.

Example
interface bus_in(unsigned 1 in with {clockport=1})
InputBus() with {data={"Pin1"}};
set clock = external_divide "Pin1" 4;

You can now use InputBus.in to get an undivided external clock.

9.1.2 Internal clocks fed from expressions

You can set the clock to be any expression or any expression divided by a given factor.

set clock = internal <Expression>;

set clock = internal_divide <Expression> factor;

The clock division factor specified with the internal_divide keyword must be a constant
integer.

Example
This allows you to set the clock to a value read from an interface.

interface port_in(unsigned 1 clk with {clockport = 1}) ClockPort();

set clock = internal ClockPort.clk;

www.celoxica.com Page 168

Handel-C Language Reference Manual

9.2 Current clock

The current clock used by a function can be referenced using the keyword __clock. This
allows the function to pass the current clock to an external interface. The value of the
system variable __clock will be the value after any divide. The clock may be an internal
or an external clock.

Example
The code below shows the assignment of the current clock to a port in an interface.

interface reg32x1k() registers(unsigned addr=address,

unsigned data=data_in, unsigned 1 clk = __clock,
unsigned out = write);

9.3 Multiple clock domains

You can have multiple clock domains in your Handel-C design by declaring more than one
main() function. If you have more than one main() function in the same source file, they
must all use the same clock. The clock is defined in each file using the set clock
construct.

You can communicate between clock domains by:

• using channels with time constraints set on the clock

• using a defined custom interface. You cannot use multiple clock domains
within the pre-defined Handel-C interface sorts.
Variables, signals and functions cannot be written to by one clock domain and read in
another.

Communicating between clock domains means that you need to consider metastability
issues.

2 If you reset one clock domain without synchronously resetting any clock
domains that it communicates with, the communicating channels will go to an
undefined state.

9.3.1 Channels communicating between clock domains

Channels that connect between clock domains can only be written to in a single domain
and read from in a single domain. Their first use defines their direction and the domains

www.celoxica.com Page 169

Handel-C Language Reference Manual

in which they transmit and receive. If you attempt to re-use the channel in a different
direction or to or from a different clock domain, the compiler generates an error.

Channels used between clock domains must be defined in one file and then declared as
extern in another.

The timing between domains is unspecified, but the transmission is guaranteed to occur
provided metastability is resolved. If fifolength is 0, both sides will wait until the
transmission is certain to complete. Otherwise, the channel will write as soon as the FIFO
is ready (and has space) and read as soon as the FIFO is ready (and isn't empty).

If you use channels to communicate between clock domains you must specify the rate
and the resolutiontime for both clocks.

Ï Most cases will be dealt with by setting the resolution time to three-quarters
of the clock period.

Example
For a 10ns clock

set clock = external "A22" with {rate=100, resolutiontime=7.5};

Note that the rate is in MHz and the resolutiontime is in nanoseconds.

If you need to adjust the channel timing due to latency issues, you may do so by
adjusting the resolutiontime and the number of flip-flops used to prevent metastability
being propagated through the circuit.

2 If the resolution time is set incorrectly then intermittent failures due to

metastability may cause the generated hardware to be unreliable. You must
test channels communicating between clock domains extremely thoroughly
(unless you know that resolutiontime is sufficiently long to guarantee an
acceptable probability of failure).

Timing issues for channels communicating between clock domains

The timing of channels across clock domains is unspecified. The values read into i and j
may differ in the example below, as the reads may not complete on the same clock cycle.

www.celoxica.com Page 170

Handel-C Language Reference Manual

Domain 1:
set clock = external with { paranoia=1, minperiod=2.0,
unconstrainedperiod=9, rate=101 };

chan <unsigned 8> ch1, ch2;

unsigned 8 i = 0;
while (1) par
{
while ( 1 ) i ++;
ch1 ! i;
ch2 ! i;
}
Domain 2:
set clock = external with { minperiod=2.0, unconstrainedperiod=10, rate=100
}

extern chan ch1, ch2;

unsigned 8 i, j;

while ( 1 )
{
par {
ch1 ? j;
ch2 ? i;
}
}

Channel communication example

This example uses a channel to communicate between two clock domains. One clock
domain runs at half the speed of the other.

www.celoxica.com Page 171

Handel-C Language Reference Manual

/*
* File: receive.hcc: primary clock domain
*/

set clock = external "A22" with { rate=100, resolutiontime = 7.5 };

unsigned 4 result;
interface bus_out() O(unsigned o = result) with {warn = 0};

//channel defined in other file

extern chan unsigned 4 ReturnData;

void main(void)
{
while(1)
{
delay;
//program will wait until data received
ReturnData ? result;
}
}

/*
* File: transmit.hcc:secondary clock domain,
* running at half the speed of the primary one
*/

set clock = external_divide "R25" 2;

chan unsigned 4 ReturnData; //channel must have global scope

void main(void)
{
static unsigned 4 x;

while(1)
{
x++;
ReturnData ! x;
}
}

www.celoxica.com Page 172

Handel-C Language Reference Manual

Example: channels between clock domains

//File: transmit.hcc
chan 8 c ; // channel must have global scope

set clock = external "P1" with (paranoia =2);

void main(void)
{
int 8 x, y;
c ! x; //program will wait until data successfully transmitted
c ! y;
}

//File: receive.hcc
extern chan c;

set clock = external "P2";

void main(void)
{
int 8 p, q;

c ? p;
c ? q;
}

Managing channel timing

The timing of channels between clock domains is controlled by:

• the number of flip-flops used to resolve metastability (this is set by the

paranoia specification, defaulting to 1)
• the value of resolutiontime (how long it is before you sample a signal
OR
the value of minperiod (how long is available before the signal is moved on)

www.celoxica.com Page 173

Handel-C Language Reference Manual

• the value of unconstrainedperiod. This is the timing constraint on the

compiler generated synchronizing control paths.

tr time to transfer between domains (paranoia in domain B + 1) X tp

tp clock period in domain B

tup unconstrainedperiod

tmp minperiod

Using clock specifications to manage timing between clock domains

You can use clock specifications to specify the timing of the synchronization hardware.
Set the values on a clock to affect the timing of ALL channels to and from that domain.

set clock = external "C43" with {rate = 40, resolutiontime = 20};

This gives a clock period of 25ns. It assumes that 20ns is required for the control signal
to stabilize, leaving 5ns for it to be routed onwards.

RESOLUTION TIME AND PROPAGATION TIME IN ONE CLOCK TICK

www.celoxica.com Page 174

Handel-C Language Reference Manual

If it takes longer for the data to stabilize, you can increase the number of flip-flops used
to stabilize the data by setting the paranoia specification. In this case, the stabilization
time in each clock period is (resolutiontime / paranoia)

If paranoia is set to 3, then the resolution time required in each clock tick is 1/3 the
value of resolutiontime, giving a larger possible value for data to be routed on.

Speed versus metastability

When you increase the paranoia specification on the clock domains, you increase the
latency of channels into the domain. The value of the paranoia specification sets the
number of flip-flops used to give the synchronization data time to stabilize. The higher
the value of paranoia, the more stable the data and the greater the latency.

www.celoxica.com Page 175

Handel-C Language Reference Manual

Setting paranoia to 0 to decrease latency

If you know there is not going to be a metastability problem (e.g, the clock domains you
are working with have a low clock rate or are synchronous with each other), you may
choose to set paranoia to 0. In this case, you must use the minperiod constraint rather
than the resolutiontime constraint.

tr time to transfer between domains (clock period in domain B when

paranoia = 0)

tup unconstrainedperiod

tmp minperiod

Latency between clock domains

The latency of channels between clock domains is unpredictable. It is dependent on:

• the value of resolutiontime

• the value of paranoia
• the value of unconstrainedperiod
For FIFOs whose size is an exact power of two, latency is higher.

In addition, it may be affected by

• the way a channel has been implemented in hardware the sequence of

communications sent across the channel
• the number of clock cycles elapsed since power-up
• environmental factors such as temperature and supply voltage
• the individual FPGA
Program your code so it can deal with variable latency. It is unsafe to rely on a particular
observed latency, either in hardware or in simulation.

www.celoxica.com Page 176

Handel-C Language Reference Manual

2 Do not make assumptions about the latency of cross clock-domain channels

The effect of constraining unconstrained paths

Unconstrained paths are created in the synchronization hardware used to connect
channels across clock domains.

set clock = external "C43" with {rate = 40, unconstrainedperiod = 100,

minperiod=5};
unconstrainedperiod can be given a value to stop place and route tools giving an
unconstrained period warning. If latency is critical in your design, note that as the value
of unconstrainedperiod increases, latency may increase.

Throughput between clock domains using channels

To ensure a throughput of one word per cycle between clock domains, you need to have
a sufficiently large FIFO.

The table below shows the average clock cycles needed to send 1000 words from one
clock domain to another of a similar frequency and back again. It was measured in the
originating domain using timing accurate simulation of a back-annotated netlist.

www.celoxica.com Page 177

Handel-C Language Reference Manual

fifolength paranoia

0 1 2

0 5008 7010 9011

1 5008 7010 9011
2 3009 5011 7012
3 1341 2010 5013
4 1808 2513 4013
5 1510 2155 3215
6 1343 1888 2731
7 1008 1010 2389
8 1102 1443 2269
9 1012 1348 1926
10 1012 1265 1771
11 1012 1192 1634
12 1012 1128 1521
13 1012 1070 1422
14 1012 1010 1354
15 1008 1010 1304
16 1012 1018 1239
17 1012 1018 1188
18 1012 1018 1142
19 1012 1018 1060
20 1012 1018 1060
This demonstrates that timing between different clock domains cannot be predicted
accurately. FIFOs with a length of a power of 2 are slower. Other differences may be
accounted for by layout.

It will not vary widely over different devices and different clock rates.

Synchronization between clock domains

You may use a zero-width channel to convey synchronization information between clock
domains. Sending 0 along a 0 width channel will create the synchronization hardware,
such that subsequent statements will be synchronized.

For example, if you have two statements in different clock domains and you want one to
execute if and only if the other one does then you can do something like:

Domain 1:

www.celoxica.com Page 178

Handel-C Language Reference Manual

chan unsigned 0 ch;

ch!0;
<statement 1>

Domain 2:

extern chan ch;

unsigned 0 junk;
ch?junk;
<statement 2>

In this example, each domain will wait for the other before statement 1 and statement 2
are executed

Using interfaces to communicate between clock domains

If you are using interfaces rather than channels to communicate between hardware
components in separate clock domains, you will need to insert resynchronizing hardware
if it is not included in the components. For example, if data is sent from port_out A in
domain bbA and received from port_in B in domain bbB, the data must be
resynchronized to the clock in domain bbB.

Using interfaces: External resynchronizing example

This example shows the three files required to connect two EDIF blocks (bbA and bbB)
which use different clocks. The small files bbA.hcc and bbB.hcc compile to the EDIF code
using the port_out from and port_in to interfaces. The metastable.hcc file connects
the two together and generates one flip –flop that resynchronizes the data by reading the
value from bbA into a variable.

File: metastable.hcc

www.celoxica.com Page 179

Handel-C Language Reference Manual

/*
* Black box code to resynchronize
* Needs to be clocked from the reading clock
* (i.e. bbB.hcc's clock)
*/

int 1 x;
interface bbA(int 1 from) A();
interface bbB() B(int 1 to=x, unsigned 1 clk = __clock);

set clock = external "P1";

void main(void)
{
while(1)
{
/*
* stabilize the data by adding resynchronization FF
*/
x = A.from;
}
}

File: bbA.hcc

/*
* Domain bbA
* Compiles to bbA.edf
*/
interface port_in(unsigned 1 clk with { clockport = 1 }) clk();
set clock = internal clk.clk;
void main(void)
{
int 1 y;
interface port_out() from (int 1 from = y);
}

File: bbB.hcc

www.celoxica.com Page 180

Handel-C Language Reference Manual

/*
*Domain bbB
* Compiles to bbB.edf
*/

set clock = external "P2";

void main(void)
{
int 1 q;

interface port_in(int 1 to) to();

par
{
while(1)
{
q = to.to; // Read data
}
}
}

Internal resynchronizing example

The resynchronizing flip-flop can be placed in the file that reads the data from the foreign
code block.

This example shows the three files required to connect two EDIF blocks (bbA and bbB)
which use different clocks. The small files bbA.hcc and bbB.hcc compile to the EDIF code
using the port_out from and port_in to interfaces. The toplevel.hcc file connects
them together. The data is resynchronized in the bbB.hcc file.

File: toplevel.hcc

www.celoxica.com Page 181

Handel-C Language Reference Manual

/*
* Code to connect data between two cores
*/

interface bbA(int 1 from) A();

interface bbB() B(int 1 to=A.from);

File: bbA.hcc

/*
* Domain bbA
* Compiles to bbA.edf
*/
set clock = external "P1";
void main(void)
{
int 1 y;
interface port_out() from (int 1 from = y);
}

File: bbB.hcc

/*
*Domain bbB
* Complies to bbB.edf
*/

set clock = external "P2";

void main(void)
{
int 1 q, y;

interface port_in(int 1 to) to();

while(1)
{
par
{
q = to.to; // Resynchronize data
y = q;
}
}
}

www.celoxica.com Page 182

Handel-C Language Reference Manual

9.3.2 Simulating multiple clock domains

You may simulate your design by

• using the DK simulator

• untimed simulation of generated VHDL code
• simulation of back-annotated netlist
Note that as the timing accuracy of the simulation increases, it is harder to relate errors
to the original Handel-C code.

Using the DK simulator

Ï The DK simulator may not simulate the timing of channels between clock
domains identically to that in the generated hardware. You must not rely on
observed latency or timing behaviour in either simulation or hardware.

When you simulate designs with multiple clocks, you will get a Select Clock dialog in the
GUI asking you which clock you want to follow. If you want to synchronize the clocks in a
simulation, use the DKSync.dll plugin.

www.celoxica.com Page 183

Handel-C Language Reference Manual

10 Targeting hardware and simulation

10.1 Interfacing with the simulator

Communication with the simulator takes place over channels. They are declared using
the keywords chanin and chanout. Standard channel communication statements can
then be used to transfer data. It is assumed that channels to and from the simulator
never block and will always complete a transfer in one clock cycle.

Ï Channels to and from the simulator are declared using chanin and chanout
instead of chan.

The special channels chanin and chanout are normally connected to files. Only integer
values can be used as input data, and files connected to chanin must be correctly
formatted. An unconnected channel that outputs data to the simulator will be displayed
in the debug window. You can declare multiple channels for input and output and connect
more than one channel to the same file, but you cannot read from the same channel
more than once in a clock cycle. If the simulation is still running when the end of the file
has been reached, the simulator will read in zeroes.

You cannot use chanin or chanout in a struct. Use pointers to chanin or chanout
instead.

Simple example
chanin unsigned Input with {infile = "../Data/source.dat"};
chanout unsigned Output;

input ? x;
output ! y;

This example declares two channels: one for input from the simulator and one for output
to the simulator. The input channel connects to a file managed by the simulator; the
output channel connects to the simulator's standard output (the debug window in the DK
GUI).

www.celoxica.com Page 184

Handel-C Language Reference Manual

Multiple channel example

chanin int 8 input_1 with
{infile = "../Data/source_1.dat"};
chanin int 16 input_2 with
{infile = "../Data/source_2.dat"};
chanout unsigned 3 output_1;
chanout char output_2;

int 8 a;
int 16 b;

input_1 ? a;
input_2 ? b;
output_1 ! (unsigned 3)(((0 @ a) + b) <- 3);
output_2 ! a;

When simulated, such a program displays the name of channels before outputting their
value on the simulating computer screen.

10.1.1 Simulator input file format

The data input file should have one number per line separated by newline characters
(either DOS or UNIX format text files may be used). Each number may be in any format
normally used for constants by Handel-C. You can only use integer values. Blank lines
are ignored as are lines prefixed by // (comments). For example:

56
0x34
0654
0b001001

//is a comment, blank lines ignored

27

If EOF file is reached while reading an input file, zeroes will be read in until the simulation
completes.

10.1.2 Block data transfers

The Handel-C simulator has the ability to read data from a file and write results to
another file. For example:

www.celoxica.com Page 185

Handel-C Language Reference Manual

chanin int 16 input with {infile = "in.dat"};

chanout int 16 output with {outfile = "out.dat"};

void main (void)

{
while (1)
{
int value;

input ? value;
output ! value+1;
}
}

This program reads data from the file in.dat and writes its results to the file out.dat.
The simulator will open and close the specified files for reading or writing as appropriate.
If EOF file is reached while reading an infile file, zeroes will be read in until the
simulation completes.

If the in.dat file consists of:

56
0x34
0654
0b001001

the out.dat will contain the decimal results as follows:

57
53
429
10

The base specification can be used to write to the outfile in different formats.

Block data transfers allow algorithms to be debugged and tested without needing to build
actual hardware. For example, an image processing application may store a source
image in a file and place its results in a second file. All that need be done outside the
Handel-C compiler is a conversion from the image (e.g. JPEG file) into the text file (which
can then be used by the simulator) and a conversion back from the output file to the
image format. The results can then be viewed and the correct operation of the Handel-C
program confirmed.

10.2 Targeting FPGA and PLD devices

The Handel-C language is designed to target real hardware devices. To do this, you must
supply this information to the compiler:

www.celoxica.com Page 186

Handel-C Language Reference Manual

• the FPGA/PLD family and part that the design will be implemented in
These are supplied on the Chip tab of the Project>Settings dialog. They can also
be specified in the source code using the set family and set part
statements or they can be supplied to the command line using the -f family
and -p part switches. They will be passed to the FPGA/PLD place and route
tool to inform it of the device it should target.
• in some cases, the location of a reset source (required for Actel devices)
The reset source is specified using the set reset command.

Ï Your license may restrict the devices you can target. The devices available to
you are listed in the Family box on the Chip tab in Project Settings.

10.2.1 Summary of supported devices

In order to target a specific FPGA or PLD, the compiler must be supplied with the part
number. Ultimately, this information is passed to the place and route tool to inform it of
the device it should target.

You can specify your target device using the Chip tab on the Project Settings dialog, or
within your source code.Your license may restrict the devices you can target. The devices
available to you are visible in the Family list on the Chip tab.

Recognized families are:

Description On-chip On-chip synchronous

asynchronous RAMs
RAMs
Actel ProASIC series Block RAM, dual- Block RAM, dual-port
FPGAs port

www.celoxica.com Page 187

Handel-C Language Reference Manual

Actel ProASIC+ series Block RAM, dual- Block RAM, dual-port

FPGAs port

Altera Apex 20K series Block RAM (in Block RAM (in ESBs),
PLDs ESBs), dual-port dual-port
Altera Apex 20KE Block RAM (in Block RAM (in ESBs),
series PLDs ESBs), dual port dual port
Altera Apex 20KC Block RAM (in Block RAM (in ESBs),
series PLDs ESBs), dual port dual port
Altera ApexII series Block RAM (in Block RAM (in ESBs),
PLDs ESBs), dual-port dual-port
Altera Cyclone PLDs - M4K dual port RAM
Altera Cyclone II PLDs - M4K dual port RAM
Altera Excalibur ARM Block RAM (in Block RAM (in ESBs),
series PLDs ESBs), dual-port dual-port
Altera Flex10K series Block RAM (in Block RAM (in EABs),
PLDs EABs), dual-port dual-port
Altera Flex10KA series Block RAM (in Block RAM (in EABs),
PLDs EABs), dual-port dual-port
Altera Flex10KB series Block RAM (in Block RAM (in EABs),
PLDs EABs), dual-port dual-port
Altera Flex10KE series Block RAM (in Block RAM (in EABs),
PLDs EABs), dual-port dual-port
Altera Mercury series Block RAM (in Block RAM (in ESBs),
ASSPs ESBs), dual-port, dual-port, quad-port
quad-port
Altera Stratix PLDs - 3 types of dual-port RAM
in TriMatrix blocks
Altera Stratix GX PLDs - 3 types of dual-port RAM
in TriMatrix blocks
Altera Stratix II PLDs - 3 types of dual-port RAM
in TriMatrix blocks

Xilinx Spartan series SelectRAM, dual- -

FPGAs port
Xilinx Spartan-XL SelectRAM, dual- -
series FPGAs port
Xilinx Spartan-II series SelectRAM, dual- Block RAM
FPGAs port
Xilinx Spartan-IIE SelectRAM, dual- Block RAM, dual-port
series FPGAs port

www.celoxica.com Page 188

Handel-C Language Reference Manual

Xilinx Spartan-3 series SelectRAM, dual- Block RAM, dual-port

FPGAs port
Xilinx Spartan-3E SelectRAM, dual- Block RAM, dual-port
series FPGAs port
Xilinx Spartan-3L SelectRAM, dual- Block RAM, dual-port
series FPGAs port
Xilinx Virtex series SelectRAM, dual- Block RAM, dual-port
FPGAs port
Xilinx VirtexE series SelectRAM, dual- Block RAM, dual-port
FPGAs port
Xilinx Virtex-II series SelectRAM, dual- Block RAM, dual-port
FPGAs port

Xilinx Virtex-II Pro SelectRAM, dual- Block RAM, dual-port

series FPGAs port
Xilinx Virtex-II Pro X SelectRAM, dual- Block RAM, dual-port
series FPGAs port
Xilinx Virtex-4 series SelectRAM, dual- Block RAM, dual-port
FPGAs port

"Generic" (VHDL or - -
Verilog projects only.
Results in HDL without
target-specific
constructs.)

10.2.2 Detecting the current device family

The __isfamily construct allows you to detect what the current device family is. If you
are writing platform-independent libraries, you can use this to conditionally select pieces
of the source code to exploit the resources available on different FPGAs.

The construct takes a device string and returns true or false. The possible device names
are the same as those used to specify devices with the set family construct. An error is
returned if the string specified inside the construct is not a recognized family string.

www.celoxica.com Page 189

Handel-C Language Reference Manual

Example
set family = XilinxVirtex;

macro expr DoThis() =

select (__isfamily(XilinxVirtex) : DoThing1() :
select (__isfamily(AlteraApex20K) : DoThing2() :
select (__isfamily(MadeUpDevice) : DoThing3() : DoThing4())
)
);

The first use of __isfamily() would return true, the second would return false, and the
third would result in a compiler error. The source code specified in the DoThing1()
function would be selected.

10.2.3 Targeting specific devices via source code

If you are not using the GUI or the command line to specify the target device, you must
insert lines in the code to specify it. In order to target a specific FPGA or PLD, the
compiler must be supplied with the FPGA part number. Ultimately, this information is
passed to the FPGA/PLD place and route tool to inform it of the device it should target.

Targeting devices is in two parts: specifying the target family and the target device. The
general syntax is:

set family = Family;

set part = Chip Number;

Recognized families are:

www.celoxica.com Page 190

Handel-C Language Reference Manual

Family name Description

Actel500K Actel ProASIC series FPGAs

ActelPA Actel ProASIC+ series FPGAs
AlteraFlex10K Flex10K series Altera PLDs
AlteraFlex10KA Flex10KA series Altera PLDs
AlteraFlex10KB Flex10KB series Altera PLDs
AlteraFlex10KE Flex10KE series Altera PLDs
AlteraApex20K Apex 20K series Altera PLDs
AlteraApex20KE Apex 20KE series Altera PLDs
AlteraApex20KC Apex 20KC series Altera PLDs
AlteraApexII Apex II series PLDs
AlteraMercury Altera Mercury series PLDs
AlteraStratix Altera Stratix PLDs
AlteraStratixII Altera Stratix II PLDs
AlteraStratixGX Altera Stratix GX PLDs
AlteraCyclone Altera Cyclone PLDs
AlteraCycloneII Altera Cyclone II PLDs
AlteraExcaliburARM Altera Excalibur ARM series PLDs

www.celoxica.com Page 191

Handel-C Language Reference Manual

XilinxVirtex Virtex Xilinx FPGAs

XilinxVirtexE VirtexE Xilinx FPGAs
XilinxVirtexII Virtex-II Xilinx FPGAs
XilinxVirtexIIPro Virtex-II Pro Xilinx FPGAs
XilinxVirtexIIProX Virtex-II Pro X Xilinx FPGAs
XilinxVirtex4 Virtex-4 Xilinx FPGAs
XilinxSpartan Spartan Xilinx FPGAs
XilinxSpartanXL Spartan-XL Xilinx FPGAs
XilinxSpartanII Spartan-II Xilinx FPGAs
XilinxSpartanIIE Spartan-IIE Xilinx FPGAs
XilinxSpartan3 Spartan-3 Xilinx FPGAs
XilinxSpartan3E Spartan-3E Xilinx FPGAs
XilinxSpartan3L Spartan-3L Xilinx FPGAs

Ï Your license may restrict the devices you can target. The devices available to
you are visible in the Family list on the Chip tab in Project Settings.

The part string is the complete Actel, Altera or Xilinx device string. For example:

set family = XilinxVirtex;

set part = "V1000BG560-4";

This instructs the compiler to target a v1000 device in a BG560 package. It also specifies
that the device is a -4 speed grade. This last piece of information is required for the
timing analysis of your design by the Xilinx tools.

The family is used to inform the compiler of which special blocks it may generate.

To target Altera Flex 10K devices:

set family = AlteraFlex10K;

set part = "EPF10K20RC240-3";

This instructs the compiler to target an Altera Flex 10K20 device in a RC240 package. It
also specifies that the device is a -3 speed grade. This last piece of information is
required for the timing analysis of your design by the Altera Max Plus II or Quartus tools.
Note that when performing place and route on the resulting design, the device and
package must also be selected via the menus in the Max Plus II or Quartus software.

To target Actel ProASIC devices:

set family = Actel500K;

set part = "A500K270-BG456I";

www.celoxica.com Page 192

Handel-C Language Reference Manual

This instructs the compiler to target an Actel ProASIC device with 270,000 gates in a
BG456 package. It also specifies that the device is a standard speed grade, and that the
device is to be used for an industrial application: the "I" at the end of the part string
specifies that the device is to conform to industrial temperature range standards. The
speed information is required for the timing analysis of your design by the Actel Designer
tools. The application information ("industrial" in this example) is required for place and
route of your design by the Actel Designer tools. Note that when performing place and
route on the resulting design, the device and package must also be selected via the
menus in the Designer software.

10.2.4 Specifying a global reset

set reset allows you to reset your device into a known state at any time. It is
particularly useful for setting up devices which are not in a known state at start up.

set reset causes the program to return to its initial state and resets global and static
variables to their initial values. However, it does not reset any RAMs (distributed or
block). By default, the reset is asynchronous and thus occurs immediately (it does not
wait for the next clock tick.) To make the global reset synchronous, use the synchronous
specification.

Examples
signal unsigned 1 x;
set reset = internal !x; // resets when x is zero

set reset = external "P1"; // resets when signal sent to named pin

set reset = external; // connects to pin, but doesn't specify which

10.3 Use of RAMs and ROMs with Handel-C

Handel-C provides support for:

• interfacing to on-chip and off-chip RAMs and ROMs using the ram and rom
keywords.
• specifying RAMs and ROMs external to the Handel-C code by using the ports
specification keyword.
• controlling the timing for read/write cycles by using specification keywords
that define the relationship between the RAM strobe and the Handel-C clock.

The usual technique for specifying timing in synchronous and asynchronous RAM is to
have a fast external clock which is divided down to provide the Handel-C clock and used
directly to provide the pulses to the RAM.

www.celoxica.com Page 193

Handel-C Language Reference Manual

10.3.1 Asynchronous RAMs

There are three techniques for timing asynchronous RAMs, depending on the clock
available

• Fast external clock. Use the Handel-C westart and welength specifications to
position the write strobe.
• External clock at the same speed as the Handel-C clock. Use multiple reads to
give the RAM enough time to respond.
• Use the wegate specification to position the write enable signal within the
Handel-C clock.

Fast external clock

This method of timing asynchronous RAMs depends on having an external clock that is
faster than the internal clock (i.e. the location of the clock is internal_divide or
external_divide with a division factor greater than 1). If so, Handel-C can generate a
write strobe for the RAM which is positioned within the Handel-C clock cycle. This is done
with the westart and welength specifications. For example:

set clock = external_divide "P78" 4;

ram unsigned 6 x[34] with { westart = 2,
welength = 1 };

The write strobe can be positioned relative to the Handel-C clock cycle by half cycle
lengths of the external (undivided) clock. The above example starts the pulse 2 whole
external clock cycles into the Handel-C clock cycle and gives it a duration of 1 external
clock cycle. Since the external clock is divided by a factor of 4, this is equivalent to a
strobe that starts half way through the internal clock cycle and has a duration of one
quarter of the internal clock cycle. This signal is shown below:

TIMING DIAGRAM: POSITIONED WRITE STROBE

This timing allows half a clock cycle for the RAM set-up time on the address and data
lines and one quarter of a clock cycle for the RAM hold times. This is the recommended
way to access asynchronous RAMs.

www.celoxica.com Page 194

Handel-C Language Reference Manual

Fast external clock example

To declare a 16Kbyte by 8-bit RAM:

set clock = external_divide "P99" 4;

ram unsigned 8 ExtRAM[16384] with {

offchip = 1,
westart = 2,
welength = 1,
data = {"P1", "P2", "P3", "P4",
"P5", "P6", "P7", "P8"},
addr = {"P9", "P10", "P11", "P12",
"P13", "P14", "P15", "P16",
"P17", "P18", "P19", "P20",
"P21", "P22"},
we = {"P23"},
oe = {"P24"},
cs = {"P25"}};

The compiled hardware generates the following cycle for a write to external RAM:

www.celoxica.com Page 195

Handel-C Language Reference Manual

The compiled hardware generates the following cycle for a read from external RAM:

Same rate external clock

This method of timing asynchronous RAMs uses multiple Handel-C RAM accesses to meet
the setup and hold times of the RAM.

ram unsigned 6 x[34];

Dummy = x[3];
x[3] = Data;
Dummy = x[3];

This code holds the address constant around the RAM write cycle, enabling a write to an
asynchronous RAM.

www.celoxica.com Page 196

Handel-C Language Reference Manual

The timing diagram below shows the address being held constant during the write strobe.
It is held constant by the two assignments to Dummy.

Undivided external clock

This method of accessing asynchronous RAMs is a compromise between the other two
methods (fast external clock and multiple RAM accesses). wegate is used with an
undivided external clock and keeps the write strobe in the first or second half of the clock
cycle. It is still necessary to hold the address constant either in the clock cycle before or
in the clock cycle after the access. For example:

ram unsigned 6 x[34] with { wegate = 1 };

x[3] = Data;
Dummy = x[3];

This places the write strobe in the second half of the clock cycle (use a value of -1 to put
it in the first half) and holds the address for the clock cycle after the write. The RAM
therefore has half a clock cycle of set-up time and one clock cycle of hold time on its
address lines.

wegate example
The wegate specification may be used when a divided clock is not available. For
example, to declare a 16Kbyte by 8-bit RAM:

www.celoxica.com Page 197

Handel-C Language Reference Manual

ram unsigned 8 ExtRAM[16384] with {

offchip = 1,
wegate = 1,
data = {"P1", "P2", "P3", "P4",
"P5", "P6", "P7", "P8"},
addr = {"P9", "P10", "P11", "P12",
"P13", "P14", "P15", "P16",
"P17", "P18", "P19", "P20",
"P21", "P22"},
we = {"P23"},
oe = {"P24"},
cs = {"P25"}};

The compiled hardware generates the following cycle for a write to external RAM:

The compiled hardware generates the following cycle for a read from external RAM:

Note that the timing diagram above may violate the hold time for some asynchronous
RAM devices. If the delay between rising clock edge and rising write enable is longer than
the delay between rising clock edge and the change in data or address then corruption in

www.celoxica.com Page 198

Handel-C Language Reference Manual

the write may occur in these devices. The two cycle access does not solve the problem
since it is not possible to hold the data lines constant beyond the end of the clock cycle.
If this causes a problem then a multiplied external clock must be used as described
above.

Ï Using the wegate specification may violate the hold time for some
asynchronous RAM devices.

Targeting external asynchronous RAMs

Handel-C provides support for accessing off-chip static RAMs in the same way as you
access internal RAMs. The syntax for an external RAM declaration is:

ram Type Name[Size] with {

offchip = 1,
data = Pins,
addr = Pins,
we = Pins,
oe = Pins,
cs = Pins};

To declare a 16Kbyte by 8-bit RAM:

ram unsigned 8 ExtRAM[16384] with {
offchip = 1,
data = {"P1", "P2", "P3", "P4",
"P5", "P6", "P7", "P8"},
addr = {"P9", "P10", "P11", "P12",
"P13", "P14", "P15", "P16",
"P17", "P18", "P19", "P20",
"P21", "P22"},
we = {"P23"},
oe = {"P24"},
cs = {"P25"}};

Note that the lists of address and data pins are in the order of most significant to least
significant. It is possible for the compiler to infer the width of the RAM (8 bits in this
example) and the number of address lines used (14 in this example) from the RAM’s
usage. This is not recommended since this declaration deals with real external hardware
which has a fixed definition.

Accessing RAM
Accessing the RAM is the same as for accessing internal RAM. For example:

www.celoxica.com Page 199

Handel-C Language Reference Manual

ExtRAM[1234] = 23;
y = ExtRAM[5678];

Similar restrictions apply as with internal RAM - only one access may be made to the
RAM in any one clock cycle.

The compiled hardware generates the following cycle for a write to external RAM:

The compiled hardware generates the following cycle for a read from external RAM:

This cycle may not be suitable for the RAM device in use. In particular, asynchronous
static RAM may not work with the above cycle due to set-up and hold timing violations.
For this reason, the westart, welength and wegate specifications may also be used with
external RAM declarations.

10.3.2 Synchronous RAMs

SSRAM clocks
Handel-C timing semantics require that any assignment takes one clock cycle. Typically,
SSRAMs have a latency of at least one clock cycle. Therefore, in order for accesses to a

www.celoxica.com Page 200

Handel-C Language Reference Manual

SSRAM device to conform to Handel-C's one-clock-cycle-per-assignment rule, the SSRAM

clock needs to be offset from the Handel-C clock. If the SSRAM has a latency of more
than one clock cycle, its clock needs to be faster than the Handel-C clock, as well as
being offset from it.

This is done by using an independent fast clock (RAMCLK) to match the SSRAM timings
with the Handel-C timing constraints.

A fast external clock (CLK) is divided to provide the Handel-C clock (HCLK), and is also
used to generate pulses to clock the SSRAM, where the pulses can be placed within a
single HCLK cycle. This placed clock is the RAMCLK. It can be carried to an external
SSRAM using the clk specification.

By default, the Handel-C compiler uses an inverted copy of the Handel-C clock to drive
synchronous on-chip memories. This may mean you need to run your design at a lower
clock frequency than you want to. You can increase the efficiency of your design by:

• using pipelined memory accesses, for certain on-chip SSRAMs. This is

illustrated by the Pipelined on-chip SSRAM examples (see page 207), and
the Pipelined on-chip SSRAM timing diagrams (see page 205).
• using the clock position specifications to alter the position of the RAM clock
relative to the Handel-C clock, to enable full memory accesses to be
performed within 1 Handel-C clock cycle. For example, you might want to
advance the write-clock, or delay the read-clock.

This is most suitable for off-chip RAMs, and is illustrated by the Flow-through
SSRAM example (see page 212) and the Pipelining off-chip SSRAM
example (see page 214).

SSRAM devices supported

Handel-C supports ZBT-compatible (Zero Bus Turnaround) flow-through and pipelined
output devices. DDR (double data rate) and QDR (quad data rate) devices are not
supported directly; you can write your own interfaces.

SSRAM write-enable
The Handel-C compiler checks the block and offchip specifications to find out what type
of RAM is being built and generates the appropriate write-enable signal (e.g. active low
for ZBT SSRAM devices and active-high for block RAMs within Xilinx Virtex chips).

www.celoxica.com Page 201

Handel-C Language Reference Manual

SSRAM read and write cycles

The inputs to most inputs to SSRAMs are captured on the rising edge of the input clock.
During a read cycle there is a latency of at least one clock cycle between an address
being captured at the input and data becoming available at the output. This is also true
for the write cycle in many devices: an address is captured on one clock cycle, and data
on the next. A diagram of a typical timing for a read (or write) cycle for an SSRAM device
is shown below.

TIMING DIAGRAM: SSRAM READ AND WRITE

Specifying SSRAM timing

You can place the RAM clock pulses at different points within the Handel-C clock if the
Handel-C clock is divided using external_divide or internal_divide.

If you have a fast undivided clock CLK, a divided clock HCLK, and you want to generate a
RAM clock RAMCLK, the following apply:

• The SSRAM clock (RAMCLK) is generated from the fast clock (CLK) according
to the specifications: rclkpos, wclkpos and clkpulselen. These
specifications can be in whole or half cycles of the external clock (i.e. the
specifications are in multiples of 0.5).
• rclkpos specifies the positions of the clock cycles of clock RAMCLK for a read
cycle. These positions are specified in terms of cycles and half-cycles of CLK,
counting forwards from a HCLK rising edge.
• wclkpos specifies the positions of the clock cycles of RAMCLK for a write cycle.
These are also counted forward from an HCLK rising edge.

www.celoxica.com Page 202

Handel-C Language Reference Manual

• clkpulselen specifies the length of the RAMCLK pulses in CLK cycles. This is
specified once per RAM. It applies to both the read and write clocks.

TIMING DIAGRAM: SSRAM READ CYCLE USING GENERATED RAMCLK

The pulse positions and lengths are specified in cycles and half-cycles of CLK.

The westart and welength specifications are used to place the write enable strobe
where it is required.

Pipelining on-chip SSRAM

By default, the DK compiler uses an inverted version of the main Handel-C clock to drive
on-chip synchronous memories. This allows it to conform to Handel-C's timing semantics
of 1 clock cycle per assignment. But it can potentially halve the maximum clock rate for a
design.

Handel-C can pipeline accesses to on-chip SSRAMs if you write your code in a certain
way. The effect is that the memory is driven by the main (non-inverted) Handel-C clock,
potentially doubling the clock rate for the design, and accesses are performed with 1
clock cycle of latency.

Creating pipelined SSRAM accesses

For memory accesses to be pipelined, the following rules must be satisfied:

• The memory must always be read into an uninitialized register, and nowhere
else.
• Nothing else must write to this register.

For multi-port memories, both rules must be satisfied for every readable port.

If these rules are satisfied, the compiler removes the output register and drives the
memory with the main (non-inverted) Handel-C clock.

www.celoxica.com Page 203

Handel-C Language Reference Manual

You can disable the transform by using the -N-piperam command line switch, or by de-
selecting the Enable memory pipelining transformations box on the Synthesis tab in Project Settings.

The transform is effective for all forms of hardware output. Simulation is not affected.

Devices supporting pipelined on-chip SSRAM

The transform only applies to certain devices and configurations:

Family BlockRAM EAB M512 M4K M-RAM

Actel ProAsic, yes n/a n/a n/a n/a

Actel ProASIC+
Altera Apex20K, n/a yes n/a n/a n/a
Altera Apex20KE,
Altera Apex20KC,
Altera Excalibur ARM,
Altera Mercury
Altera ApexII n/a yes, except n/a n/a n/a
for single-
port RAMs
and true
dual-port
RAMs
Altera Stratix, n/a n/a yes, except yes, except no
Altera StratixGX, for true for single-
dual-port port RAMs
Altera Stratix II RAMs; and true
dual-port
RAMs
Altera Cyclone, n/a n/a no except for no
Altera Cyclone II single-port
RAMs and
true dual-port
RAMs
Xilinx Virtex, no n/a n/a n/a n/a
Xilinx Spartan-II

Xilinx Virtex-II, yes n/a n/a n/a n/a

Xilinx Virtex-II Pro,
Xilinx Spartan-3
Xilinx Spartan-3E
Xilinx Spartan-3L

www.celoxica.com Page 204

Handel-C Language Reference Manual

Pipelined on-chip SSRAM timing diagrams

The timing diagrams below illustrate the difference between pipelined accesses to SSRAM
and non-pipelined accesses. The non-pipelined RAM can be transformed into a pipelined
RAM if the memory is read into an uninitialized register reserved specifically for the use
of the memory.

Non-pipelined access to RAM

3 write cycles are performed:

• At time t0, the rising edge of the main Handel-C clock CLK initiates a write
cycle.
• At event e1, WE is asserted and Addr and Din, are set up, so that when the
memory is next clocked, the data at Din will be written at the location
specified in Addr.
• At time t0.5, the inverted clock rising edge clocks the memory, causing it to
execute the write operation.
• At event e2, after the write operation has completed, the data that has been
written becomes available at the output from the memory Dout.

Two further write cycles are performed, starting at time t1 and t2. This is followed by a
read cycle:

www.celoxica.com Page 205

Handel-C Language Reference Manual

• At time t3, the main Handel-C rising clock edge initiates a read cycle.
• At event e3, WE is de-asserted and Addr is set up, so that when the memory is
next clocked, the location specified at Addr will be read.
• At time t3.5, the inverted clock rising edge clocks the memory, causing it to
execute the read operation.
• At event e4, after the read operation has completed, the data that has been
read becomes available at the output from the memory Dout.
• At time t4, the main Handel-C rising clock edge clocks the data that has been
read from the memory into the pipeline register, as well as initiating the next
read cycle.
• At event e5, after the write-to-register operation has completed, the data that
has been written becomes available at the register output Rout.
• At time t5, the data that was read via the pipeline register (D0 in this case) is
ready to be clocked into its destination.

Two further read cycles are performed, starting at time t4 and t5.

Pipelined access to RAM

3 write cycles are performed:

• At time t0, the main Handel-C rising clock edge initiates a write-cycle.
• At event e1, WE is asserted and Addr and Din are set up, meaning that when
the memory is next clocked, the data at Din will be written at the location
specified in Addr.
• At time t1, the main Handel-C rising clock edge clocks the memory, as well as
initiating the next write cycle.

www.celoxica.com Page 206

Handel-C Language Reference Manual

• At event e2, after the write operation has completed, the data that has been
written becomes available at the output from the memory Dout.

Two further write cycles are performed, starting at time t1 and t2. This is followed by a
read cycle:

• At time t3, the main Handel-C rising clock edge initiates a read cycle.
• At event e3, WE is de-asserted and Addr is set up, meaning that when the
memory is next clocked, the location specified at Addr will be read.
• At time t4, the main Handel-C clock rising edge clocks the memory, as well as
initiating the next read cycle.
• At event e4, after the read operation has completed, the data that has been
read becomes available at the output from the memory Dout.
• At time t5, the data that was read (D0 in this case) is ready to be clocked into
its destination.

Two further read cycles are performed, starting at time t4 and t5.

Effect of performing a pipelining transform

The output from the pipeline register (Rout) in the non-pipelined version and the output
from the memory (Dout) in the pipelined version are equivalent, showing that the
transformation does not change the overall behaviour of the circuit. Valid data is
available from the memory output one whole clock cycle later in the pipelined version,
which is why the transform is only valid when there’s a ‘pipeline’ register.

Pipelined SSRAM examples

The following examples demonstrate how you can pipeline accesses to on-chip
SSRAM (see page 203). If the correct conditions are met, the RAM will use the main
Handel-C clock instead of an inverted clock, and the output register will be removed.

www.celoxica.com Page 207

Handel-C Language Reference Manual

SPRAM Example 1: transform is performed

void main(void)
{
ram unsigned 4 rax[4] with {block = "BlockRAM"};
static unsigned 2 i;
unsigned 4 x; // x is un-initialized
interface bus_in(unsigned 4 i) I();
interface bus_out() O(unsigned 4 o = x);

while(1)
{
rax[i] = I.i;
i++;
x = rax[i]; // RAM only read into x
}
}

SPRAM Example 2: transform is not performed (register is initialized)

void main(void)
{
ram unsigned 4 rax[4] with {block = "BlockRAM"};
static unsigned 2 i;
static unsigned 4 x; // x is initialized to zero
interface bus_in(unsigned 4 i) I();
interface bus_out() O(unsigned 4 o = x);
while(1)
{
rax[i] = I.i;
i++;
x = rax[i]; // RAM only read into x
}
}

www.celoxica.com Page 208

Handel-C Language Reference Manual

SPRAM Example 3: transform is not performed (memory read into two

destinations)
void main(void)
{
ram unsigned 4 rax[4] with {block = "BlockRAM"};
static unsigned 2 i;
unsigned 4 x; // x is un-initialized
unsigned 4 y; // y is un-initialized
interface bus_in(unsigned 4 i) I();
interface bus_out() O(unsigned 4 o = x);
while(1)
{
rax[i] = I.i;
i++;
x = rax[i]; // RAM read into x...
y = rax[i]; // ...but also into y
}
}

SPRAM Example 4: transform is not performed (pipeline register written to from

elsewhere)
void main(void)
{
ram unsigned 4 rax[4] with {block = "BlockRAM"};
static unsigned 2 i;
unsigned 4 x; // x is un-initialized
interface bus_in(unsigned 4 i) I();
interface bus_out() O(unsigned 4 o = x);
while(1)
{
rax[i] = I.i;
i++;
x = rax[i]; // RAM only read into x...
x = 1; // ...but x also written to from elsewhere
}
}

www.celoxica.com Page 209

Handel-C Language Reference Manual

MPRAM Example 1: transform is performed

void main(void)
{
mpram
{
ram unsigned 4 rax1[4];
ram unsigned 4 rax2[4];
} max with {block=1};
static unsigned 2 i1, i2;
unsigned 4 x; // x is un-initialized
unsigned 4 y; // y is un-initialized
interface bus_in(unsigned 4 i1) I1();
interface bus_out() O1(unsigned 4 o1 = x);
interface bus_in(unsigned 4 i2) I2();
interface bus_out() O2(unsigned 4 o2 = y);
while(1)
{
max.rax1[i1] = I1.i1;
max.rax2[i2] = I2.i2;
i1++;
i2++;
x = max.rax1[i1]; // mpram port rax1 only read into x
y = max.rax2[i2]; // mpram port rax2 only read into y
}
}

www.celoxica.com Page 210

Handel-C Language Reference Manual

MPRAM Example 2: transform is not performed (port ‘rax2’ does not read into a
register)
void main(void)
{
mpram
{
ram unsigned 4 rax1[4];
ram unsigned 4 rax2[4];
} max with {block=1};
static unsigned 2 i1, i2;
unsigned 4 x; // x is un-initialized
interface bus_in(unsigned 4 i1) I1();
interface bus_out() O1(unsigned 4 o1 = x);
interface bus_in(unsigned 4 i2) I2();
// port rax2 read directly into an interface, not a ‘pipeline’ register
interface bus_out() O2(unsigned 4 o2 = max.rax2[i2]);

while(1)
{
max.rax1[i1] = I1.i1;
max.rax2[i2] = I2.i2;
i1++;
i2++;
x = max.rax1[i1]; // mpram port rax1 only read into x...
}
}

Targeting external synchronous RAMs

Off-chip synchronous SRAMs can be specified in exactly the same way as on-chip
synchronous SRAMs, with the addition of the rclkpos, wclkpos, clkpulselen and clk
specifications. clk specifies the pin on which the generated RAMCLK will appear, when
the SSRAM in question is external (offchip = 1).

www.celoxica.com Page 211

Handel-C Language Reference Manual

Example
macro expr addressPins = {Pin List...};
macro expr dataPins = {Pin List...};
macro expr csPins = {Pin List...};
macro expr wePins = {Pin List...};
macro expr oePins = {Pin List...};
macro expr clkPins = {Pin List...};

ram unsigned 32 ExtBank[1024] with {offchip = 1,

addr = addressPins,
data = dataPins,
cs = csPins,
we = wePins,
oe = oePins,
westart = 2,
welength = 1,
rclkpos = {1.5, 2.5},
wclkpos = {1.5, 2.5, 3.5},
clkpulselen = 0.5,
clk = clkPins};

Flow-through SSRAM example

ram unsigned 18 FlowBank[1024]
with {block = 1,
westart = 2,
welength = 1,
rclkpos = {1.5},
wclkpos = {2.5, 3.5},
clkpulselen = 0.5};

This code instructs the compiler to build hardware to generate SSRAM control signals as
shown below. It is also applicable for reading from block RAMs in Actel and Xilinx FPGAs
and Altera ESB and tri-matrix memories.

www.celoxica.com Page 212

Handel-C Language Reference Manual

Read cycle for a flow-through SSRAM

The timing diagram shows a read-cycle from a flow-through SSRAM.

The rising HCLK edge at t0 initiates the read cycle. Some time later, the address A1 is
set up, which is sampled somewhere in the middle of the HCLK cycle: t0+1.5 in this case.
By the time the next HCLK rising edge occurs at t1, the data is available for reading. The
cycle completes within one Handel-C clock cycle.

Write cycle for a flow-through SSRAM

Flow-through SSRAMs perform a "late" write cycle; the data is clocked in one clock cycle
after the address is sampled.

The timing diagram shows the complete write cycle.

www.celoxica.com Page 213

Handel-C Language Reference Manual

The HCLK rising edge at t0 initiates the write cycle, causing the ADDRESS and DATAIN
signals to change. Two cycles of RAMCLK are needed to clock the new data into the RAM
at the specified address: the first to sample the address, the second to sample the data.
However, since we’re not expecting to read from the RAM’s output, we can wait until the
last possible moment. In this case, the two rising edges of RAMCLK occur at t0+2.5 and
t0+3.5.

The write enable signal must be low during the rising edge of RAMCLK that samples the
address, but not during the one that samples the data. This can be done by setting
westart and welength as shown. The entire cycle completes within a single Handel-C
clock cycle.

Pipelining off-chip SSRAM example

This method of pipelining SSRAM is most suitable for off-chip RAMs. For on-chip SSRAM,
it is usually more efficient to use a pipelining transformation.

ram unsigned 18 PipeBank[1024]

with {block = 1,
westart = 1.5,
welength = 1,
rclkpos = {1.5, 2.5},
wclkpos = {1.5, 2.5, 3.5},
clkpulselen = 0.5};

www.celoxica.com Page 214

Handel-C Language Reference Manual

Read cycle for a pipelined-output SSRAM

The timing diagram shows the read cycle

This read cycle is very similar to that for a flow through RAM. The rising HCLK edge at t0
initiates the read cycle. Some time later, the address A1 is set up, which is sampled
somewhere near the middle of the HCLK cycle: (t0+1.5 in this case). The RAM contents
at address A1 are then piped to the RAM’s output register; it must be made available at
the RAM output. A second RAMCLK pulse (at t0+2.5 in this case) is used to do this. By
the time the next HCLK rising edge occurs at t1, the data is available for reading by the
Handel-C design. The cycle completes within one Handel-C clock cycle.

Write cycle for a pipelined-output SSRAM

Pipelined-output SSRAMs perform a "late-late" write cycle. This means that data is
written to memory two clock cycles after the address is sampled.

www.celoxica.com Page 215

Handel-C Language Reference Manual

The timing diagram shows the complete cycle.

The HCLK rising edge at t0 initiates the write cycle, causing the ADDRESS and DATAIN
signals to change. Three cycles of RAMCLK are needed to clock the new data into the
RAM at the specified address: the first to sample the address and the third to sample the
data. Since you will not read from the RAM on a write strobe, you can sample the data as
late as possible to give the circuit maximum time to set up the data. In this case, the
three rising edges of RAMCLK occur at t0+1.5, t0+2.5 and t0+3.5.

The write enable signal must be low during the rising edge of RAMCLK that samples the
address, but not during the one that samples the data. This can be done by setting
westart and welength as shown. The entire cycle completes within a single Handel-C
clock cycle.

10.3.3 Targeting Stratix and Cyclone memory blocks

Altera Stratix, Stratix GX and Stratix II devices have 3 types of embedded memory:
M512, M4K and M-RAM. Cyclone and Cyclone II devices only have M4K. You can specify
what type of memory you want to build by using the block specification.

Type of block specification

memory
M512 with {block = "M512"}

M4K with {block = "M4K"}

M-RAM with {block = "M-RAM"}

www.celoxica.com Page 216

Handel-C Language Reference Manual

If you do not use the block specification the memory is set to "AUTO" and Quartus
determines the most appropriate memory type when you place and route.

All Stratix memories are fully synchronous. If you try to make them asynchronous, for
example by using the westart and welength specifications, you will get a compiler error.

M-RAM cannot be initialized. This means that you cannot have a ROM built out of M-RAM.
You will get a compiler error if you build a ROM using the with {block = "M-RAM"}
specification.

M512 memory cannot be configured as a bi-directional dual-port MPRAM. If you try to

create this, the compiler will issue a warning.

Example
set family = AlteraStratix;
set part = "EP1S10B672C7";
set clock = external;

ram unsigned 8 autoRam[16]; // Let Quartus select a suitable memory

structure
ram unsigned 8 m512Ram[16] with {block = "M512"}; // Use M512 blocks
ram unsigned 8 m4kRam[16] with {block = "M4K"}; // Use M4K blocks
ram unsigned 8 mRam[16] with {block = "M-RAM"}; // Use M-RAM blocks

void main(void)
{
autoRam[0] = 1;
m512Ram[0] = 1;
m4kRam[0] = 1;
mRam[0] = 1;

...etc...
}

10.3.4 Using on-chip RAMs in Actel devices

On-chip RAMs in Actel ProASIC and ProASIC+ devices use the embedded memory
structures, which are of a fixed width and depth. These blocks can be combined to create
deeper and wider memory spaces. When writing Handel-C programs, you must be careful
not to exceed the number of memory blocks in the target device or the design will not
place and route successfully. It is possible to use RAMs that do not match one of the
width/depth combinations, but memory space may be wasted.

www.celoxica.com Page 217

Handel-C Language Reference Manual

Synchronous and asynchronous access

Memory blocks in ProASIC and ProASIC+ parts can be configured to be either
synchronous or asynchronous. If you do not apply any clock or write-enable
specifications, Handel-C will create RAMs with a synchronous write port and
asynchronous read port.

If you apply clock position specifications to the RAM, the read and write ports will both be
synchronous.

If you apply any of the write-enable specifications (westart, welength or wegate) to the
RAM, both write and read access will be asynchronous.

When declaring a memory as a MPRAM, if you only apply write-enable specifications to

the read port AND you apply clock specifications to the write port, you will get a compiler
error, as you cannot have an asynchronous write port and a synchronous read port.

Initialization
Actel memories may not be initialized.

10.3.5 Using on-chip RAMs in Altera devices

EAB structures
On-chip RAMs in Altera Flex10K devices use the EAB structures. These blocks can be
configured in a number of data width/address width combinations. When writing Handel-
C programs, you must be careful not to exceed the number of EAB blocks in the target
device or the design will not place and route successfully. While it is possible to use RAMs
that do not match one of the data width/address width combinations, EAB space may be
wasted by such a RAM.

Synchronous and asynchronous access

RAM blocks in Flex, Apex, Excalibur and Mercury parts can be configured to be either
synchronous or asynchronous. If you do not apply any clock or write-enable
specifications, Handel-C will create RAMs with a synchronous write port and
asynchronous read port as long as the target hardware supports it.

If you apply clock position specifications to the RAM, the read and write ports will both be
synchronous.

If you apply any of the write-enable specifications (westart, welength or wegate) to the
RAM, both write and read access will be asynchronous.

When declaring a memory as a MPRAM, if you only apply write-enable specifications to

the read port AND you apply clock specifications to the write port, you will get a compiler
error, as you cannot have an asynchronous write port and a synchronous read port.

www.celoxica.com Page 218

Handel-C Language Reference Manual

Initialization
RAM/ROM initialization files with a .mif extension will be generated on compilation to
feed into the Max Plus II or Quartus software. This process is transparent if they are in
the same directory as the EDIF (.edf extension) file generated by the Handel-C compiler.

Creating RAMs without an inverted clock

If you declare a single-port RAM for Altera Flex, Apex 20, Mercury or Excalibur devices,
the Handel-C compiler converts this into an MPRAM with a ROM port and a WOM port.
This removes the inverted clock, and so increases the possible clock rate. If you want to
remove the inverted clock from an on-chip memory on an ApexII device, you need to do
this manually by creating an MPRAM instead of a RAM. The compiler does not do this
automatically as the hardware created for an MPRAM is larger than that for a RAM on
ApexII devices.

Stratix and Cyclone memories are totally synchronous, so creating an MPRAM with a ROM
and a WOM port does not automatically result in the inverted clock being removed.
Instead, you can pipeline the MPRAM, or you can customize the clock using the rclkpos,
wclkpos and clkpulselen specifications.

10.3.6 Using on-chip RAMs in Xilinx devices

Handel-C supports the synchronous RAMs on Virtex series and Spartan-II and Spartan-3
parts directly simply by declaring a RAM or ROM. For example:

ram unsigned 6 x[34];

This will declare a RAM with 34 entries, each of which is 6 bits wide.

When writing Handel-C programs, you must be careful not to exceed the number of
memory blocks in the target device or the design will not place and route successfully.

10.3.7 Using external ROMs

An external ROM is declared as an external RAM with an empty write enable pin list. For
example:

www.celoxica.com Page 219

Handel-C Language Reference Manual

ram unsigned 8 ExtROM[16384] with {

offchip = 1,
data = {"P1", "P2", "P3", "P4",
"P5", "P6", "P7", "P8"},
addr = {"P9", "P10", "P11", "P12",
"P13", "P14", "P15", "P16",
"P17", "P18", "P19", "P20",
"P21", "P22"},
we = {},
oe = {"P24"},
cs = {"P25"}};

Note that no westart, welength or wegate specification is required since there is no

write strobe signal on a ROM device.

10.3.8 Connecting to RAMs in foreign code

You can create ports to connect to a RAM by using the ports = 1 specification to your
memory definition. This will generate VHDL, Verilog or EDIF wires which can be
connected to a component created elsewhere. The ports specification cannot be used in
conjunction with the offchip=1 specification, but all other specifications will apply.

The interface generated will have separate read (output) and write (data) ports, write
enable, data enable and clock wires. This ensures that it can be connected to any device.
Pin names provided in the addr, data, cs, we, oe, and clk specifications will be
passed through to the generated EDIF. They are not passed through to VHDL or Verilog,
since VHDL and Verilog interfaces are generated as n-bit wide buses rather than n 1-bit
wide wires. This means that it is ambiguous to specify a separate identifier for each wire.
If they are used when compiling to VHDL or Verilog, the compiler issues a warning.

For VHDL or Verilog output, the compiler generates meaningful port names. For example,
with the following RAM declaration compiled to VHDL:

ram unsigned 4 rax[4] with

{ports = 1, data = dataPins, addr = addrPins,
we = wePins, cs = csPins, oe = oePins};

the compiler will warn that all the pins specifications have been ignored, and will
generate an interface in VHDL with the following ports:

www.celoxica.com Page 220

Handel-C Language Reference Manual

component rax_SPPort
port(
rax_SPPort_addr: in unsigned(1 downto 0);
rax_SPPort_clk: in std_logic;
rax_SPPort_cs: in std_logic;
rax_SPPort_data_en: in std_logic;
rax_SPPort_data_in: out unsigned(3 downto 0);
rax_SPPort_data_out: in unsigned(3 downto 0);
rax_SPPort_oe: in std_logic;
rax_SPPort_we: in std_logic
);

The port names consist of the memory name (rax in this case), description of the
memory type (SPPort : single port in this case) and an identifier describing the ports
function.

A clock port will always be generated.

If you use the ports specification with an MPRAM, a separate interface will be generated
for each port.

Generating an interface to a foreign code RAM

set family = XilinxVirtex;
set part = "V1000BG560-4";
set clock = external "C1";

unsigned 4 a;
ram unsigned 4 rax[4] with {ports = 1};

void main(void)
{
static unsigned 2 i = 0;

while(1)
{
par
{
i++;
a++;
rax[i] = a;
}
a = rax[i];
}
}

www.celoxica.com Page 221

Handel-C Language Reference Manual

The declaration of rax would produce wires

rax_SPPort_addr<0> // Address
rax_SPPort_addr<1>
rax_SPPort_data_in<0> // Data In
rax_SPPort_data_in<1>
rax_SPPort_data_in<2>
rax_SPPort_data_in<3>
rax_SPPort_data_out<0> // Data Out
rax_SPPort_data_out<1>
rax_SPPort_data_out<2>
rax_SPPort_data_out<3>
rax_SPPort_data_en // Data Enable
rax_SPPort_clk // Clock
rax_SPPort_cs // Chip Select
rax_SPPort_oe // Output Enable
rax_SPPort_we // Write Enable

www.celoxica.com Page 222

Handel-C Language Reference Manual

Generating an interface to a foreign code MPRAM

set family = XilinxVirtex;
set part = "V1000BG560-4";
set clock = external "C1";

unsigned 4 a;

mpram Mpaz
{
wom unsigned 4 wox[4];
rom unsigned 4 rox[4];
} mox with {ports = 1};

void main(void)
{
static unsigned 2 i = 0;

while(1)
{
par
{
i++;
a++;
mox.wox[i] = a;
}
a = mox.rox[i];
}
}

The declaration of the read only port rox would produce wires

mox_rox_addr_0 // Address
mox_rox_addr_1
mox_rox_clk // Clock
mox_rox_cs // Chip select
mox_rox_data_en // Data enable
mox_rox_oe // Output enable
mox_rox_we // Write enable
mox_rox_data_in_0 // Data into Handel-C, out from foreign code memory
mox_rox_data_in_1
mox_rox_data_in_2
mox_rox_data_in_3

The declaration of the read only port wox would produce wires

www.celoxica.com Page 223

Handel-C Language Reference Manual

mox_wox_addr_0 // Address
mox_wox_addr_1
mox_wox_clk // Clock
mox_wox_cs // Chip select
mox_wox_data_en // Data enable
mox_wox_data_out_0 // Data out from Handel-C, into foreign code memory
mox_wox_data_out_1
mox_wox_data_out_2
mox_wox_data_out_3
mox_wox_oe // Output enable
mox_wox_we // Write enable

10.3.9 Using other RAMs

The interface to other types of RAM such as DRAM should be written by hand using
interface declarations. Macro procedures can then be written to perform complex or even
multi-cycle accesses to the external device.

www.celoxica.com Page 224

Handel-C Language Reference Manual

11 Interfacing with external hardware

All off-chip accesses are based on the idea of a bus which is just a collection of external
pins. Handel-C provides the ability to read the state of pins for input from the outside
world and set the state of pins for writing to the outside world. Tri-state buses are also
supported to allow bi-directional data transfers through the same pins.

The pins used may be defined in Handel-C by using pin specifications (e.g. data). If this
is omitted, the pins will be left unconstrained and can be assigned by the place and route
tools.

Note that Handel-C provides no information about the timing of the change of state of a
signal within a Handel-C clock cycle. Timing analysis is available from the FPGA or PLD
manufacturer's place-and-route tools.

Handel-C programs can also interface to external logic (other Handel-C programs,
programs written in VHDL or Verilog etc.) by using user-defined interfaces or Handel-C
ports.

Ï Your license may not allow you to use interfaces. If this is the case you can
only interface to external devices using macros provided in any Celoxica
libraries you have licenses for, such as PAL.

11.1 Interface sorts

Handel-C provides a number of predefined interface sorts.

"bus-type" interfaces (bus_*) generate the hardware for buses connected to pins.

"port-type" interfaces (port_*) generate the hardware for floating ports (buses which
are not connected to pins).

These can be of any width, and can carry signals between different sections of Handel-C
code, or to software or hardware beyond the Handel-C program.

You can also define your own sorts to interface to external blocks of code ("generic" or
custom interface sorts).

www.celoxica.com Page 225

Handel-C Language Reference Manual

Predefined interface sorts

Sort identifier Description

bus_in Input bus from pins

bus_latch_in Registered input bus from pins
bus_clock_in Clocked input bus from pins
bus_out Output bus to pins
bus_ts Bi-directional tri-state bus
bus_ts_latch_in Bi-directional tri-state bus with
registered input
bus_ts_clock_in Bi-directional tri-state bus with
clocked input
port_in Input port from logic
port_out Output port to logic

Custom or generic interface sorts

You can define your own interface sorts to connect to non-Handel-C objects:

• Hardware descriptions written in another language.

VHDL, Verilog and EDIF are currently supported. For a VHDL code interface,
the interface sort would be the name of the VHDL entity. For a Verilog code
interface, the interface sort would be the name of the Verilog module.

• Native PC object code used in simulation.

Programs that run on your PC for simulation and connect to a Handel-C
interface are known as plugins. There are special port specifications to enable
you to connect user-defined interfaces with a plugin for simulation. These are
extlib, extfunc, and extinst.

11.1.1 Reading from external pins bus_in

The bus_in interface sort allows Handel-C programs to read from external pins. Its
general usage is:

interface bus_in(type portName)

Name()
with {data = {Pin List}};

Reading the bus is performed by accessing the identifier Name.portName as a variable

which will return the value on those pins at that clock edge. If no input port name is
given, the port name defaults to in.

www.celoxica.com Page 226

Handel-C Language Reference Manual

Example
interface bus_in(int 4 To) InBus()
with {data = {"P4", "P3", "P2", "P1"}};
int 4 x;

x = InBus.To;

This declares a bus connected to pins P1, P2, P3 and P4 where pin P4 is the most
significant bit and pin P3 is the least significant bit.

The variable x is set to the value on the external pins. The type of InBus.To is int 4 as
specified in the type list after the bus_in keyword.

11.1.2 Registered reading from external pins: bus_latch_in

The bus_latch_in interface sort is similar to bus_in but allows the input to be registered
on a condition. This may be required to sample the signal at particular times. Its general
usage is:

interface bus_latch_in(type portName)

Name(type conditionPortName=Condition)
with {data = {Pin List}};

Reading the bus is performed by accessing the identifier Name.portName as a variable

which will return the value on those pins at that clock edge. If no input port name is
given, the port name defaults to in. Condition specifies a signal that is used to clock the
input registers in the FPGA or PLD. The rising edge of this signal clocks the external
signal into the internal value.

Example
unsigned 1 get;
int 4 x;

interface bus_latch_in(int 4 To)

InBus(unsigned 1 condition = get)
with {data = {"P4", "P3", "P2", "P1"}};

get = 0;
get = 1; // Register the external value
x = InBus.To; // Read the registered value

www.celoxica.com Page 227

Handel-C Language Reference Manual

11.1.3 Clocked reading from external pins: bus_clock_in

The bus_clock_in interface sort is similar to the bus_in interface sort but allows the
input to be clocked continuously from the Handel-C global clock. This may be required to
synchronize the signal to the Handel-C clock. Its general usage is:

interface bus_clock_in(type portName) Name()

with {Specs};

Reading the bus is performed by accessing the identifier Name.portName as a variable

which will return the value on those pins at that clock edge. If no input port name is
given, the port name defaults to in. The rising edge of the Handel-C clock clocks the
external signal into the internal value. For example:

interface bus_clock_in(int 4 InTo) InBus() with

{data = {"P4", "P3", "P2", "P1"}};

x = InBus.InTo; // Read flip-flop value

11.1.4 Writing to external pins: bus_out

The bus_out interface sort allows Handel-C programs to write to external pins. Its
general usage is:

interface bus_out()
Name(type portName=Expression)
with {data = {Pin List}};

A specific example is:

interface bus_out () OutBus(int 4 OutPort=x+y)

with {data = {"P4", "P3", "P2", "P1"}};

This declares a bus connected to pins 1, 2, 3 and 4 where pin 4 is the most significant bit
and pin 1 is the least significant bit. The value appearing on the external pins is the value
of the expression x+y at all times.

11.1.5 Bidirectional data transfer: bus_ts

The bus_ts interface sort allows Handel-C programs to perform bi-directional off-chip
communications via external pins. Its general usage is:

www.celoxica.com Page 228

Handel-C Language Reference Manual

interface bus_ts (type inPortName)

Name(type outPortName = Value,
type conditionPortName = Condition)
with {Specs};
Value is an expression giving the value to output on the pins. Condition is an
expression giving the condition for driving the pins. When Condition is non-zero (i.e.
true), the value of Value is driven on the pins. When the value of Condition is zero, the
pins are tri-stated and the value of the external bus can be read using the identifier
Name. inPortName. If inPortName is not defined, the port name defaults to in.

If you attempt to read from a tri-state bus when it is in write mode (i.e. condition is non-
zero), you will get the value that you are writing to the bus.

Example
unsigned 1 condition;
int 4 x;

interface bus_ts(int 4 read)

BiBus(int write=x+1,
unsigned 1 enable= condition)
with {data = {"P4", "P3", "P2", "P1"}};

condition = 0; // Tri-state the pins

x = BiBus.read; // Read the value
condition = 1; // Drive x+1 onto the pins

This example reads the value of the external bus into variable x and then drives the
value of x + 1 onto the external pins.

2 Take care when driving tri-state buses that the FPGA/PLD and another device
on the bus cannot drive simultaneously as this may result in damage to one or
both of them.

11.1.6 Bidirectional data transfer with registered input:

bus_ts_latch_in

The bus_ts_latch_in interface sort allows Handel-C programs to perform bidirectional

off-chip communications via external pins with inputs registered on a condition. Its
general usage is:

www.celoxica.com Page 229

Handel-C Language Reference Manual

interface bus_ts_latch_in (type inPortName)

Name(type outPortName = Value,
type conditionPortName = Condition,
type clockPortName = Clock)
with {Specs};

Value is an expression giving the value to output on the pins. Condition is an

expression giving the condition for driving the pins. Clock is an expression giving the
signal to clock the input from the pins. When Condition is non-zero (i.e. true), the value
of Value is driven on the pins. When the value of Condition is zero, the pins are tri-
stated and the registered value of the external bus can be read using the identifier Name.
inPortName. If inPortName is not defined, the port name defaults to in.

The rising edge of the value of the third expression clocks the external values through to
the internal values on the chip.

If you attempt to read from a tri-state bus when it is in write mode (i.e. condition is non-
zero), you will get the value that you are writing to the bus.

Example
int 1 get;
unsigned 1 condition;
int 4 x;

interface bus_ts_latch_in(int 4 read)

BiBus(int write = x+1,
unsigned 1 enable = condition,
unsigned 1 clock_port = get)
with {data = {"P4", "P3", "P2", "P1"}};

condition = 0; // Tri-state external pins

get = 0;
get = 1; // Register external value
x = BiBus.read; // Read registered value
condition = 1; // Drive x+1 onto external pins

This example samples the external bus and reads the registered value into variable x and
then drives the value of x + 1 onto the external pins.

2 Take care when driving tri-state buses that the FPGA/PLD and another device
on the bus cannot drive simultaneously as this may result in damage to one or
both of them.

www.celoxica.com Page 230

Handel-C Language Reference Manual

11.1.7 Bidirectional data transfer with clocked input:

bus_ts_clock_in

The bus_ts_clock_in interface sort allows Handel-C programs to perform bidirectional

off-chip communications via external pins with inputs clocked continuously with the
Handel-C clock. Its general usage is:

interface bus_ts_clock_in (type inPortName)

Name(type outPortName = Value,
type conditionPortName = Condition)
with {Specs};

Value is an expression giving the value to output on the pins. Condition is an

expression giving the condition for driving the pins. When Condition is non-zero (i.e.
true), the value of Value is driven on the pins. When the value of Condition is zero, the
pins are tri-stated and the value of the external bus can be read using the identifier
Name. inPortName. If inPortName is not defined, the port name defaults to in.

If you attempt to read from a tri-state bus when it is in write mode (i.e. condition is non-
zero), you will get the value that you are writing to the bus.

The rising edge of the Handel-C clock reads the external values into the internal flip-flops
on the chip. For example:

unsigned 1 condition;
int 4 x;

interface bus_ts_clock_in (int 4 read)

BiBus(int 4 writePort=x+1,
unsigned 1 enable=condition)
with {data = {"P4", "P3", "P2", "P1"}};

condition = 0; // Tri-state external pins

x = BiBus.read; // Read registered value
condition = 1; // Drive x+1 onto external pins

This example reads the value from the flip-flop into variable x and then drives the value
of x + 1 onto the external pins.

2 Take care when driving tri-state buses that the FPGA/PLD and another device
on the bus cannot drive simultaneously as this may result in damage to one or
both of them.

www.celoxica.com Page 231

Handel-C Language Reference Manual

11.1.8 Example hardware interface

The example shows the use of buses. The scenario is of an external device connected to
the FPGA/PLD which may be read from or written to. The device has a number of signals
connected to the FPGA/PLD.

Signals connected

Signal FPGA pin Description

Name

D3..0 1, 2, 3, 4 Data Bus

Write 5 Write strobe
Read 6 Read strobe
WriteRdy 7 Able to write to device
ReadRdy 8 Able to read from device

Read cycle timing

A read from the device is performed by waiting for ReadRdy to become active (high). The
Read signal is then taken high for one clock cycle and the data sampled on the falling
edge of the strobe.

www.celoxica.com Page 232

Handel-C Language Reference Manual

Write cycle timing

A write to the device is performed by waiting for WriteRdy to become active (high). The
Write signal is then taken high for one clock cycle while the data is driven to the device
by the FPGA. The device samples the data on the falling edge of the Write signal.

Bus declarations
The first stage of the code declares the buses associated with each of the external
signals.

int 4 Data;
int 1 En = 0;
interface bus_ts_clock_in(int 4 DataIn)
dataB(int outPort=Data, int EnableSignal=En) with
{data = {"P4", "P3", "P2", "P1"}};

int 1 Write = 0;
interface bus_out() writeB(int WriteSignal = Write) with
{data = {"P5"}};

int 1 Read = 0;
interface bus_out() readB(int readSignal=Read) with
{data = {"P6"}};

interface bus_clock_in(int 1 wr)

WriteReady() with {data = {"P7"}};

interface bus_clock_in(int 1 readySignal)

ReadReady() with {data = {"P8"}};

www.celoxica.com Page 233

Handel-C Language Reference Manual

void main (void)

{
int 4 Data, Reg;

// Read word from external device

while (ReadReady.readySignal == 0)
delay;

Read = 1; // Set the read strobe

par
{
Data = dataB.DataIn; // Read the bus
Read = 0; // Clear the read strobe
}

// Write one word back to external device

Reg = Data + 1;
while (WriteReady.wr == 0)
delay;

par
{
En = 1; // Drive the bus
Write = 1; // Set the write strobe
}

Write = 0; // Clear the write strobe

En = 0; // Stop driving the bus
}

Writing data
You can change the values on the output buses by setting the values of the Data, Write
and Read variables. You can drive the data bus with the contents of Data by setting En
to 1.

The variables that drive buses have been initialized to 0. That means that these variables
must be static or global. This may be important when driving write strobes. Care should
be taken during configuration that the FPGA pins are disconnected in some way from the
external devices because the FPGA pins become tri-state during this time.

The main program

The main program reads a word from the external device before writing one word back.

www.celoxica.com Page 234

Handel-C Language Reference Manual

void main (void)

{
int 4 Data, Reg;

// Read word from external device

while (ReadReady.readySignal == 0)
delay;
Read = 1; // Set the read strobe
par
{
Data = dataB.DataIn; // Read the bus
Read = 0; // Clear the read strobe
}

// Write one word back to external device

Reg = Data + 1;
while (WriteReady.wr == 0)
delay;
par
{
En = 1; // Drive the bus
Write = 1; // Set the write strobe
}
Write = 0; // Clear the write strobe
En = 0; // Stop driving the bus
}

Note that during the write phase, the data bus is driven for one clock cycle after the write
strobe goes low to ensure that the data is stable across the falling edge of the strobe.

11.2 Simulating interfaces

You can combine the hardware and simulation versions of your program by using the
#ifdef construct. For example:

www.celoxica.com Page 235

Handel-C Language Reference Manual

#define SIMULATE

#ifdef SIMULATE
{
...
}
#else
{
...
}
#endif

There are several ways to simulate the reading and writing of data across an interface.

Bus-type and port-type interfaces

If you have a bus-type interface or a port-type interface (port_in or port_out) you can
use the infile and outfile specifications to read and write data. (Bus-type interfaces
are bus_in, bus_latch_in, bus_clock_in, bus_out, bus_ts, bus_ts_latch_in and
bus_ts_clock_in).

For example:

set clock = external "P1";

unsigned 8 out;
interface port_in(unsigned 8 i) pi() with {infile = "in.txt"};
interface port_out() po(out) with {outfile = "out.txt"};
void main (void)
{
do
{
out = pi.i;
}while(out != 0);
}

infile and outfile can only connect to files with data in a simple format. If your data is
more complex, you could write a C/C++ function and call it to bring in the data.

If you want to model the hardware as well as the functionality of your design, you will
need to co-simulate your interface with a model of the component to which it will be
connected (see below).

Generic interfaces
If you have written a custom (generic) interface, you will need to co-simulate the
interface with a model of the component to which it will be connected in hardware. If you
write the model in Handel-C, you can co-simulate it with your Handel-C interface using

www.celoxica.com Page 236

Handel-C Language Reference Manual

dkconnect.dll. To synchronize the simulations, use dksync.dll. If your model is in

VHDL or Verilog, you can co-simulate it with your Handel-C design using the Co-
simulation Bridge for ModelSim provided in the Platform Developer's Kit.

11.3 Buses and the simulator

The Handel-C simulator cannot simulate buses directly, because the simulation of buses
cannot determine when input and output should occur. The recommended process for
debugging is:

For simple data, use a channel or a chanin/chanout to connect to a file. This is the
simplest method.

For more complex buses/interfaces, write a C/C++ function and call it to bring in data.
This allows you to operate on the data or read it in a complex format. This models
functionality but not hardware.

To model buses accurately, use the Plugin Library to write a plugin which can be co-
simulated. This is precise and allows you to read I/O signals using the Waveform
Analyzer, but can be slow and cumbersome.

Using preprocessor definitions

By using the #define and #ifdef...#endif constructs of the preprocessor, it is possible
to combine both the simulation and hardware versions of your program into one.

Channel example
#define SIMULATE
#ifdef SIMULATE
input ? value;
#else
value = BusIn.in;
#endif

External function call example

#define SIMULATE

#ifdef SIMULATE
extern "C++" int 8 bus_input_function(void);
data_in = bus_input_function();
#else
interface bus_in(int 8 in) BusIn();
data_in = BusIn.in;
#endif

www.celoxica.com Page 237

Handel-C Language Reference Manual

Example with plugin

To simulate a tri-state bus:

interface bus_ts (int 32 in with

{extlib = "MyPlugin.dll", extinst = "1", extfunc = "DataBusIn"})
DataBus(int 32 out = DataOut with {extlib = "MyPlugin.dll",
extinst = "1", extfunc = "DataBusOut"},
int 1 enable = !WriteBus.in with {extlib = "MyPlugin.dll",
extinst = "1", extfunc = "DataBusEnable"})
with {data = pinList};

In this case, the functions DataBusIn, DataBusOut and DataBusEnable would be

provided in the plugin MyPlugin.dll and called by the simulator. The extlib, extfunc
and extinst specifications are ignored if compiled to HDL so the interface definition does
not have to be within an #ifdef.

11.4 Merging pins

11.4.1 Merging clock pins

You can merge clock pins as long as:

• any pins specifications given to the two clocks match.

• there are no conflicts between any timing specifications given to the clocks.

For example, if you specified two clock domains in the same project with the following
code:

set clock = external "C1" with {rate = 10}; //clock declaration in file
one.hcc
set clock = external "C1" with {rate = 20}; //clock declaration in file
two.hcc

you would get a compiler error, as the rate specifications don't match.

If one of the clocks is divided you need to divide the value of the rate specification to
match. For example:

set clock = external "C1" with {rate = 10}; // file one.hcc

set clock = external_divide 3 "C1" with {rate = 3.3333333333333333}; //
file two.hcc

If you need to use decimal places to specify the rate for the divided clock, the compiler
will round up the value to the nearest whole number as long as you use at least 16
decimal places (3 x3.3333333333333333 is rounded up to 10).

www.celoxica.com Page 238

Handel-C Language Reference Manual

11.4.2 Merging input pins

Input pins can be merged so that pins can be read simultaneously into multiple variables.
This can be done by specifying multiple interfaces (bus_in, bus_clock_in,
bus_latch_in) which have some pins in common. If required, a different subset of pins
can be specified for each instance of the interface. For example:

interface bus_in(int 8 wide) wideDataBus() with

{data ={"P7", "P6", "P5", "P4", "P3",
"P2", "P1", "P0"}};
interface bus_in(int 3 thin) thinDataBus() with
{data ={"P5", "P4", "P3"}};

wideDataBus.wide would give the values of pins P0 – P7, whereas thinDataBus.thin

would give the three bit value on pins P3, P4 and P5.

If the input pins have an intime specification, you need to ensure that these match.

11.4.3 Merging tri-state pins

Tri-state bus pins can be merged, though doing so will generate a compiler warning, as
the compiler cannot detect whether the outputs for both pins might be enabled at the
same time. If both outputs are enabled at the same time, the result is undefined. If you
have used any intime and outtime specifications, make sure that they match.

You might wish to merge output pins for a tri-state bus if you wished to switch the circuit
connections from one external piece of logic to another. For example:

int 1 en1, en2;

int 4 x, y;
interface bus_ts_clock_in (int 4 read)
BiBus1(int 4 writePort=x+1, unsigned 1 enable = (en1==1))
with {data = {"P4", "P3", "P2", "P1"}};
interface bus_ts_clock_in (int 4 read)
BiBus2(int 4 writePort=y+1, unsigned 1 enable = (en2==1))
with {data = {"P4", "P3", "P2", "P1"}};

2 Take care when driving tri-state buses that the FPGA/PLD and another device
on the bus cannot drive simultaneously as this may result in damage to one or
both of them.

www.celoxica.com Page 239

Handel-C Language Reference Manual

11.5 Timing considerations for buses

bus_in interfaces
This form of bus is built with no register between the external pin and the points inside
the FPGA or PLD where the data is used. If the value on the external pin changes
asynchronously with the Handel-C clock then routing delays within the FPGA can cause
the value to be read differently in different parts of the circuit. The solution to this
problem is to use either a bus_latch_in or a bus_clock_in interface sort.

bus_out interfaces
The output value on pins cannot be guaranteed except at rising Handel-C clock edges. In
between clock edges, the value may be in the process of changing. Since the routing
delays through different parts of the logic of the output expression are different, some
pins may change before others giving rise to intermediate values appearing on the pins.
This is particularly apparent in deep combinational logic. Adding a flip-flop to the output
(as shown in the bus_out example) will minimize these effects.

Race conditions within the combinational logic can lead to glitches on output pins
between clock edges. When this happens, pins may glitch from 0 to 1 and back to zero or
vice versa as signals propagate through the combinational logic. Adding a flip-flop at the
output removes these effects.

Bi-directional tri-state buses

The timing considerations for bus_in and bus_out interfaces should also be taken into
account when using bi-directional tri-state buses since these are effectively a
combination of an input bus and an output bus.

11.5.1 Example timing considerations for input buses

interface bus_in(int 1 read) a() with

{data = {"P1"}};

par
{
x = a.read;
y = a.read;
}

www.celoxica.com Page 240

Handel-C Language Reference Manual

Even though a.read is assigned to both x and y on the same clock cycle, if the delay
from pin 1 to the flip-flop implementing the x variable is significantly different from that
between pin 1 and the flip-flop implementing the y variable then x and y may end up
with different values.

The delay between pin 1 and the input of y is slightly longer than the delay between pin
1 and the input to x. As a result, when the rising edge of the clock registers the values
of x and y, there is one clock cycle when x and y have different values.

This effect can also occur in places that are more obscure.

interface bus_in(int 1 read) a() with

{data = {"P1"}};

while (a.read==1)
{
x = x + 1;
}

Although a.read is only apparently used once, the implementation of a while loop
requires the signal to be routed to two different locations giving the same problem as
before. The solution to this problem is to use either a bus_latch_in or a bus_clock_in
interface sort.

The compiler will detect any occurrences of a pin feeding more than one register, and
issue a warning.

www.celoxica.com Page 241

Handel-C Language Reference Manual

11.5.2 Example timing considerations for output buses

int 8 x;
int 8 y;

interface bus_out() output(int out = x * y)

with {data = {"P7", "P6", "P5", "P4",
"P3", "P2", "P1", "P0"}};

A multiplier contains deep logic so some of the 8 pins may change before others leading
to intermediate values. It is possible to minimize this effect (although not eliminate it
completely) by adding a variable before the output. This effectively adds a flip-flop to the
output. The above example then becomes:

int 8 x;
int 8 y;
int 8 z;

interface bus_out() output(int out = z)

with {data = {"P7", "P6", "P5", "P4",
"P3", "P2", "P1", "P0"}};

z = x * y;

You must now take care to update the value of z whenever the value output on the bus
must change.

11.6 Metastability
If the input of a flip-flop is connected to a signal which is not synchronous with the flip-
flop's clock then its setup or hold time may be violated. This can result in the flip-flop
entering a metastable state when it is clocked. The output of the flip-flop will then have
an unpredictable value for an indeterminate period of time but will eventually become
either 0 or 1.

In some circumstances (such as when two independent clocks are involved) metastability
cannot be avoided. While a metastable flip-flop may remain so for any length of time,
there is a high probability that it will enter a stable state after a relatively short delay.

www.celoxica.com Page 242

Handel-C Language Reference Manual

The metastability characteristics of digital logic devices vary enormously. Refer to

product data sheets for details.

The diagram shows flip-flops in separate clock domains. The central flip-flop receives
data from the other clock domain. Its value is copied to the second flip-flop after 1 clock
tick.

In that clock tick, it must resolve metastability and pass through any routing and output
and setup delays.

11.6.1 Techniques to minimize the problem

• use extra registers to stabilize the data

• decouple the FPGA/PLD from external synchronous hardware by using external
buffer storage

Stabilizing the data

The ideal system is designed such that when data is clocked into a register it is
guaranteed to be stable.

The solution is to clock the data into the Handel-C program more than once, so it is
clocked into one register, and the output of that register is then clocked into another
register. On the first clock edge the data could be changing state so the output could be
metastable for a short time after the clock. However, as long as the clock period is long
relative to the possible metastable period, the second clock edge will clock stable data.
Even more clock edges further reduce the possibility of metastable states entering the
program, however the move from one clock to two clock ticks is the most significant and
should be adequate for most systems.

The example below has 4 clock edges. The first is in the bus_clock_in procedure, and
the next 3 are in the assignments to the variables x, y, and z.

www.celoxica.com Page 243

Handel-C Language Reference Manual

int 4 x,y,z;

interface bus_clock_in(int 4 read) InBus() with

{data = {"P4", "P3", "P2", "P1"}};

par
{
while(1)
x = InBus.read;

while(1)
y = x;

{
......
z = y;
}
}

Designing the system to minimize the problem

Remember to keep the problem in perspective by examining the details of the board to
estimate the probability of metastability. You can use external buffers to stabilize data
from synchronous hardware before it is input to the FPGA.

Techniques to minimize the problem

If using channels to communicate between clock domains, you may use clock
specifications to balance speed and metastability issues

If using interfaces to communicate between clock domains, you can insert extra
stabilizing flip-flops to reduce the likelihood of metastability being propagated through
the circuit

Timing constraints used for channels across clock domains

Within a single clock tick, data transmitted from another asynchronous clock domain
must settle (stop being metastable) and be routed to the next flip flop.

www.celoxica.com Page 244

Handel-C Language Reference Manual

If you are using channels to communicate between clock domains, you can set the timing
constraints which specify how long it is before you sample data (the amount of time for it
to settle) OR the amount of time available for it to move onwards.

The amount of time used for it to settle is known as the resolution time (tres). You can
specify a maximum period for this by using the resolutiontime specification. A sensible
value for resolutiontime is three-quarters of the clock period.

The amount of time left is the amount of time for the control signal to get from one flip-
flop to the next, including all output, setup and routing delays. This is the minperiod
specification. This would normally only be used if paranoia is set to 0.

How channels are designed to deal with metastability

When you use a channel to communicate across clock domains, synchronization
hardware is built automatically.

tr time to transfer between domains (paranoia in domain B + 1) X tp

tp clock period in domain B

tup unconstrainedperiod

www.celoxica.com Page 245

Handel-C Language Reference Manual

tmp minperiod

The control signals are clocked through a number of flip-flops specified by paranoia. On
each clock edge, the data is moved through another flip-flop, such that it is less likely to
be metastable.

11.6.2 Using interfaces: External resynchronizing example

This example shows the three files required to connect two EDIF blocks (bbA and bbB)
which use different clocks. The small files bbA.hcc and bbB.hcc compile to the EDIF code
using the port_out from and port_in to interfaces. The metastable.hcc file connects
the two together and generates one flip –flop that resynchronizes the data by reading the
value from bbA into a variable.

File: metastable.hcc

www.celoxica.com Page 246

Handel-C Language Reference Manual

/*
* Black box code to resynchronize
* Needs to be clocked from the reading clock
* (i.e. bbB.hcc's clock)
*/

int 1 x;
interface bbA(int 1 from) A();
interface bbB() B(int 1 to=x, unsigned 1 clk = __clock);

set clock = external "P1";

void main(void)
{
while(1)
{
/*
* stabilize the data by adding resynchronization FF
*/
x = A.from;
}
}

File: bbA.hcc

/*
* Domain bbA
* Compiles to bbA.edf
*/
interface port_in(unsigned 1 clk with { clockport = 1 }) clk();
set clock = internal clk.clk;
void main(void)
{
int 1 y;
interface port_out() from (int 1 from = y);
}

File: bbB.hcc

www.celoxica.com Page 247

Handel-C Language Reference Manual

/*
*Domain bbB
* Compiles to bbB.edf
*/

set clock = external "P2";

void main(void)
{
int 1 q;

interface port_in(int 1 to) to();

par
{
while(1)
{
q = to.to; // Read data
}
}
}

11.7 Ports: interfacing with external logic

Handel-C provides the interface sorts port_in and port_out. These allow you to have a
set of wires, unconnected to pins, which you can use to connect to a simulated device or
to another function within the FPGA or PLD. Handel-C supplies the interface declaration
for these sorts, and you supply the instance definition.

port_in
For a port_in, you define the port(s) carrying data to the Handel-C code and any
associated specifications.

interface port_in(Type data_TO_hc [with {port_specs}])

Name() [with {Instance_specs}];

For example:

interface port_in(int 4 signals_to_HC) read();

You can then read the input data from the variable Name.data_TO_hc, in this case
read.signals_to_HC

www.celoxica.com Page 248

Handel-C Language Reference Manual

port_out
For a port_out, you define the port(s) carrying data from the Handel-C code, the
expression to be output over those ports, and any associated specifications.

interface port_out() Name(Type data_FROM_hc =

output_Expr[with {port_specs}])
[with {Instance_specs}];

For example:

int X_out;
interface port_out()
drive(int 4 signals_from_HC = X_out);

In this case, the width of X_out would be inferred to be 4, as that is the width of the port
that the data is sent to.

Port names
The name of each port in a port_in or port_out interface must be different, as they will
all be built to the top level of the design.

The examples below would both generate a compiler error.

Example 1:

interface port_in(unsigned 1 soggy) In1();

interface port_in(unsigned 1 soggy) In2();

Example 2:

interface port_in(unsigned 1 soggy) In1();

void main(void)
{
interface port_in(unsigned 1 soggy) In2();
...
}

Both examples build two ports to the top level of the design called soggy. When they
were integrated with external code, the PAR tools wouldn’t know which soggy to use
where.

11.8 Specifying the interface

You can specify your own interface format. This allows you to communicate with code
written in another language such as VHDL, Verilog or EDIF and allows the Handel-C
simulator to communicate with an external plugin program (e.g., a connection to a VHDL
simulator).

www.celoxica.com Page 249

Handel-C Language Reference Manual

The expected use for this is to allow you to incorporate bought-in or handcrafted pieces
of low-level code in your high-level Handel-C program. It also allows your Handel-C
program code to be incorporated within a large EDIF, VHDL or Verilog program. You can
also use it to communicate with programs running on a PC that simulate external
devices.

To use such a piece of code requires that you include an interface definition in the
Handel-C code to connect it to the external code block. This interface definition also tells
the simulator to call a plugin (which in turn may invoke a simulator for the foreign code).

11.9 Targeting ports to specific tools

When compiling to EDIF, Handel-C has the capacity to format the names of wires to
external logic according to the different syntaxes used by any external components
generated by foreign tools. You can do this using the busformat specification to a port.
This allows you to specify how the bus name and wire number are formatted.

To specify a format, you use the syntax

with {busformat = "formatString"}

formatstring can be one of the following strings. B represents the bus name, and I
represents the wire number.

BI
B_I
B[I]
B(I)
B<I>
B specifies a bus

B[N:0], B<N:0> or B(N:0) specify a bus of width (N+1).

www.celoxica.com Page 250

Handel-C Language Reference Manual

Example format B[I]

interface port_in(int 4 signals_to_HC with
{busformat="B[I]"}) read();

would produce wires

signals_to_HC[0]
signals_to_HC[1]
signals_to_HC[2]
signals_to_HC[3]

Example format B<I>

ram unsigned 4 rax[4] with
{ports = 1, busformat="B<I>"};

would produce wires

rax_SPPort_addr<0> // Address
rax_SPPort_addr<1>
rax_SPPort_data_in<0> // Data In
rax_SPPort_data_in<1>
rax_SPPort_data_in<2>
rax_SPPort_data_in<3>
rax_SPPort_data_out<0> // Data Out
rax_SPPort_data_out<1>
rax_SPPort_data_out<2>
rax_SPPort_data_out<3>
rax_SPPort_data_en // Data Enable
rax_SPPort_clk // Clock
rax_SPPort_cs // Chip Select
rax_SPPort_oe // Output Enable
rax_SPPort_we // Data In

www.celoxica.com Page 251

Handel-C Language Reference Manual

12 Object specifications
Handel-C provides the ability to add ‘tags’ to certain objects (variables, channels, ports,
buses, RAMs, ROMs, mprams, clocks, resets and signals) to control their behaviour.
These tags or specifications are listed after the definition of the object using the with
keyword. All specifications can be applied to generic output. Others are only valid for
simulation (Debug or Release) or for hardware output.

When defining multiple objects, the specification must be given at the end of the line and
it applies to all objects defined on that line. For example:
extern unsigned x, y;
unsigned x, y with {show=0};

This attaches the show specification with a value of 0 to both x and y variables.

Specifications can only be applied to the definition of objects, not to declarations:

extern rom unsigned 32 SomeRom[1] with {Spec}; // Wrong; spec applied to de

claration
rom unsigned 32 SomeRom[1]={1} with {Spec}; // OK; spec applied to definiti
on

The with keyword takes one or more of the following attributes.

12.1 Summary of specifications

12.1.1 Compiler atttributes

These specifications are interpreted by the compiler.

Specification Possible Default Applies to Meaning

values

warn 0, 1 1 variables Enable warnings for object

memories
channels
interfaces
clocks
extpath Name of port None port FROM Specify any direct logic
TO Handel-C Handel-C (combinational logic)
on the same connections to another port
interface

www.celoxica.com Page 252

Handel-C Language Reference Manual

12.1.2 Simulator attributes

These specifications are interpreted by the simulator.

Specification Possible Default Applies to Meaning

values

show 0, 1 1 variables Show variable during

channels simulation
o/p
interfaces
tri-state
interfaces
base 2, 8, 10, 10 variables Print variable in specified
16 chanouts base
o/p
interfaces
tri-state
interfaces
infile Any valid None chanins Redirect from file
filename i/p
interfaces
tri-state
interfaces
outfile Any valid None chanouts Redirect to file
file name o/p
interfaces
tri-state
interfaces,
variables
extlib Name of a None interface or Specify external plugin for
plugin port simulator
.dll
extfunc Name of a PlugInSet interface or Specify external function
function or port within the simulator for this
within the PlugInGet port
plugin depending
on port
direction
extinst Instance None interface or Specify simulation instance
name port used
(with
optional
parameter
s)

www.celoxica.com Page 253

Handel-C Language Reference Manual

12.1.3 Clock attributes

These specifications apply to a clock, and affect the hardware built in that clock domain.

www.celoxica.com Page 254

Handel-C Language Reference Manual

Specification Possible Default Applies to Meaning

Values

clockport 0, 1 0 for a ports on Mark port as

port on an interfaces, feeding a clock.
interface, external When applied to a
1 for a clocks generic interface
clock port, it marks that
declaration port as feeding a
clock. When applied
to an external
clock, it marks that
clock as using a
dedicated clock pin.

minperiod Any time in None clocks with minimum period for

nanoseconds channels to place and route
other clock tools to achieve
domains between flip-flops

paranoia 0 or any 1 clocks specifies number of

positive extra flip-flops used
integer in stabilizing
(above 10 synchronization
causes a data
warning)
rate Any floating- None clocks Minimum frequency
point at which the clock
frequency in in question should
MHz be capable of
running
resolutiontim Any time in None clocks with Time for
e nanoseconds channels to metastability to
other clock resolve on channels
domains into clock domains
retime 0 or 1 1 clocks, Prevent flip-flops in
variables a specific clock
domain or
generated by a
variable from being
moved by the
retimer
unconstrained Any time in None clocks with Constraint for
period nanoseconds channels to compiler-generated
other clock control paths into
domains clock domain

www.celoxica.com Page 255

Handel-C Language Reference Manual

12.1.4 Channel attributes

This specification defines how channels are built.

Specification Possible values Default Applies to Meaning

fifolength 0 or any positive 0 channel Create FIFO of

integer specified length

12.1.5 Channel and memory attributes

This specification defines where memories and FIFOs are built.

Specification Possible values Default Applies to Meaning

block "AUTO" for any "AUTO" memories Specify memory

device; (on-chip) resource type to
"BlockRAM" for FIFOs of use for
Actel; two or RAM/ROM

"LUT", "EAB", more parts

"M512", "M4K" or
"M-RAM" for Altera;
"BlockRAM" or
"SelectRAM" for
Xilinx

12.1.6 Memory attributes

These specification defines how memories are built.

www.celoxica.com Page 256

Handel-C Language Reference Manual

Specification Possible Default Applies to Meaning

Values

offchip 0, 1 0 memories Set RAM/ROM to

be off chip. Cannot
be used in
conjunction with
ports
ports 0, 1 0 memories Set RAM/ROM to
be in external
code. Cannot be
used in
conjunction with
offchip
wegate -1, 0, 1 0 RAMs Place write enable
signal
westart in multiples of None RAMs Position write
0.5 to (clock enable signal
division -0.5)
welength in multiples of None RAMs Set length of write
0.5 to clock enable signal
division
rclkpos in multiples of None memories Set read cycle
0.5 to (clock position of SSRAM
division -0.5) clock
wclkpos in multiples of None memories Set write cycle
0.5 to (clock position of SSRAM
division -0.5) clock
clkpulselen in multiples of None memories Set pulse length of
0.5 to clock SSRAM clock
division
clk Any valid pin None memories Set pins for
list (off-chip) external RAM or
ROM clock
addr Any valid pin None memories Set address pins
list (off-chip)
oe Any valid pin None memories Set output enable
list (off-chip) pin(s)
we Any valid pin None RAMs Set write enable
list (off-chip) pin(s)
cs Any valid pin None memories Set chip select
list (off-chip) pin(s)

www.celoxica.com Page 257

Handel-C Language Reference Manual

12.1.7 Interface and memory attributes

This specification defines how interfaces and memory connections are built.

Specification Possible Default Applies to Meaning

Values

speed 0, 1, 2 2 for Actel o/p or tri- Set buffer speed

(Actel ProASIC state
ProASIC and interfaces
only) ProASIC+

0, 1 1 for
(Altera and Altera and
Xilinx) Xilinx
Virtex,
Spartan-
II/IIE/3/3E
/3L series
intime Any floating- None input port or Maximum
point delay interfaces or allowable delay
(ns) tri-state between interface
interfaces and variable
external RAMs
outtime Any floating- None output port or Maximum
point delay interfaces or allowable delay
(ns) tri-state between variable
interfaces and interface
external RAMs
standard Specified LVCMOS33 any external I/O standard used
keywords for interface or (electrical
representing ProASIC / external clock characteristics)
I/O standards ProASIC+ (dependent on
LVTTL for FPGA type),
other and off-chip
devices memories
strength 2, 4, 6, 8, Various, external Signal strength.
12, 16, 24 refer to interfaces and
(mA) device off-chip
datasheets memories
OR

0 (Min), -1
(Max)

www.celoxica.com Page 258

Handel-C Language Reference Manual

dci 0, 0.5, 1 0 (No DCI) external Digital control

interfaces and impedance
external enabled (only valid
clocks (Virtex- with some
II, Virtex-II standards)
Pro and
Spartan-
3/3E/3L only)
and off-chip
memories
busformat Format string BI generic Specify the way
interfaces, that wire names
port-type are formatted in
interfaces and EDIF
ports to
memories in
external logic
pull 0, 1 None Xilinx and Add pull up or pull
ApexII down resistor(s)
interfaces
data Any valid pin None memories Set data pins
list interfaces

12.1.8 Interface attributes

These specifications defines how interfaces are built.

www.celoxica.com Page 259

Handel-C Language Reference Manual

Specification Possible Default Applies to Meaning

values

bind 0,1 0 interface, Bind component to

port work library
buffer string Depends on bus-type In EDIF: specify
value target interfaces, type of buffer to
architecture external build
and type of clocks &
interface resets
properties string- None generic In EDIF:
value interfaces Parameterize
pair OR instantiations of
string- external black
value- boxes
string In VHDL: Define
triplet generics
In Verilog: Define
parameters
quartus_proj_assign string- None bus-type In EDIF: specify
value interfaces, Quartus project
pair offchip RAM pins assignments
sc_type string- bool for 1 port_in, Create a SystemC
value bit wide port_out or port of a specified
ports, uint generic type
otherwise interfaces
vhdl_type string- std_logic port_in, Create a VHDL port
value for 1 bit port_out or of a specified type
wide ports, generic
unsigned interfaces
otherwise

12.1.9 Examples

Specifications can be added to objects as follows:

unsigned 4 w with {show=0};

int 5 x with {show=0, base=2};
chanout char y with {outfile="output.dat"};
chanin int 8 z with {infile="input.dat"};
interface bus_clock_in(int 4 in) InBus() with
{ pull = 1, data = {"P4", "P3", "P2", "P1"} };

www.celoxica.com Page 260

Handel-C Language Reference Manual

12.2 base specification

The base specification may be given to variable, output channel, output bus and tri-state
bus declarations. You can only use it for simulation output (Debug or Release). The value
that this specification is set to tell the Handel-C compiler which base to display the value
of the object in. Valid bases are 2, 8, 10 and 16 for binary, octal, decimal and
hexadecimal respectively.

The default value of this specification is 10. If you write with {base = 0} this is
equivalent to not specifying a base.

Example
int 5 x with {base=2};

12.3 bind specification

The bind specification may be given to a user-defined interface that connects to a
component in external logic. It only has meaning when instantiating an external block of
code from Handel-C generated VHDL or Verilog. If bind is set to 1, it is assumed that the
definition of the component exists in HDL elsewhere. If it is set to 0, it does not and the
component is assumed to be a black box.

In VHDL, setting bind to 1 instantiates the component and generates a declaration of

this component of which the definition is assumed to be within the work library. Setting
bind to 0 (default) instantiates the component and generates a black box component
declaration.

In Verilog, setting bind to 1 instantiates the component but does not declare it. Setting
bind to 0 instantiates the component and generates a black box component declaration.
This black box component declaration is an empty module, which merely describes the
interfaces of the component.

VHDL example 1: with bind set to 0:

interface Bloo(unsigned 1 myin)
B(unsigned 1 myout = x) with {bind = 0};

results in Handel-C generating this VHDL instantiation of the Bloo component:

component Bloo
port (
myin : out std_logic;
myout : in std_logic
);
end component;

www.celoxica.com Page 261

Handel-C Language Reference Manual

VHDL example 2: with bind set to 1:

interface Bloo(unsigned 1 myin)
B(unsigned 1 myout = x) with {bind = 1};

results in Handel-C generating this VHDL instantiation/declaration of the Bloo

component:

component Bloo
port (
myin : out std_logic;
myout : in std_logic
);
end component;
for all : Bloo use entity work.Bloo;

In this case Bloo is bound to the work library.

Verilog example 1: with bind set to 0:

interface Bloo(unsigned 1 myin)
B(unsigned 1 myout = x) with {bind = 0};

results in Handel-C generating this Verilog instantiation of the Bloo component:

module Bloo;
input myin;
output myout;
endmodule;

module MyModule;
...
wire a, b;
...
Bloo MyInstance (.myin(a), .myout(b));
...
endmodule;

Note that the code includes a black box declaration of Bloo.

Verilog example 2: with bind set to 1:

interface Bloo(unsigned 1 myin) B(unsigned 1 myout = x) with {bind = 1};

results in Handel-C generating this Verilog instantiation of the Bloo component:

www.celoxica.com Page 262

Handel-C Language Reference Manual

module MyModule;
...
wire a, b;
...
Bloo MyInstance (.myin(a), .myout(b));
...
endmodule;

(The VHDL or Verilog synthesizer expects the declaration of Bloo to be provided in

another block of HDL.)

12.4 block specification

The block specification may be given to a RAM or ROM declaration, for EDIF, VHDL or
Verilog output. The block specification may also given to channels where fifolength is
2 or greater.

The specification takes a string to specify the type of block memory required. Possible
values are:

• Actel devices: "BlockRAM"

• Altera devices: "LUT", "EAB", "M512", "M4K", "M-RAM" ("EAB" should be used
for both EABs and ESBs)
• Xilinx devices: "SelectRAM", "BlockRAM"
• All devices: "AUTO". This is the same as not using the block specification, but
can be used as a placeholder to pass in an active value.

For example:

ram int 8 a[15][43] with {block = "BlockRAM"};

chan <unsigned 1> ch with {fifolength=15, block ="SelectRAM"};

If you want to build a ROM from look-up tables (distributed memory) in Altera devices,
you need to declare the ROM with {block = "LUT"}.

"M512", "M4K" and "M-RAM" are used to specify memory blocks in Stratix and Cyclone
devices.

Ï The block specification has changed since DK1.1, although the old method,
using block = 1 to specify block RAMs, is still supported for backward
compatibility.

www.celoxica.com Page 263

Handel-C Language Reference Manual

Issues with Xilinx Virtex, VirtexE and Spartan-IIE

Due to the pipelined nature of Virtex and Spartan-IIE block RAM, if you attempt to read
from one bank of block RAM and write the value into another on a single cycle, the value
read is the value in block RAM on the previous clock cycle, not the current cycle.

Code example with timing issues

static ram unsigned 8 RAM1[4] = {0,1,2,3} with {block="BlockRAM"};
ram unsigned 8 RAM2[4] with {block="BlockRAM"};
signal s;
unsigned x;
unsigned i;

while(1)
{
par
{
s = RAM1[i];
RAM2[i] = s;
x = s;
i++;
}
}

Here, x and RAM2[i] get different values. s changes on the falling edge. x is written to
on the rising edge. RAM2[i] is written to on the falling edge.

Therefore, RAM2[i] gets the value of RAM1[i-1] and x gets the value of RAM1[i].

To alter this, you must use the rclkpos, wclkpos and clkpulselen specifications to set
the RAM clock cycle positions.

www.celoxica.com Page 264

Handel-C Language Reference Manual

Solution to timing problem

//divide CLK by four to give Handel-C clock
set clock = external_divide "C1" 4;

static ram unsigned 8 RAM1[4] = {0,1,2,3} with {block = "BlockRAM",

rclkpos = {1.0},
wclkpos = {3.5},
clkpulselen = 0.5,
westart = 3.0,
welength = 1.0};

ram unsigned 8 RAM2[4] with {block = "BlockRAM",

rclkpos = {1.0},
wclkpos = {3.5},
clkpulselen = 0.5,
westart = 3.0,
welength = 1.0};

www.celoxica.com Page 265

Handel-C Language Reference Manual

HCLK initiates the parallel read from and write to the different blocks of RAM.

The settings of rclkpos and clkpulselen delay the read cycle until the address is stable.
(Read clock pulse 1 CLK pulse after HCLK, held for 0.5 CLK pulses).

The settings of wclkpos and clkpulselen delays the write cycle until after the data has
been read and is stable. The settings of westart and welength position the write enable
appropriately.

12.5 buffer specification

The buffer specification can be applied to all bus-type interfaces and external
clock/reset declarations. It accepts a string, and it specifies the type of buffer that should
be built on the corresponding interface. "None" may be used to specify that no buffer
should be built.

Example 1:
interface bus_in(unsigned 3 i) I() with {buffer = "IBUFG"};
builds a standard bus_in interface, where the buffer is of type IBUFG, specifying that the
bus_in should feed a global buffer (for Xilinx) instead of a basic input buffer (for
connecting to DCMs, for instance).

Example 2:
interface bus_in(unsigned 3 i) I() with {buffer = "None"};
builds a standard bus_in interface with no buffer. That is, any logic reading from I.i
will be fed by pins directly.

Example 3:
set clock = external with {buffer = "GL25LP"};
specifies that the clock should use a low-power clock buffer for Actel.

Where no buffer spec is used, the default buffer type is used.

12.6 busformat specification

The busformat specification may be given to

• generic and port-type (port_in and port_out) interfaces (but not bus-type
interfaces)
• port memories (memories using with {ports = 1} to connect to external
code)

busformat specifications are ignored for VHDL and Verilog output and for bus-type
interfaces (bus_in, bus_ts etc).

www.celoxica.com Page 266

Handel-C Language Reference Manual

When compiled to EDIF, the busformat string defines the format of the wire names. Valid
values for the busformat string are

BI B_I B[I] B(I) B<I>

B represents the bus name and I the wire number. The default format is BI

If you want to specify a single port for the entire bus, use

B B[N:0] B<N:0> B(N:0)

B specifies a bus without specifying a width and B[N:0] and B<N:0> specify a bus of
width (N +1). A 6-bit port could therefore be generated as port, port[5:0]or
port<5:0> depending on the value of busformat.

Ï If data specifications are used with busformat, they are ignored and a
warning is issued.

You can place the busformat specification after any port, or at the end of an interface
statement. If you place a specification at the end of the interface declaration, it will apply
to all ports in the declaration, except for any ports that have their own specification. For
example:

interface Bloo (unsigned 4 in)

InstBloo (unsigned 4 out = x
with {busformat = "BI"})
with {busformat = "B(I)"};
// first port has spec B(I) and second port has spec BI

If you want to apply a busformat specification to a 1-bit wide bus, you need to place the
specification after the port. If the specification is applied to the whole interface, it will be
ignored for any 1-bit wide buses in the interface (to enable these to be used as signals
etc.).

Examples
interface port_in(int 4 signals_to_HC with {busformat="B[I]"}) read();

creates four ports named signals_to_HC[0], signals_to_HC[1], signals_to_HC[2]

and signals_to_HC[3].

interface port_in(unsigned 6 myvar) MyFunction()

with {busformat = "B[N:0]"};

creates a single 6-bit port: myvar[5:0].

www.celoxica.com Page 267

Handel-C Language Reference Manual

unsigned 6 x;
interface ExtThing(unsigned 6 myvar)
Inst1ExtThing(unsigned 6 anothervar = x)
with {busformat = "B[N:0]"};

creates two ports: myvar[5:0] and anothervar[5:0].

interface ExtThing(unsigned 5 a,
unsigned 1 b with {busformat = "B[I]"},
unsigned 1 c)
InstExtThing(unsigned 6 d)
with {busformat = "B[I]"};

In this example, the busformat specification is applied to ports a and d, because they are
more than 1-bit wide, and to port b, as this has an individual busformat specification,
but not to port c as this is 1-bit wide and does not have an individual busformat
specification.

12.7 Specifying the clock pin for SSRAM

The clk specification is used for external SSRAM or ROM declarations, for EDIF, VHDL or
Verilog output. It specifies the pin(s) that carry the RAM/ROM clock to the external
SSRAM/ROM. To use this specification, you must be using the external_divide or
internal_divide clock types with a division factor of 2 or more, and you must use the
wclkpos, rclkpos and clkpulselen specifications to define the clock that will appear at
the specified pin(s).

www.celoxica.com Page 268

Handel-C Language Reference Manual

Example
set clock = external_divide "C1" 4;

ram unsigned 4 ExtSyncMem[32] with

{
offchip = 1,
wclkpos = {2.5},
rclkpos = {2.5},
clkpulselen = 1,
clk = {"P22"},
westart = 2,
welength = 1,
we = {"P23"},
cs = {"P24"},
oe = {"P25"}
};

void main(void)
{
static unsigned index;
static unsigned data;

ExtSyncMem[index] = data;
etc...

data = ExtSyncMem[index];
etc...
}

The clock pattern defined by the wclkpos, rclkpos and clkpulselen specifications
appears at pin "P22". The write enable strobe defined by westart and welength appears
at pin "P23".

12.8 clockport specification

The clockport specification can be used when declaring a port on an interface, or when
declaring a clock. You can use it for EDIF, VHDL or Verilog output.

Port declaration
You can use the clockport specification to indicate that a port on an interface is used to
drive a clock in the Handel-C design. This is useful when the clock for the Handel-C
design originates in an external 'black box' component. For example

www.celoxica.com Page 269

Handel-C Language Reference Manual

unsigned 1 En;
interface BlackBox(unsigned 1 CLK with {clockport=1})
Instance(unsigned 1 Enable = En);

set clock = internal Instance.CLK;

Ï If you don't use the clockport specification you may end up with
combinational loops.

Clock declaration
You can use the clockport specification, with {clockport=1}, when declaring external
clocks to assign the clock to a dedicated clock input resource on the target device.

If you apply the clockport specification to Xilinx Virtex parts, you can use it to specify a
particular "input" clock buffer.

If clockport is set to 0, the clock is assigned to a pin that is not a dedicated clock input
and the I/O standard and dci specifications are not available.

Example clock declarations

set family = XilinxVirtexII;
set clock = external with {standard = "LVCMOS33", dci = 1};
OR

set family = XilinxVirtexII;

set clock = external with {clockport = 1, standard = "LVCMOS33", dci = 1};

both instruct the compiler to build an external clock interface, using a dedicated Virtex-II
clock input (IBUFG) resource. That is, the clock interface logic built will be:

set family = XilinxVirtexII;

set clock = external with {clockport = 0, standard = "LVCMOS33", dci = 1};

www.celoxica.com Page 270

Handel-C Language Reference Manual

This instructs the compiler to build an external clock interface, without using a dedicated
Virtex-II clock input resource. That is, the clock interface logic built will be:

12.9 data specification (pin constraints)

The data specification can be used to constrain pin location or to name ports:

• When applied to bus-type interfaces or off-chip memories, data specifies pin

locations as a list of pin numbers separated by commas. If you are using a
differential I/O standard, the pins must be specified as pairs enclosed in
braces.
• When applied to foreign code memories (using with {ports=1}), port-type
interfaces and generic interfaces, data specifies port names as a list of names
separated by commas
If the data specification is omitted for bus-type interfaces or off-chip memories, the
place and route tools will assign the pins. The pins are listed in order MSB to LSB, but the
LSB pin (rightmost element of list) is assigned first. If you do not assign all the pins
used, the MSB pins remain unassigned.

If you are targeting EDIF output, the data specification can also be used for a port_in or
port_out interface to specify the names of the ports to be exported. (This part of the
data specification is ignored for VHDL or Verilog output.)

If you are compiling your Handel-C code to VHDL or Verilog, you can only use the data
specification to constrain pin locations for Precision and Synplify style outputs. If you
compile for ModelSim or Active-HDL, the data specification is ignored. In Precision VHDL
or Verilog output styles, pin constraints are implemented using the pin_number attribute.
In Synplify-style output, pin constraints are implemented using the loc attribute.

Ï If the busformat specification is used as well as data specifications for port-

type or generic interfaces, the data specifications are ignored and a warning is
issued.

www.celoxica.com Page 271

Handel-C Language Reference Manual

Bus-type interface example

macro expr dataPins = {"P3", "P2", "P1", "P0"};
interface bus_in(unsigned 4 inPort) hword()
with {data = dataPins, intime = 5};
Port-type interface example
macro expr dataInNames = {"I3", "I2", "I1", "I0"};
macro expr dataOutNames = {"O3", "O2", "O2", "O1"};

unsigned 4 x;
interface port_in(unsigned 4 in) Ig()
with {data = dataInNames};
interface port_out() Og(unsigned 4 out = x)
with {data = dataOutNames};

Generic interface example

macro expr dataInNames = {"I3", "I2", "I1", "I0"};
macro expr dataOutNames = {"O3", "O2", "O2", "O1"};

unsigned 4 x;
interface Igator
(
unsigned 4 in with {data = dataInNames}
)
InstIgator
(
unsigned 4 out = x with {data = dataOutNames}
);

12.10 dci specification

The dci specification may be used with the standard specification on external bus
interfaces connected to pins (not port_in or port_out) to select whether Digital
Controlled Impedance is to be used on all pins of that interface. You can also use it with
the standard specification when declaring external clocks. The dci specification may also
be applied to off-chip memories. The specification is only valid for EDIF, and is ignored
for all other outputs.

The only devices that currently support DCI are Xilinx Virtex-II, Virtex-II Pro, Virtex-4
and Spartan-3/3E/3L. For more information on DCI, please refer to the Xilinx Data Book.

If you have used the clockport specification and set it to 0, dci specifications will be
ignored. (The default for clockport is 1.)

www.celoxica.com Page 272

Handel-C Language Reference Manual

Standards supporting dci are:

GTL GTL+

HSTL Class I HSTL Class II HSTL Class III HSTL Class

IV
LVCMOS33 LVCMOS25 LVCMOS18 LVCMOS15
SSTL2 Class I SSTL2 Class II SSTL3 Class I SSTL3 Class
II

The possible values for the dci specification are:

0 No DCI (default)
1 DCI with single termination
0.5 DCI with split termination. This can only be used
with LVCMOS standards.

Ï If dci is used on a device or standard that does not support it, a warning is
issued and the specification is ignored.

Examples
// Use dci on all pins
interface bus_out() Eel(int 4 outPort = x)
with {data = dataPinsO, standard = "HSTL_I", dci=1};

//Use dci for clock pin

set clock = external "C1" with {standard = "HSTL_III", dci=1};

12.11 extinst, extlib, extfunc specifications

The extlib, extfunc and extinst specifications are used when connecting a Handel-C
interface to a simulation .dll. There is a default value for extfunc, but extlib and
extinst must both be specified.

www.celoxica.com Page 273

Handel-C Language Reference Manual

Specification Possible Default Meaning

values

extlib Name of a None Specify external plugin for simulator

plugin .dll
extfunc Name of a PlugInSet or Specify external function within the
function within PlugInGet simulator for this port
the plugin depending on
port direction
extinst Instance name None Specify simulation instance used
(with optional
parameters)
extlib
extlib takes the name of a .dll. It specifies that the named .dll plugin will be
connected to the port or interface.

extfunc
extfunc specifies the name of an external function within the .dll.

On output ports, this function is called by the simulator to pass data from the Handel-C
simulator to the plugin (default PlugInSet). It is guaranteed to be called every time the
value on the port changes but may be called more often than that.

On input ports, this function is called by the simulator to get data from the plugin
(default PlugInGet). It is guaranteed to be called at least once every clock cycle.

extinst
extinst takes a string, which is passed to the PlugInOpenInstance function within the
plugin. If parameters must be passed to the .dll instance, they can be done so in the
string. A new instance of the plugin will be generated for each unique extinst string.

Examples
interface bus_out() MyBusOut(outPort=MyOutExpr) with
{extlib="pluginDemo.dll", extinst="0", extfunc="MyBusOut"};

interface TTL7446(unsigned 7 segments, unsigned 1 rbon)

decode(unsigned 1 ltn=ltnVal, unsigned 1 rbin=rbinVal,
unsigned 4 digit=digitVal, unsigned 1 bin=binVal)
with {extlib="PluginModelSim.dll",
extinst="decode; model=TTL7446_wrapper; delay=1"};

www.celoxica.com Page 274

Handel-C Language Reference Manual

12.12 extpath specification

The extpath specification is used when connecting a Handel-C interface to external
(black-box) logic. It is valid for any DK output.

extpath is used during simulation to tell the simulator about ports within the black box,
so that it knows what order to update the ports in. It specifies that a Handel-C output
port on an interface will have direct logic connections via the black box to one or more
input ports on the same interface.

Its usage is

portName with {extpath={portNameList}}

portNameList is a comma-separated list of port names.

Example
interface blackBox
(int 1 Two, int 1 Four)
bb1(int 1 One = out with {extpath = {bb1.Two}},
int 1 Three = bb1.Two with {extpath={bb1.Four}});

This example tells the compiler that there are direct connections within the black box
between ports 1 and 2, and between ports 3 and 4. The interface also specifies an
external connection from port 2 to port 3 (this connection is outside the black box).

12.13 fifolength specification

The fifolength specification converts a channel into a FIFO of the given length. If
fifolength is two or greater the block specification can be used.

If fifolength is not a power of 2, and the paranoia specification is 0 or 1 (default), the

FIFO will be created with low latency, else it will be created with a higher latency.

Example

int 8 chan_FIFO with {fifolength = 7, block = "MK4"}

//creates a FIFO in Altera Cyclone block RAM

www.celoxica.com Page 275

Handel-C Language Reference Manual

12.14 infile and outfile specifications

The infile specification may be given to chanin, port_in, port_out, bus_in,
bus_latch_in, bus_clock_in, bus_ts, bus_ts_latch_in and bus_ts_clock_in
declarations. The outfile specification may be given to chanout, bus_out, bus_ts,
bus_ts_latch_in and bus_ts_clock_in declarations. The strings that these
specifications are set to will inform the simulator of the file that data should be read from
(infile) or the file that data should be written to (outfile).

Note that when applying the outfile specification, it should not be given to multiple
channels. For example, the following declarations are allowed, but it would be better to
place them in separate files to avoid undefined results:

chanout int x, y with {outfile="out.dat"};

chanout unsigned a, b with {outfile="out.dat"};

The filename passed to infile and outfile is a standard string and follows all string
rules, including the need to specify the backslash character as '\\'.

12.15 intime and outtime specifications

The intime specification may be given to an input port or bus, tri-state bus, foreign code
memory or off-chip memory. The outtime specification may be given to an output port
or bus, tri-state bus, foreign code memory or off-chip memory. The specifications are
only valid for EDIF output.

intime specifies the maximum delay in ns allowed between an interface or memory

interface and the sequential elements it feeds. outtime specifies the maximum delay in
ns allowed between an interface or memory interface and the sequential elements it is
fed from. They can be floating-point numbers. For example:

macro expr memoryPins = {"P13", "P12", "P11",

"P10", "P9", "P8", "P7", "P6"};
macro expr dataPins = {"P4", "P3", "P2", "P1"};

interface bus_in(unsigned 4 dataIn) hword()

with {data = dataPins, intime = 5};
interface port_out()
new_hword(unsigned 4 out = hword.dataIn + 1)
with {outtime = 5.2};
ram int 8 a[15][43] with {outtime = 5.2,
offchip = 1,
data = memoryPins};

When applied to Actel ProASIC devices, intime and outtime specifications cause Handel-
C to generate a GCF file for the design. When an Altera device is the target, Handel-C
generates ACF or TCL files. When applied to Xilinx chips, Handel-C generates a a Netlist

www.celoxica.com Page 276

Handel-C Language Reference Manual

Constraints File (NCF). These files are used by the place-and-route tools to constrain the
relevant paths.

12.16 Timing constraints example

This example shows the use of the rate specification and the intime and outtime
specifications to constrain a design for speed. The use of these specifications causes the
generation of a timing constraints file (with the type of file determined by the target
platform).

The design is constrained for a clock speed of 40MHz, with input data from two sources,
taking a maximum of 5.5 and 5.0 nanoseconds, and output data taking a maximum of 4
nanoseconds to transmit.

www.celoxica.com Page 277

Handel-C Language Reference Manual

// Clock
set clock = external "C13" with {rate = 40};

// Data path width

macro expr OpWidth = 8;

// Data pins
macro expr DataInA = {"D5","C5","E7","G8","H9","A5","A6","B5"};
macro expr DataInB = {"B6","D7","F8","E8","G9","F9","G10","H10"};
macro expr DataOut = {"B12","D12","D13","F13","G13","H13","H14","C14"};

// Data In/Out timing requirements

macro expr InTimeRequirementA = 5.5;
macro expr InTimeRequirementB = 5.0;
macro expr OutTimeRequirement = 4;

// Input data
interface bus_in(unsigned OpWidth dina) DINA() with
{
data = DataInA,
intime = InTimeRequirementA
};
interface bus_in(unsigned OpWidth dinb) DINB() with
{
data = DataInB,
intime = InTimeRequirementB
};

// Output data
unsigned result;
interface bus_out() DOUT(unsigned OpWidth dout = result) with
{
data = DataOut,
outtime = OutTimeRequirement
};

// Main program - pipelined multiplier

void main(void)
{
unsigned xx[OpWidth];
unsigned yy[OpWidth];
unsigned rr[OpWidth];

www.celoxica.com Page 278

Handel-C Language Reference Manual

while (1)
{
par
{
// Read operands from input interfaces
xx[0] = DINA.dina;
yy[0] = DINB.dinb;
rr[0] = xx[0][0] ? yy[0] : 0;

/*
* Replicator: generates the pipeline stages of
* the long multiplier, which are done in parallel.
*/
par (Stage=1; Stage<OpWidth; Stage++)
{
xx[Stage] = xx[Stage-1] >> 1;
yy[Stage] = yy[Stage-1] << 1;
rr[Stage] = rr[Stage-1] + (xx[Stage][0] ? yy[Stage] : 0);
}

// Update result
result = rr[OpWidth-1];
}
}
}

www.celoxica.com Page 279

Handel-C Language Reference Manual

12.17 minperiod specification

The minperiod specification specifies the maximum delay in nanoseconds between flip-
flops in a synchronizer. including output delay, setup time and skew at either end). Its
value must be less than the clock period.

The higher the value for minperiod, the less time will be available within a clock tick for
control signals to stabilize (resolutiontime). You may set the value of minperiod or
resolutiontime, but not both. If paranoia has been set to 0, you should use
minperiod.

PERIODS WITH PARANOIA AT ITS DEFAULT OF 1

www.celoxica.com Page 280

Handel-C Language Reference Manual

tmp minperiod

tup unconstrainedperiod

tp clock period

PERIODS IF PARANOIA SET TO 0

In this case, it is possible that the control signal may be metastable within the first flip-
flop, and if minperiod is inadequate, the metastability may be propagated into the rest
of the circuit.

12.18 offchip specification

The offchip specification may be given to a RAM or ROM declaration (you cannot have
offchip MPRAMs). When set to 1, the Handel-C compiler builds an external memory
interface for the RAM or ROM using the pins listed in the clk, addr, data, cs, we and oe
specifications. When set to 0, the Handel-C compiler builds the RAM or ROM on the FPGA
or PLD and ignores any pins given with other specifications. You can use the offchip
specification for EDIF, VHDL or Verilog output.

The compiler generates an error if the ports and offchip specification are both set to 1
for the same memory.

You cannot initialize an offchip RAM.

Example
ram int 8 a[15][43] with {offchip = 1};

www.celoxica.com Page 281

Handel-C Language Reference Manual

12.19 paranoia specification

The paranoia specification controls the number of flip-flops used in synchronization
hardware for channels across clock domains. The higher the value for paranoia, the
higher the stability and latency of the channels. The default is 1, which should be
adequate in most cases. If latency is an issue, it is possible to set paranoia to 0, but the
circuit is more likely to be metastable.

Circuit with paranoia set to default of 1

The diagram below shows a circuit with paranoia set to 1. In this case the
synchronization data goes through one extra flip flop before generating the clock enable
signal for the register.

TIMES WITH PARANOIA AT ITS DEFAULT OF 1

tr time to transfer between domains (paranoia +1 ) x tp

tup unconstrainedperiod

tmp minperiod

tp clock period

www.celoxica.com Page 282

Handel-C Language Reference Manual

Circuit showing constraints if paranoia is set to 0

TIMES WITH PARANOIA SET TO 0

12.20 Pin specifications

The addr, data, we, cs and oe specifications each take a list of device pins and are
used to define the connections between the FPGA/PLD and external devices. The
specifications only have meaning for EDIF, VHDL and Verilog output. If the specifications
are omitted, the place and route tools will assign the pins. The specifications apply to the
following objects:

Specification Meaning Input Output Tri-state RAM ROM

bus bus bus

addr Address pins - - - • •

data Data pins • • • • •
we Write Enable pin - - - • -
cs Chip Select pin - - - • •
oe Output Enable - - - • •
pin
clk Clock pin - - - • •

Pin lists are always given in the order most significant to least significant. Multiple write
enable, chip select and output enable pins can be given to allow external RAMs and ROMs
to be constructed from multiple devices. For example, when using two 4-bit wide chips to
make an 8-bit wide RAM, the following declaration could be used:

www.celoxica.com Page 283

Handel-C Language Reference Manual

ram unsigned 8 ExtRAM[256]

with {offchip=1,
addr={"P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8"},
data={"P9", "P10", "P11", "P12", "P13", "P14", "P15", "P16"},
we={"P17", "P18"},
cs={"P19", "P20"},
oe={"P21", "P22"}
};

12.21 ports specification

The ports specification may be given to a RAM, ROM or MPRAM declaration and is valid
for EDIF, VHDL and Verilog output. When set to 1 the compiler builds an external
memory interface, allowing you to connect to dedicated memory resources on an
FPGA/PLD or to connect to RAMs in external code. You can only use "simple" types for
memories with the ports specification (e.g. int, unsigned; not array or struct).

The compiler generates an error if the ports and offchip specification are both set to 1
for the same memory. All other specifications can be applied.

If you use the ports specification with an MPRAM, a separate interface will be generated
for each port.

You cannot initialize a memory that uses the ports specification.

Examples
mpram
{
ram <unsigned 8> ReadWrite[256]; // Read/write port
rom <unsigned 8> Read[256]; // Read only port
} Joan with {ports = 1, busformat = "B<I>"};

generates EDIF ports with names prefixed by Joan_Read and Joan_ReadWrite. For
example:

(interface
(port Joan_Read_addr<0> (direction INPUT))
(port Joan_Read_addr<1> (direction INPUT))

......

(interface
(port Joan_ReadWrite_addr<0> (direction INPUT))
(port Joan_ReadWrite_addr<1> (direction INPUT))
.....

www.celoxica.com Page 284

Handel-C Language Reference Manual

12.22 properties specification

The properties specification can be given to generic interfaces.

If you are generating EDIF, it is used to parameterize instantiations of external black

boxes. Each valid property is propagated through to the EDIF netlist as an EDIF property.

If you are generating VHDL or Verilog, the result of the properties specification depends
on the value of the bind specification. When the bind specification has a value of 1, it is
used to define generics (VHDL) or parameters (Verilog) when creating a user-defined
interface to an existing VHDL or Verilog code block. When the bind specification is 0, the
properties specification is used to define attributes for black boxes.

Properties are specified as a list of property items, where each item comprises two or
three values:

{property_name, property_value [, property_type]}

• property_name is a string
• property_value can be a string or an integer
• property_type is optional, with 3 possible values (all strings): "integer",
"boolean" or "string"

If your property is a boolean, you need to specify 0 (false) or 1 (true) as the property
value, and specify "boolean" as the type.

If your property is an integer or string, the type can be inferred from the property value
and you do not need to specify it.

Compiler warnings are issued if illegal values are entered, or if there is a mismatch
between the property type and property value.

EDIF Example
unsigned 6 x;
interface ExtThing(unsigned 6 myvar)
Inst1ExtThing(unsigned 6 anothervar = x)

with {properties = {{"LPM_TYPE", "LPM_RAM_DQ"},

{"LPM_WIDTH", 6, "integer"}}, busformat = "B[N:0]"};

This interface will generate an EDIF block with the following EDIF properties: LPM_TYPE
and LPM_WIDTH.

www.celoxica.com Page 285

Handel-C Language Reference Manual

VHDL/Verilog example (bind = 1)

interface ExtThing (unsigned 6 myvar)
Inst1ExtThing(unsigned 6 anothervar = x)
with {bind = 1,
properties = {{"prop1", 0, "integer"},
{"prop2", "SomeString", "string"},
{"prop3", 0, "boolean"},
{"prop4", 1, "boolean"}}};

For Verilog, this interface will generate the instantiation:

ExtThing #(O, // prop1

"SomeString", // prop2
0, // prop3
1) // prop4
InstanceN (.anothervar(x_Out),
.myvar(W_10))

For VHDL, the interface will generate the following component declaration:

component ExtThing
generic (
prop1 : integer := 0;
prop2 : string := "SomeString";
prop3 : boolean := false;
prop4 : boolean := true
);
port (
anothervar : in unsigned(5 downto 0);
myvar : out unsigned(5 downto 0)
);
end component;

and the following component instantiation:

InstanceN : ExtThing
generic map (prop1 => 0,
prop2 => "SomeString",
prop3 => false,
prop4 => true)
port map (anothervar => x_Out,
myvar => globals_W_10
);

www.celoxica.com Page 286

Handel-C Language Reference Manual

VHDL/Verilog example (bind = 0)

When the bind specification has a value of 0, attributes are produced instead of generics
or parameters, for example:

interface ExtThing (unsigned 6 myvar)

Inst1ExtThing(unsigned 6 anothervar = x)
with {bind = 0,
properties = {{"prop1", 0, "integer"},
{"prop2", "SomeString", "string"},
{"prop3", 0, "boolean"},
{"prop4", 1, "boolean"}}};

For Verilog and Precision as an output style, this interface will generate a module
instantiation with the following Precision attributes:

// pragma attribute InstanceN prop1 0

// pragma attribute InstanceN prop2 SomeString
// pragma attribute InstanceN.prop3 0
// pragma attribute InstanceN prop4 1

For VHDL, the interface will generate a component instantiation with the following VHDL
attributes:

attribute prop1: integer;

attribute prop2: string;
attribute prop3: boolean;
attribute prop4: boolean;
attribute prop1 of InstanceN : label is 0;
attribute prop2 of InstanceN : label is "SomeString";
attribute prop3 of InstanceN : label is false;
attribute prop4 of InstanceN : label is true;

Ï For Verilog the properties specification with a bind specification value of 0 is

only supported for Precision output style

12.23 pull specification

The pull specification may be given to an input or tri-state bus. It is only valid for EDIF
output. When set to 1, a pull up resistor is added to each of the pins of the bus. When

www.celoxica.com Page 287

Handel-C Language Reference Manual

set to 0, a pull down resistor is added to each of the pins of the bus. When this
specification is not given for a bus, no pull up or pull down resistor is used.

Actel ProASIC and ProASIC+ devices have a pull-up resistor but no pull-down resistor.
Refer to the appropriate data sheet for details.

Most Altera devices do not have pull-up or pull-down resistors. ApexII, Mercury, Stratix
and Cyclone devices have a pull-up resistor but no pull-down resistor. Refer to the
appropriate data sheet for details.

Refer to the Xilinx FPGA data sheet for details of pull up and pull down resistors.

By default, no pull up or pull down resistors are attached to the pins.

Example
interface bus_clock_in(int 4 in) InBus() with
{ pull = 1,
data = {"P4", "P3", "P2", "P1"}
};

12.24 quartus_proj_assign specification

The quartus_proj_assign specification can be given to bus-type interfaces or offchip
RAM for EDIF output. It allows you to specify Quartus project pins assignments.

Assignments are specified as a list of pairs of items enclosed in braces. The items are
strings, and enclosed in quotes. The first item in each pair specifies the item you are
assigning, and the second item specifies its value:

{"assignment_name", "assignment_value"}

Example
interface bus_out() MyBusOut(unsigned 3 outPort = MyOutExpr)
with {quartus_proj_assign = {{"TERMINATION", "Series"},
{"ENABLE_BUS_HOLD_CIRCUITRY", "On"}},
standard = "HSTL_I", strength = -1}

12.25 rate specification

The rate specification may be given to a clock, and is used to specify the frequency (in
MHz) at which the clock will need to be driven. The specification only applies to EDIF
output (it is ignored for other outputs). The rate specification causes Handel-C to
generate one of the following:

• a Gate-field Constraints File (GCF) for Actel ProASIC and ProASIC+

• an Assignments and Constraints File (ACF) for use with Max+PlusII for non-
Apex Altera devices

www.celoxica.com Page 288

Handel-C Language Reference Manual

• a TCL script (for use with Quartus) for Altera Apex, Cyclone and Stratix
devices
• a Netlist Constraints File (NCF) for Xilinx devices

The place-and-route tools then use these timing requirements to constrain the relevant
paths so that the part of the design connected to the clock in question can be clocked at
the specified rate. In the example below, the clock will need to run at 17.5MHz.

set clock = external_divide "D17" 4

with {rate = 17.5};

When rate is applied to a divided clock (as shown), it is the divided clock that will be
constrained by the specification, not the external clock. Undivided clocks are also
constrained to the appropriate value as calculated from the specified rate and the division
factor.

12.26 rclkpos, wclkpos and clkpulselen

specifications (SSRAM timing)
The rclkpos, wclkpos and clkpulselen may be given to internal or external SSRAM
declarations. They are valid for EDIF, VHDL and Verilog outputs. They are specified as
floating-point numbers in multiples of 0.5. To use these specifications, you must be using
the external_divide or internal_divide clock types with a division factor of 2 or
more.

rclkpos specifies the positions of the clock cycles of the RAM clock for a read cycle.
These positions are specified in terms of cycles of a fast external clock, counting forwards
from the rising edge of the divided Handel-C clock rising edge. You need to write the
value(s) for the specification in braces. For example, with {rclkpos = {1.5}}.

wclkpos specifies the positions of the clock cycles of the RAM clock, for a write cycle. You
need to write the value(s) for the specification in braces. For example, with {wclkpos =
{1.5, 2.5}}.

clkpulselen specifies the length of the pulses of the RAM clock, in terms of cycles of a
fast external clock.

rclkpos, wclkpos and clkpulselen can be applied to the whole of a RAM or MPRAM, or
to individual ports within a memory. Specifications applied to the whole memory will
apply to each port that does not have its own specification. If you apply rclkpos or
wclkpos to the whole memory, the compiler will issue a warning as rclkpos only applies
to the read port(s) and wclkpos only applied to the write port(s). However, the memory
will build correctly.

www.celoxica.com Page 289

Handel-C Language Reference Manual

Illustration

Examples
• Applying RAM clock specifications to ports:
mpram
{
rom int 1 ro[16]
with {rclkpos = {1}, clkpulselen = 0.5};
wom int 1 wo[16]
with {wclkpos = {1.5}, clkpulselen = 0.5};
} Mympram;

• Pipelined-out SSRAM timing

• Flow through SSRAM
• Targeting external synchronous RAMs

www.celoxica.com Page 290

Handel-C Language Reference Manual

12.27 resolutiontime specification

The resolutiontime specification specifies the maximum time in nanoseconds for
metastability to resolve in the channel synchronization hardware. It is needed when you
are using channels to communicate between multiple clock domains. The higher the
value for resolutiontime the less time will be available within a clock tick for
combinational logic in the synchronizer. This only matters if you have set paranoia to 0.

Its value must be less than (clock period x paranoia)where paranoia is > 0. If
paranoia has been set to 0, you should use minperiod rather than resolutiontime.

Either resolutiontime or minperiod may be set, but not both.

Achieving a given value of resolution time

If you need a higher value of resolution time, you can increase the value of the paranoia
specification. The resultant value for minperiod will be clock period -
(resolutiontime/paranoia).

RESOLUTION TIME SUMMED OVER THREE CLOCK TICKS WHEN PARANOIA = 3

12.28 retime specification

In some circumstances it is desirable to prevent some flip-flops in a circuit from being
moved by the retimer. This often occurs when writing interfaces to devices external to

www.celoxica.com Page 291

Handel-C Language Reference Manual

the FPGA or to other IP on the FPGA. The retime specification can be added to any
variable declaration to lock the position of the flip-flops generated by that variable.

unsigned 16 In1, In2 with { retime = 0 };

unsigned 8 SomeOtherVar;
For instance in the code above, variables In1 and In2 are prevented from moving
whereas SomeOtherVar can be moved as required by the retimer to meet the specified
clock rate.

To disable all flip-flops from being retimed in a specific clock domain, the retime
specification can be applied to a clock, for instance:

set clock = external "D17" with { retime = 0 };

12.29 sc_type specification

The sc_type specification may be given to port_in, port_out or generic interfaces to
specify the type of a port in SystemC.

Valid string values of this specification are:

sc_int sc_uint bool sc_logic sc_lv

The default type of a port is bool if the port is 1 bit wide, sc_uint otherwise. You can
apply the sc_type specification to individual ports. If you place the specification at the
end of the interface statement, it will be applied to all the ports.

Example 1: Handel-C ports in SystemC without sc_type specification set:

int X_out;
interface port_in(int 1 To) read();
interface port_out() drive(int 4 From = X_out);

results in Handel-C generating the SystemC ports:

sc_in< bool > To;

sc_out< sc_uint<4> > From;

Example 2: Handel-C ports in SystemC with sc_type specification set:

int X_out;
interface port_in(int 1 To) read() with {sc_type = "sc_logic"};
interface port_out() drive(int 4 From = X_out} with {sc_type = "sc_int"};

results in Handel-C generating the SystemC ports:

sc_in< sc_logic > To;

sc_out< sc_int<4> > From;

www.celoxica.com Page 292

Handel-C Language Reference Manual

12.30 show specification

The show specification may be given to variable, channel, output bus and tri-state bus
declarations. When set to 0, this specification tells the Handel-C simulator not to list this
object in its output. This means that it will not appear in the Variables debug window in
the GUI, but it can be seen in the Watch window.

The default value of this specification is 1.

int 5 x with {show=0};

12.31 speed specification

The speed specification may be given to an output or tri-state bus. It only applies to EDIF
output. The value of this specification controls the slew rate of the output buffer for the
pins on the bus.

For Actel ProASIC and ProASIC+ devices there are three possible values: 0 (slow), 1
(normal) and 2 (fast – default value).

For Altera devices, Xilinx Virtex series and Xilinx Spartan-II and Spartan-3 series, 0 is
slow, 1 is fast, and the default value is 1. Refer to the Altera or Xilinx data sheets for
details of slew rate control.

Example
interface bus_out()
drive(int 4 signals_from_HC = X_out) with {speed=0};

12.32 standard specification

The standard specification may be applied to any external bus interface (not port_in or
port_out) connected to pins to select the I/O standard to be used on all pins of that
interface. It may also be applied to external clocks and to off-chip memories. If the
standard supports it, you can use the strength specification to set the drive current and
the dci specification to set digital controlled impedance. The standard specification only
applies to EDIF output (it is ignored for other outputs).

standard and dci specifications are ignored if you have used the clockport specification
and set it to 0. (The default for clockport is 1.)

Different device families support different standards. Consult the data sheet for a specific
device for details of which standard it supports. The compiler will issue errors if a non-
supported standard is selected for a particular device, or if the standard specification is
used on a family not supporting selectable I/O standards.

www.celoxica.com Page 293

Handel-C Language Reference Manual

12.32.1 Available I/O standards

I/O Handel-C I/O Handel-C I/O Handel-C

standard keyword standard keyword standard keyword
LVTTL "LVTTL" HSTL "HSTL18_II" LVDS (2.5V) "LVDS25"
(1.8v) see note 1
Class I

www.celoxica.com Page 294

Handel-C Language Reference Manual

LVCMOS "LVCMOS33" HSTL "HSTL18_II" LVDS (3.3V) "LVDS33"

(3.3 V) (1.8v)
Class II
LVCMOS "LVCMOS25" HSTL "HSTL18_III BLVDS (2.5V) "BLVDS25"
(2.5 V) (1.8v) " see note 1
Class III
LVCMOS "LVCMOS18" HSTL "HSTL18_IV" LVPECL "LVPECL"
(1.8 V) (1.8v) (3.3V) see
Class IV note 1
LVCMOS "LVCMOS15" SSTL "SSTL2_I" LVDCI (3.3 "LVDCI_33"
(1.5 V) (2.5v) V) - see note
Class I 2
LVCMOS "LVCMOS12" SSTL "SSTL2_II" LVDCI (2.5V) "LVDCI_25"
(1.2 V) (2.5v) - see note 2
Class II
PCI (33 "PCI33_3" SSTL( "SSTL3_I" LVDCI (1.8 "LVDCI_18"
MHz, 3.3 3.3v) V) - see note
V) Class I 2
PCI (33 "PCI33_5" SSTL "SSTL3_II" LVDCI (1.5 "LVDCI_15"
MHz, 5.0 (3.3v) V) - see note
V) Class II 2
PCI (66 "PCI66_3" SSTL "SSTL18_I" LVDCI (3.3 V, "LVDCI_DV2_33
MHz, 3.3 (1.8v) split "
V) Class I termination)
- see note 3
PCI-X "PCIX" SSTL "SSTL18_II" LVDCI (2.5 V, "LVDCI_DV2_25
(1.8v) split "
Class II termination)
- see note 3
GTL "GTL" CTT "CTT" LVDCI (1.8 V, "LVDCI_DV2_18
split "
termination)
- see note 3
GTL+ "GTL+" AGP (1x) "AGP-1X" LVDCI (1.5 V, "LVDCI_DV2_15
split "
termination)
- see note 3

HSTL "HSTL_I" AGP (2x) "AGP-2X"

(1.5v)
Class I
HSTL "HSTL_II" HyperTranspo "HyperTranspo
(1.5v) rt rt"
Class II

www.celoxica.com Page 295

Handel-C Language Reference Manual

HSTL "HSTL_III"
(1.5v)
Class III
HSTL "HSTL_IV"
(1.5v)
Class IV
Notes:

1. The only differential I/Os supported for tri-state interfaces are BLVDS25 on the
VirtexII, VirtexII-Pro and Virtex-4 and LVDS25 and LVPECL33 on the VirtexE.
2. LVDCI standards are equivalent to using LVCMOS standards with a dci
specification of 1
3. LVDCI split termination standards are equivalent to using LVCMOS standards
with a dci specification of 0.5
If no I/O standard is specified, the default for Actel ProASIC and ProASIC+ is LVCMOS33
(with drive strength "High" or "Max"). The default for all other devices is LVTTL (with a
drive current of 12mA in the case of Xilinx families supporting Select I/O).

Examples
set clock = external "C1" with {standard = "HSTL_III"};
interface bus_out()
Eel(int 4 outPort=x)
with {data = dataPinsO, standard = "HSTL_I"};

interface bus_ts(unsigned 3)
Baboon(unsigned 3 ape1 = y, unsigned 1 ape2 = en)
with {data = dataPinsT, standard = "LVTTL", strength = 24};

12.32.2 I/O standards supported by different chips

You can specify the I/O standard for a particular device using the standard specification.
Consult the manufacturer's datasheet for the standards supported by a particular chip.

• Spartan, Spartan XL and Flex10 series devices do not support selectable

standards.
• Actel ProASIC and ProASIC+ only support the LVCMOS33 (default) and
LVCMOS25 standards.
• If you are using differential I/Os with Mercury devices, you need to use the
dedicated pins interfacing to the HSDI (high-speed differential interface)

www.celoxica.com Page 296

Handel-C Language Reference Manual

12.32.3 I/O standard details

The following input/output standards are available in Handel-C. To select a standard, use
the standard specification.

AGP (1x, 2x) – Advanced Graphics Port

The AGP standard is specified by the Advanced Graphics Port Interface Specification
Revision 2.0 introduced by Intel Corporation for graphics applications. AGP is a voltage-
referenced standard requiring a reference voltage of 1.32 V, an input/output source
voltage of 3.3 V and no termination. This standard requires a Differential Amplifier input
buffer and a Push-Pull output buffer.

BLVDS - Bus Low Voltage Differential Signal

BLVDS is a differential I/O scheme, although it is not currently defined by any
IEEE/EIA/TIA industry standards. Unlike LVDS and LVPECL, which are intended for point-
to-point communications, BLVDS allows for bi-directional data transfer over the same set
of transmitter-receiver pin pairs (also known as transceivers). It thus enables
transmission of high-speed differential signals over multipoint backplanes. Due to the bi-
directional transfer capability, 50 ohm termination resistors are needed at both ends of
the transmission line.

CTT – Center Tap Terminated

The CTT standard is a 3.3V memory bus standard, specified by JEDEC Standard JESD 8-
4, Center-Tap-Terminated (CTT) Low-Level, High-Speed Interface Standard for Digital
Integrated Circuits, and sponsored by Fujitsu. CTT is a voltage-referenced standard
requiring a reference voltage of 1.5 V, an input/output source voltage of 3.3 V and a
termination voltage of 1.5 V. The CTT standard is a superset of LVTTL and LVCMOS. CTT
receivers are compatible with LVCMOS and LVTTL standards. CTT drivers, when un-
terminated, are compatible with the AC and DC specifications for LVCMOS and LVTTL.
This standard requires a Differential Amplifier input buffer and a Push-Pull output buffer.

GTL+ – Gunning Transceiver Logic Plus

The GTL+ standard is a high-speed bus standard (JESD 8-3) first used by Intel
Corporation for interfacing with the Pentium Pro processor and is often used for processor
interfacing or communication across a backplane. GTL+ is a voltage-referenced standard
requiring a 1.0 V input reference voltage and board termination voltage of 1.5 V. The
GTL+ standard is an open-drain standard that requires a minimum input/output source
voltage of 3.0 V.

www.celoxica.com Page 297

Handel-C Language Reference Manual

HSTL – High-speed Transceiver Logic

The HSTL standard, specified by JEDEC Standard JESD 8-6, High-Speed Transceiver Logic
(HSTL), is a 1.5 V output buffer supply voltage based interface standard for digital
integrated circuits. This is a voltage-referenced standard, and has four variations or
classes. Classes I & II require a reference voltage of 0.75 V and a termination voltage of
0.75 V; classes III & IV require a reference voltage of 0.9 V and a termination voltage of
1.5 V. All four classes require an input/output source voltage of 1.5 V. This standard
requires a Differential Amplifier input buffer and a Push-Pull output buffer.

HyperTransport
HyperTransport technology is a differential high-speed, high-performance I/O interface
standard. It is a point-to-point standard requiring a 2.5-V VCCIO, in which each
HyperTransport technology bus consists of two point-to-point unidirectional links. Each
link is 2 to 32 bits. The HyperTransport technology standard does not require an input
reference voltage. However, it does require a 100-ohm termination resistor between the
two signals at the input buffer.

LVCMOS (3.3 V) – 3.3 Volt Low-Voltage CMOS

This standard is an extension of the LVCMOS standard and is defined in JEDEC Standard
JESD 8-A, Interface Standard for Nominal 3.0 V/3.3 V Supply Digital Integrated Circuits.
This is a single-ended general-purpose standard also used for 3.3V applications. It uses a
5V-tolerant CMOS input buffer and a Push-Pull output buffer. This standard requires a
3.3V input/output source voltage, but does not require the use of a reference voltage or
a board termination voltage.

LVCMOS (2.5 V) – 2.5 Volt Low-Voltage CMOS

This standard is an extension of the LVCMOS standard and is documented by JEDEC
Standard JESD 8-5, 2.5 V ± 0.2 V (Normal Range) and 1.7 V to 2.7 V (Wide Range)
Power Supply Voltage and Interface Standard for Non-terminated Digital Integrated
Circuit. This is a single-ended general-purpose standard, used for 2.5V (or lower)
applications. It uses a 5V-tolerant CMOS input buffer and a Push-Pull output buffer. This
standard requires a 2.5V input/output source voltage, but does not require the use of a
reference voltage or a board termination voltage. Altera documentation refers to this
standard as simply "2.5 V".

LVCMOS (1.8 V) – 1.8 Volt Low-Voltage CMOS

This standard is an extension of the LVCMOS standard and is documented by JEDEC
Standard JESD 8-7, 1.8 V ± 0.15 V (Normal Range) and 1.2 V to 1.95 V (Wide Range)
Power Supply Voltage and Interface Standard for Non-terminated Digital Integrated

www.celoxica.com Page 298

Handel-C Language Reference Manual

Circuit. This is a single-ended general-purpose standard, used for 1.8V power supply
levels and reduced input and output thresholds. It uses a 5V-tolerant CMOS input buffer
and a Push-Pull output buffer. This standard does not require the use of a reference
voltage or a board termination voltage. Altera documentation refers to this standard as
simply "1.8 V".

LVCMOS (1.5 V) – 1.5 Volt Low-Voltage CMOS

This standard is an extension of the LVCMOS standard. This is a single-ended general-
purpose standard, used for 1.5V applications. It uses a 5V-tolerant CMOS input buffer
and a Push-Pull output buffer. This standard does not require the use of a reference
voltage or a board termination voltage. Altera documentation refers to this standard as
simply "1.5 V".

LVCMOS (1.2 V) - 1.2 Volt Low-Voltage CMOS

This standard is an extension of the LVCMOS standard. This is a single-ended general-
purpose standard, used for 1.2V applications. It uses a 5V-tolerant CMOS input buffer
and a Push-Pull output buffer. This standard does not require the use of a reference
voltage or a board termination voltage.

LVDCI - Low Voltage Digital Controlled Impedance

Xilinx Virtex II devices are able to provide controlled impedance input buffers and output
drivers that eliminate reflections without an external source termination. Output drivers
can be configured as controlled impedance drivers, or as controlled impedance drivers
with half impedance. Inputs can be configured to have termination to VCCO or to VCCO/2
(split termination), where VCCO is the input/output source voltage. All of these are
available at four voltage levels: 1.5 V, 1.8 V, 2.5 V and 3.3 V. For further details, please
refer to the Xilinx Data Book.

LVDS – Low Voltage Differential Signal

LVDS is a differential I/O standard. It requires that one data bit be carried through two
signal lines. The LVDS I/O standard is used for very high-performance, low-power-
consumption data transfer. Two key industry standards define LVDS: IEEE 1596.3 SCI-
LVDS and ANSI/TIA/EIA-644. Both standards have similar key features, but the IEEE
standard supports a maximum data transfer of 250 Mbps. The use of a reference voltage
or a board termination voltage is not required, but a 100 ohm termination resistor is
required between the two traces at the input buffer.

www.celoxica.com Page 299

Handel-C Language Reference Manual

LVPECL – Low Voltage Positive Emitter Coupled Logic

LVPECL is a differential I/O standard. It requires that one data bit be carried through two
signal lines. The LVPECL standard is similar to LVDS. In LVPECL, the voltage swing
between the two differential signals is approximately 850 mV. The use of a reference
voltage or a board termination voltage is not required, but an external termination
resistor is required.

LVTTL – Low Voltage TTL

The Low-Voltage TTL, or LVTTL standard is a single ended, general purpose standard for
3.3V applications that uses an LVTTL input buffer and a Push-Pull output buffer. The
LVTTL interface is defined by JEDEC Standard JESD 8-A, Interface Standard for Nominal
3.0 V/3.3 V Supply Digital Integrated Circuits. This standard requires a 3.3V output
source voltage, but does not require the use of a reference voltage or a termination
voltage.

PCI (33 MHz, 3.3 V) & PCI (66 MHz, 3.3 V) – 3.3 Volt PCI
The PCI standard specifies support for 33 MHz, 66 MHz and 133 MHz PCI bus
applications. It uses a LVTTL input buffer and a Push-Pull output buffer. This standard
requires a 3.3V input output source voltage, but not the use of input reference voltages
or termination.

PCI (33 MHz, 5.0 V) – 5.0 Volt PCI

Some Xilinx devices may be configured in this mode (an extension of the 3.3 Volt PCI
standard), which makes them 5V tolerant. No Altera devices currently support this mode.

PCI-X
The PCI-X standard is an enhanced version of the PCI standard that can support higher
average bandwidth and has more stringent requirements.

SSTL2 – Stub Series Terminated Logic for 2.5 V

The SSTL2 standard, specified by JEDEC Standard JESD 8-9, Stub-Series Terminated
Logic for 2.5 Volts (SSTL-2), is a general purpose 2.5 V memory bus standard sponsored
by Hitachi and IBM. This is a voltage-referenced standard, and has two variations or
classes, both of which require a reference voltage of 1.25 V, an input/output source
voltage of 2.5 V and a termination voltage of 1.25 V. This standard requires a Differential
Amplifier input buffer and a Push-Pull output buffer. SSTL2 is used for high-speed SDRAM
interfaces.

www.celoxica.com Page 300

Handel-C Language Reference Manual

SSTL3 – Stub Series Terminated Logic for 3.3 V

The SSTL2 standard, specified by JEDEC Standard JESD 8-8, Stub-Series Terminated
Logic for 3.3 Volts (SSTL-3), is a general purpose 3.3 V memory bus standard sponsored
by Hitachi and IBM. This is a voltage-referenced standard, and has two variations or
classes, both of which require a reference voltage of 1.5 V, an input/output source
voltage of 3.3 V and a termination voltage of 1.5 V. This standard requires a Differential
Amplifier input buffer and an Push-Pull output buffer. SSTL3 is used for high-speed
SDRAM interfaces.

SSTL18 - Stub Series Terminated Logic for 1.8 V

The SSTL18 standard, specified by JEDEC Preliminary Standard JC42.3, is a general
purpose 1.8V memory bus standard. This is a voltage-referenced standard, and has two
variations or classes, both of which require a reference voltage of 0.90 V, an input/output
source voltage of 1.8 V and a termination voltage of 0.90 V. This standard requires a
Differential Amplifier input buffer and a Push-Pull output buffer. SSTL18 is used for high-
speed SDRAM interfaces.

GTL – Gunning Transceiver Logic Terminated

The GTL standard is a high-speed bus standard (JESD 8-3) invented by Xerox. Xilinx has
implemented the terminated variation for this standard (Altera has not). This standard
requires a differential amplifier input buffer and an Open Drain output buffer.

12.32.4 Differential I/O standards

Differential I/O standards can be used with bus-type interfaces, offchip memories and
external clocks in EDIF output. They are specified using the standard specification. The
differential I/O standards supported by Handel-C are LVDS25, LVDS33, BLVDS25,
LVPECL33 and HyperTransport.

If you want to build a tri-state interface, you can use only the BLVDS25 standard.

To specify pins for a bus_type interface with a differential I/O, use the data specification.
Pins are specified in pairs enclosed in braces:

interface bus_in (unsigned 2 datain) I()

with {standard = "LVDS25",
data = {{"P1", "P2"}, {"P3", "P4"}}}

The first pin in a pair is the positive one. You can omit the second pin of each pair, but
you still need to enclose the single pins within braces.

www.celoxica.com Page 301

Handel-C Language Reference Manual

You also need to specify pair of pins enclosed in braces for pin specifications for offchip
memories (addr, we, cs, oe and clk) when you are using a differential I/O. For example:

ram unsigned 4 ExtRAM[256]

with {offchip=1, standard = "LVPECL33",
addr={{"P1", "P2"}, {"P3", "P4"}, {"P5", "P6"}, {"P7", "P8"}},
data={{"P9", "P10"}, {"P11", "P12"}, {"P13", "P14"}, {"P15", "P16"}},
we={{"P17", "P18"}},
cs={{"P19", "P20"}},
oe={{"P21", "P22"}}
};

If you use a differential I/O for an external clock, the pins are specified using the set
clock construct, rather than the data specification:

set clock = external {"C1", "C2"}

with {standard = "LVDS25"}

The standard specification is ignored for VHDL and Verilog output, but if you have used a
data specification with pairs of pins, and then build the code for VHDL or Verilog output,
the first pin in each pair will be assigned and the other pin will be ignored.

12.33 std_logic_vector specification

The std_logic_vector specification may be given to port_in, port_out or generic
interfaces, where you want to use a std_logic_vector port instead of an unsigned port
in VHDL. Set std_logic_vector to 1 if you want to:

• instantiate an external block of code in Handel-C generated VHDL, and the

external block uses one or more std_logic_vector ports
• produce a block of VHDL that will be linked into another VHDL block that uses
one or more std_logic_vector ports.

The default value for std_logic_vector is 0. You can apply the std_logic_vector
specification to an individual port. If you place the specification at the end of the
interface statement, it will be applied to all the ports.

The std_logic_vector specification is ignored for all outputs except for VHDL

Example 1: Handel-C instantiation of a Bloo component with

std_logic_vector set to 0 (default):
interface Bloo(unsigned 1 myin) B(unsigned 4 myout = x) with
{std_logic_vector = 0};

results in Handel-C generating this VHDL instantiation of the Bloo component:

www.celoxica.com Page 302

Handel-C Language Reference Manual

component Bloo
port (
myin : out std_logic;
myout : in unsigned (3 downto 0)
);
end component;
Example 2: Handel-C instantiation of a Bloo component with
std_logic_vector set to 1:
interface Bloo(unsigned 1 myin)
B(unsigned 4 myout = x) with {std_logic_vector = 1};

results in Handel-C generating this VHDL instantiation of the Bloo component:

component Bloo
port (
myin : out std_logic_vector (0 downto 0);
myout : in std_logic_vector (3 downto 0)
);
end component;

12.34 strength specification

The strength specification may be used in conjunction with the standard specification
on any external bus interface (not port_in or port_out) connected to pins to select the
drive current (in mA) to be used on all pins of that interface. It may also be applied to
off-chip memories. You can only use the strength specification for EDIF output.

Different device families support different values. The compiler will issue warnings if a
non-supported value is selected for a particular device. Check the device datasheet to
confirm what values it supports

The following standards do not support drive strength selection: PCI, GTL, HSTL III, HSTL
IV, CTT, AGP(1x), AGP(2x), LVDS, LVPECL, LVDCI and BLVDS.

The following devices do not support drive strength selection for any standards:
Excalibur, Apex 20, Apex 20KE and Apex 20KC.

Example
interface bus_out() Eel(int 4 outPort = x)
with {data = dataPinsO, standard = "HSTL_I", strength = -1};
interface bus_ts(unsigned 3 inPort) Baboon(ape1 = y, ape2 = en)
with {data = dataPinsT, standard = "LVTTL",
strength = 24};

www.celoxica.com Page 303

Handel-C Language Reference Manual

12.35 synchronous specification

The synchronous specification may be given to a reset signal. The value of this
specification controls whether the reset is synchronous (occurs on next clock tick) or
asynchronous (occurs immediately). The default is asynchronous (0)

Example
set reset = external with {synchronous=1};

12.36 unconstrainedperiod specification

The unconstrainedperiod specification gives the maximum period in nanoseconds on
channel control paths between clock domains. If this specification is not used, the place
and route tools may generate a warning for affected paths crossing the clock domain.

www.celoxica.com Page 304

Handel-C Language Reference Manual

If the specification is used, it applies to unconstrained paths into the clock domain. The
diagram below shows where it is used.

TIMES WITH PARANOIA AT ITS DEFAULT OF 1

tr: time to transfer between domains (paranoia +1 ) x tp

tup: unconstrained period

tmp: minperiod

tp: clock period

set clock = external with {unconstrained period=10};

12.37 vhdl_type specification

The vhdl_type specification may be given to port_in, port_out or generic interfaces to
specify the type of a port in VHDL.

Valid string values of this specification are:

unsigned signed std_logic std_logic_vector

The default type of a port is std_logic if the port is 1 bit wide, unsigned otherwise. You
can apply the vhdl_type specification to individual ports. If you place the specification at
the end of the interface statement, it will be applied to all the ports.

Ï The vhdl_type specification replaces the deprecated std_logic_vector

specification

www.celoxica.com Page 305

Handel-C Language Reference Manual

Example 1: Handel-C instantiation of a Bloo component without

vhdl_type specification set:
interface Bloo(unsigned 1 myin) B(unsigned 4 myout = x);

results in Handel-C generating this VHDL instantiation of the Bloo component:

COMPONENT Bloo
PORT (
myin : OUT std_logic;
myout : IN unsigned (3 DOWNTO 0)
);
END COMPONENT;
Example 2: Handel-C instantiation of a Bloo component with vhdl_type
applied to entire interface:
interface Bloo(unsigned 1 myin)
B(unsigned 4 myout = x) with {vhdl_type = "std_logic_vector"};

results in Handel-C generating this VHDL instantiation of the Bloo component:

COMPONENT Bloo
PORT (
myin : OUT std_logic_vector (0 DOWNTO 0);
myout : IN std_logic_vector (3 DOWNTO 0)
);
END COMPONENT;

Example 3: Handel-C instantiation of a Bloo component with vhdl_type

applied to individual ports:
interface Bloo(unsigned 1 myin with {vhdl_type = "std_logic_vector"} )
B(unsigned 4 myout = x with {vhdl_type = "signed"} );

results in Handel-C generating this VHDL instantiation of the Bloo component:

COMPONENT Bloo
PORT (
myin : OUT std_logic_vector (0 DOWNTO 0);
myout : IN signed (3 DOWNTO 0)
);
END COMPONENT;

www.celoxica.com Page 306

Handel-C Language Reference Manual

12.38 warn specification

The warn specification may be given to a variable, RAM, ROM, channel, bus or clock. It
can be used for any DK output. When set to zero, certain non-crucial warnings will be
disabled for that object. When set to one (the default value), all warnings for that object
will be enabled.

int 5 x with {warn=0};

12.39 wegate specification

The wegate specification may be given to external or internal RAM declarations to place
the write-enable strobe. You can only use this specification with an undivided clock. If it
is used in the absence of SRAM clock specifications (rclkpos, wclkpos and
clkpulselen), it forces the generation of an asynchronous memory or memory port. If
you have a divided clock, use the westart and welength specifications instead. The
wegate specification is valid for EDIF, VHDL and Verilog output.

When the wegate specification is set to 0, the write strobe will appear throughout the
Handel-C clock cycle. When set to -1, the write strobe will appear only in the first half of
the Handel-C clock cycle. When set to 1, the write strobe will appear only in the second
half of the Handel-C clock cycle.

You can apply the specification to the whole of a RAM or MPRAM, or to individual write
ports within an MPRAM. Specifications applied to individual ports take precedence over
specifications applied to the whole memory. Specifications applied to the whole memory
apply to each port that does not have its own specification.

12.40 westart and welength specifications

The westart and welength specifications position the write enable strobe within the
Handel-C clock cycle. If they are used in the absence of SRAM clock specifications
(rclkpos, wclkpos and clkpulselen), they force the generation of an asynchronous
memory or memory port. The specifications may be given to internal or external RAM
declarations. You can only use these specifications together with external_divide or
internal_divide clock types with a division factor greater than 1. If you have an
undivided clock, use the wegate specification instead. westart and welength are valid
for EDIF, VHDL and Verilog output.

westart is used to specify the starting position of the write enable strobe, and welength
is used to specify its length. For both of these specifications, a unit value corresponds to
a single cycle of the fast clock which has been divided in order to generate the Handel-C
clock. The size of welength and westart can be given in multiples of 0.5, but (westart +
welength) must not exceed the clock divide.

www.celoxica.com Page 307

Handel-C Language Reference Manual

You can apply the specification to the whole of a RAM or MPRAM, or to individual write
ports within a memory. Specifications applied to the whole memory will apply to each
port that does not have its own specification.

Examples
//applying the specifications to the whole RAM
set clock = external_divide "P78" 4;
ram unsigned 6 x[34] with {westart = 1, welength = 1.5};

WRITE ENABLE STROBE WITH A WESTART OF 1, A WELENGTH OF 1.5, AND A CLOCK DIVIDE OF 4

//applying the specifications to ports

mpram
{
wom unsigned 6 r[32}
with {westart = 1, welength = 1.5};
wom unsigned 6 s[32];
rom unsigned 6 t[32];
rom unsigned 6 u[32};

} with {westart = 1.5, welength = 0.5};

This example would result in a compiler warning as the specifications at the end would be
applied to all ports that do not have their own specification (s, t and u). t and u are
read-only ports and therefore cannot have write-enable specifications. However, the
mpram would build correctly with the first set of specifications applied to port r and the
second set to port s.

www.celoxica.com Page 308

Handel-C Language Reference Manual

www.celoxica.com Page 309

Handel-C Language Reference Manual

13 Handel-C preprocessor
The preprocessor is invoked by the Handel-C compiler as the first stage in the
compilation process, and is used to manipulate the text of source code files. Correct use
of this tool can simplify code development and the subsequent maintenance process.
There are a number of functions performed by the preprocessor:

• Macro substitution
• File inclusion
• Conditional compilation
• Line splicing
• Line control
• Concatenation
• Error generation
• Predefined macro substitution

Communication with the preprocessor occurs through the use of directives. Directives
are lines within source code which begin with the # character, followed by an identifier
known as the directive name. For example, the directive to define a macro is ‘#define’.

13.1 Preprocessor macros

Simple macros
The preprocessor supports several types of macros. Simple macros (or manifest
constants) involve the simplest form of macro substitution and are defined with the form:

#define name sequence-subsitute

Any occurrences of the token name found in the source code are replaced with the token
sequence sequence-substitute, which may include spaces. All leading and trailing white
spaces around the replacement sequence are removed. For example:

#define FOO 1024

#define loop_forever while (1)

Parameterized macros
You can also define macros with arguments. This allows replacement text to be passed as
parameters. For example:

#define mul(A, B) A*B

This will replace

x = mul (2, 3);

www.celoxica.com Page 310

Handel-C Language Reference Manual

with

x = 2 * 3;

Take care to preserve the intended order of evaluation when passing parameters. For
example the line

x = mul (a – 2, 3);

will be expanded into

x = a – 2 * 3;

The multiplication is evaluated first, then the result subtracted from variable a. This is
almost certainly not the intention, and errors of this type may be difficult to locate.

If a parameter name is preceded by a # when declared as part of a macro, it is expanded

into a quoted string by the preprocessor. E.g., if a macro is defined:

#define quickassert(X) assert (width(X)==1,O "Width of " #X " is not

1!\n");

The line:

quickassert(length);

will expand into:

assert (width(X)==1,O "Width of length is not 1!\n");

Undefining identifiers
To undefine an identifier, the #undef directive may be used. E.g.

#undef FOO

Note that no error will occur if the identifier has not previously been defined.

Ï Preprocessor directives cannot be used unexpanded in a library; use macro

procedures instead.

13.2 File inclusion

File inclusion makes it possible to easily manage and reuse declarations, macro
definitions, and other code. The feature is helpful when writing general purpose functions
and declarations which can be reused for a number of designs. File inclusion is achieved
using directives of the form:

#include "filename"

www.celoxica.com Page 311

Handel-C Language Reference Manual

or

#include <filename>

Such lines are replaced by the contents of the file indicated by filename. If the file name
is enclosed by quotation marks, the preprocessor looks for the file in the directory
containing source code for the current design. If the file cannot be found there, or the file
name is enclosed with angular brackets, the search examines user-defined include file
directories (specified using Tools>Options>Directories), and the main Agility include file
directory.

13.3 Conditional compilation

Conditional directives
You can control preprocessing with conditional directives. These statements can add a
great deal of flexibility to source code. For example, they may be used to alter the
behaviour of a design, depending upon whether a macro definition is present. Conditional
statements must begin with an #if directive and an expression to be evaluated, and end
with the #endif directive. Valid directives are:

#if expression

#elif expression
#else

#endif

Example
#if a==b
// include this section if a is equal to b
#elif a>b
// include this section if a is greater than b
#else
// otherwise include this section
#endif

If the expression is evaluated to be zero, then any text following the directive will be
discarded until a subsequent #elif, #else, or #endif statement is encountered;
otherwise the lines will be included as normal. Note that each directive should be placed
individually on its own line starting at column 0.

A useful application for conditional directives is easy exclusion of code without the use of
comments. For example:

www.celoxica.com Page 312

Handel-C Language Reference Manual

#if (0)
// Code for debugging purposes
#endif
// Code continues

By amending the above evaluation to (1), the code can quickly be included during
compilation.

Conditional definition
To test for the existence of a macro definition, use the following directives:

#ifdef identifier (equivalent to #if defined (identifier))

#ifndef identifier (equivalent to #if !defined (identifier))
These are used in the same way as #if, but are followed by an identifier, rather than an
expression. The #ifndef directive is often used to ensure that source code is only
included once during compilation. E.g.

#ifndef UTILCODE
#define UTILCODE

// Utility code is written here

#endif

13.4 Line control

A directive of the form:

#line integer

instructs the compiler that the next source line is the line number specified by integer.
If a filename token is also present:

#line integer "filename"

the compiler will additionally regard filename as the name of the current input file.

13.5 Concatenation in macros

If a macro is defined with a token sequence containing a ## operator, each instance of
## is removed (along with any surrounding white space), thus concatenating adjacent
tokens into one. For example, if the macro below was declared:

#define million(X) X ## e6

then

www.celoxica.com Page 313

Handel-C Language Reference Manual

i = million (3);

is expanded into:

i = 3e6;

Take care when specifying parameters. In the example above, if 3e6 was passed instead
of 3, then the line would be expanded into:

i = 3e6e6;

which would result in an error.

13.6 Error generation

Fatal error messages may be reported during preprocessing using the directive:

#error error_message

This may be useful with conditional compilation if your design only supports certain
combinations of parameter definitions.

13.7 Predefined macro substitution

The preprocessor contains a number of useful predefined macros which may be placed
into source code:

_ _FILE_ _ Expands to the name of the current file being compiled

_ _LINE_ _ Expands to the number of the current source line
_ _TIME_ _ Expands to the current time of compilation in the form hh:mm:ss
_ _DATE_ _ Expands to the current date of compilation in the form mmm dd
yyyy

13.8 Line splicing

You can splice multiple lines together by placing a backslash character (‘\’) followed by a
carriage return between them. This feature allows you to break lines for aesthetic
purposes when writing code, which are then joined by the preprocessor prior to
compilation. For example, if a macro is defined:

#define ERRORCHECK(error) \
if (error!=0) \
return (error)

The line:

www.celoxica.com Page 314

Handel-C Language Reference Manual

ERRORCHECK(i);

Expands to:

if (i!=0)
return i;

www.celoxica.com Page 315

Handel-C Language Reference Manual

14 Language syntax
The complete Handel-C language syntax is given in BNF-like notation.

The overall syntax for the program is:

program ::= {external_declaration}

void main(void)
{
{declaration}
{statement}
}

Language
external_declaration ::= function_definition
| declaration
| set_statement

14.1 Language syntax conventions

BNF (Backus-Naur Format) is a way to describe the syntax of file formats. It consists of
definitions of the form

identifier ::= definition

The identifier is a word which describes this part of the syntax.

The ::= represents "consists of".
The definition lists the permitted contents of the identifier.

The conventions used in this language reference are:

• Terminal symbols are set in typewriter font like this.

• Non-terminal symbols are set in italic font like this.
• Square brackets [...] denote optional components.
• Braces {...} denotes zero, one or more repetitions of the enclosed
components.
• Braces with a trailing plus sign {...}+ denote one or several repetitions of the
enclosed components.
• Parentheses (...) denote grouping.

14.2 Keyword summary

The keywords listed below are reserved and cannot be used for any other purpose.

www.celoxica.com Page 316

Handel-C Language Reference Manual

Keyword Meaning ANSI-C/C++

?

= assignment operator Yes

; statement terminator Yes
, comma operator Yes
{} code block delimiters Yes
<> type clarifier No
( open delimiter Yes
) close delimiter Yes
[] array index delimiters, Yes
bit selection
[:] bit range selection No
! logical NOT operator Yes
! output to channel No
+ addition operator Yes
- subtraction operator Yes
- unary minus operator Yes
* multiplication operator Yes
/ division operator Yes
% modulo operator Yes
\\ drop LSBs No
<- take LSBs No
? read from channel No
? conditional expression Yes
^ Bitwise XOR Yes
& Bitwise AND Yes
| Bitwise OR Yes
~ bitwise NOT Yes
&& Logical AND Yes1
|| Logical OR Yes1
. structure member Yes
operator
<< left-shift operator Yes
>> right shift operator Yes
< less than operator Yes1
> greater than operator Yes1
<= less or equal operator Not standard1

www.celoxica.com Page 317

Handel-C Language Reference Manual

>= greater or equal Not standard1

operator
== equality operator Not standard1
!= inequality operator Not standard1
++ increment operator Not standard
-- decrement operator Not standard
+= assignment operator Not standard
-= assignment operator Not standard
*= assignment operator Not standard
/= assignment operator Not standard
%= assignment operator Not standard
<<= assignment operator Not standard
>>= assignment operator Not standard
&= assignment operator Not standard
|= assignment operator Not standard
^= assignment operator Not standard
... Reserved. Not valid in Yes
Handel-C, but can be
used for C/C++ calls.
-> structure pointer Yes
operator
@ concatenation operator No
1
Note, the results of these tests are a single bit unsigned int

www.celoxica.com Page 318

Handel-C Language Reference Manual

Keyword Meaning ANSI-C/C++ ?

assert diagnostic macro to print to Not standard

stderr
auto auto variable Yes
break immediate exit from code block Yes
case selection within switch and prialt Yes
chan define channel variable No
chanin simulator channel in No
chanout simulator channel out No
char 8-bit variable Yes
clock define clock No
const specify that variable's value will Yes
not change
continue force next iteration of loop Yes
default default case within switch, Yes
prialt
delay wait one clock cycle No
do start do while loop Yes
double Reserved. Not valid in Handel-C C-only
else conditional execution Yes
enum enumeration constant Yes
expr define macro as expression No
extern define global variable Yes
external clock from device pin No
external_divide clock from device pin with integer No
division
family define target device's family No
float Reserved. Not valid in Handel-C C-only
for for loop iteration Yes
goto jump to specified label Yes
if conditional execution Yes
ifselect conditional compilation on No
compile-time selection
in define scope for local macro No
expression declaration
inline declaration of inline function No

www.celoxica.com Page 319

Handel-C Language Reference Manual

int definable width variable Yes

interface declaration of off-chip interface No
internal use internal clock No
internal_divid internal clock with integer No
division
intwidth set integer width No
let start declaration of local macro No
expression
long declare 32-bit variable Yes
macro declare a macro No
mpram declare a multi-port RAM No
par execute statements in parallel No
part define target hardware No
prialt execute first ready channel No
proc define macro as procedure No
ram declare a RAM (array) No
register declare register variable Yes
releasesema free semaphore No
(semaphore)
reset reset design No
return return from function Yes
rom declare a ROM (array) No
select select expression or macro expr No
at compile time
sema declare a semaphore No
set specify device family or part, int No
width, target, reset or clock
seq execute statements in sequence No
shared declare a shared expression No
short declare 16-bit variable Yes
signal declare a signal object No
signed declare a signed variable Yes
sizeof Reserved. Not valid in Handel-C Yes
static specify variable with limited Yes
scope
struct declare a structure variable Yes
switch switch statement (between Yes
cases)

www.celoxica.com Page 320

Handel-C Language Reference Manual

try execute statements if Condition No

reset(Condition is true during execution within
) related try block
{...}
trysema Test if semaphore owned. Take if No
not.
typedef define type Yes
typeof return type of expression No
undefined specify a variable of undefined No
width
union Reserved. Not valid in Handel-C Yes
unsigned declare an unsigned variable Yes
void specify void return type, Yes
volatile declare volatile variable Yes
while loop statement Yes
width return integer width No
with specify interface, signals, No
channels, RAM and ROM types,
variables etc.
wom declare a WOM (array) No

The following character sequences are also reserved:

/* */ // # " '

14.3 Constant expressions

The following constants are available in Handel-C

• Identifiers
• Integer constant
• Character constants
• String constant
• Floating-point constants

14.3.1 Identifiers: syntax

identifier ::= letter {letter | 0...9}

letter ::= A...Z | a...z | _

www.celoxica.com Page 321

Handel-C Language Reference Manual

14.3.2 Integer constants: syntax

integer_constant ::= [-]{1...9}+{0...9}

| [-](0x | 0X){0...9 | A...F | a...f}+
| [-](0){0...7}
| [-](0b | 0B){0...1}+

14.3.3 Character constants: syntax

character is any printable character or any of the following escape codes.

Escape code ASCII value Meaning

\a 7 Bell (alert)
\b 8 Backspace
\f 12 Form feed
\t 9 Horizontal tab
\n 10 New line
\v 11 Vertical tab
\r 13 Carriage return
\" - Double quote mark
\0 0 String terminator
\\ - Backslash
\’ - Single quote mark
\? - Question mark

14.3.4 Strings: syntax

string ::= "{character}"

14.3.5 Floating-point constants: syntax

float_constant::=
[{0...9}+].{0...9}+[(e | E)[+|-]{0...9}+][f | F | l | L]
| {0...9}+.[(e | E)[+|-]{0...9}+][f | F | l | L]
| {0...9}+(e | E)[+|-]{0...9}+[f | F | l | L]

www.celoxica.com Page 322

Handel-C Language Reference Manual

14.4 Functions and declarations: syntax

function_definition ::= declaration_specifiers declarator
compound_ statement [ with initializer ;]
| declarator compound_statement [ with initializer ;]

declaration ::= declaration_specifiers [ init_declarator_list ] [with

initializer ] ;
| interface_declaration
| macro_declaration

declaration_specifiers ::= storage_class_specifier [ declaration_specifiers

]
| type_specifier [ declaration_specifiers]
| type_qualifier [ declaration_specifiers]

storage_class_specifier ::= auto

| register
| inline
| typedef
| extern
| static

type_specifier ::= void

| char
| short
| int
| long
| float
| double
| signed
| unsigned
| typeof ( expression )
| signal_specifier
| channel_specifier
| ram_specifier
| struct_or_union_specifier
| enum_specifier
| typedef_name

type_qualifier ::= const

| volatile

www.celoxica.com Page 323

Handel-C Language Reference Manual

typedef_name ::= identifier

init_declarator_list ::= declarator

[= initializer] { ,declarator [= initializer]}

14.5 Macro/shared exprs/procs: syntax

macro_declaration ::= macro_proc_decl
| macro_expr_decl

macro_proc_decl ::= [ static | extern]

macro_proc_spec identifier
[ ( [ macro_param{, macro_param} ] )] statement
[ with initializer ;]

macro_expr_decl ::= [ static | extern]

macro_expr_spec identifier
[ ( [macro_param{, macro_param} ] )] ;
| [ static | extern] macro_expr_spec identifier
[ ( [macro_param{, macro_param} ] )] = let_initializer
[with initializer ] ;

macro_proc_spec ::= macro proc

macro_expr_spec ::= macro expr

| shared expr

let_initializer ::= initializer

| let macro_expr_decl in let_initializer

macro_param ::= identifier

www.celoxica.com Page 324

Handel-C Language Reference Manual

14.6 Interfaces: syntax

interface_declaration ::= interface identifier
( [int_parameter_declaration
{ , int_parameter_declaration} ] ) identifier
([ assignment_expr_spec {, assignment_expr_spec } ] )
[with initializer];
| interface_type_declarator
| old_style_interface_declarator

interface_type_declarator :: = interface identifier

( [ int_parameter_proto{ , int_parameter_proto}] )
identifier ( [int_init_parameter_declaration
{ ,
int_init_parameter_declaration} ] )

This format is deprecated but retained for compatibility reasons:

old_style_interface_declarator ::= interface identifier

( [int_parameter_declaration {, int_parameter_declaration}] )
identifier ([ assignment_expr_spec {,assignment_expr_spec})
[with initializer ] ;

interface ::= [ static | extern] interface

int_parameter_proto::= declaration_specifiers
| declaration_specifiers declarator
| declaration_specifiers abstract_declarator
| declaration_specifiers width

int_parameter_declaration ::= declaration_specifiers [with initializer ]

| declaration_specifiers declarator [with initializer ]
| declaration_specifiers abstract_declarator [ with initializer ]
| declaration_specifiers width [with initializer ]

int_init_parameter_declaration ::= int_parameter_declaration

| declaration_specifiers declarator [ = initializer
] [with initializer ]

assignment_expr_spec ::= assignment_expression [with initializer ]

www.celoxica.com Page 325

Handel-C Language Reference Manual

14.7 Structures and unions: syntax

struct_or_union_specifier ::= aggregate_form [ identifier] {
{struct_declaration}+ }
| aggregate_form identifier

aggregate_form ::= struct

| union
| mpram

struct_declaration ::= { type_specifier | type_qualifier}+

{struct_declarator} + [with initializer ];

struct_declarator ::= declarator

| [declarator]: constant_expression

Ï The current version of Handel-C does not support unions.

14.8 Enumerated types: syntax

enum_specifier ::= enum [ identifier ] { enumerator {,[ enumerator]} }
| enum identifier
enumerator ::= identifier
| identifier = constant_expression

14.9 Signal specifiers: syntax

signal_specifier ::= signal < type_name >
| signal

14.10 Channel syntax

channel_specifier ::= chan [ < type_name > ]
| chanin [ < type_name > ]
| chanout [ < type_name > ]

www.celoxica.com Page 326

Handel-C Language Reference Manual

14.11 Ram specifiers: syntax

ram_specifier ::= ram [ < type_name > ]
| rom [ < type_name > ]
| wom [ < type_name > ]

14.12 Declarators: syntax

declarator ::= [ width ] pointer direct_declarator

width ::= undefined

| primary_expression

direct_declarator ::= identifier

| ( pointer direct_declarator )
| direct_declarator [ [constant_expression] ]
| direct_declarator ( [ {parameter_declaration}+ ] )

pointer ::= *
| * type_qualifier
| * pointer
| * type_qualifier pointer

14.13 Function parameters: syntax

parameter_declaration ::= declaration_specifiers
| declaration_specifiers width
| declaration_specifiers abstract_declarator
| declaration_specifiers declarator

www.celoxica.com Page 327

Handel-C Language Reference Manual

14.14 Type names and abstract declarators:

syntax
type_name ::= { type_specifier | type_qualifier}+
| { type_specifier | type_qualifier}+ abstract_declarator
| { type_specifier | type_qualifier}+ width

abstract_declarator ::= [width] pointer direct_abstract_declarator

direct_abstract_declarator ::= ( pointer direct_abstract_declarator )

| [direct_abstract_declarator][ [constant_expression] ]
| [direct_abstract_declarator] ( [ {parameter_declaration}+ ] )

14.15 Statements: syntax

statement ::= semi_statement ;
| non_semi_statement

semi_statement ::= expression_statement

| do statement while ( expression )
| jump_statement
| assert ( constant_expression [, assignment_expression {,
assignment_expression}] )
| delay
| channel_statement
| set_statement

non_semi_statement ::= labelled_statement

| compound_statement
| selection_statement
| iteration_statement

The following statements can appear in for start/end conditions:

www.celoxica.com Page 328

Handel-C Language Reference Manual

for_statement ::= non_semi_statement

| expression_statement
| do statement while ( expression )
| assert ( constant_expression , constant_expression
[, assignment_expression{, assignment_expression}] )
| delay
| channel_statement

These are the statements that can appear in prialt blocks:

www.celoxica.com Page 329

Handel-C Language Reference Manual

prialt_statement ::= semi_statement ;

| non_semi_prialt_statement

non_semi_prialt_statement ::= prialt_labelled_statement

| compound_statement
| selection_statement
| iteration_statement

labelled_statement ::= identifier : statement

| case constant_expression : statement
| default : statement

prialt_labeled_statement ::= identifier : prialt_statement

| case channel_statement : prialt_statement
| default : prialt_statement

expression_statement ::= [ expression ]

channel_statement ::= unary_expression ! expression

| logical_or_expression ? expression

jump_statement ::= goto identifier

| continue
| break
| return
| return expression

selection_statement ::= if ( expression ) statement if

| if ( expression ) statement else statement
| ifselect ( constant_expression ) statement if
| ifselect ( constant_expression ) statement else statement
| switch ( expression ) statement
| prialt { [{ prialt_statement }+] }

set_statement ::= set part = STRING

| set clock = clock
| set family = identifier
| set intwidth = constant_expression
| set intwidth = undefined
| set reset = reset

clock ::= internal expression [with initializer ]

www.celoxica.com Page 330

Handel-C Language Reference Manual

| external expression [with initializer ]

| internal_divide expression expression [with initializer ]
| external_divide expression expression [with initializer ]

reset ::= internal expression

| external expression

iteration_statement ::= while ( expression ) statement

| for ( [for_statement] ; [ expression] ;
[ for_statement] ) statement

14.15.1 Compound statements with replicators

compound_statement ::= [seq | par] {{ declaration} {statement} }

| [seq | par] ( [repl_macro_param{, repl_macro_param}]
;constant_expression;
[repl_update_param {, repl_update_param}] ) {{declaration} {statement}
}

14.16 Replicators: syntax

Replicator initialization definitions
repl_macro_param ::= repl_param = initializer
| ( repl_param = initializer )

Replicator update definitions

repl_update_param ::= repl_update_param_body
| ( repl_update_param )

repl_update_param_body ::= repl_param assignment_operator initializer

| ++ repl_param
| repl_param ++
| -- repl_param
| repl_param --

repl_param ::= identifier

| ( repl_param )

www.celoxica.com Page 331

Handel-C Language Reference Manual

14.17 Expressions: syntax

constant_expression ::= assignment_expression

expression ::= assignment_expression

| expression, assignment_expression}

assignment_expression ::= conditional_expression

| unary_expression assignment_operator assignment_expression

assignment_operator ::= = | *= | /= | %= | += | -= | <<= | >>=

| &=
| ^= | |=

initializer ::= assignment_expression

conditional_expression ::= logical_or_expression

| logical_or_expression ? expression : conditional_expression

logical_or_expression ::= logical_and_expression

| logical_or_expression || logical_and_expression

logical_and_expression ::= inclusive_or_expression

| logical_and_expression && inclusive_or_expression

inclusive_or_expression ::= exclusive_or_expression

| inclusive_or_expression | exclusive_or_expression

exclusive_or_expression ::= and_expression

| exclusive_or_expression ^ and_expression

and_expression ::= equality_expression

| and_expression & equality_expression

equality_expression ::= relational_expression

| equality_expression == relational_expression
| equality_expression != relational_expression

relational_expression ::= cat_expression

| relational_expression < cat_expression
| relational_expression > cat_expression
| relational_expression <= cat_expression

www.celoxica.com Page 332

Handel-C Language Reference Manual

| relational_expression >= cat_expression

cat_expression ::= shift_expression

| cat_expression @ shift_expression

shift_expression ::= additive_expression

| shift_expression << additive_expression
| shift_expression >> additive_expression

additive_expression ::= multiplicative_expression

| additive_expression + multiplicative_expression
| additive_expression - multiplicative_expression

multiplicative_expression ::= take_drop_expression

| multiplicative_expression * take_drop_expression
| multiplicative_expression / take_drop_expression
| multiplicative_expression % take_drop_expression

take_drop_expression ::= cast_expression

| take_drop_expression <- cast_expression
| take_drop_expression \\ cast_expression

cast_expression ::= unary_expression

| ( type_name ) cast_expression

unary_expression ::= postfix_expression

| ++ unary_expression
| -- unary_expression
| unary_operator cast_expression
| sizeof unary_expression
| sizeof ( type_name )
| width ( expression )

unary_operator ::= & | + | - | ~ | ! | *

postfix_expression ::= select_expression

| postfix_expression [ expression ]
| postfix_expression [ expression : expression ]
| postfix_expression [ : expression ]
| postfix_expression [ expression : ]
| postfix_expression [ ]

www.celoxica.com Page 333

Handel-C Language Reference Manual

| postfix_expression ( [assignment_expression {,
assignment_expression}] )
| postfix_expression . identifier
| postfix_expression -> identifier
| postfix_expression ++
| postfix_expression --

select_expression ::= primary_expression

| select ( constant_expression , constant_expression ,
constant_expression )

primary_expression ::= identifier

| constant
| ( expression )
| { }
| {[initializer {, initializer}[, ] ]}

constant ::= integer_constant

| character_constant
| string_constant

integer_constant ::= NUMBER

character_constant ::= CHARACTER

string_constant ::= STRING

www.celoxica.com Page 334

Handel-C Language Reference Manual

== (equal to) ............................... 106

15 Index > (greater than) ........................... 106

-- (postfix and prefix operators) ........ 95 -> (structure pointer operator)........ 109

- (subtraction) .............................. 104 >= (greater than or equal) ............. 106

! ............................................ 44, 107 >> (shift operator)........................ 102

!= ............................................... 106 1.2V ..................................... 286, 292

## (macro concatenation).............. 306 1.5V ..................................... 286, 292

#define ....................................... 303 1.8V ..................................... 286, 291

#elif ............................................ 305 2.5V ..................................... 286, 291

#else .......................................... 305 3.3V ..................................... 286, 291

#endif ......................................... 305 33MHz 3.3V........................... 286, 293

#ifdef .......................................... 305 33MHz 5.0V........................... 286, 293

#ifndef ........................................ 305 66MHz 3.3V........................... 286, 290

#include ..........................41, 116, 304 abstract declarators ....................... 321

#undef ........................................ 303 ACF files ............................... 269, 281

% (modulo).................................. 104 Actel..................................... 180, 183

(line breaker) ............................... 307 devices 180, 183

*/ (comments delimiter) .................. 10 on-chip RAM 210

. (structure member operator) ........ 109 specifying reset pin 186

/ (division) ................................... 104 addition ....................................... 104

/* (comments delimiter) .................. 10 addr ............................................ 276

// (comments delimiter) ................... 10 AGP...................................... 286, 290

?............................................ 44, 109 AGP I/O standard ............ 286, 289, 290

@ (concatenation) ......................... 102 AGP-1X 286

[ ] (bit selection)........................... 103 AGP-2X 286

\ (drop operator)........................... 102 algorithms...............................22, 178

^ (bitwise XOR) ............................ 108 debugging 22, 178

__clock ........................................ 162 Altera ............................ 180, 183, 211

__isfamily() construct .................... 182 devices 180, 183

+ (addition) ................................. 104 on-chip RAM 211

++ (prefix and postfix operators) ...... 95 ROMs 256

< (less than) ................................ 106 ampersand (address operator) .......... 43

<- (take operator)......................... 102 ANSI-C .................................... 15, 25

<< (shift operator)........................ 102 calling from Handel-C 65

<= (less than or equal).................. 106 compared to Handel-C 15, 25

<> (type qualifier) .......................... 72 Apex devices ......................... 180, 183

= (assignment)............................... 81 arithmetic operators 104

www.celoxica.com Page 335

Handel-C Language Reference Manual

constraints files 281 bitwise logical operators ................. 108

I/O standards supported 289, 296 bitwise AND 108
mprams 59 bitwise NOT 108
RAM 211 bitwise OR 108
architectural types........................... 44 bitwise XOR 108
arithmetic operators ...................... 104 block RAM .................................... 256
arrays ....................34, 36, 46, 56, 119 block specification ......................... 256
channels blocks................................... 178, 256
arrays ...................................... 46 data transfer 178

functions 119, 120, 121 BLVDS .................................. 286, 290

indices 36 BLVDS I/O standard ........ 286, 290, 294

multi-dimensional 34, 56 break ............................78, 86, 88, 89

pointers to 34 breaking lines ............................... 307

assert............................................ 99 buffer specification ........................ 259

assertion failed ............................... 99 BUFG........................................... 262

assignments ................................... 81 bus_clock_in.......................... 218, 221

asterisk (indirection operator) ........... 43 bus_in .................................. 218, 219

asynchronous RAM .......... 187, 192, 300 bus_latch_in .......................... 218, 220

divided clock 300 bus_out ................................ 218, 221

examples 188, 190 bus_ts .................................. 218, 221

generating 300 bus_ts_clock_in ..................... 218, 224

timing 187 bus_ts_latch_in...................... 218, 222

undivided clock 300 buses50, 52, 219, 220, 221, 230, 233,
243
asynchronous reset ................. 186, 297
bidirectional 221, 222, 224
attributes ..................................... 245
clocked 221
auto .............................................. 64
input 219
base specification .......................... 254
latched 220
basic concepts ..................................5
naming 243
bidirectional data transfers221, 222, 224
read/write 221
clocked input 224
read/write clocked 224
registered input 222
registered 220, 222
binary............................................ 30
simulating 230
bind specification .......................... 254
specification 50, 52
bit fields ........................................ 38
timing 233, 235
bit manipulation ............................ 101
write 221
operators 101
busformat specification ........... 243, 259
bit selection.................................. 103

www.celoxica.com Page 336

Handel-C Language Reference Manual

C language................................15, 25 clockport specification .................... 262

compared to Handel-C 15, 25 clocks .....................141, 160, 161, 162
C++.............................................. 65 clock domains 162, 172
calling from Handel-C 65 clock pins 231, 261
type mapping in Handel-C 65 current 162
case .............................................. 88 cycles 195
casting ..........................17, 39, 96, 97 dummy 160
chan....................................... 44, 319 external 161
chanin .................................. 177, 319 external resynchronization 172
channels ............................... 6, 44, 46 fast 187, 193
arrays 46 internal 161
between clock domains 162, 164, 166, inverted 193, 196
168, 238 locating 160
chanin and chanout 177 multiple 160, 162, 172
channels period 154
arrays ...................................... 46 position specifications 282
communication 6, 44, 162, 164 reading from external pins 221
examples 164 resynchronizing 172
metastability 237, 238 simulation 160
reading from 44 source 160
restrictions 46 specifying 160
simulating 177 SSRAM 193, 196
simultaneous access 46 SSRAMs 193, 195, 196, 261
specifying 319 combinational loops ...........90, 149, 262
syntax 319 comments ...................................... 10
writing to 44 communication ............. 6, 44, 162, 164
chanout ................................ 177, 319 between clock domains 162, 164
char .............................................. 32 channels 6, 44, 164
character constants ....................... 315 comparison ........................... 106, 107
chips ........................................... 180 implicit 107
clk ....................................... 204, 261 operators 106
clkpulselen ............................ 195, 282 signed/unsigned 107
clock cycles used.................... 141, 147 compile-time .............. 70, 99, 131, 132
clock pin specifications ................... 261 messages 99
clock position specifications ............ 282 selection 70, 131, 132
clock rate..................................... 281 complex declarations ................. 69, 71
clocked reading from external pins... 221 complex expressions.................. 72, 95

www.celoxica.com Page 337

Handel-C Language Reference Manual

compound statements with replicators file format 178

.................................................. 324 input and output 22
concatenation ........................ 102, 306 data specification .......................... 264
operator 102 dci specification ............................ 265
preprocessor 306 DDR devices ................................. 193
conditional compilations ................. 305 debug............................................ 99
conditional directives ..................... 305 assertions 99
conditional execution (if ... else)........ 84 decimal.......................................... 30
conditional operator................ 109, 131 declarations........................... 118, 320
const ............................................. 71 disambiguating 72
constant expressions ..................... 314 functions 118
constant macro expressions............ 130 interfaces 49
constants ................................ 30, 315 mpram 57
binary 30 RAM 54
character 315 ROM 54
decimal 30 syntax 320
hexadecimal 30 declarators ................................... 320
manifest 303 default..................................... 78, 88
octal 30 defining the clock .......................... 160
constraints ..............264, 269, 270, 281 delay ...............................90, 141, 147
files 269, 281 device specifiers............................ 183
pins 264 devices ........... 179, 180, 182, 183, 218
timing 269, 270, 281 detecting current device 182
continue ........................................ 82 external 218
conversion .......................... 17, 96, 97 specifying 183
cs ............................................... 276 differential.................................... 294
CTT ...................................... 286, 290 differential I/O standards................ 294
CTT I/O standard ............ 286, 289, 290 Digital Controlled Impedance .......... 265
current clock ................................ 162 disambiguator................................. 72
Cyclone devices ..................... 183, 209 division ........................................ 104
constraints files 281 do ... while ............................... 86, 89
I/O standards supported 289, 296 does not equal .............................. 106
mprams 57, 59 domains......................... 162, 168, 172
pull-up resistors 280 channel timing 168
RAMs 211 multiple clocks 162, 172
targeting embedded memory 209 double ....................................16, 309
data ....................................... 22, 178 drop operator ............................... 102

www.celoxica.com Page 338

Handel-C Language Reference Manual

EAB............................... 180, 211, 256 extern (linking to C/C++ code) ......... 65

EDIF..................................... 243, 259 external clocks................ 161, 187, 189
buses 259 external hardware ......................... 218
wire names 243 external ROMs .............................. 212
efficiency ..................................... 154 external variables............................ 65
else............................................... 84 external_divide ...................... 160, 161
enum ..................................... 37, 319 extfunc ........................................ 266
enumerated types .................... 37, 319 extinst ......................................... 266
equal to ....................................... 106 extlib........................................... 266
error generation....................... 99, 307 extpath........................................ 268
ESB...................................... 180, 256 families.......................... 179, 180, 183
examples recognized 180, 183
asynchronous RAM 188, 190 fast external clock ......................... 187
between clock domains 164 fifolength ..................................... 268
function pointers 123 FIFOs ...................................... 6, 268
functions 114, 120, 121 code example 46, 145
interfacing to hardware 225 timing 144
macros 114 files............................................. 304
mprams 61 including 304
optimizing code 123, 154, 157 reading and writing 178
prialt 79 timing constraints 269, 281
SSRAM 200, 205, 207 Flex devices........................... 180, 183
targeting external RAM 192, 204 constraints files 281
targeting ports to specific tools 243 I/O standards supported 289
timing 141, 152, 270 RAMs 211
Excalibur devices ................... 180, 183 float .......................................16, 309
I/O standards supported 289, 296 floating-point arithmetic ................... 16
RAM 211 floating-point constants.................. 315
exit from code block ........................ 89 for loops .................................. 86, 89
expressions ....................... 23, 95, 314 differences from ANSI-C 86
comparison with ANSI-C 23 formatting bus and wire names ....... 243
complex 72 FPGA devices ......................... 179, 180
constant 314 function calls ................................ 127
shared 135, 136 parallel 127
syntax 325 simultaneous 127
timing 95 functions........... 19, 111, 114, 117, 118
extern (external variables) ............... 65 arrays 119, 120, 121

www.celoxica.com Page 339

Handel-C Language Reference Manual

clock cycles 114, 141 syntax 309

compared to macros 111, 113, 114 types 14
definitions and declarations 118 values and widths 29
differences to ANSI-C 19 Handel-C preprocessor ................... 303
examples 114 hardware ..................................... 177
inline 68 interfaces 177, 225
parameters 320 hexadecimal ................................... 30
pointers 122, 123 HSTL I/O standard........... 286, 289, 291
prototypes 118 Class I 286
restrictions 117, 127, 129 Class II 286
returning macro expr 71 Class III 286
scope 119 Class IV 286
shared 127 I/O standards .. 265, 286, 289, 290, 294
syntax 316, 320 differential 294
GCF files ............................... 269, 281 I/O standards supported 289, 296
generic interfaces.......................... 218 IBUFG.......................................... 262
generics (VHDL)............................ 278 identifiers..................................... 314
getting started ..................................5 if...else .......................................... 84
goto .............................................. 83 ifselect......................................... 132
greater than ................................. 106 implicit compares .......................... 107
greater than or equal to ................. 106 in (let...in) ................................... 137
GTL I/O standard .....286, 289, 290, 294 indirection operator ......................... 43
GTL 286, 290, 294 indirection techniques ................ 39, 43
GTL+ 286, 290 inferring widths............................... 33
Handel-C5, 12, 14, 15, 25, 29, 75, 95, infile............................................ 269
111, 245, 309 initialization.............................. 59, 73
code 5 MPRAM 59
compared to ANSI-C 15, 25 RAM and ROM 54, 210, 211
expressions 95 structures 36
functions 111 variables 73
getting started 5 inline ....................................... 64, 68
keywords 309 input .............. 220, 221, 269, 290, 294
macros 111 clocked 221
object specifications 245 files 269
operators 12 latched 220
programs 5 standards 286, 290, 294
statements 75 int................................................. 31

www.celoxica.com Page 340

Handel-C Language Reference Manual

integer ................................... 31, 315 labels ............................................ 83

constants 315 language basics ................................9
range 31 language summary ..........9, 15, 25, 309
syntax 315 language syntax............................ 309
interfaces..................... 49, 50, 52, 218 latch............................................ 220
bidirectional buses 221, 222, 224 register 220
bus_* interfaces 219, 220, 221, 222, latency ............................48, 157, 169
224 left shift ....................................... 102
customized 218, 242 less than ...................................... 106
debugging 228 less than or equal to ...................... 106
declaration 49, 51 let ... in ....................................... 137
definition 50, 52 line control ................................... 306
format 242 line splicing .................................. 307
generic 218, 242 loc attribute.................................. 264
overview 49 locating the clock .......................... 160
pointers 42 logic depth ................................... 154
port_* interfaces 241 reducing 154
simulating 228 logic types...................................... 31
sorts 218 logical operators ........................... 107
specification 50, 52 long .............................................. 32
syntax 318 loops ..................... 20, 85, 86, 89, 149
types 218 combinational 149
interfacing...................... 177, 218, 241 do ... while 86
with external hardware 218 for loops 86
with external logic 218, 241 termination 89
with memory 186, 213 while loops 85
with the simulator 177 LVCMOS I/O standard286, 289, 291, 292
internal clocks ....................... 160, 161 1.2V 286, 292
internal RAM and ROM ..................... 54 1.5V 286, 292
internal_divide....................... 160, 161 1.8V 286, 291
intime................................... 269, 270 2.5V 286, 291
intwidth ......................................... 33 3.3V 286, 291
inverted clocks................ 193, 196, 273 LVDCI I/O standard ..265, 286, 289, 292
ISO-C .......................................15, 25 1.5V 286
calling from Handel-C 65 1.8V 286
compared to Handel-C 15, 25 2.5V 286
keywords ..................................... 309 3.3V 286

www.celoxica.com Page 341

Handel-C Language Reference Manual

split termination 265, 286 RAM 54, 186

LVDS I/O standard ...286, 289, 292, 294 restrictions 97
LVPECL I/O standard 286, 289, 293, 294 ROM 54, 186
LVTTL I/O standard ......... 286, 289, 293 simultaneous access 97
macro expressions71, 130, 131, 133, specifications 256, 274
135, 136 synchronous 193, 204, 261, 282
in widths 71 type 256
macro procedures .................. 138, 139 WOM 62
macros ............111, 130, 131, 138, 303 Xilinx 212
compared to functions 111, 113, 114 Mercury devices ..................... 180, 183
differences to ANSI-C 19 I/O standards supported 289, 296
examples 114 mprams 57
introduction 130 pull up resistors 280
parameterized 131, 138 RAM 211
preprocessor 303 merging pins ......................... 231, 232
recursion 133, 135, 136 metastability........................... 168, 235
substitution 303, 307 channels across clock domains 168,
syntax 317 237, 238
main function ...................................9 clock domains 168
malloc ........................................... 22 examples 172
manifest constants ........................ 303 external resynchronization 172
mapping of different width ports........ 59 stabilizing data in interfaces 236
maximum clock rate ...................... 154 MIF files....................................... 211
member operators......................... 109 minperiod .............................. 167, 273
memory. 54, 57, 62, 186, 187, 193, 196 modulo arithmetic ......................... 104
Actel 210 mpram (multi-ported RAM) .... 57, 59, 61
allocation 22 multidimensional arrays ................... 56
Altera 211 multi-file projects .......................... 116
asynchronous 187, 192, 300 multiple ................................ 160, 162
block 256 channel timing issues 163, 166
initialization 54 communicating between clock domains
multi-port 57 162, 172
off-chip 274 multiple clocks ....................... 160, 162
on Cyclone devices 209 multiplication ................................ 104
on Stratix devices 209 -N option ..................................... 196
on-chip 180, 210, 211, 212 NCF files ............................... 269, 281
pipelining 196, 207 not equal to.................................. 106
object specifications....................... 245

www.celoxica.com Page 342

Handel-C Language Reference Manual

octal.............................................. 30 programs 5
oe ............................................... 276 statements 75
offchip ......................................... 274 structure 9
on-chip RAMs ..........180, 210, 211, 212 parameterized macro expressions .... 131
operators12, 101, 102, 104, 106, 107, parameters............................ 111, 278
108, 109 functions 111
arithmetic 104 macros 111
bit manipulation 101 Verilog 278
bitwise logical 108 paranoia ................................ 169, 275
comparison 106 PCI I/O standard ............. 286, 289, 293
concatenation 102 33MHz 3.3V 286, 293
conditional 109 33MHz 5.0V 286, 293
drop 102 66MHz 3.3V 286, 290
logical 107 PCI-X 286, 293
precedence 12 pin specifications.................... 264, 276
relational 106, 107 omitting 276
shift 102 pin_number attribute ..................... 264
summary 12 pinouts ........................................ 276
take 102 specifying 276
trysema 92 pins................ 218, 231, 232, 264, 276
width 104 constraining 264
optimizing code............... 123, 154, 157 merging 231, 232
examples 123, 154, 157 naming 264
outfile.......................................... 269 reset 186
output ....................269, 286, 290, 294 specifying 276
files 269 tri-state 232
standards 286, 290, 294 pipelining ................. 76, 157, 196, 207
outtime................................. 269, 270 examples 207
overflow ........................................ 29 PLD devices ....................179, 180, 183
overview of Handel-C5, 12, 14, 15, 25, pointers ....................... 39, 41, 42, 122
29, 36, 75, 95, 111, 245, 309
addresses 41
padding ............................ 29, 38, 102
casting 17
par...........................................75, 76
declaration 39
parallel ...................... 5, 9, 44, 75, 151
operations 39
access to variables 151
to arrays 34
branch synchronization 6, 44, 164
to functions 122, 123
execution 75
to interfaces 42
functions 119

www.celoxica.com Page 343

Handel-C Language Reference Manual

port_in ................................. 218, 241 quartus_proj_assign specification .... 281

port_out ............................... 218, 241 RAM ........................ 57, 186, 187, 193
porting C to Handel-C ...................... 32 Actel 210
ports .................................... 241, 277 Altera 211
interfacing with external logic 241 arrays 56
port names 241, 264 asynchronous 187, 192, 300
specification 277 block RAM 256
precedence .................................... 12 different to arrays 54
preprocessor .................. 303, 305, 306 external 188, 190, 192
concatenation 306 foreign code 213
conditional compilation 305 initialization 54, 56
error generation 307 multi-ported 57, 61
file inclusion 304 off-chip 188, 190, 192, 274
line control 306 on-chip 180, 210, 211, 212
line splicing 307 overview 54
macros 139, 303, 307 restrictions 97
prialt .............................46, 78, 79, 89 simultaneous access 97
prialt examples 79 synchronous 193, 195, 204, 261, 282
ProASIC devices..................... 180, 183 syntax 320
constraints files 281 targeting 192, 204
I/O standards supported 289, 296 use of 186
pull up resistors 280 writing to 54
RAMs 210 Xilinx 212
slew rate on output buffer 286 range ............................................ 31
proc ..................................... 138, 139 rate specification .................... 270, 281
program structure .............................9 rclkpos.................................. 195, 282
properties .................................... 278 reading from external pins....... 219, 220
specification 278 recursion........................111, 117, 133
protecting critical code ..................... 62 recursive macros111, 133, 135, 136,
prototypes ..................... 116, 118, 138 137

functions 118 shared expressions 135, 136, 137

macros 116, 138 reducing logic depth ...................... 154

pull ............................................. 280 reference books ................................4

QDR devices ................................. 193 register.......................................... 68

qualifiers........................................ 29 registered reading from external pins220

Quartus ....................................... 281 relational operators ....................... 106

assignments 281 releasesema()................................. 93

www.celoxica.com Page 344

Handel-C Language Reference Manual

replicated code ............................... 76 set clock ...................................... 160

replicators.................................... 324 set family ..................................... 183
reset ...............................90, 186, 297 set part........................................ 183
global 186 set reset ....................................... 186
specifying reset pin 186 shared code..... 113, 116, 127, 135, 136
restrictions .......... 46, 97, 117, 127, 136 shared expressions ................. 135, 136
casting 97 restrictions 136
functions 117, 127, 129 shift operators
on channels 46 shift operators 102
on RAM and ROM 97 short ............................................. 32
on shared expressions 136 show specification ......................... 286
retime specification ....................... 284 side effects............................... 18, 95
return.....................................84, 117 sign extension ..................97, 102, 133
types 117 signals ....................................63, 319
right shift ..................................... 102 signed .............................. 31, 32, 107
ROM................................54, 186, 212 signed/unsigned................. 32, 96, 107
external 212 casting 96
LUT ROM in Altera devices 256 simulations................................... 228
overview 54 clock required 160
same rate external clock ................ 189 file I/O 178
sc_type specification...................... 285 simulating buses 230
scope ................................. 8, 29, 119 simulating interfaces 228
variable sharing 8 simulator ..................................... 178
Select Clock dialog ........................ 162 input file format 178
select operator.............................. 131 output 286
selection within switch ..................... 88 sizeof ............................................ 17
sema ............................................. 62 sorts ........................................... 218
semaphores ........................ 62, 92, 93 interfaces 218
seq ............................................... 76 Spartan devices ..................... 180, 183
sequential and parallel execution ....... 75 constraints files 281
sequential replication ....................... 76 I/O standards supported 289, 296
set .......................... 33, 160, 183, 186 mprams 59
clock 160 on-chip RAMs 212
family 183 RAM timing issues 256
intwidth 33 slew rate of output buffer 286
part 183 specifications ......................... 245, 276
reset 186 base 254

www.celoxica.com Page 345

Handel-C Language Reference Manual

bind 254 westart and welength 300

block 256 speed .......................................... 286
busformat 259 SSRAM ...................193, 195, 261, 282
clk 261 pipelined access 196, 198, 200
clkpulselen 282 read and write cycles 195, 198
clock position 282 SSRAMs 193, 195, 196, 261
clockport 262 timing 195, 196, 198, 200, 282
data 264 SSTL I/O standard....286, 289, 293, 294
dci 265 SSTL18 Class I 286, 294
extinst extlib extfunc 266 SSTL18 Class II 286, 294
extpath 268 SSTL2 Class I 286, 293
fifolength 268 SSTL2 Class II 286, 293
infile and outfile 269 SSTL3 Class I 286, 294
intime and outtime 269 SSTL3 Class II 286, 294
minperiod 167, 273 standard specification ...... 286, 289, 290
object 245 AGP 286, 290
offchip 274 BLVDS 286, 290
paranoia 169, 275 CTT 286, 290
pin 276 GTL 286, 294
ports 277 HSTL 286, 291
properties 278 LVCMOS 286, 291, 292
pull 280 LVDCI 286, 292
quartus_proj_assign 281 LVDS 286, 292
rate 281 LVPECL 286, 293
rclkpos 282 LVTTL 286, 293
retime 284 PCI 286, 293
sc_type 285 SSTL 286, 293, 294
show 286 standards.......................286, 290, 294
speed 286 statements .....10, 25, 75, 141, 147, 321
standard 286, 290 comparison with ANSI-C 25
std_logic_vector 295 compound 324
strength 296 syntax 321
unconstrainedperiod 297 timing 141, 147
vhdl_type 298 static ....................................... 69, 73
warn 300 initializing static variables 73
wclkpos 282 std_logic_vector specification .......... 295
wegate 300 storage class specifiers..................... 64

www.celoxica.com Page 346

Handel-C Language Reference Manual

Stratix devices ................ 180, 183, 209 take operator................................ 102

constraints files 281 targeting.................177, 179, 183, 186
embedded memory 209 FPGA/PLD devices 179, 183, 209
I/O standards supported 289, 296 hardware 177
mprams 59 ports 243
pull-up resistors 280 RAM and ROM 54, 186
RAMs 211 specific tools 243
strength specification..................... 296 Tcl files ................................. 269, 281
string constants .............................. 30 timing............................ 141, 154, 233
strings .................................... 30, 315 asynchronous RAM 187
struct ............................................ 36 buses 233, 235
structure member operator............. 109 constraints 269, 270, 281
structure pointer operator .............. 109 efficiency 154
structure pointers............................ 42 examples 141, 152, 233
structures ......................... 36, 42, 319 introduction 141
storage 36 SSRAM 195, 282
syntax 319 statements 141, 147
subtraction................................... 104 TriMatrix memory.......................... 209
summaries ................... 10, 12, 14, 309 tri-state ... 218, 221, 222, 224, 232, 294
keywords 309 buses 218, 221, 222, 224
operators 12 interfaces 218, 294
statements 10 pins 232
types 14 try ... reset..................................... 90
supported ............................... 32, 180 trysema()....................................... 92
devices 180 ts...........................218, 221, 222, 224
types for porting 32 type ........................ 14, 16, 22, 32, 72
switch ......................................88, 89 clarifier 72
termination 89 conversion 17, 96, 97
synchronization.................................6 mapping for C and C++ 32, 65
synchronous RAMs193, 195, 204, 261, names 321
282 operators 16, 68, 70, 71
clocks 193, 195, 196, 261 qualifiers 71
examples 196, 200, 205, 207 summary 14
generating 282 type clarifier <>.............................. 72
read and write cycles 195, 198 typedef .......................................... 69
timing 196, 198, 200, 282 typeof............................................ 70
syntax ......................................... 309 types ..................14, 16, 22, 29, 31, 44

www.celoxica.com Page 347

Handel-C Language Reference Manual

architectural 44 void.................................. 39, 84, 117

logic 31 volatile .......................................... 71
overview 14, 29 warn specification.......................... 300
types in C and Handel-C 16, 22 wclkpos ................................ 195, 282
VHDL 295 we .............................................. 276
unconstrainedperiod ...................... 297 wegate ...................188, 190, 192, 300
undefined....................................... 33 welength......... 187, 188, 190, 192, 300
undivided external clock ................. 190 westart ........... 187, 188, 190, 192, 300
unions .................................... 21, 309 while loops ............................... 85, 86
unsigned........................... 31, 32, 107 width........................... 17, 29, 33, 104
values ........................................... 29 adjustment 17, 102
overflow 29 inference 33
variables ................................. 73, 151 of variables 17, 29
auto 64 operator 104
default values 73 wires ......................................63, 243
initialization 30, 64, 71, 73 naming 243
local 64 with ............................................ 245
parallel access 151 WOM (write-only memory ports) . 57, 62
width of variables 17, 29 work library .................................. 254
Verilog......................................... 278 write enable ................... 187, 193, 300
instantiating components 254 asynchronous RAM 187, 300
parameters 278 positioning 300
VHDL........................................... 295 synchronous RAM 193
generics 278 write strobe.................................. 187
instantiating component 254 write-only memory .......................... 62
types 295 writing to external pins .................. 221
vhdl_type specification................... 298 Xilinx ............................. 180, 183, 212
Virtex devices ........................ 180, 183 bit mapping 59
constraints files 281 block specification 256
I/O standards supported 286, 296 devices 180, 183
mprams 59 on-chip RAM 212
on-chip RAM 212 ZBT-compatible devices ................. 193
RAM timing issues 256
slew rate of output buffer 286
specifying clock input 262
specifying DCI 265
Virtex-II Pro .......................... 180, 183

www.celoxica.com Page 348