SMCube HDL Reference Manual - Evidence · SMCube HDL Reference Manual The Lattice Diamond Verilog component generator Version: 1.2 November 15, 2012

SMCube HDL Reference Manual

The Lattice Diamond Verilog component generator

Version: 1.2

November 15, 2012

About Evidence S.r.l.

Evidence is a company operating in the field of software for embedded real-time systems.It started in 2002 as a spin-off company of the Real-Time Systems (ReTiS) Lab of theScuola Superiore Sant’Anna (Pisa, Italy). Today, Evidence is a dynamic company havingcollaborations in the field of electronics, telecommunications, automotives, and industrialautomation.

People at Evidence are experts in the domain of embedded and real-time systems, witha deep knowledge on the design and specification flow of embedded software, especiallyfor the embedded market.

Besides providing consultancy services, Evidence also provides: BSPs based on Linuxfor embedded devices, evaluation boards featuring most innovative 8, 16 and 32-bitmicrocontrollers for the embedded market, development tools for making embeddedsoftware development easier, and tools for the schedulability analysis of real-time tasksrunning on your final product.

For more information see: http://www.evidence.eu.com

Contact Info

Evidence Srl,Via Carducci 56Localita Ghezzano56010 S.Giuliano TermePISA Italy

Tel: +39 050 99 11 224Fax: +39 050 99 10 812

For more information about Evidence products, please send an e-mail to the follow-ing address: [email protected]. Other information about the Evidence productline can be found at the Evidence web site at: http://www.evidence.eu.com.

This document is Copyright 2011-2012 Evidence S.r.l.

Information and images contained within this document are copyright and the property of Evidence

S.r.l. All trademarks are hereby acknowledged to be the properties of their respective owners. The

information, text and graphics contained in this document are provided for information purposes only by

Evidence S.r.l. Evidence S.r.l. does not warrant the accuracy, or completeness of the information, text,

and other items contained in this document. Matlab, Simulink, Mathworks are registered trademarks

of Matworks Inc. Microsoft, Windows are registered trademarks of Microsoft Inc. Java is a registered

trademark of Sun Microsystems. in the USA. and other countries, and are used under license. All

other trademarks used are properties of their respective owners. This document has been written using

LATEX.

2

http://www.evidence.eu.com

[email protected]

http://www.evidence.eu.com

Contents

1. Introduction 91.1. Quick feature list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3. Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.4. Feedback, bugs, and additional examples . . . . . . . . . . . . . . . . . . 10

2. Semantics behind a SMCube HDL model 112.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2. Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.4. Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3. SMCube HDL language 163.1. Examples of usage of the SMCube HDL Language . . . . . . . . . . . . . 18

3.1.1. Examples of actions . . . . . . . . . . . . . . . . . . . . . . . . . . 183.1.2. Examples of guards . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4. The SMCube HDL editor 204.1. Drawing states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.2. Drawing transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.3. Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.3.1. Global preferences . . . . . . . . . . . . . . . . . . . . . . . . . . 254.3.2. State preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.3.3. Transition preferences . . . . . . . . . . . . . . . . . . . . . . . . 28

4.4. Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.4.1. File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.4.2. Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.4.3. Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.4.4. Zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.4.5. Align . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4.5. Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.5.1. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4.5.1.1. Types of the Data Model . . . . . . . . . . . . . . . . . 314.5.1.2. Definition of the Data Model . . . . . . . . . . . . . . . 31

4.5.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344.6. External logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3

Contents

5. Code Generation 37

6. State machine behavioral simulation 416.1. Input definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416.2. Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7. Examples 457.1. Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457.2. Encoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467.3. Pulse Width Modulation . . . . . . . . . . . . . . . . . . . . . . . . . . . 467.4. External logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

A. SMCube HDL Language: BNF-like description 50

B. Demo license version 52

C. QT Libraries Licensing 53

4

List of Figures

2.1. Architecture of an SMCube HDL component. . . . . . . . . . . . . . . . 112.2. An initial state of a SMCube HDL State Machine. . . . . . . . . . . . . . 132.3. A State with its entry, exit and while actions. . . . . . . . . . . . . . . . 132.4. A transition between two SMCube HDL states. . . . . . . . . . . . . . . 14

4.1. The SMCube HDL Welcome Page. . . . . . . . . . . . . . . . . . . . . . 204.2. The SMCube HDL editor window. . . . . . . . . . . . . . . . . . . . . . . 214.3. SMCube HDL editor with states. . . . . . . . . . . . . . . . . . . . . . . 224.4. How to resize a regular State. . . . . . . . . . . . . . . . . . . . . . . . . 234.5. Creating a transition: source state selection. . . . . . . . . . . . . . . . . 234.6. Creating a transition: destination state selection (note the dashed line). . 244.7. Create transition: completed (note the solid line). . . . . . . . . . . . . . 244.8. Transition control points. . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.9. Global preferences: State Machine. . . . . . . . . . . . . . . . . . . . . . 264.10. Global preferences: States. . . . . . . . . . . . . . . . . . . . . . . . . . . 264.11. Global preferences: transitions. . . . . . . . . . . . . . . . . . . . . . . . 274.12. State preferences Dialog Box. . . . . . . . . . . . . . . . . . . . . . . . . 274.13. Transition preferences Dialog Box. . . . . . . . . . . . . . . . . . . . . . . 284.14. Data Model: input data definition. . . . . . . . . . . . . . . . . . . . . . 324.15. Data Model: output definition. . . . . . . . . . . . . . . . . . . . . . . . 324.16. Data Model: local variables. . . . . . . . . . . . . . . . . . . . . . . . . . 334.17. Data Model: parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . 344.18. The Configuration Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . 354.19. The External Logic Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.1. Error check examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375.2. The Code Generation dialog. . . . . . . . . . . . . . . . . . . . . . . . . . 385.3. The Code Generation dialog after the generation of a component. . . . . 395.4. Tree structure generated by SMCube HDL. . . . . . . . . . . . . . . . . . 40

6.1. Simulation Window: Inputs tab. . . . . . . . . . . . . . . . . . . . . . . . 426.2. Simulation Window: Simulation tab. . . . . . . . . . . . . . . . . . . . . 436.3. The state machine of the SMCube HDL simulation engine. . . . . . . . . 44

7.1. Timer Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457.2. Encoder Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467.3. Pulse Width Modulation Example. . . . . . . . . . . . . . . . . . . . . . 477.4. External Logic Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

5

List of Figures

7.5. External Logic Example: Configuration. . . . . . . . . . . . . . . . . . . 49

6

List of Tables

3.1. Language operators supported by the SMCube HDL Language. . . . . . 173.2. Data model used in the examples of the SMCube HDL Language. . . . . 18

4.1. Data model types mapping. . . . . . . . . . . . . . . . . . . . . . . . . . 31

7

About this document

This document describes SMCube HDL, Lattice Diamond MSB component generatorfrom discrete time finite state machine diagrams.

Function of the document

The function of this document is to provide a reference manual for the various function-alities offered by SMCube HDL.

Document history

Version Date Author Company Change Description

0.1 Jan 2012 Giuseppe Arturi,

Paolo Gai

Evidence Srl Initial version

0.2 Jan 2012 Marco Di Natale Evidence Srl Added Semantic of

SMCube State

Machines

0.3 Jan 2012 Giuseppe Arturi,

Paolo Gai

Evidence Srl Added examples,

FLEX Demo Board

simulator, licenses.

1.0 Jan 2012 Paolo Gai Evidence Srl Released version 1.01.1 Nov 2012 Giuseppe Arturi Evidence Srl Added HDL specific

features.1.2 Nov 2012 Paolo Gai Evidence Srl Minor fixes.

Acronyms

Acronym MeaningSMCube SMCube, or SM3, is a recursive factorized acronym which

