Jobs: Task Fanout

Modified on Wed, 26 Jun at 3:18 PM

Jobs: Task Fanout

Job tasks can be programmatically generated in your job file to run in parallel with specific values, so that you don't have to repeat the same task multiple times. You can define a single fanout rule per task based on the results of a value generator. The task will be generated, or will fanout, as one task per value generator result. The results are accessible from the generated tasks as variables using $(fanout.variablename), to repeat the same task multiple times with different values.

The fanout variable $(fanout.variablename) can only be used in the commands sections of the job file.

There is a limit of 3,000 post-fanout tasks per job file.

Example job files with fanout rules for various types of value generators below will help illustrate the use of task fanout.

Sequence Value Generator

The Sequence Value Generator generates a sequence of integers (positive or negative) from the property from to the property to, inclusively:

from and to must be greater than -9007199254740991 and less than 9007199254740991
|to - from| must be less than 1000000

Example job file carry_lookahead_adder_sequence.yml

Let's examine carry_lookahead_adder_sequence.yml, shown below and can be downloaded from the carry_lookahead_adder design.

name: carry-lookahead-adder-sequence
tasks:
  - name: simulate
    mdc_work: SystemVerilog/sim
    commands:
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -l logs/carry_lookahead_log_$(fanout.seed).log -sv_seed $(fanout.seed)
    fanout:
      name: seed
      type: sequence
      from: 100
      to: 110
    outputs:
      artifacts:
        - name: carry_lookahead_log
          path: SystemVerilog/sim/logs

Required fanout rule:

fanout: Task property indicating the task will fanout to multiple generated tasks.

name: seed Name of fanout task. Accessible in generated tasks as $(fanout.seed) in the example.

type: sequence Type of value generator.

from: 100 Minimum sequence value.

to: 110 Maximum sequence value.

The task simulate will fanout to 11 tasks, named simulate-<fanout.seed>. Each task will execute the dsim command with a different value for $(fanout.seed), from 100 to 110, inclusively, so that 11 commands are executed as follows:

      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -l logs/carry_lookahead_log_100.log -sv_seed 100
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -l logs/carry_lookahead_log_101.log -sv_seed 101
      ...
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -l logs/carry_lookahead_log_109.log -sv_seed 109
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -l logs/carry_lookahead_log_110.log -sv_seed 110

Each task will have an artifact named carry_lookahead_log-<fanout.seed> that contains the log file from the dsim command. Artifacts can be downloaded using mdc job download.

Random Value Generator

The Random Value Generator generates a count number of unique random integers (positive or negative) from the property from to the property to, inclusively:

from and to must be greater than -9007199254740991 and less than 9007199254740991
|to - from| must be less than 1000000

Example job file carry_lookahead_adder_random.yml

Let's examine carry_lookahead_adder_random.yml, shown below and can be downloaded from the carry_lookahead_adder design.

name: carry-lookahead-adder-random
tasks:
  - name: simulate
    mdc_work: SystemVerilog/sim
    commands:
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until $(fanout.time)ns -l logs/carry_lookahead_log_$(fanout.time)ns.log -sv_seed random
    fanout:
      name: time
      type: random
      from: 10
      to: 6500
      count: 5
    outputs:
      artifacts:
        - name: carry_lookahead_log
          path: SystemVerilog/sim/logs

Note that we have used random for the option -sv_seed instead of $(fanout.time). We recommend using the DSim built-in option -sv_seed random to generate SystemVerilog random seeds rather than the random value generated by the Random Value Generator.

Required fanout rule:

fanout: Task property indicating the task will fanout to multiple generated tasks.

name: time Name of fanout task. Accessible in generated tasks as $(fanout.time) in the example.

type: random Type of value generator.

from: 10 Minimum sequence value.

to: 6500 Maximum sequence value.

count: 5 Number of unique random integers.

The task simulate will fanout to 5 tasks, named simulate-<fanout.time>. Each task will execute the dsim command with a different value for $(fanout.time), from 10ns to 6500ns, inclusively, so that 5 commands are executed as follows, for example. The actual values of -run-until and -sv_seed will vary.

      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 200ns -l logs/carry_lookahead_log_200ns.log -sv_seed random
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 4269ns -l logs/carry_lookahead_log_4269ns.log -sv_seed random
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 4292ns -l logs/carry_lookahead_log_4292ns.log -sv_seed random
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 4340ns -l logs/carry_lookahead_log_4340ns.log -sv_seed random
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 5430ns -l logs/carry_lookahead_log_5430ns.log -sv_seed random

Each task will have an artifact named carry_lookahead_log-<fanout.time> that contains the log file from the dsim command. Artifacts can be downloaded using mdc job download.

Static Value Generator

The Static Value Generator generates a static set of values defined by the user in the values array. Example values arrays:

[1,2,3,4,'words']
[1,2,3,4]
['one', 'two']
[1, 'two']
[one, two]
[one, two words]
[1ns, two microseconds, 5000]

The maximum length of individual values in the values array is 128 characters. All values are treated as strings, so both ['one', 'two'] and [one, two] will result in fanout variables one and two. Values can be made up of uppercase and lowercase letters, numbers, and the characters ., _ and -. They cannot end in ., have consecutive . characters, or any whitespace.

Example job file carry_lookahead_adder_static.yml

Let's examine carry_lookahead_adder_static.yml, shown below and can be downloaded from the carry_lookahead_adder design.

name: carry-lookahead-adder-static
tasks:
  - name: simulate
    mdc_work: SystemVerilog/sim
    commands:
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until $(fanout.time) -l "logs/carry_lookahead_log_$(fanout.time).log"
    fanout:
      name: time
      type: static
      values:
        [
          1000ns,
          2345ns,
          5ns,
          6500ns
        ]
    outputs:
      artifacts:
        - name: carry_lookahead_log
          path: SystemVerilog/sim/logs

Required fanout rule:

fanout: Task property indicating the task will fanout to multiple generated tasks.

name: time Name of fanout task. Accessible in generated tasks as $(fanout.time) in the example.

type: static Type of value generator.

values: Values array.

The task simulate will fanout to 4 tasks, named simulate-<fanout.time>ns. Each task will execute the dsim command with a different value for $(fanout.time), so that 4 commands are executed as follows.

      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 1000ns -l "logs/carry_lookahead_log_1000ns.log"
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 2345ns -l "logs/carry_lookahead_log_2345ns.log"
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 5ns -l "logs/carry_lookahead_log_5ns.log"
      - dsim -top work.carry_lookahead_adder_tb -F filelist.txt -run-until 6500ns -l "logs/carry_lookahead_log_6500ns.log"

Each task will have an artifact named carry_lookahead_log-<fanout.time>ns that contains the log file from the dsim command. Artifacts can be downloaded using mdc job download.