Part 6 · Agents & Protocol IP · Intermediate

Configuration and Documentation: Making VIP Usable by Others

Designing self-consistent cfg schemas and practical docs so external teams can adopt, tune, and troubleshoot VIP without source spelunking.

Documentation as API surface

For reusable VIP, documentation quality directly affects integration time and defect rate. Docs should mirror cfg schema and runtime behavior exactly.

A high-quality cfg-and-docs layer enables new teams to integrate confidently without reverse engineering implementation details.

diagram

[VIP][DOC] minimum doc set

quickstart:
  instantiate + connect in minimal env

cfg reference:
  every field, type, default, valid range, behavior

mode guide:
  active vs passive responsibilities

debug guide:
  common symptoms and remediation steps

migration guide:
  changes between versions

diagram

[CFG] schema quality criteria

field has:
  - precise name
  - type and units
  - default
  - legal range
  - side effects
  - interaction notes with other fields

Make docs authoritative and versioned with source.
Keep cfg references complete and behaviorally specific.
Include quickstart and debug guides, not only API lists.

Cfg schema design and validation

Cfg objects should be structured, validated, and stable. Group related fields and avoid ambiguous booleans where enums communicate intent better.

systemverilog

typedef enum {CHK_OFF, CHK_BASIC, CHK_STRICT} check_mode_e;

class vip_cfg extends uvm_object;
  `uvm_object_utils(vip_cfg)
  uvm_active_passive_enum is_active = UVM_ACTIVE;
  check_mode_e check_mode = CHK_BASIC;
  int unsigned timeout_cycles = 256;
  int unsigned max_outstanding = 8;
  bit coverage_enable = 1;
  bit random_gap_enable = 0;
  virtual vip_if vif;

  function new(string name = "vip_cfg");
    super.new(name);
  endfunction
endclass

systemverilog

function void validate_cfg(vip_cfg c);
  if (c.vif == null)
    `uvm_fatal("CFG", "vif must be assigned")
  if (c.timeout_cycles < 4)
    `uvm_fatal("CFG", "timeout_cycles must be >= 4")
  if (c.max_outstanding == 0)
    `uvm_fatal("CFG", "max_outstanding must be > 0")
endfunction

diagram

[VIP][CFG] naming guidelines

prefer:
  timeout_cycles        (units explicit)
  check_mode            (enum intent)
  max_outstanding       (resource semantics)

avoid:
  timeout               (units ambiguous)
  strict_checks_en      (boolean mode creep)
  misc_cfg              (non-semantic bucket)

Use enums for multi-state behavior rather than chained booleans.
Validate cfg values at build time with precise fatal messages.
Choose field names that encode units and intent.

Quickstart and integration examples

Every VIP package should include minimal working examples for active and passive integration. Consumers copy these patterns first.

systemverilog

// Active quickstart
vip_cfg cfg = vip_cfg::type_id::create("cfg");
cfg.is_active = UVM_ACTIVE;
cfg.vif = tb_top.vip_vif;
cfg.timeout_cycles = 200;

uvm_config_db#(vip_cfg)::set(this, "env.vip_agt", "cfg", cfg);
env.vip_agt = vip_agent::type_id::create("vip_agt", env);

systemverilog

// Passive quickstart
vip_cfg mon_cfg = vip_cfg::type_id::create("mon_cfg");
mon_cfg.is_active = UVM_PASSIVE;
mon_cfg.vif = tb_top.vip_vif;

uvm_config_db#(vip_cfg)::set(this, "env.vip_mon_agt", "cfg", mon_cfg);
env.vip_mon_agt = vip_agent::type_id::create("vip_mon_agt", env);

diagram

[DOC] quickstart page outline

section 1: dependencies
section 2: active instantiation snippet
section 3: passive instantiation snippet
section 4: connect_phase analysis wiring
section 5: first smoke test command
section 6: expected startup log signatures

Provide copy-paste-ready snippets for both modes.
Keep examples synchronized with current cfg schema.
Include expected logs to help users validate setup quickly.

Troubleshooting docs and supportability

Good docs include failure signatures and likely causes. This reduces support load and helps consumers self-diagnose integration mistakes.

diagram

[VIP][DEBUG] troubleshooting table examples

symptom                                  likely cause
---------------------------------------------------------------
build fatal: cfg missing                 config_db path mismatch
build fatal: vif null                    interface not assigned
no transactions in active mode           sequence not started or mode mismatch
no transactions in passive mode          monitor sampling/config issue
unexpected warnings after upgrade        deprecated field still in use

diagram

[DOC] support playbook section

collect:
  VIP version
  simulator + UVM version
  startup mode logs
  topology excerpt
  minimal reproducer

then:
  compare with known-issues matrix
  apply documented fix or migration step

diagram

[CI][DOC] doc correctness checks

- snippet compile sanity
- cfg field names match source
- links to quickstart and migration are valid
- version string in docs matches release tag

Key takeaways

Cfg schema and docs together define practical usability of VIP.
Validated, example-driven docs accelerate adoption and reduce support churn.
Troubleshooting guidance should map symptoms to concrete fixes.
Automated doc sanity checks keep documentation trustworthy over time.

Common pitfalls

Letting docs lag behind cfg and behavior changes.
Publishing abstract guidance without concrete integration snippets.
Using ambiguous cfg names and undocumented side effects.
Treating troubleshooting as external support burden instead of product scope.

Practice this lessonQuestions tagged for this topic in the bank