means “SMCube is a State Machine System Modeler”.FSM Finite State MachineHDL Hardware Description Language

8

1. Introduction

SMCube HDL is a tool for modeling, simulation, and code generation of discrete timestate machines.In particular, SMCube HDL is able to generate Verilog components withall the surrounding interfaces needed to be included in a Lattice Diamond [1] MSBProject.

Why another state machine editor? Most FPGA designs nowadays include a mixtureof library components (soft cores, peripherals, interconnection fabric, . . . ) provided bythe FPGA producer, plus customized components that implement simple interfacingwith the outside world. Whereas creating a design using only the pre-built componentis a relatively easy task, designing a custom component that needs to be integrated in astandard design requires additional knowledge. This additional knowledge includes:

� VHDL/Verilog languages;

� Details about the interconnection fabric (e.g., the Whishbone bus and its rules andtimings);

� Knowledge on how to design a slave peripheral exporting data registers, IRQ re-quests, . . .

Therefore, the idea driving the development of SMCube HDL was the need for a lightweightState Machine editor, simulator, and code generator which could be used to directlygenerate all the needed HDL files needed to implement a Wishbone peripheral to beintegrated with the Lattice Diamond MSB Tool.

Using SMCube HDL, you can easily:

� Design your own state machine, drawing states and transitions and configuringtheir parameters.

� Define a data model for the state machine, with inputs, outputs and local variables.

� Save your state machine into a XML file.

� Simulate the state machine response given an input pattern.

� Generate a Verilog implementation of the state machine, with all the surroundingfiles needed for the import inside Lattice Diamond MSB.

The following Chapters will describe the main functionalities of SMCube HDL, as wellas its integration with the Lattice tools.

9

Chapter 1. Introduction

1.1. Quick feature list

This is a quick feature list of SMCube HDL version 1.0:

� editing of flat (non hierarchical) state machines, with undo support.

� XML file format.

� possibility to specify various kind of inputs and outputs (wires, registers, localregisters, with the additional possibility to generate a IRQ request).

� graphical simulation of a state machines.

� export of a state machine in a bitmap format (BMP, JPG, PNG).

� code generation of a Lattice MSB component in Verilog, ready to be imported.

1.2. Requirements

SMCube HDL is currently distributed as a standalone application, and has the followingrequirements:

� Visual C++ 2008 (or 2010) Express edition (for the simulation environment);

1.3. Licensing

SMCube HDL is distributed with a commercial per-seat license. Additionally, a 2-stateslimited version is also available for free with a Demo License.

SMCube HDL uses the Qt Libraries, which are dynamically linked to allow you tochange the library with new versions at your choice. Licensing information about theQt Libraries is available in Appendix C.

1.4. Feedback, bugs, and additional examples

We hope that you will enjoy the tool as we are doing in our experiments and projects. Ifyou have any suggestions on how to better use, or on how to improve SMCube HDL, orif you need technical support, please do not hesitate to write to [email protected].

10

[email protected]

2. Semantics behind a SMCube HDL model

2.1. Introduction

SMCube HDL allows you to generate Verilog Lattice Diamond [1] MSB componentsstarting from a graphical representation of a state machine. Figure 2.1 shows the archi-tecture of an MSB component generated by SMCube HDL.

OUT REGS

IN REGS

IRQLOCAL WIRES

LOCAL REGS

OUT WIRES

IN WIRES

Data Model

EXTERNAL INPUT

FSM

External Logic

Filter

Wrapper

Wishbone bus

External Peripherals

Figure 2.1.: Architecture of an SMCube HDL component.

The main architectural elements of a MSB component generated by SMCube HDLare the following:

� The Finite State Machine (FSM), implemented in Verilog.

� The Data Model, which is composed by:

– a set of input/output registers visible on the wishbone bus;

– a set of local registers;

11

Chapter 2. Semantics behind a SMCube HDL model

– a set of input/output wires for the connection to the outside world.

� Additional input wires filters, to automatically generate additional register barriersto protect the input wires.

� Additional IRQ request on the Wishbone bus, to help generating an asynchronousinterrupt to the Mico32 softcore.

� Additional External Logic, to provide additional custom behavior not modeledwith the finite state machine. The external logic module has visibility of theinput, output and local variables (see Section 4.5.1 for details) of the state machinemodule. Moreover, the external logic module can provide additional inputs to thestate machine module to influence its execution.

� An additional Verilog wrapper used to wrap all the content in a way compatiblewith the Wishbone bus.

In addition to the various architectural parts, SMCube also generates:

� An XML file compatible with Lattice Diamond MSB, for a seamless import of thecomponent.

� A C language header file to export the various registers to the Mico32 softcore.

� A directory structure containing all the above, packaged following the LatticeDiamond MSB component standard.

The following sections of this chapter describe the semantics of the state machine im-plemented by SMCube HDL.

2.2. Structure

An SMCube HDL FSM is defined by a tuple F = {S, sinit, IS,OS,Θ,V}, where S ={s1, s2, . . . s|S|} is a set of states, sinit ∈ S is the initial state, IS = {i1, i2, . . . i|IS|} andOS = {o1, o2, . . . o|OS|} are the input and output signals,Θ is the set of transitions andV a set of internal variables. Each ij (oj) may also be denoted as αj.

Each signal is a function defined on the discrete time domain, with values in a givenrange. The range of the admissible values matches the range of data types. Currently,only 1 bit wide wire and 32 bit register types are allowed for IS and OS and V. Eachsignal is identified by a unique name.

Θ is the set of transition rules. Each transition θj ∈ Θ consists of a tuple θj ={src(θj), dst(θj), ε(θj), gj, aj, pj}, where src(θj) ∈ S is the source state, dst(θj) ∈ S is thedestination state, gj is the guard condition (an expression with boolean value of the inputand output signals and internal variable values), aj is the action, and pj is the transitionpriority (the lower the number, the higher the priority). Priorities must be unique amongall the transitions with the same source state. The guard gj can be a boolean-valued

12


Figure 2.2.: An initial state of a SMCube HDL State Machine.

Figure 2.3.: A State with its entry, exit and while actions.

expression obtained as a SMCube HDL language boolean-valued expression using thecomparison operators and arithmetic operators of the SMCube HDL language togetherwith the values of the input signals and the internal variables (see Section 3). Theaction aj is a sequence of action statements as provided by the SMCube HDL languagedescribed in Section 3.

Each state sj ∈ S is further characterized by a name and a set {en(sj), ex(sj), wh(sj)}.en(sj) is the entry action for state sj. It is an action (see the description of the actionsassociated to transitions) executed whenever sj is the destination of an active transition.ex(sj) is the exit action, executed whenever sj is the source of an active transition.wh(sj) is the while action, executed whenever an input event is active, state sj is theactive state and no transition is taken.

2.3. Syntax

The SMCube HDL syntax is graphical and is described in the following Figures:

� Figure 2.2 shows an initial state.

� Figure 2.3 shows a state with its entry, exit and while actions

� Figure 2.4 shows a transition, the graphical notation of a transition is a directedlink (as indicated by the arrow) from the source state to the destination state.Please note that the priority appears at the foot (origin) of the transition link, the

13


Figure 2.4.: A transition between two SMCube HDL states.

guard expression is shown in a string that is associated with the link and can bemoved. A separate string shows the action.

2.4. Behavior

The behavior of the SMCube HDL is defined as follows. First, we define the concept ofactive state sa(tk). At time tk=0 the active state is the initial state sinit = sa(t0). At anypoint in discrete time tk the machine has one currently active state.

At time tk, the transitions outgoing from the current state are sorted by priority.Priorities are used to discriminate which transition should be performed when two ormore transitions can be taken out of a state (their guards are true). The guard expressionassociated to each transition in priority order is computed. If the guard evaluates tofalse, then the next transition in priority order is considered. If the guard evaluates totrue, then the transition is active and is taken. Formally, if the active transition is θ∗,then it must be:

