Tunnel Message Formats

The Simscope Tunnel uses a JSON input format for its input messages (from the input-queue).

Tunnel Input Message Types

Tunnel consumes three types of input messages.

These are determined via the message Type field in RabbitMQ.

Each message must also contain a Correlation-ID value containing the regression associated with the message.

Each message Body should be a JSON object. This JSON body has a specific format, for each message type (see below).

Message Types

There are 3 required message types to implement (the others are optional for your flow):

1. regr-start
2. regr-finish
3. job-finish

All message types available:

1. regr-start (Regression Start)

A regr-start message notifies Simscope of a regression start event. This should be the first message sent from a new regression.

The message Body should contain a Regression JSON object.

Simscope will automatically flag the regression as LIVE, until a regr-finish message is received.

2. job-live (Job Start)

This is an optional message, to indicate a job has started running.

This lets users see which jobs are running (and remaining) in a regression.

→ See Live Job Tracking for more details.

3. job-finish (Job Finish)

A job-finish message notifies Simscope that a Job has completed (pass, fail, or skip).

The message Body should contain a Job JSON object.

4. batch-job-finish (Batch Job Finish)

A batch-job-finish message notifies Simscope that an array of Jobs has completed (pass, fail, or skipped).

The message Body should contain an array of Job JSON object.

Note: batch-job-finish should only be used for higher performance bulk updates (e.g. 100 jobs updated).
It should not be used for single-job updates.

For example this is a skeleton for a 2-job update:

[
    {
        "jobdir": "/home/runs/myregr/100/job-1",
        "category": "sim",
        <etc>...
    },
    {
        "jobdir": "/home/runs/myregr/100/job-2",
        "category": "sim",
        <etc>...
    }
]

5. regr-update (Regression Update — Optional message)

A regr-update is an optional message, which notifies Simscope of a regression metadata update event.

This is useful for two purposes:

• If Live Tracking with submitted or running jobs, you can notify Simscope dynamically that a Regression has more jobs either submitted and/or running.
• To post end-of-regression metadata, like coverage values.

The message Body should contain a partial Regression JSON object.

Notes:

• regr-update can be published any time after a regression has started (or even after it finishes, to update coverage).
• If you publish a regr-update message after a regression has finished, and do not specify pending: false in the JSON, Simscope will set the regression back to LIVE.
  • To keep it the regression as finished in the user interface, append pending: false to the JSON.

Example Submitted count update

For example, to update the regression submitted count field:

{
    "name": "full_chip_weekly/9",
    "submitted": 225
}

Example Coverage update

To update Regression Custom Metadata after a regression has finished:

{
    "name": "cpu_smoke/125",
    "pending": false,
    "custom_metadata": [
        ["Functional Coverage", "72.4"],
        ["line_cov", "94.6"]
    ]
}

6. regr-finish (Regression Finish)

A regr-finish message notifies Simscope of a regression completion event. Once this event has been sent, Simscope is assumed the regression and all of its jobs have completed.

• This event automatically turns off the LIVE flag for this regression in Simscope.

For regr-finish messages, the Body field is an optional JSON body.

• This can be used to update regression metadata while the regression is marked finished (the same format as the regr-update message.
• For example, you can update coverage results at end-of-regression.

Tunnel Message Output

The tunnel outputs messages directly to an output queue, which can be consumed by Simscope.

Example Tunnel Message Flow

To publish the results of a regression with 5 jobs, publish these 7 messages to the Tunnel:

1. Publish regr-start     — Regression will show as LIVE
   2. Publish job-finish  — after Job #1 finishes
   3. Publish job-finish  — after Job #2 finishes
   4. Publish job-finish  — after Job #3 finishes
   5. Publish job-finish  — after Job #4 finishes
   6. Publish job-finish  — after Job #5 finishes
7. Publish regr-finish    — Regression will show as complete

• Note: the five job-finish events (messages #2 through #6 above) can occur in any order (as queue/grid/compute machine parallel ordering is unpredictable).