API Reference

Complete reference for PYHDL language features and supported constructs.

Language Elements

Entity Declaration

Define hardware components with ports.

Syntax:

entity EntityName([input_ports]) -> [output_ports]:
    # Implementation

Parameters:

EntityName: Name of the entity
input_ports: List of name: type input port declarations
output_ports: List of name: type output port declarations

Example:

entity Adder(
    a: std_logic_vector(7 downto 0),
    b: std_logic_vector(7 downto 0)
) -> sum: std_logic_vector(8 downto 0):
    sum <= ('0' & a) + ('0' & b)

Port Types

Supported VHDL types:

std_logic - Single bit
std_logic_vector(n downto m) - Vector of bits
integer - Integer type
boolean - Boolean type

Process Statements

Define sequential logic processes.

Syntax:

process ProcessName([sensitivity_list]):
    # Sequential statements

Example:

process counter(clock, reset):
    if reset = '1' then:
        value <= X"00"
    elif rising_edge(clock):
        value <= value + 1
    end if

If Statements

Conditional logic support.

Syntax:

if condition:
    statements
elif condition:
    statements
else:
    statements

Example:

if enable = '1':
    result <= input_a
elif select_signal = '0':
    result <= input_b
else:
    result <= (others => 'Z')

For Loops

Iterative statements.

Syntax:

for variable in range(start, end):
    statements

Example:

for i in range(0, 8):
    temp(i) <= data(i) when selector(i) = '1' else temp(i-1)

While Loops

Conditional iteration.

Syntax:

while condition:
    statements

Example:

while count < max_value:
    output <= input
    count <= count + 1

Functions

Reusable function definitions.

Syntax:

function FunctionName([parameters]) -> return_type:
    # Function body
    return expression

Example:

function Multiply(
    a: std_logic_vector(7 downto 0),
    b: std_logic_vector(7 downto 0)
) -> std_logic_vector(15 downto 0):
    return a * b

Operators

Arithmetic Operators

+ - Addition
- - Subtraction
* - Multiplication
/ - Division (limited support)

Logical Operators

and - Logical AND
or - Logical OR
not - Logical NOT
xor - Exclusive OR

Comparison Operators

= - Equality
/= - Inequality
< - Less than
> - Greater than
<= - Less than or equal
>= - Greater than or equal

Concatenation

& - Concatenation operator

Example:

result <= a & b  # Concatenate a and b

Signal Assignments

Direct Assignment

signal <= value

Conditional Assignment

signal <= value when condition else default_value

Selected Assignment

signal <= value_a when selector = "00" else
          value_b when selector = "01" else
          value_c

Type Conversions

Literals

# Bit literal
signal <= '0'
signal <= '1'

# Vector literal
signal <= "10101010"  # std_logic_vector
signal <= X"FF"       # Hexadecimal
signal <= O"123"      # Octal
signal <= B"1010"     # Binary

# Integer literal
count <= 42

Reserved Words

Avoid using these Python reserved words:

if, elif, else
for, while, in, range
def, return
and, or, not, in, is

Avoid these VHDL reserved words:

entity, architecture, process
signal, variable, constant
in, out, inout, buffer
std_logic, std_logic_vector

Conversion Rules

Basic Transformations

Python Syntax	VHDL Output
`=` (assignment)	`<=`
`if condition:`	`if condition then`
`elif condition:`	`elsif condition then`
`for i in range(x, y):`	`for i in x to y loop`
`and/or/not`	`and/or/not`
`# comment`	`-- comment`

Process Conversion

Python-like process:

process example(clock):
    if condition:
        signal <= value

Converts to:

process example(clock) is
begin
    if condition then
        signal <= value;
    end if;
end process;

Entity Conversion

Python syntax:

entity Example(a: std_logic) -> b: std_logic:
    # implementation

VHDL output:

entity Example is
    port(
        a: in std_logic;
        b: out std_logic
    );
end entity Example;

architecture ExampleArch of Example is
begin
    -- implementation
end architecture ExampleArch;

Error Handling

Common Errors

Invalid Indentation
- Error: “invalid definition level at line X”
- Fix: Use consistent 4-space indentation
Missing Colon
- Error: “expected definition block after line X”
- Fix: Add colon after control structures
Reserved Word
- Error: Syntax error
- Fix: Use alternative names
Type Mismatch
- Error: Invalid type
- Fix: Use proper VHDL types

Debugging Tips

Use --verbose flag for detailed output
Check indentation carefully
Verify type annotations
Test with simple examples first
Compare with generated VHDL

Examples

See the Usage Guide for complete working examples.

For more examples, check the repository’s examples directory.