� (1) src(θ∗) = sa(tk)

� (2) g(θ∗)(tk) = TRUE

� p∗ = min{pk such that (1), (2) are true for θk}

Please note that at any point in time there can be one and only one active transition(the one with minimum priority index) or none.

When θ∗ is taken, the following actions are executed in parallel:

� The exit action of the state src(θ∗) (if defined).

� the action a(θ∗) (if defined).

� The entry action of the state dst(θ∗) (if defined).

Then, the new active state becomes dst(θ∗).If no transition is active at time tk for the active state, then

14


� The while action of the state sa(tk) is executed (if defined).

IMPORTANT: Please note that the code that will be generated is HDL code. For thatreason, all the statements are executed in parallel. That is, the output value and thelocal variables will change at the end of the step. This means that if a variable x havinga value xk−1 changes its value to xk at the time tk in the exit action of src(θ∗), thenduring the transition action a(θ∗) and the entry action of dst(θ∗) it will still be evaluatedto xk−1 instead of xk.In other words, the execution of the statements is not sequential as in the C languagebut is parallel as in all HDL languages such as Verilog and VHDL.

15

3. SMCube HDL language

The entry, exit and while actions for states, and likewise the action and guard fortransitions can contain statements according to the SMCube HDL Language.

The SMCube HDL Language is a simple intuitive language providing a set of basicoperations. The language is specified by a BNF-like grammar described in Appendix A.

Basically, actions and guards can be composed of statements (stmt in the grammar);a statement can be an assignment (assignment in the grammar), a function call (func-tion call in the grammar) or an expression (expr in the grammar).

An assignment as the following structure: LHS = RHS (where LHS means left handside while RHS means right hand side of the assignment operation). The assignment isused to change the value of an identifier; to write an assignment you should typewritethe identifier, then the assignment symbol (“=”) and finally an expression. It is alsopossible for registers to change the value of a single bit using the bit selection expression(identifier[TOKEN NUMBER]).

A function call has the following notation: function name(). As described at the endof this section, only one function call is currently supported, which is the GENERATE IRQ()

function used to generate an interrupt through the interrupt request line on the Wish-bone bus.

An expression can be used to compose complex statement by combining identifiers andnumbers with operators. The expression is recursively defined in the grammar allowingcomplex composition of simple expressions. The base cases of recursion are identifiersand numbers.

For example, an expression can be built as follow: <expr1> <operatorX> <expr2>,where:

� <expr1> is an identifier

� <operatorX> is an one of the binary operators supported by the language (seeTable 3.1);

� <expr2> is <expr3> <operatorY> <expr4>

� <expr3> is an identifier

� <operatorY> is another binary operator supported by the language;

� <expr4> is a number

The previous expressions composition results in the following complex expression:

identifier <operatorX> identifier <operatorY> number.

16

Chapter 3. SMCube HDL language

The operators precedence and associativity define the order in which complex expressionsare executed. The language allows you to change the default behavior using roundbrackets (“(“ and “)”) to enclose expressions.

The operators list with precedence and associativity is shown in Table 3.1.

Precedence Operator Description Associativity

1 ! ∼ Logical not and bitwisenot (unary)

right-to-left

2 + − Addition andsubtraction

left-to-right

3 << >> Bitwise left shift andright shift

left-to-right

4 < <= > >= Relational operators:less, less equal, greater,

greater equal

left-to-right

5 == ! = Relational operators:equal, not equal

left-to-right

6 & Bitwise AND left-to-right7 ˆ Bitwise XOR (exclusive or) left-to-right8 | Bitwise OR (inclusive

or)left-to-right

9 && Logical AND left-to-right10 || Logical OR left-to-right

Table 3.1.: Language operators supported by the SMCube HDL Language.

The following rules are applied in evaluating the Language:

� Only assignment and function call statements are allowed for actions. An actioncan be composed of multiple assignments and function call separated by semi-colons;

� Only expression elements are allowed for guards;

� Every identifier must be listed as an entry in the Data Model (see Section 4.5.1);

� The expression: identifier[TOKEN NUMBER] for bit selection is allowed only forREGISTER types;

� In the expression: identifier[TOKEN NUMBER] the token number must be aninteger number between 0 and 31 (which is the REGISTER type size);

� An input register or input wire is not allowed as the left hand side (LHS) of anassignment expression;

� The only supported function call is GENERATE IRQ().

17


3.1. Examples of usage of the SMCube HDL Language

The SMCube HDL Language is better explained by using simple examples. For thatreason, the following paragraphs show a lists of correct / wrong actions and guardsstatements. All of them will be based on a reference Data Model described in Table 3.2.

Kind of Data Name Type

INPUT IN0 REGISTER

INPUT IN1 WIRE

OUTPUT OUT0 REGISTER

OUTPUT OUT1 WIRE

LOCAL VARIABLE LVAR0 REGISTER

LOCAL VARIABLE LVAR1 WIRE

Table 3.2.: Data model used in the examples of the SMCube HDL Language.

3.1.1. Examples of actions

These are valid actions:

1. OUT0 = IN0 + 0xFF;

A register can be set as the sum of an input register and a constant. The sum isinterpreted using 2’s complement.

2. OUT1 = IN1 + LVAR1;

An output wire can be set as the sum of two other wires.

3. GENERATE IRQ();

This action generates an IRQ request on the Wishbone bus.

4. OUT0 = 0x12;

A register can be set equal to a constant value.

5. OUT1 = 1;

A wire can be set either to 0 or 1.

6. OUT1 = IN0[23];

A wire can be set to the value of a specific bit of a register.

These are wrong actions

1. IN0 = 0x12;

An input cannot be assigned.

18


2. OUT2 = IN0;

OUT2 is not part of the Data Model in Table 3.2.

3. OUT1 = IN0[34];

IN0[34] is out of range for IN0 register.

4. OUT1 == IN1;

Only assignment or function calls are allowed in actions (Note “==” is the equalcomparison, whereas “=” is the assignment operator).

5. OUT1[0] = IN1[0];

Bit selection is not allowed only for wire types.

6. FUNC();

Only “GENERATE IRQ()” is a valid function call.

7. OUT0 + 0x3 = IN0;

The LHS in assignment must be an identifier and not an expression.

3.1.2. Examples of guards

These are valid guards:

1. (IN0 & 0xFF) == 0x45

2. LVAR1 | IN1

3. OUT0 == 0x12

4. OUT1 != 1

5. OUT1 == IN0[23]

6. !IN1

These are wrong guards:

� OUT0 = 0x12

Assignment is not allowed in guards.

� FUNC();

Function calls are not allowed in guards.

� LVAR0[32] == 0

LVAR0[32] is out of range for LVAR0 register.

19

4. The SMCube HDL editor

Once started, SMCube HDL shows the welcome page displayed in Figure 4.1. This pageshows an information text briefly describing the SMCube HDL features (main “Infor-mation” box), the recent files list (“Recent Files” box on the left side), the examples listcoming with the product (“Examples” box just below the “Recent Files” box) and thelicense information (“License” box below the “Information” box).

Figure 4.1.: The SMCube HDL Welcome Page.

In order to start the state machine editing you can:

� Create a new file;

� Open an existing file using the File Menu;

20

Chapter 4. The SMCube HDL editor

� Open a recent file if present;

� Open one of the example variable in the examples list. If you choose to open anexample, SMCube HDL will ask you to copy the file in another location to preservethe original file from modification (you can also choose to do not copy the examplefile, by pressing the cancel button in the dialog, meaning that every modificationwill be applied to the original example file).

The SMCube HDL editor appears as shown in Figure 4.2.

Figure 4.2.: The SMCube HDL editor window.

