File Formats

config.toml

General and output configuration. Located at .sawmill/config.toml (project-level) or ~/.config/sawmill/config.toml (user-level).

[general]
default_plugin = "vivado"    # Plugin name to use by default

[output]
color = true                 # Enable coloured output (bool)
format = "text"              # Default output format (string: text/json/count)

Local config overrides user config with a shallow per-section merge.

suppress.toml

Display suppression rules. Located at .sawmill/suppress.toml.

[suppress]
patterns = [
    "INFO:.*Synthesizing",
    "Phase \\d+ .*Complete",
]
message_ids = [
    "Common 17-55",
    "Vivado 12-1023",
]

patterns

List of regex patterns. Messages with raw_text matching any pattern are hidden from display.

message_ids

List of exact message IDs to hide.

Suppressions are display-only — they do not affect CI pass/fail.

waivers.toml

Waiver entries for CI acceptance. Located at .sawmill/waivers.toml.

[metadata]
tool = "vivado"

[[waiver]]
message_id = "Vivado 12-3523"
reason = "Expected warning, reviewed by team"
author = "engineer@company.com"
date = "2026-01-15"

[[waiver]]
message_id = "Synth 8-6157"
content_match = "raw"
content_pattern = "synthesizing module 'top'"
reason = "Top-level synthesis message"
author = "engineer@company.com"
date = "2026-01-15"

[[waiver]]
message_id = "DRC RTSTAT-10"
content_match = "regex"
content_pattern = "Net .* has no driver"
reason = "Test stub nets"
author = "engineer@company.com"
date = "2026-01-15"

Fields per [[waiver]] entry:

Field	Required	Description
message_id	yes	Exact message ID to match.
reason	yes	Why this message is acceptable.
author	yes	Who created this waiver.
date	yes	Creation date (ISO format, e.g. 2026-01-15).
content_match	no	How to interpret content_pattern: "raw" (substring) or "regex".
content_pattern	no	Narrows match beyond message_id. If omitted, matches all instances.

See Waivers for matching semantics.

JSON report

Generated by --report report.json. Top-level structure:

metadata

log_file (string), plugin (string), timestamp (ISO-8601), fail_on_level (int).

exit_code

0 = pass, 1 = failure.

summary

total (int), suppressed (int), waived (int), by_severity (object mapping severity ID to count), waived_by_severity (same shape).

issues

Array of unwaived messages. Each has message_id, severity, content, line, raw_text.

waived

Array of waived messages. Each has message_id, severity, content, line, waiver_message_id, waiver_reason.

suppressed

Array of display-suppressed messages. Each has message_id, severity, content, line, raw_text.

unused_waivers

Array of waivers that matched no messages. Each has message_id, reason.