Jobs: Tasks

Modified on Wed, 18 Sep, 2024 at 10:52 AM

Jobs: Tasks

A job is comprised of tasks, which are executed in the remote workspace in parallel unless otherwise specified by the depends property. Each task should have a unique and descriptive name made up of uppercase and lowercase letters, numbers and the character -, but cannot start with a - or have any whitespace. The status of these tasks is obtained with the job-id. If there is an error in executing a task, all the following tasks are omitted and not executed.

Task Dependencies

Job tasks are executed in parallel unless they contain the depends property. The value of the depends property, given as an array of task names, specifies which task(s) must complete before the current task can be executed. A single job can have multiple tasks linked by a Directed Acyclic Graph (DAG), resulting in task dependencies. Each task can execute multiple simulator commands. This diagram shows a job with multiple tasks with dependencies:

Task elaborate depends on task compile. Tasks sim1 to sim5 depend on task elaborate.

All files required to execute a task with dependencies must be passed to it by a previously executed task as working inputs inputs.working. Tasks pass files to other tasks as working outputs outputs.working. All working inputs and outputs are intermediate files that are removed upon job completion, ie. they are not available for download.

Let's examine the following tasks from carry_lookahead_adder.yml to see the task dependencies:

- name: compile-sv
  depends: [sim-vhdl-sv]
  commands:
    - dsim -genimage image_sv -F SystemVerilog/sim/filelist.txt +acc+b
  inputs:
    working:
      - name: sim-vhdl-sv.source
        path: ./
  outputs:
    artifacts:
      - name: log-sv
        path: dsim.log
    working:
      - name: image-sv
        path: dsim_work/image_sv.so
- name: sim-vhdl-sv
  compute_size: s8
  mdc_work: VHDL_SystemVerilog/sim/
  commands:
    - dvhcom -F filelist_VHDL.txt
    - dvlcom -F filelist_SV.txt
    - dsim -top work.carry_lookahead_adder_tb +acc+b -waves waves_vhdl_sv.mxd
  outputs:
    working:
      - name: source
        path: ./

The task compile-sv depends on the task sim-vhdl-sv and requires all the files from the local workspace. The files are passed to inputs.working of compile-sv as sim-vhdl-sv.source since the required outputs.working of sim-vhdl-sv is source. The path ./ indicates all folders and files of the remote work directory.

- name: run-sv-1
  depends: [compile-sv]
  commands:
    - dsim -image image_sv -waves waves_sv_1.mxd -sv_seed 1
  inputs:
    working:
      - name: compile-sv.image-sv
        path: dsim_work/image_sv.so

The task run-sv-1 depends on the task compile-sv and requires only the image file generated by it. The file is passed to inputs.working of run-sv-1 as compile-sv.image-sv from the outputs.working image-sv of compile-sv. The path dsim_work/image_sv.so is relative to the remote work directory.

- name: run-sv-2
  depends: [compile-sv]
  commands:
    - dsim -image image_sv -waves waves_sv_2.mxd -sv_seed 2
  inputs:
    working:
      - name: compile-sv.image-sv
        path: dsim_work/image_sv.so
  outputs:
    artifacts:
      - name: waves-sv-2
        path: waves_sv_2.mxd
      - name: log-sv-2
        path: dsim.log
- name: run-sv-3
  depends: [compile-sv]
  commands:
    - dsim -image image_sv -waves waves_sv_3.mxd -sv_seed 3
  inputs:
    working:
      - name: compile-sv.image-sv
        path: dsim_work/image_sv.so

The tasks run-sv-2 and run-sv-3 also depend on the task compile-sv. This is how you can compile only once and run many times using the same image.

- name: sim-vhdl
  depends: [run-sv-3, sim-vhdl-sv]
  commands:
    - dvhcom -F VHDL/sim/filelist.txt
    - dsim -top work.carry_lookahead_adder_tb +acc+b -waves waves_vhdl.mxd
  inputs:
    working:
      - name: sim-vhdl-sv.source
        path: ./

Similarly, task sim-vhdl depends on tasks run-sv-3 and sim-vhdl-sv. This is how you can specify the order of task execution.

So instead of all tasks being executed in parallel, they will be executed in this order:

sim-vhdl-sv
compile-sv
run-sv-1, run-sv-2, and run-sv-3
sim-vhdl

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.

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.

Task Limits

Each job file is limited to 25 tasks. Exceeding this limit will result in an error during job submission. If this occurs, consider using Task Fanout or breaking up the job file into multiple smaller job files.

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

There is a limit of 100 concurrent tasks across all jobs. This limit can be increased for paid plans by contacting support.