The user interface is composed of the following graphical regions:

� A menu bar (1), with the usual commands for file handling, Cut & Paste, Export,and so on;

21


� A toolbar (2), containing useful buttons to speed up your editing;

� The items palette (3), containing the state machine basic items;

� The working area (4), which is the region of the screen where you can create yourstate machine;

� The data model summary (5), which shows the current data model summary usefulduring the state machine editing.

4.1. Drawing states

The items palette shown in part (3) of Figure 4.2 contains the following items:

� The initial state (the black dot).

� A regular state (the rounded box).

To put an item onto the working area (4), you need to drag the item from the palette tothe scene. After that, you can move the shapes by first selecting the item with a click,and then dragging it to the appropriate position.

For example, in Figure 4.3, the initial state and two regular states have been droppedon the scene.

Figure 4.3.: SMCube HDL editor with states.

22


Figure 4.4.: How to resize a regular State.

You can also resize objects. The initial state can be resized by dragging the squarehandles at the edges of the object. The size of the black dot is controlled in the globalpreferences (see Figure 4.10). The regular state object can be resized by dragging itscorners (see Figure 4.4).

Most of the common editing commands works as expected. For example, you canselect more than one item simply drawing a rubber band selection rectangle on theworking area and covering all the items you are interested in. Then you will be able tomove these items (dragging them using your mouse) or delete them (pressing the DELkey or pressing “Cancel” in the Edit Menu). Multiple items selection can be done alsoclicking on the various items while keeping the CTRL key pressed. Copy, Cut and Pasteworks as well.

4.2. Drawing transitions

Creating a transition is extremely easy. Go with your mouse on the border of a regularstate, as shown in Figure 4.5. You will note that the cursor assumes a cross shape.

Figure 4.5.: Creating a transition: source state selection.

When the cursor is a cross, you can click the left button of your mouse and drag anew transition out of the state.

23


You can drop the transition arrow on the scene (not on a state). In that case, thetransition is not correctly connected. Whenever a transition is not properly connected(source state, target state or both source and target states are missing), it is displayedwith a dashed line, as it happens for the initial transition in the Figure 4.6.

Figure 4.6.: Creating a transition: destination state selection (note the dashed line).

On the other hand, when a transition is dragged over a regular state, the state itselfwill be highlighted (see Figure 4.6). Releasing a transition on a highlighted state connectsthe transition to that state. The transition line will be solid, meaning that the transitionhas been correctly connected on both edges (see Figure 4.7).

Figure 4.7.: Create transition: completed (note the solid line).

You can select a transition by clicking on it. Whenever a transition is selected, threecontrol points are displayed on it: the start point, the middle point and the end point.These three points can be used to determine the shape of the line according to your needs.The start and end points are used to connect a transition to a state or to disconnect itfrom a state. The middle point instead has the precise task to help adjusting the linebending. You will note that when the three points are not aligned, two dashed control

24


Figure 4.8.: Transition control points.

lines are displayed in order to connect the middle point to the other two. When thetransition is not selected, control points and control lines disappear. All these conceptsare synthesized in Figure 4.8.

4.3. Preferences

Preferences control the parameters which apply to a specific object. SMCube HDL hasthree kind of preferences.

Global Preferences Global preferences control the main settings of a SMCube HDLdiagram.

State Preferences State preferences are used to control the appearance and the behav-ior of a state, included entry, exit, and while actions.

Transition Preferences Transition preferences are used to control the transition prior-ity, as well as the transition guards and actions.

4.3.1. Global preferences

Global Preferences are used to specify attributes that apply globally to the entire Statemachine.

To change the Global Preferences, you can access the Preferences dialog going toOptions� Preferences. . . , or you can right click on the scene selecting “Preferences. . . ”from the context menu.

The Global Preferences dialog is composed of three tabs.

State Machine Tab The first tab allows you to change the state machine name (seeFigure 4.9) which is used as base name for the state machine target implementation(see further).

25


Figure 4.9.: Global preferences: State Machine.

States Tab The second tab allows you to change the default parameters used when newstates are created (see Figure 4.10).

Figure 4.10.: Global preferences: States.

Transitions Tab The third tab allows you to change the default parameters used whennew transitions are created (see Figure 4.11).

26


Figure 4.11.: Global preferences: transitions.

4.3.2. State preferences

The State Preferences Dialog Box displays the basic information about a state. To editthe parameters of a specific state, you can right click on the state itself and select the“Edit preferences” item, in order to access the State preferences Dialog Box (see Figure4.12).

Figure 4.12.: State preferences Dialog Box.

27


This Dialog Box allows you to change the state name, width, height, font family andfont size. Furthermore it is possible to set an entry action, an exit action and a whileaction for the state as explained in Chapter 3.

Note that a state can be resized also by selecting it and dragging one of its corners,as shown in Figure 4.4.

4.3.3. Transition preferences

To edit the parameters of a specific transition, you can right click on the transitionitself and select the “Edit preferences” item, in order to access the transition preferencesdialog.

Figure 4.13.: Transition preferences Dialog Box.

The Dialog Box shown in Figure 4.13 allows you to change the transition guard andaction, as detailed in Chapter 3.

The “Visible” check box enables or disables the displaying of text items (guard andaction). It is also possible to change the font family and the font size for such textitems. When visible, you can move these elements by dragging them in the appropriatepositions. If you move the transition, and you need to readjust the position of the threetext boxes, you can make these boxes invisible and then visible again, and they will bepositioned near the transition line.

Finally, you can change the transition priority. Higher priority values denote a lowerpriority in transition execution. Changing a priority implicitly reassigns all priorities ofthe transitions going out from the same regular state. Please always remember that the

28


priority number is relative to the state where the transition starts (in other words, whenlooking at Figure 2.4, priorities are related to State 1 and are not related to State 2).

4.4. Toolbar

As shown in Figure 4.2, the SMCube HDL editor has a toolbar with several buttonsallowing you to perform different operations.

4.4.1. File

The File toolbar buttons allow you to:

� Create a new state machine;

� Open an existing state machine;

� Save the current state machine;

� Save the state machine using another file name.

4.4.2. Edit

The Edit toolbar buttons allow you to:

� Undo an action;

� Redo an action;

� Cut the selected items;

� Copy the selected items;

� Paste the selected items.

4.4.3. Tools

The Tools toolbar buttons allow you to:

� Open the generation dialog to generate the code implementing the state machinefor simulation and target. Furthermore, prior to open the dialog the error checkingis performed (see Chapter 5 for details);

29


� Open the simulation window in order to debug the behavioral of the state machine(see Chapter 6).

4.4.4. Zoom

The Zoom toolbar buttons allow you to:

� Increase the zoom level;

� Decrease the zoom level;

� Restore the zoom level to 1:1;

� Best fit for all the items in the view;

� Fit the area by drawing a rubber band selection rectangle.

4.4.5. Align

The Align toolbar buttons allow you to align the selected states in various ways. Theleftmost button states whether the alignment is done with respect to the page or not,while the other buttons allow you to align to the left, the right, the top, the bottom,vertically and horizontally.

4.5. Settings

The settings are defined using the Settings dialog which is accessible going to Options �Settings. As shown in Figure 4.14 and Figure 4.18, the dialog is composed of two pages:the Data Model page and the Configuration page. The former allows you to define thedata model of the state machine while the latter permits the configuration of interrupt,reset and clock enable (see below for details).

4.5.1. Data Model

SMCube HDL allows you to define a Data Model, which is the list of variables usedby the State Machine, with their types. The idea is that you can first define the DataModel, and afterward use the variables you defined in Actions and Guards to controlthe behavior of the state machine.

30


4.5.1.1. Types of the Data Model

The current version of SMCube HDL supports a limited number of types, listed inTable 4.11. The table shows the correspondence between the various types used in thesecontexts:

