📖 Introduction — What are Tokens?

A Verilog source file is read by the compiler character by character. The compiler groups those characters into meaningful units called lexical tokens — the smallest building blocks of the language, just as words are the smallest meaningful units in a sentence.

Understanding tokens is important because the Verilog compiler’s first job is lexical analysis — breaking your source file into a stream of tokens before it attempts to understand the grammar of the design.

🧩 The 7 Token Types

Every character in a Verilog source file belongs to one of seven token categories:

assign   y   =   a   &   b;
──────   ─   ─   ─   ─   ─
keyword  id  op  id  op  id

🔑 Keywords

Keywords are reserved words that have a fixed, predefined meaning in the Verilog language. They form the vocabulary of the language itself — the compiler assigns special significance to each one.

📂 Keyword Categories

Verilog keywords can be grouped by purpose. Here is the complete set organized into four categories:

Module & Port Declarations blue

Control Flow purple

Procedural Blocks green

Gate Primitives orange

module counter (            // ← declaration keyword
  input      clk, rst,       // ← port keyword
  output reg [3:0] count    // ← declaration keywords
);
  always @(posedge clk) begin  // ← procedural keywords
    if (rst)               // ← control flow keyword
      count <= 4'd0;
    else                   // ← control flow keyword
      count <= count + 1;
  end                      // ← control flow keyword
endmodule                  // ← declaration keyword

🏷 Identifiers

Identifiers are user-defined names given to modules, ports, signals, instances, tasks, functions, and parameters. They let you refer to design elements by meaningful names rather than anonymous positions.

A good identifier is descriptive, consistent, and unambiguous. Poor naming is one of the most common causes of bugs that are hard to find.

module uart_tx (         // ← module name    (identifier)
  input      clk,          // ← port name       (identifier)
  input      tx_data,      // ← port name       (identifier)
  output reg tx_out        // ← port name       (identifier)
);
  parameter BAUD_DIV = 868;  // ← parameter name  (identifier)
  reg [9:0] shift_reg;        // ← signal name     (identifier)
  integer   bit_count;        // ← variable name   (identifier)

  baud_gen u_baud (...);      // ← module & instance name (identifiers)
endmodule

📐 Identifier Rules

Verilog identifiers must follow strict syntactic rules:

Naming Conventions (Best Practices)

// Modules          — lowercase with underscores (snake_case)
module uart_tx   fifo_ctrl   axi_master

// Parameters       — UPPER_CASE (screaming snake case)
parameter DATA_WIDTH = 32;
parameter FIFO_DEPTH = 16;

// Clocks           — clk prefix/suffix
clk   clk_50m   sys_clk   axi_clk

// Active-low resets — _n suffix
rst_n   reset_n   arst_n

// Active signals   — descriptive, lowercase
tx_valid   rx_ready   data_in   addr_out

// Instance names   — u_ prefix is common industry convention
u_fifo   u_alu   u_uart   u0   u1

✅ Valid vs Invalid Identifiers

🔡 Case Sensitivity

Verilog is fully case-sensitive, exactly like C. This means the same sequence of letters in different cases are treated as completely independent identifiers by the compiler.

wire clk;         // declares a signal named "clk"
wire CLK;         // declares a DIFFERENT signal named "CLK"
wire Clk;         // yet another different signal named "Clk"

assign CLK = clk;  // legal — connecting two distinct signals

Keywords are lowercase only

Since all Verilog keywords are defined in lowercase, writing MODULE, WIRE, or ALWAYS will not be treated as keywords — they will be parsed as identifiers. This is technically valid but extremely confusing and should never be done.

module  my_block (...);  // ✅ correct keyword
MODULE  my_block (...);  // ❌ MODULE is an identifier, not a keyword — compile error

␣ White Space Characters

White space in Verilog refers to any character that produces blank space in a file but carries no semantic meaning of its own. The Verilog compiler uses white space to separate tokens — once the tokens are identified, all white space is discarded.

// Compact — tokens separated by single spaces
assign y = a & b;

// Spread across lines — still the same statement
assign
  y
    =
      a & b;

// Extra spaces — still valid
assign   y   =   a   &   b   ;

White Space and Readability

While white space is semantically meaningless to the compiler, it is critically important to human readers. Well-spaced, consistently indented code is easier to read, review, and debug. Most teams enforce a style guide (e.g., 2-space or 4-space indentation, spaces around operators).

// ❌ Hard to read — no spacing or indentation
always@(posedge clk)begin if(rst) q<=0; else q<=d; end

// ✅ Readable — proper spacing and indentation
always @(posedge clk) begin
  if (rst)
    q <= 1'b0;
  else
    q <= d;
end

💬 Comments

Comments are text in the source file that is completely ignored by the compiler. They exist purely for human readers — to explain intent, document assumptions, mark TODOs, or disable code temporarily.

Verilog supports two comment styles:

// ─── File Header (multi-line comment) ───────────────────────────
/*
 * Module  : uart_tx
 * Author  : VLSI Trainers
 * Date    : 2026-05-14
 * Purpose : Serial UART transmitter, 8N1 format
 * Notes   : Baud rate configured via BAUD_DIV parameter
 */

module uart_tx #(
  parameter BAUD_DIV = 868    // 50MHz / 57600 baud ≈ 868
) (
  input      clk,              // system clock, 50 MHz
  input      rst_n,            // active-low async reset
  input [7:0] tx_data,          // byte to transmit
  input      tx_start,         // pulse high to begin TX
  output reg tx_out,           // serial output line
  output reg tx_busy           // high while transmitting
);

  // TODO: add parity support (currently 8N1 only)
  // FIXME: baud counter rolls over incorrectly at reset

  always @(posedge clk) begin
    /* Main TX state machine
       States: IDLE → START → DATA[0..7] → STOP */
  end

endmodule

Cannot Nest Multi-Line Comments

/* outer comment start
     /* inner comment — this does NOT work! */
   outer comment end? */   ← compiler sees end here — rest is code!

// ✅ Correct way to comment out a block containing comments:
// Use // on each line, or use `ifdef 0 ... `endif trick
`ifdef NEVER
  /* old code with comments inside */
  assign x = y;
`endif

Comments vs Compiler Directives

Comments are not the same as compiler directives (sometimes called preprocessor directives). Directives like `timescale, `include, `define, and `ifdef are active instructions to the compiler — they are not ignored. They begin with a backtick (`), not // or /*.

// This is a comment — ignored by the compiler

`timescale 1ns/1ps   // This is a compiler directive — NOT ignored
`define WIDTH 8       // Defines a text macro — NOT ignored