C⏚ v2.0.0Updated 2026-05-12·Getting started

C⏚ Documentation

C⏚ (pronounced C-Ground) is a hardware description language that compiles to synthesizable Verilog and VHDL, or to bytecode for near-instant cycle-accurate simulation. This manual covers the language, the bytecode simulator, the standard library, and the VS Code extension.

Read Install first if you need the required Java version, project layout rules, or CLI entry points. Read Quick tutorial first if you want the shortest working end-to-end example.

Manual

Getting started

InstallGet the VS Code extension or the standalone CLI.
Quick tutorialBuild a 4-bit counter end-to-end: source → bytecode trace → Verilog.
Project layoutPackage names, folders, file naming, and output conventions.

Guides

Bytecode simulatorHow the fast cycle-accurate sim works. Monitors, test properties, VCD inspection.
Cross-check against HDLRun the same testbench through bytecode and Icarus Verilog or GHDL.
Cross a clock domainMove a signal between two clocks with the std.lib synchronizers.
Integrate with an FPGA toolchainTake generated Verilog or VHDL into Vivado, Quartus, Yosys, or open flows.
TroubleshootingCommon toolchain problems and recovery procedures.

Language

OverviewThe mental model: tasks, networks, ports, on a clock.
ConceptsBit-accurate types, cycle-by-cycle execution, determinism.
DeclarationsVariables, types, functions, ports - push/stream/confirm qualifiers.
BundlesStateless containers for types, constants, and helper functions.
TasksAtomic sequential entities. State, setup/loop, cycle breaks, external tasks.
NetworksHierarchical entities that wire instances together.
ExpressionsEvaluation rules, type unification, operators, literals.
StatementsControl flow, fence, idle, print, return, write.

Platform

PropertiesClocks, reset, type, test, implementation.
Standard libraryFIFOs, RAMs, clock-domain synchronizers.
Language serverStandard LSP plus custom neosyn/* methods for editor integrations.
CLI referenceCommands, defaults, options, and common invocation patterns.
Glossary & migrationTerminology definitions plus mappings from older naming.

A small C⏚ example

A counter that pushes its current value on every cycle:

task Counter {
  out push u8 count;
  u8 value = 0;
 
  void loop() {
    count.write(value);
    value = value + 1;
  }
}

This same source compiles to synthesizable Verilog/VHDL via the HDL backend, and runs directly in the bytecode simulator for fast iteration. See Quick tutorial for the full walk-through.

Conventions

u<n> - unsigned integer of n bits. i<n> is signed.
task / network / bundle - the three kinds of C⏚ entity.
push / stream / confirm - port synchronization qualifiers (replace the v1 sync / sync ready / sync ack).
.cg - C⏚ source file extension.
/* … */ and // … - comments, as in C.

Before you start

Use Java 17 or newer when running cg-language-server.jar directly.
Keep the file path aligned with the declared package. Example: package com.example; should live under .../com/example/.
In examples below, generated Verilog usually lands in verilog-gen/ and IR usually lands in .ir/ unless an explicit output directory overrides that default.