SMCube HDL This is the type specification used in the State Machine Data Model.

Simulation This is the type used when generating the C++ simulation engine.

Target This is the type used when generating Verilog code for the target.

SMCube HDL Simulation Target

REGISTER Register reg[31:0]

WIRE Bit wire

WIRE(32) Register wire[31:0]

Table 4.1.: Data model types mapping.

The data model allows you to define parameters (see further) which are constantnumber with a name. This type of elements are macros for the simulation and parameterfor the target (parameter type in Verilog).

4.5.1.2. Definition of the Data Model

As stated before, the data model can be modified selecting its page in the Settings dialog.The Data Model Page is composed of four tabs:

Input Tab The first tab (see Figure 4.14) allows you to set input variables, specifyingthe name, the type, the reset value (decimal number) (the value written in theregister at reset, so that is enabled only for REGISTER input type) and the filtertype (the filter applied to the input wire, so that it is enabled only for WIRE inputtype). The filter type can be: none for no filtering or FF for latched filter.

1The WIRE(32) type is valid only for external logic input. Register and Bit types for simulation areC++ classes emulating the REGISTER and the WIRE types respectively.

31


Figure 4.14.: Data Model: input data definition.

Output Tab The second tab (see Figure 4.15) allows you to set output variables, spec-ifying the name and the type.

Figure 4.15.: Data Model: output definition.

32


Local Variables The third tab (see Figure 4.16) allows you to set local variables, spec-ifying the name and the type.

Figure 4.16.: Data Model: local variables.

Parameters Finally the fourth tab allows you to define parameters (see Figure 4.17).For these variables you can specify the name and the value (hexadecimal numberthat must start with 0x notation).

33


Figure 4.17.: Data Model: parameters.

In every tab you can:

� Add an element using the add button .

� Delete the selected elements (to select and element just click on the progressive

number on its right) using the delete button .

� Clear all elements using the clear button .

4.5.2. Configuration

The Configuration page is shown in Figure 4.18.

34


Figure 4.18.: The Configuration Dialog.

Through this page you can:

� Enable/Disable the interrupt request functionality and define if the interrupt re-quest line signal should be active high or low;

� The reset type for the state machine: asynchronous or synchronous;

� Add the clock enable line to the state machine.

4.6. External logic

As described in Section 2.1 an External Logic module can be added to the component.The External Logic can be enabled and configured using the External Logic dialog thatis accessible from the option menu (Options � External Logic).

The External Logic dialog appears as shown in Figure 4.19.

35


Figure 4.19.: The External Logic Dialog.

In order to enable the External Logic module you should check the outer box named“Enable”. Once enabled, the three inner boxes will be available for editing.

The “Data Model Export” box shows the list of the data model elements that can beexported to the external logic module; to make an element visible to the module justcheck its checkbox close to the name.

The “Additional Input” box allows you to specify the module output (i.e. the addi-tional input to the state machine module) in the same way you define the data modeloutput and local variables; the only supported types are WIRE and WIRE(32) as explainedin Section 4.5.1.1.

Finally, the “Verilog Code” box is used to define the behavior of the external logicmodule by writing Verilog code inside the text area. Above the text area, the signatureof the external logic module is composed to facilitate the code writer.

SMCube HDL does not simulate the external logic behavior nor does itchecks whether the Verilog code written for the external logic module iscorrect.

36

5. Code Generation

The Code Generation dialog is accessible through the Tools � Code Generation menu.Prior to open the dialog, SMCube HDL performs an errors check. If succeeded, the

Code Generation dialog is shown otherwise if something goes wrong, a dialog is displayedshowing the errors list. Moreover, if an error involves a graphical element this elementis highlighted in red when the error entry is selected from the list (see Figure 5.1).

Figure 5.1.: Error check examples.

Once your state machine is errors free, the Code Generation dialog in Figure 5.2 isopened. The dialog allows you to choose the generation settings and the C++ compilerused to build the simulation library (see further for details). Moreover, the “Log” boxshows relevant information about the code generation result. In the bottom part of thedialog there are three buttons: the “Generate” button used to trigger the generation,the “Simulation” button to open the simulation window (see below) and the “Close”button to hide the Code Generation dialog.

37

Chapter 5. Code Generation

Figure 5.2.: The Code Generation dialog.

The “Simulation” button is disabled until a successful generation is performed (seeFigure 5.3).

38


Figure 5.3.: The Code Generation dialog after the generation of a component.

The project name and the version number will be used for the name and the versionof the component integrated into the Lattice Diamond MSB.

SMCube HDL will try to find the following C++ compilers automatically:

� The compiler provided with Microsoft Visual Studio Express Edition 2008;

� The compiler provided with Microsoft Visual Studio Express Edition 2010;

� The compiler provided with MinGW.

If none of the previous compilers is found the “other” option should be used to manuallyselect a C++ compiler. The C++ compiler is used to generate and compile a C++implementation of the state machine use for simulation purposes.

SMCube HDL creates a folder, named with the value provided in the Project Namefield, into the path specified in the Destination Folder field.

WARNING. If the destination folder already contains a folder with the samename, the previous folder will be erased prior to start the new generation(anyway, SMCube HDL will ask you for confirmation).

Suppose you are generating a component with the following settings:

39


� Project Name: Test;

� State Machine Name: TestFsm1;

� The External Logic module is enabled;

Then, the generated folder tree structure (shown in Figure 5.4) is composed of two fold-ers: the “Simulation” folder, which contains the C++ library used during the simulation,and the “Component” folder, which contains all the files and folder needed to integratethe component into the Lattice Diamond MSB. As can be seen, the Component foldercontains:

� Timer.xml: an XML file describing the component read by the Lattice DiamondMSB;

� TestWrp.v: the Verilog source code file defining the wrapper module;

� TestFsm.v: the Verilog source code file defining the state machine module;

� TestFsmExtLogic.v: the Verilog source code file defining the external logic mod-ule2.

� Test.h: the C header file with useful macros to access the component registers inC Language programs.

Figure 5.4.: Tree structure generated by SMCube HDL.

1SMCube HDL will complain if the Project Name and the State Machine Name are equal.2This file is not generated if the external logic is not enabled.

40

6. State machine behavioral simulation

Once the component has been successfully generated (according to the procedure de-scribed in Chapter 5), SMCube HDL allows you to debug the state machine using theSimulation window accessible through the Tools menu or directly from the Code Gen-eration dialog.

It is important to notice that only the behavioral of the state machine can be testedusing the Simulation window without timing constraints. Furthermore, as stated inSection 4.6, the external logic is not part of the simulation.

The simulation is executed in two steps:

1. Define the input stimuli using the Inputs tab (see Section 6.1);

2. Start the simulation feeding the state machine with the input previously defined(see Section 6.2).

6.1. Input definition

The “Inputs” tab appears as shown in Figure 6.1. Through this tab is possible to createthe inputs to be feeded to the state machine during the simulation, to save the currentinputs list to file and to load a file previously saved.

The user interface is composed of the following graphical regions:

� The region (1) is composed of (from left to right):

– An Open button to load a previously saved file;

– A Save button to save the current inputs list;

– A label showing the number of inputs in the list;

– An informative message label;

– A Go To Simulation button to open the Simulation tab.

� The region (2) is used to add an input to the list (using the “green cross” button)and define the input values of the currently selected input in the list;

� Finally, the region (3) shows the input list and allows you to select an elementfrom the list in order to be modified, remove the selected elements (using the “redminus” button) and to clear the list (using the “broom” button).

41

Chapter 6. State machine behavioral simulation

Figure 6.1.: Simulation Window: Inputs tab.

The “Define Input” box (region 2) contains all the inputs present in the Data Model(see Section 4.5.1) and, if enabled, the external inputs coming from the external logic(see Section 4.6).

