Specman Notes

1. Specman Notes

2. Specman Elite • From Verisity (http://www.verisity.com) • Presents a high-level language for writing test environments • Test Benches • Coverage • Constraint based test generation and checking

3. Configuration • On pitteda3 or pitteda4 # Verisity user Environment variables (no newlines) setenv SPECMAN_HOME $CAD_DIR/verisity/specman_3.3.3/sn_rel3.3.3 setenv PATH {SPECMAN_HOME}/`${SPECMAN_HOME}/bin/sn_arch.sh`:${SPECMAN_HOME}/bin:${PATH} setenv SPECMAN_DIR $SPECMAN_HOME/`${SPECMAN_HOME}/bin/sn_arch.sh` setenv VERISITYLD_LICENSE_FILE 5286@pitteda1.ee.pitt.edu

4. Files • Copy the tutorial tar file • Copy the emacs specman-mode file • If you use emacs • If you like language editors • Untar the tutorial directories into your own account ( ./src and ./gold )

5. Running (make sure X and DISPLAY are right) specview &

6. e language • Looks like verilog to me… • Has support for data types • With statistical values • With constraints (hard and soft) • Stimulus • Checking • Events

7. On Line Help • Verisity has all their help on line • e language ref • Command ref for Specman Elite • Usage etc. • Tutorial is on OUR web page (large pdf) • Do not print it, just do it. • Its not great

8. File Format • A code segment is enclosed with a begin-code marker <' and an end-code marker '>. • Both the begin-code and the end-code markers must be placed at the beginning of a line (left most), with no other text on that same line (no code and no comments). • The following three lines of code form a code segment: <' import cpu_test_env; '> Several code segments can appear in one file. Each code segment consists of one or more statements.

9. Comments e files begin as a comment which ends when the first begin-code marker <' is encountered. Comments within code segments can be marked with double dashes (--) or double slashes (//): a = 5; -- This is an inline comment b = 7; // This is also an inline comment The end-code '> and the begin-code <' markers can be used in the middle of code sections, to write several consecutive lines of comment

10. Pre Defined Constants Constant Description TRUE For Boolean variables and expressions. FALSE For Boolean variables and expressions. NULL For structs, specifies a NULL pointer. For character strings, specifies an empty string. UNDEF UNDEF indicates NONE where an index is expected. MAX_INT Represents the largest 32-bit int (231 -1) MIN_INT Represents the smallest 32-bit int (-231). MAX_UINT Represents the largest 32-bit uint (232-1).

11. Keywords bytes c export case change check that compute computed consume continue cover cross cvl call cvl callback cvl method cycle default define delay detach do down to dut_error each edges else emit event exec expect extend fail fall file first of for force from gen global hdl pathname if #ifdef #ifndef in index • all of • all_values • and • as a • as_a • assert • assume • async • attribute • before • bit • bits • bool • break • byte

12. Keywords key like line list of matching me nand new nor not not in now nxor on only or others pass prev print range ranges release repeat return reverse rise routine select session soft start state machine step struct string sync sys that then time to transition true try • int • is a • is also • is c routine • is empty • is first • is inline • is instance • is not a • is not empty • is only • is undefined • item • keep • keeping

13. type uint unit until using var verilog code verilog function verilog import verilog simulator verilog task verilog time verilog timescale verilog trace verilog variable vhdl code vhdl driver vhdl function vhdl procedure vhdl driver vhdl simulator vhdl time when while with within Keywords

14. Syntactic Elements • Statements Statements are top-level constructs and are valid within the begin-code <' and end-code '> markers. Statements end with a semicolon ‘;’ • Structmembers Struct members are second-level constructs and are valid only within a struct definition. • Actions Actions are third-level constructs and are valid only when associated with a struct member, such as a method or an event. • Expressions Expressions are lower-level constructs that can be used only within another e construct. The syntax hierarchy roughly corresponds to the level of indentation shown below: statements struct members actions expressions

15. Statements • Statements are top-level constructs and are valid within thebegin-code <' and end-code '> markers. • Key Statement Types: • Struct – defines a new data structure • Type – defines an enumerated/subtype • Extend – extends a previously defined struct or type • Define – extends language with new commands, actions, expressions • More: import, verilog-x, vhdl-x … • Order is not critical – but imports must be first (after macro defines)

16. Struct & Struct Members • Struct members are second-level constructs and are valid only within a struct definition. struct struct-type: struct-descriptor [like base-struct-type: struct-descriptor] { [member: struct-member; ...]} Example: type packet_kind: [atm, eth]; struct packet { len: int; keep len < 256; kind: packet_kind; };

17. Struct Members • field declaration • Defines a data entity that is a member of the enclosing struct and has an explicit data type. • method declaration • Defines an operational procedure that can manipulate the fields of the enclosing struct and access run-time values in the DUT. • subtype declaration • Defines an instance of the parent struct in which specific struct members have particular values or behavior. (e.g., when) • constraint declaration • Influences the distribution of values generated for data entities and the order in which values are generated. (e.g., keep) • coverage declaration • Defines functional test goals and collects data on how well the testing is meeting those goals. • temporal declaration • Defines e events and their associated actions.(e.g., on,expect,assume)

18. Fields [!][%] field: field-name[: type: type] [[min-val: int .. max-val: int]] [((bits | bytes):num: int)] Syntax example: type NetworkType: [IP=0x0800, ARP=0x8060] (bits: 16); struct header { address: uint (bits: 48); hdr_type: NetworkType; !counter: int; };

19. Fields • !Ungenerated Fields • A field defined as ungenerated (with the “!” option) is not generated automatically. • This is useful for fields that are to be explicitly assigned during the test, or whose values involve computations that cannot be expressed in constraints. • Ungenerated fields get default initial values (0 for scalars, NULL for structs, empty list for lists). • An ungenerated field whose value is a range (such as [0..100]) gets the first value in the range. • If the field is a struct, it will not be allocated and none of the fields in it will be generated.

20. Fields • % Physical Fields • A field defined as a physical field (with the “%” option) is packed when the struct is packed. • Fields that represent data that is to be sent to the HDL device in the simulator or that are to be used for memories in the simulator or in Specman Elite, need to be physical fields. • Nonphysical fields are called virtual fields and are not packed automatically when the struct is packed, although they can be packed individually. • If no range is specified, the width of the field is determined by the field’s type. For a physical field, if the field’s type does not have a known width, you must use the (bits | bytes : num) syntax to specify the width.

21. Actions • Actions are third-level constructs and are valid only when associated with a struct member, such as a method or an event. <' struct packet{ event xmit_ready is rise('top.ready'); on xmit_ready {transmit();}; transmit() is { out("transmitting packet..."); }; }; '>

22. Actions • Creating & modifying variables • var, = , op=, • Interacting with the DUT • force, release • Flow control • Conditionals • if then else, labeled case, boolean case • Iteratation • While, repeat until, for each, for from-to, for each-line, for each-file-matching • Flow control • break, continue

23. Actions • Invoking methods and routines • method(), tcm(), start tcm(), routine(), compute method(), return • Performing time consuming actions • emit, sync, wait, all of , first of, state machine • Generating data items • gen • Detecting/handling errors • check that, dut_error(), assert, warning(), error(), fatal(), try • Printing • print, set_config()

24. Expressions • Expressions are lower-level constructs that can be used only within another e construct • Expressions are constructs that combine operands and operators to represent a value • A literal value • A constant • An e entity, such as a method, field, list, or struct • An HDL entity, such as a signal • A compound expression applies one or more operators to one or more operands.

25. Struct Hierarchy • global • sys • switch • ctrl_stub • port_stub1 • sender • listener • port_stub2 • port_stub3 • port_stub4 • packing • files • scheduler • simulator • session

26. Implicit Variables • it : The implicit variable it always refers to the current item. for each in sys.packets{ it.len = 5; .good = TRUE; -- it is assumed };

27. Implicit Variables • Me: The implicit variable me refers to the current struct and can be used anywhere in the struct. struct packet { data: uint; stm() is { var tmp: uint; gen tmp keeping {it < me.data}; - - it is tmp print data, tmp using hex; }; };

28. Implicit Variables • result:The resultvariable returns a value of the method’s return type. If no returnaction is encountered, resultis returned by default. The following method returns the sum of “a” and “b”: sum(a: int, b: int): int is { result = a + b; };

29. Implicit Variables • index: The indexvariable holds the current index of the item referred to by it. The scope of the indexvariable is limited to the action block. for each in packets do { packets[index].len = 5; .id = index; };

30. [ ] List indexing (subscripting) [..] List slicing [ : ] Bit slicing (selection) f(…) Method and routine calls . Field selection ~ Bitwise not ! (not) Boolean not {;} List concatenation %{…} Bit concatenation + - Unary plus, minus *, /, % Binary multiply, divide, modulus +, - Binary add and subtract >> << Shift right, shift left < <= > >= Comparison is [not] a Subtype identification == != Equality, inequality === !== Verilog four-state comparison ~ !~ String matching in Range list operator & Bitwise AND | Bitwise OR ^ Bitwise XOR && (and) Boolean AND || Boolean or => Boolean implication ? : Conditional operator Operators & Precedence

31. Examples num1 = %{num2,num3}; = pack(packing.high,num2,num3); e.g. Num2 = 0x1234; Num3 = 0x7777; Num1 = %{Num2,Num3}; What is Num3?

32. Examples var loc1: list of colors: {red;green;blue}; print loc1;

33. int Represents numeric data, both negative and non-negative integers. (32 bits) uint Represents unsigned numeric data, non-negative integers only. (32 bits) bit An unsigned integer in the range 0–1. (1 bit) byte An unsigned integer in the range 0–255. (8 bits) time An unsigned integer in the range 0–263 -1.( 64 bits) bool Represents truth (logical) values, TRUE(1) and FALSE(0). (1 bit) Types: Scalars

34. Subtypes • By range • int [0..100] • By width • int (bits: 8) • Named Subtypes • type int_count : int [0..99] (bits:7); • var count : int_count;

35. Enumerated Types • You can define the valid values for a variable or field as a list of symbolic constants. var kind: [immediate, register]; • You can extend the definition: type packet_protocol: []; extend the definition of the type with extend packet_protocol : [Ethernet, IEEE, foreign];

36. Struct Subtypes type packet_protocol: [Ethernet, IEEE, foreign]; struct packet { protocol: packet_protocol; size: int [0..1k]; data[size]: list of byte; legal: bool; }; extend sys { gen_eth_packet () is { var packet: legal Ethernet packet; -- local sub-type gen packet keeping {it.size < 10;}; print packet; }; };

37. Generate example struct location { address: int; … } gen l keeping {it.address == 2*i}

38. Subtypes with extend & when type packet_protocol: [Ethernet, IEEE, foreign]; struct packet { protocol: packet_protocol; size: int [0..1k]; data[size]: list of byte; // when Ethernet packet {e_field: int; -- same as extend below // show() is {out("I am an Ethernet packet") // }; }; extend Ethernet packet { e_field: int; show() is {out("I am an Ethernet packet")}; };

39. Accessing sub-typed structs type packet_protocol: [Ethernet, IEEE, foreign]; struct packet { protocol: packet_protocol; when IEEE packet { i_val: int;}; }; var pk_inst: IEEE packet; pk_inst.i_val = 1; if pk_inst is a IEEE packet (ip) {ip.i_val = 1; }; pk_list.first(it is a IEEE packet (ip) and ip.i_val == 1);

40. List functions list.add, list.add0, list.clear, list.insert, list.delete, list.first var ilist: list of int; ilist.add(5); var iitem: instr; iitem = instr_list.first(it.op1 > 15);

41. List add usage struct p_l { ! packeti : packet ! plst: list of packet; mklst() @sysclk is { gen packeti; plst.add(packeti); stop.run(); } }

42. @ event sim_ready is change(‘top\ready’) @sim; Simulator object change @sys.any – predefined event occurs everytime anyother event occurs extend sys { event clk is rise(‘top.clk’) @sim; }

43. List types • perl-like array/list semantics • my_list[0] refers to the first item in the list var lob: list of byte = {15;31;63;127;255}; print lob[0..2]; • No multi-dimensional lists. To create a list with sublists in it, create a struct to contain the sublists

44. Example type packet_protocol : [Ethernet, IEEE, foreign]; struct packet { protocol: packet_protocol; len: int [0..10]; }; extend sys { packets[10] : list of packet; do_print() is { var all_lengths: list of packet'len; all_lengths = packets.len; -- multi-element assignment print packets; print all_lengths; }; };

45. sys = packets = item type protocol len 0. packet Ethernet 10 1. packet Ethernet 10 2. packet IEEE 4 3. packet IEEE 0 4. packet Ethernet 7 5. packet Ethernet 8 6. packet foreign 8 7. packet Ethernet 5 8. packet Ethernet 3 9. packet foreign 6 all_lengths = 0. 10 1. 10 2. 4 3. 0 4. 7 5. 8 6. 8 7. 5 8. 3 9. 6 Run system:

46. Keyed Lists • A keyed list data type is similar to hash tables or association lists found in other programming languages. struct person { name: string; id: int; }; struct city { persons: list(key: name) of person; street_names: list(key: it) of string; };

47. Constraints with Keep keep constraint-bool-exp Syntax example: keep kind != tx or len == 16; Parameters constraint-bool-exp A simple or a compound Boolean expression. • States restrictions on the values generated for fields in the struct or the struct subtree,or describes required relationships between field values and other items in the struct or its subtree. • Hard constraints are applied whenever the enclosing struct is generated. For any keep constraint in a generated struct, the generator either meets the constraint or issues a constraint contradiction message. Note If the keep constraint appears under a when construct, the constraint is considered

48. Keep examples struct pkt { kind: [tx, rx]; len: int; keep kind == tx => len == 16; // when tx pkt { -- this acts exactly the same way // keep len == 16; // }; }; Both these constraints are identical to the constraint: keep kind != tx or len == 16; Note: this is just the true meaning of “=>” Boolean implication

49. Keep examples Using the predefined method “is_a_permutation()” struct astr { l_1: list of int; l_2: list of int; keep l_2.is_a_permutation(l_1); }; struct transaction { address: uint; keep soft address == select { -- using keep soft and select 10: [0..49]; 60: 50; 30: [51..99]; }; };

50. struct transaction { address: uint; keep soft address == select { 10: [0..49]; 60: 50; 30: [51..99]; }; }; extend transaction { keep address in [10..50]; keep soft address == select { 10: min; 60: others; 30: max; }; }; extend instr { keep soft opcode == select { 40: [ADD, ADDI, SUB, SUBI]; 20: [AND, ANDI, XOR, XORI]; 10: [JMP, CALL, RET, NOP]; ‘top.carry' * 90: JMPC; }; }; Keep examples