Frequently Asked Questions

The CLI is written in Rust. Build from source using Cargo:

cargo install xsil

Pre-built binaries for Linux and macOS are available on the GitHub releases page.

Use the Extension Wizard. Either fill the web form at extensilica.com/wizard and download a ready-to-edit .xsil, or run the CLI:

xsil new my-extension

Both paths produce the same skeleton: manifest.json, opcodes.json, an opcodes.h header with __asm__ .insn macros for each declared instruction, a Spike extension_t stub under sim/spike-extension/ withMakefile, runnable per-instruction examples in examples/, an SPDX LICENSE, a Keep-a-Changelog CHANGELOG.md, and standard tests/, docs/, and toolchain/ placeholders. The wizard requires a repository URL (use the future GitHub URL if the repo does not exist yet).

The wizard never publishes for you — the output is a local archive you can edit, version, and ship with xsil publish when ready.

Every package on ExtenSilica must declare its honest relationship to the RISC-V standard. The label appears as a badge on the package page and powers the homepage counts. Five values are allowed:

• ratified — frozen specification approved by RISC-V International. The encoding is locked.
• draft — working draft from RISC-V International or another standards body. Not ratified yet — the encoding may still change.
• vendor — custom extension defined and shipped by a commercial vendor (T-Head, SiFive, Qualcomm, Andes, Ventana, …).
• research — academic / experimental extension, often used in research papers or pre-production prototypes.
• custom — bespoke or one-off extension that does not fit the categories above.

The accompanying authority field is free text (2–200 characters) identifying who defines the spec — for example RISC-V International, T-Head / XuanTie, or University of Michigan. Both fields are stored at the top of manifest.json, validated by the registry, and required by both the web wizard and xsil new. Do not label a package ratified unless RISC-V International has actually frozen the spec — the registry checks this and we audit the catalog regularly.

portStatus is orthogonal to standardStatus: the latter describes the SPEC, the former describes who put the package on ExtenSilica and whether the upstream maintainer has blessed it. It is always server-set — we never read it from the uploaded manifest, so publishers cannot lie about being the official maintainer. Five values exist:

• seeded — auto-published by the ExtenSilica catalog-seed agent from public sources. The upstream maintainer has not (yet) claimed authorship.
• community_port — ported by a non-upstream community member. Useful, but not vetted as official.
• claimed — the current owner went through the Request authorship flow and was approved by a platform admin.
• official — a platform admin verified the publisher's identity / affiliation with the upstream project.
• archived — upstream is dead or the package has been intentionally frozen. Still installable; no further updates expected.

Packages published directly by a user are unmarked ("self-published") until either an ownership claim or an admin verification flips them. Approving an ownership request on a seeded or community_port package automatically promotes it to claimed.

• name, version, description, author, license
• isa — RISC-V ISA string (e.g. rv64gc, rv64imafc)
• targets — declared execution platforms (typically spike, optionally qemu, binutils, llvm, fpga)
• entry / testEntry — primary run / test entry points
• checksums.payload — SHA-256 of the non-manifest payload for integrity verification
• repository — http(s) URL to the source (required for wizard-generated packages)

Common companion files (all optional but produced by xsil new and the web wizard):

• opcodes.json — schema-versioned descriptor of custom instructions (mnemonic, format, opcode, funct3/funct7, operands, summary)
• opcodes.h — C header with __asm__ macros that emit the custom instructions via GAS .insn, no toolchain patch required
• sim/spike-extension/ — Spike extension_t C++ stub plus Makefile for building lib<slug>_spike.so
• examples/, tests/, docs/, toolchain/ — runnable examples, expected-output tests, prose docs, and a placeholder for any bundled toolchain
• README.md, CHANGELOG.md, LICENSE, .xsilignore — standard surface metadata
• bitstream/ — optional FPGA artifacts when applicable

1. Create a free account at extensilica.com/register.
2. Authenticate the CLI:

   xsil login

3. Create your package directory with a valid manifest.json. Run a dry-run to validate it:

   xsil publish ./my-package/ --dry-run

4. Set resolution.mode to bundled, resolved, or host-dependent per your reproducibility story. If you use resolved with dependencies.tools, you can upload matching binaries to ExtenSilica artifacts so installs resolve with auth; it is optional for other modes.
5. Publish when ready:

   xsil publish ./my-package/

The CLI validates your manifest, computes SHA-256 checksums, packs the directory into a .xsil archive, and uploads it to the registry. The backend stores your declared resolution.mode and dependencies; strict artifact linkage is applied only when every declared resolved tool matches a registered ExtenSilica artifact.