The inputs values can be specified in different bases: Binary, Octal, Decimal andHexadecimal.

6.2. Simulation

The “Simulation” tab is shown in Figure 6.2.The dialog is mainly composed of the following graphical regions:

� Control area (1): this area contains, from left to right, the start button, the playbutton, the step button, the pause button, the stop button, the simulation speedmodifier and the simulation progress bar;

� State Machine View area (2): this is a read-only zoomable view that shows theevolution of the state machine. Please note that the current state and the lasttransition taken are highlighted;

� Events list area (3): this area shows a list of items; each item corresponds to anevent processed by the SMCube HDL simulator. Each item can be enlarged toshow its inputs, outputs, local variables and current state;

42


Figure 6.2.: Simulation Window: Simulation tab.

43


� Event Details area (4): this area shows a concise representation of the event cur-rently selected in the Events list area.

The simulation engine of SMCube HDL can be described using a state machine, whichis shown in Figure 6.3.

The simulation starts in IDLE state and moves in PAUSE state after clicking the startbutton; the idea is that the events are evaluated continuously at simulation speed ratein the PLAY state. When in the STEP state, events are evaluated one by one whenthe step button is clicked (allowing you to execute a step by step simulation). In everystates, the simulation goes back in IDLE state when the stop button is clicked.

Figure 6.3.: The state machine of the SMCube HDL simulation engine.

44

7. Examples

This Chapter describes a set of examples available in the default installation of SM-Cube HDL. Please note that some examples require more than 2 states, and or thatreason they cannot be opened by the SMCube HDL Demo version.

7.1. Timer

Figure 7.1 describes a Timer able to generate a periodic interrupt according to the valueset into the PERIOD register. The CONTROL register is used to start (value equals to 0x1)and to stop (value equals to 0x0) the counter.

Figure 7.1.: Timer Example.

45

Chapter 7. Examples

7.2. Encoder

The state machine implemented in this example decodes the quadrature outputs (enc h

and enc l wire inputs to the state machine) coming from an encoder1 (Figure 7.2).The outputs are given through the COUNT and STATUS registers. The COUNT registeris incremented during clockwise rotation and is decremented during counter-clockwiserotation. The STATUS register is set to 0x00000000 during clockwise rotation while isset to 0x00000001 during counter-clockwise rotation.

Figure 7.2.: Encoder Example.

7.3. Pulse Width Modulation

In this example a PWM (Pulse Width Modulation) pulse generator is implemented(Figure 7.3). A PWM pulse is generated according to the input registers value PERIOD

and DUTY CYCLE. The input register CONTROL is used to configure, start and stop the pulsegeneration. The output is given through the output wires pwm l (the “active low” pulse)and pwm h (the “active high” pulse); it is possible to enable only the pwm l output, onlythe pwm h output or both outputs using the CONTROL register (0x00000008, 0x00000004or 0x0000000C respectively).

1In this implementation, only the rising edges and the falling edges of the enc h input signal are usedto count the clockwise and the counter-clockwise pulses.

46

Chapter 7. Examples

Figure 7.3.: Pulse Width Modulation Example.

7.4. External logic

This is a simple example using the external logic module (Figure 7.4). The external logicmodule controls the current state using the external logic input EXT STATUS. In the UP

state the internal COUNTER register is incremented while it is decremented in the DOWN

state.

47

Chapter 7. Examples

Figure 7.4.: External Logic Example.

The external logic module changes the current state of the state machine accordingto the COUNTER value; the state is reset to IDLE if the input register CLEAR is equals to0x1. The external logic configuration is shown in Figure 7.5.

48

Chapter 7. Examples

Figure 7.5.: External Logic Example: Configuration.

49

A. SMCube HDL Language: BNF-likedescription

The following is a description in BNF-like form of the SMCube HDL Language, used todescribe actions and guards (see Section 3).

D [0-9]

L [a-zA-Z_]

H [abcdefABCDEF]

B [01]

BITWISE_NOT "~"

LOGICAL_NOT "!"

PLUS "+"

MINUS "-"

LSHIFT "<<"

RSHIFT ">>"

LESS "<"

GREATER ">"

LESS_EQ "<="

GREATER_EQ ">="

EQUAL "=="

NOT_EQUAL "!="

BITWISE_AND "&"

BITWISE_XOR "^"

BITWISE_OR "|"

LOGICAL_AND "&&"

LOGICAL_OR "||"

ASSIGN "="

OPENPAR "("

CLOSEPAR ")"

OPENSB "["

CLOSESB "]"

NUMBER {D}+

HEXNUMBER ("0x")({H}|{D})+

BINNUMBER ("0b")({B})+

IDENTIFIER {L}({L}|{D})*

stmt:

assignment

| function_call

50

Appendix A. SMCube HDL Language: BNF-like description

| expr

| error

expr:

LOGICAL_NOT expr

| BITWISE_NOT expr

| expr PLUS expr

| expr MINUS expr

| expr RSHIFT expr

| expr LSHIFT expr

| expr LESS expr

| expr GREATER expr

| expr LESS_EQ expr

| expr GREATER_EQ expr

| expr EQUAL expr

| expr NOT_EQUAL expr

| expr BITWISE_AND expr

| expr BITWISE_XOR expr

| expr BITWISE_OR expr

| expr LOGICAL_AND expr

| expr LOGICAL_OR expr

| NUMBER

| HEXNUMBER

| BINNUMBER

| IDENTIFIER

| IDENTIFIER OPENSB NUMBER CLOSESB

| OPENPAR expr CLOSEPAR

assignment:

IDENTIFIER ASSIGN expr

| IDENTIFIER OPENSB NUMBER CLOSESB ASSIGN expr

function_call:

IDENTIFIER OPENPAR CLOSEPAR

51

B. Demo license version

The SMCube HDL distributed under the demo license has the following limitations:

� The state machines cannot have more the two states excluding the initial pseudo-state;

� The external logic module is not available.

52

C. QT Libraries Licensing

SMCube HDL is written using the Qt Libraries, which are dynamically linked to theexecutable. The Qt GUI Toolkit is Copyright (C) 2011 Nokia Corporation and/or itssubsidiary(-ies), and the following license applies.

The GNU Lesser General Public License (Version 2.1)

GNU LESSER GENERAL PUBLIC LICENSEVersion 2.1, February 1999

Copyright (C) 1991, 1999 Free Software Foundation, Inc.51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USAEveryone is permitted to copy and distribute verbatim copies of this license document, but

changing it is not allowed.

[This is the first released version of the Lesser GPL. It also counts as the successor of theGNU Library Public License, version 2, hence the version number 2.1.]

Preamble

The licenses for most software are designed to take away your freedom to share and changeit. By contrast, the GNU General Public Licenses are intended to guarantee your freedom toshare and change free software–to make sure the software is free for all its users.

This license, the Lesser General Public License, applies to some specially designated softwarepackages–typically libraries–of the Free Software Foundation and other authors who decide touse it. You can use it too, but we suggest you first think carefully about whether this licenseor the ordinary General Public License is the better strategy to use in any particular case,based on the explanations below.

When we speak of free software, we are referring to freedom of use, not price. Our GeneralPublic Licenses are designed to make sure that you have the freedom to distribute copies offree software (and charge for this service if you wish); that you receive source code or can getit if you want it; that you can change the software and use pieces of it in new free programs;and that you are informed that you can do these things.

To protect your rights, we need to make restrictions that forbid distributors to deny youthese rights or to ask you to surrender these rights. These restrictions translate to certainresponsibilities for you if you distribute copies of the library or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you mustgive the recipients all the rights that we gave you. You must make sure that they, too, receive

53

Appendix C. QT Libraries Licensing

or can get the source code. If you link other code with the library, you must provide completeobject files to the recipients, so that they can relink them with the library after making changesto the library and recompiling it. And you must show them these terms so they know theirrights.

We protect your rights with a two-step method: (1) we copyright the library, and (2) weoffer you this license, which gives you legal permission to copy, distribute and/or modify thelibrary.

To protect each distributor, we want to make it very clear that there is no warranty for thefree library. Also, if the library is modified by someone else and passed on, the recipients shouldknow that what they have is not the original version, so that the original author’s reputationwill not be affected by problems that might be introduced by others.

Finally, software patents pose a constant threat to the existence of any free program. Wewish to make sure that a company cannot effectively restrict the users of a free program byobtaining a restrictive license from a patent holder. Therefore, we insist that any patent licenseobtained for a version of the library must be consistent with the full freedom of use specifiedin this license.

Most GNU software, including some libraries, is covered by the ordinary GNU General PublicLicense. This license, the GNU Lesser General Public License, applies to certain designatedlibraries, and is quite different from the ordinary General Public License. We use this licensefor certain libraries in order to permit linking those libraries into non-free programs.

When a program is linked with a library, whether statically or using a shared library, thecombination of the two is legally speaking a combined work, a derivative of the original library.The ordinary General Public License therefore permits such linking only if the entire combi-nation fits its criteria of freedom. The Lesser General Public License permits more lax criteriafor linking other code with the library.

We call this license the “Lesser” General Public License because it does Less to protect theuser’s freedom than the ordinary General Public License. It also provides other free softwaredevelopers Less of an advantage over competing non-free programs. These disadvantages arethe reason we use the ordinary General Public License for many libraries. However, the Lesserlicense provides advantages in certain special circumstances.

For example, on rare occasions, there may be a special need to encourage the widest possibleuse of a certain library, so that it becomes a de-facto standard. To achieve this, non-freeprograms must be allowed to use the library. A more frequent case is that a free library doesthe same job as widely used non-free libraries. In this case, there is little to gain by limitingthe free library to free software only, so we use the Lesser General Public License.

In other cases, permission to use a particular library in non-free programs enables a greaternumber of people to use a large body of free software. For example, permission to use the GNUC Library in non-free programs enables many more people to use the whole GNU operatingsystem, as well as its variant, the GNU/Linux operating system.

54


Although the Lesser General Public License is Less protective of the users’ freedom, it doesensure that the user of a program that is linked with the Library has the freedom and thewherewithal to run that program using a modified version of the Library.

The precise terms and conditions for copying, distribution and modification follow. Payclose attention to the difference between a “work based on the library” and a “work that usesthe library”. The former contains code derived from the library, whereas the latter must becombined with the library in order to run.

GNU LESSER GENERAL PUBLIC LICENSETERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License Agreement applies to any software library or other program which containsa notice placed by the copyright holder or other authorized party saying it may be distributedunder the terms of this Lesser General Public License (also called “this License”). Each licenseeis addressed as “you”.

A “library” means a collection of software functions and/or data prepared so as to beconveniently linked with application programs (which use some of those functions and data)to form executables.

The “Library”, below, refers to any such software library or work which has been distributedunder these terms. A “work based on the Library” means either the Library or any derivativework under copyright law: that is to say, a work containing the Library or a portion of it, eitherverbatim or with modifications and/or translated straightforwardly into another language.(Hereinafter, translation is included without limitation in the term “modification”.)

“Source code” for a work means the preferred form of the work for making modifications toit. For a library, complete source code means all the source code for all modules it contains,plus any associated interface definition files, plus the scripts used to control compilation andinstallation of the library.

Activities other than copying, distribution and modification are not covered by this License;they are outside its scope. The act of running a program using the Library is not restricted,and output from such a program is covered only if its contents constitute a work based on theLibrary (independent of the use of the Library in a tool for writing it). Whether that is truedepends on what the Library does and what the program that uses the Library does.

1. You may copy and distribute verbatim copies of the Library’s complete source code as youreceive it, in any medium, provided that you conspicuously and appropriately publish on eachcopy an appropriate copyright notice and disclaimer of warranty; keep intact all the noticesthat refer to this License and to the absence of any warranty; and distribute a copy of thisLicense along with the Library.

You may charge a fee for the physical act of transferring a copy, and you may at your optionoffer warranty protection in exchange for a fee.

55


2. You may modify your copy or copies of the Library or any portion of it, thus forminga work based on the Library, and copy and distribute such modifications or work under theterms of Section 1 above, provided that you also meet all of these conditions:

a) The modified work must itself be a software library.

b) You must cause the files modified to carry prominent notices stating that you changedthe files and the date of any change.

c) You must cause the whole of the work to be licensed at no charge to all third partiesunder the terms of this License.

d) If a facility in the modified Library refers to a function or a table of data to be suppliedby an application program that uses the facility, other than as an argument passed when thefacility is invoked, then you must make a good faith effort to ensure that, in the event anapplication does not supply such function or table, the facility still operates, and performswhatever part of its purpose remains meaningful.

(For example, a function in a library to compute square roots has a purpose that is en-tirely well-defined independent of the application. Therefore, Subsection 2d requires that anyapplication-supplied function or table used by this function must be optional: if the applicationdoes not supply it, the square root function must still compute square roots.)

These requirements apply to the modified work as a whole. If identifiable sections of thatwork are not derived from the Library, and can be reasonably considered independent andseparate works in themselves, then this License, and its terms, do not apply to those sectionswhen you distribute them as separate works. But when you distribute the same sections aspart of a whole which is a work based on the Library, the distribution of the whole must beon the terms of this License, whose permissions for other licensees extend to the entire whole,and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work writtenentirely by you; rather, the intent is to exercise the right to control the distribution of derivativeor collective works based on the Library.

In addition, mere aggregation of another work not based on the Library with the Library(or with a work based on the Library) on a volume of a storage or distribution medium doesnot bring the other work under the scope of this License.

3. You may opt to apply the terms of the ordinary GNU General Public License insteadof this License to a given copy of the Library. To do this, you must alter all the notices thatrefer to this License, so that they refer to the ordinary GNU General Public License, version2, instead of to this License. (If a newer version than version 2 of the ordinary GNU GeneralPublic License has appeared, then you can specify that version instead if you wish.) Do notmake any other change in these notices.

Once this change is made in a given copy, it is irreversible for that copy, so the ordinaryGNU General Public License applies to all subsequent copies and derivative works made fromthat copy.

This option is useful when you wish to copy part of the code of the Library into a programthat is not a library.

56


4. You may copy and distribute the Library (or a portion or derivative of it, under Section2) in object code or executable form under the terms of Sections 1 and 2 above provided thatyou accompany it with the complete corresponding machine-readable source code, which mustbe distributed under the terms of Sections 1 and 2 above on a medium customarily used forsoftware interchange.

If distribution of object code is made by offering access to copy from a designated place, thenoffering equivalent access to copy the source code from the same place satisfies the requirementto distribute the source code, even though third parties are not compelled to copy the sourcealong with the object code.

5. A program that contains no derivative of any portion of the Library, but is designed towork with the Library by being compiled or linked with it, is called a “work that uses theLibrary”. Such a work, in isolation, is not a derivative work of the Library, and therefore fallsoutside the scope of this License.

However, linking a “work that uses the Library” with the Library creates an executable thatis a derivative of the Library (because it contains portions of the Library), rather than a “workthat uses the library”. The executable is therefore covered by this License. Section 6 statesterms for distribution of such executables.

When a “work that uses the Library” uses material from a header file that is part of theLibrary, the object code for the work may be a derivative work of the Library even thoughthe source code is not. Whether this is true is especially significant if the work can be linkedwithout the Library, or if the work is itself a library. The threshold for this to be true is notprecisely defined by law.