• Contain only lowercase letters (a–z), digits (0–9), and hyphens (-) — no underscores
• Start and end with a letter or digit (no leading or trailing hyphen)
• Be between 2 and 64 characters
• Be unique across the entire registry
• Not match a reserved name (e.g. extensilica, admin, api, system) — the full list is enforced server-side

Pattern: ^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$|^[a-z0-9]{1,2}$

Organizations and scoped slugs use the form @<org>/<package>; both segments follow the same rules above.

Names that impersonate popular projects, contain offensive language, or are reserved for abuse purposes may be removed.

You cannot overwrite or delete a published version. Version immutability is a core design principle: once [email protected] is published, its bytes are permanent. This ensures reproducible builds for anyone who depends on that version.

What you can do:

• Publish a new version — use semantic versioning to supersede the old one.
• Yank a version — mark it as unsafe. Yanked versions are excluded from normal installs but remain in the registry for auditability.
• Deprecate a package — mark the entire package as deprecated (e.g., if it has been renamed). A deprecation notice is shown on the package page.
• Edit metadata — description, keywords, links, and README can be updated at any time via the dashboard or xsil publish. Version artifacts are immutable; metadata is not.

There is no manual review gate. Packages are indexed and publicly visible immediately upon successful upload. We perform integrity verification (checksum validation) at upload time but do not perform automated behavioral analysis of package contents.

Authors are solely responsible for the content of their packages. See the Terms of Service for the full acceptable-use policy.

Organization profiles live under /orgs/<slug>. Package pages and CLI commands accept scoped slugs wherever a package name is accepted.

The latest tag always points to the semver-greatest non-yanked version of a package. It is recomputed automatically after every publish. This means publishing a backport patch (e.g., 1.0.1 after 1.1.0 is already live) does not move the latest tag.

You can explicitly target latest in the CLI:

xsil install rvx-demo@latest
xsil info    rvx-demo@latest

Use the @version suffix with any xsil command that accepts a package name:

xsil install [email protected]
xsil run     [email protected]
xsil info    [email protected]

The version history table on every package page shows per-version install commands that you can copy with one click.

Yanking marks a version as unsafe without deleting it. Yanked versions:

• Are excluded from normal resolution (latest, bare installs).
• Appear in the version history with a yanked badge.
• Can only be installed explicitly with xsil install pkg@version --override-security.
• Are not deleted — the artifact remains accessible for auditing and for systems that were already pinned to that version.

Every .xsil package records a SHA-256 checksum of all non-manifest files at publish time. The xsil CLI recomputes this checksum on every install and before every run or test. If the bytes do not match — the file was tampered with, corrupted in transit, or silently replaced — the CLI refuses to execute it and prints an error.

This gives you a strong integrity check: what runs matches the author-published payload checksum, regardless of how the file was served.

Exercise caution. .xsil packages may contain executable scripts and binaries. The registry verifies archive integrity (checksums match what the author published) but does not perform behavioral analysis.

Before running a package from an unknown author:

• Review the package description, README, and repository link.
• Inspect the entry point and any scripts listed in the manifest.
• Check download counts and reviews — popular, well-reviewed packages from active authors are lower risk.
• Consider running inside a sandbox or container.

For IP / copyright infringement, use the formal DMCA / Takedown Request page.

For malware, abuse, or policy violations, email [email protected] or open an issue on the project’s GitHub repository with the package name, version(s), and a description of the concern. We treat security and abuse reports as high priority and will investigate promptly. Confirmed malicious packages will be yanked and the publishing account suspended.

At publish time the CLI computes two SHA-256 digests:

• Payload checksum — SHA-256 over all non-manifest files (sorted by path), stored in manifest.json.
• Archive checksum — SHA-256 of the full .xsil archive byte stream, verified by the server on upload and stored in the registry database.

At install time the CLI re-downloads the archive, recomputes the archive checksum, and recomputes the payload checksum from the extracted files. Any mismatch causes an immediate abort.

For resolved mode with dependencies.tools, the CLI may download each declared tool archive, verify SHA-256, and cache it before execution. bundled and host-dependent flows skip those downloads.

Running xsil login prompts for your email and password. On success the registry returns a random opaque API token. The CLI stores this token in ~/.extensilica/config.json. All subsequent authenticated requests (publish, etc.) send the token as a Bearer header.

The token is not a session cookie and is not stored in the browser. Running xsil logout invalidates the token on the server and removes it from the config file.

Keep your config file and token private. Do not commit it to version control.

Yes. Email [email protected] or open an issue on GitHub to request account deletion. We will remove your email, password hash, and API token.

Your published packages will remain in the registry — they are attributed to your username but no longer linked to active account credentials. Other users’ builds may depend on your packages, so we do not delete artifacts on account closure.