If such an object file uses only numerical parameters, data structure layouts and accessors,and small macros and small inline functions (ten lines or less in length), then the use of theobject file is unrestricted, regardless of whether it is legally a derivative work. (Executablescontaining this object code plus portions of the Library will still fall under Section 6.)

Otherwise, if the work is a derivative of the Library, you may distribute the object code forthe work under the terms of Section 6. Any executables containing that work also fall underSection 6, whether or not they are linked directly with the Library itself.

6. As an exception to the Sections above, you may also combine or link a “work that uses theLibrary” with the Library to produce a work containing portions of the Library, and distributethat work under terms of your choice, provided that the terms permit modification of the workfor the customer’s own use and reverse engineering for debugging such modifications.

You must give prominent notice with each copy of the work that the Library is used init and that the Library and its use are covered by this License. You must supply a copy ofthis License. If the work during execution displays copyright notices, you must include thecopyright notice for the Library among them, as well as a reference directing the user to thecopy of this License. Also, you must do one of these things:

a) Accompany the work with the complete corresponding machine-readable source code forthe Library including whatever changes were used in the work (which must be distributed under

57


Sections 1 and 2 above); and, if the work is an executable linked with the Library, with thecomplete machine-readable “work that uses the Library”, as object code and/or source code,so that the user can modify the Library and then relink to produce a modified executablecontaining the modified Library. (It is understood that the user who changes the contents ofdefinitions files in the Library will not necessarily be able to recompile the application to usethe modified definitions.)

b) Use a suitable shared library mechanism for linking with the library. A suitable mech-anism is one that (1) uses at run time a copy of the library already present on the user’scomputer system, rather than copying library functions into the executable, and (2) will op-erate properly with a modified version of the library, if the user installs one, as long as themodified version is interface-compatible with the version that the work was made with.

c) Accompany the work with a written offer, valid for at least three years, to give the sameuser the materials specified in Subsection 6a, above, for a charge no more than the cost ofperforming this distribution.

d) If distribution of the work is made by offering access to copy from a designated place,offer equivalent access to copy the above specified materials from the same place.

e) Verify that the user has already received a copy of these materials or that you have alreadysent this user a copy.

For an executable, the required form of the “work that uses the Library” must includeany data and utility programs needed for reproducing the executable from it. However, as aspecial exception, the materials to be distributed need not include anything that is normallydistributed (in either source or binary form) with the major components (compiler, kernel,and so on) of the operating system on which the executable runs, unless that component itselfaccompanies the executable.

It may happen that this requirement contradicts the license restrictions of other proprietarylibraries that do not normally accompany the operating system. Such a contradiction meansyou cannot use both them and the Library together in an executable that you distribute.

7. You may place library facilities that are a work based on the Library side-by-side in asingle library together with other library facilities not covered by this License, and distributesuch a combined library, provided that the separate distribution of the work based on theLibrary and of the other library facilities is otherwise permitted, and provided that you dothese two things:

a) Accompany the combined library with a copy of the same work based on the Library,uncombined with any other library facilities. This must be distributed under the terms of theSections above.

b) Give prominent notice with the combined library of the fact that part of it is a workbased on the Library, and explaining where to find the accompanying uncombined form of thesame work.

8. You may not copy, modify, sublicense, link with, or distribute the Library except asexpressly provided under this License. Any attempt otherwise to copy, modify, sublicense, linkwith, or distribute the Library is void, and will automatically terminate your rights under this

58


License. However, parties who have received copies, or rights, from you under this License willnot have their licenses terminated so long as such parties remain in full compliance.

9. You are not required to accept this License, since you have not signed it. However,nothing else grants you permission to modify or distribute the Library or its derivative works.These actions are prohibited by law if you do not accept this License. Therefore, by modifyingor distributing the Library (or any work based on the Library), you indicate your acceptanceof this License to do so, and all its terms and conditions for copying, distributing or modifyingthe Library or works based on it.

10. Each time you redistribute the Library (or any work based on the Library), the recipientautomatically receives a license from the original licensor to copy, distribute, link with or modifythe Library subject to these terms and conditions. You may not impose any further restrictionson the recipients’ exercise of the rights granted herein. You are not responsible for enforcingcompliance by third parties with this License.

11. If, as a consequence of a court judgment or allegation of patent infringement or forany other reason (not limited to patent issues), conditions are imposed on you (whether bycourt order, agreement or otherwise) that contradict the conditions of this License, they donot excuse you from the conditions of this License. If you cannot distribute so as to satisfysimultaneously your obligations under this License and any other pertinent obligations, then asa consequence you may not distribute the Library at all. For example, if a patent license wouldnot permit royalty-free redistribution of the Library by all those who receive copies directly orindirectly through you, then the only way you could satisfy both it and this License would beto refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any particular circum-stance, the balance of the section is intended to apply, and the section as a whole is intendedto apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other propertyright claims or to contest validity of any such claims; this section has the sole purpose ofprotecting the integrity of the free software distribution system which is implemented by publiclicense practices. Many people have made generous contributions to the wide range of softwaredistributed through that system in reliance on consistent application of that system; it is upto the author/donor to decide if he or she is willing to distribute software through any othersystem and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence ofthe rest of this License.

12. If the distribution and/or use of the Library is restricted in certain countries eitherby patents or by copyrighted interfaces, the original copyright holder who places the Libraryunder this License may add an explicit geographical distribution limitation excluding thosecountries, so that distribution is permitted only in or among countries not thus excluded. Insuch case, this License incorporates the limitation as if written in the body of this License.

59


13. The Free Software Foundation may publish revised and/or new versions of the LesserGeneral Public License from time to time. Such new versions will be similar in spirit to thepresent version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library specifies a versionnumber of this License which applies to it and “any later version”, you have the option offollowing the terms and conditions either of that version or of any later version published bythe Free Software Foundation. If the Library does not specify a license version number, youmay choose any version ever published by the Free Software Foundation.

14. If you wish to incorporate parts of the Library into other free programs whose distri-bution conditions are incompatible with these, write to the author to ask for permission. Forsoftware which is copyrighted by the Free Software Foundation, write to the Free SoftwareFoundation; we sometimes make exceptions for this. Our decision will be guided by the twogoals of preserving the free status of all derivatives of our free software and of promoting thesharing and reuse of software generally.

NO WARRANTY

15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NOWARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLELAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLD-ERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WAR-RANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOTLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESSFOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PER-FORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DE-FECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR ORCORRECTION.

16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TOIN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAYMODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LI-ABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTALOR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USETHE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEINGRENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES ORA FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVENIF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OFSUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public,we recommend making it free software that everyone can redistribute and change. You can

60


do so by permitting redistribution under these terms (or, alternatively, under the terms of theordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attach themto the start of each source file to most effectively convey the exclusion of warranty; and eachfile should have at least the “copyright” line and a pointer to where the full notice is found.

¡one line to give the library’s name and a brief idea of what it does.¿Copyright (C) ¡year¿ ¡name of author¿

This library is free software; you can redistribute it and/or modify it under the terms ofthe GNU Lesser General Public License as published by the Free Software Foundation; eitherversion 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WAR-RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR APARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. Youshould have received a copy of the GNU Lesser General Public License along with this library;if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,MA 02110-1301 USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, if any, tosign a “copyright disclaimer” for the library, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the library ‘Frob’ (a library fortweaking knobs) written by James Random Hacker.

¡signature of Ty Coon¿, 1 April 1990Ty Coon, President of Vice

That’s all there is to it!

61

Bibliography

[1] Lattice Semiconductors. Lattice diamond. http://www.latticesemi.com/

latticediamond.

62

http://www.latticesemi.com/latticediamond

http://www.latticesemi.com/latticediamond

Documents

SMCube HDL Reference Manual - Evidence · SMCube HDL Reference Manual The Lattice Diamond Verilog component generator Version: 1.2 November 15, 2012