### Setup virtual environment and install with pip

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Standard procedure for creating a virtual environment and installing the package via pip.

```bash
python3 -m venv .venv
source .venv/bin/activate
```

```bash
pip install floogen
```

```bash
floogen --help
```

--------------------------------

### Install FlooGen globally with uv

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Installs the package globally and verifies the installation.

```bash
uv tool install floogen
# and verify installation
floogen --help
```

--------------------------------

### Clone FlooNoC repository

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Initial step for source-based installation.

```bash
git clone https://github.com/pulp-platform/FlooNoC.git && cd FlooNoC
```

--------------------------------

### Install Bender

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Methods to install the Bender dependency manager via precompiled binary or Cargo.

```shell
curl --proto '=https' --tlsv1.2 https://pulp-platform.github.io/bender/init -sSf | sh
```

```shell
cargo install bender
```

--------------------------------

### Verify Bender Installation

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Check if Bender is correctly configured by fetching project dependencies.

```shell
bender checkout
```

--------------------------------

### Traffic Configuration File Structure

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Example YAML configuration defining traffic flows between initiator and endpoint nodes.

```yaml
traffic_flows:
  - name: "cl_0_0_to_mem_1_0"
    initiator: [0, 0]
    endpoint: [1, 0]
    rw: write
    narrow_burst:
      number: 4
      length: 8
    wide_burst:
      number: 32
      length: 256
```

--------------------------------

### Install FlooGen in editable mode

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Installs the package in editable mode for development purposes.

```bash
python3 -m venv .venv
source .venv/bin/activate
```

```bash
pip install -e .
```

--------------------------------

### Visualize Network Topology

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates a graphical representation of the network. Requires the 'viz' extra to be installed.

```bash
uv tool install 'floogen[viz]'
```

```bash
uv run --extra viz floogen visualize -c <config_file>
```

```bash
pip install 'floogen[viz]'
```

```bash
floogen visualize -c <config_file> [-o <output_dir>]
```

--------------------------------

### Run FlooGen ephemerally with uvx

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Executes the tool without permanent installation.

```bash
uvx floogen --help
```

--------------------------------

### Define a route encoding for a 4x4 2D mesh

Source: https://pulp-platform.github.io/FlooNoC/floonoc/route_algos

Example of how a route is represented as an array of port identifiers in a 4x4 2D mesh network.

```SystemVerilog
  route_t route = '{3'b0, 3'b1, 3'b2, 3'b3, 3'b4, 3'b5, 3'b6};
```

--------------------------------

### Build documentation with zensical

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Commands to build and serve the project documentation.

```bash
uv run zensical build
```

```bash
python3 -m venv .venv
source .venv/bin/activate
```

```bash
pip install .[dev]
```

```bash
uv run zensical serve -o
```

```bash
zensical serve -o
```

--------------------------------

### CLI Synopsis and Help

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

General syntax for invoking the CLI and accessing help documentation for specific commands.

```bash
floogen <command> [options]
```

```bash
floogen rtl --help
```

--------------------------------

### Run Mesh Testbenches

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Commands to execute generated testbenches using different simulation tools.

```makefile
make run-vsim TB_DUT=tb_floo_<mesh> EXTRA_BENDER_FLAGS="-t <mesh>"
```

```bash
# Currently not supported
```

--------------------------------

### Run Testbenches

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Commands to execute specific testbenches, including batch mode options.

```Makefile
make run-vsim TB_DUT=<testbench_name>
```

```Makefile
make run-vsim-batch TB_DUT=<testbench_name>
```

```Makefile
make run-vcs TB_DUT=<testbench_name>
```

--------------------------------

### Compile Hardware RTL

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Commands to compile RTL and testbenches for QuestaSim or VCS.

```Makefile
make compile-vsim
```

```Makefile
make compile-vcs TB_DUT=<testbench_name>
```

--------------------------------

### Configure AXI4 with Custom User Fields

Source: https://pulp-platform.github.io/FlooNoC/floogen/protocols

Uses a dictionary for the user_width parameter to generate a packed SystemVerilog struct for custom signals.

```yaml
protocols:
  - name: "axi_custom_user"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 4
    user_width:
      qos: 4
      region: 4
      parity: 1
```

--------------------------------

### Render Custom Templates

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Renders user-provided Mako templates using the network model.

```bash
floogen template -c <config_file> --template <template_file> -o <output_dir>
```

--------------------------------

### Run FlooGen from source with uv

Source: https://pulp-platform.github.io/FlooNoC/floogen/installation

Executes the tool within the repository using uv's automatic environment management.

```bash
uv run floogen --help
```

--------------------------------

### Generate traffic using configuration files

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Use a traffic configuration file to explicitly define flows between endpoints.

```bash
floogen traffic -c <config_file> --traffic-cfg <traffic_file> -o <output_dir>
```

--------------------------------

### FlooGen CLI Commands

Source: https://pulp-platform.github.io/FlooNoC/floogen/minimal_example

Commands to visualize the network topology and generate the corresponding SystemVerilog RTL.

```bash
floogen visualize -c axi_mesh.yaml
```

```bash
floogen rtl -c axi_mesh.yaml -o out/
```

--------------------------------

### Define a basic connection

Source: https://pulp-platform.github.io/FlooNoC/floogen/connections

Connects a single source component to a destination component.

```yaml
connections:
  - src: "cpu_0"
    dst: "router_0"
```

--------------------------------

### Generate Mesh Testbenches

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Commands to generate mesh testbenches using FlooGen with specific configuration files.

```bash
uv run floogen rtl -c floogen/examples/<mesh>_<route_algo>.yml -o generated
```

```bash
floogen rtl -c floogen/examples/<mesh>_<route_algo>.yml -o generated
```

--------------------------------

### Generate RTL

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates both the SystemVerilog package and the top-level module using a configuration file.

```bash
floogen rtl -c <config_file> -o <output_dir>
```

--------------------------------

### Define general network configuration

Source: https://pulp-platform.github.io/FlooNoC/floogen/network_types

Basic YAML configuration block for defining the network name, description, and type.

```yaml
name: my_noc
description: "My first NoC"
network_type: "axi"
```

--------------------------------

### Generate traffic using built-in mesh patterns

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generate traffic based on predefined patterns without requiring a dedicated configuration file.

```bash
floogen traffic -c <config_file> --traffic-type <pattern> --traffic-rw <read|write> -o <output_dir>
```

--------------------------------

### floogen pkg

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates only the SystemVerilog package file.

```APIDOC
## floogen pkg

### Description
Generates only the SystemVerilog package (`*_pkg.sv`) containing types and routing tables.

### Usage
`floogen pkg -c <config_file> -o <output_dir>`
```

--------------------------------

### Define Global Settings and Protocols

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/complex

Configures the network as narrow-wide with multicast enabled and defines protocol widths for AXI4 interfaces.

```yaml
name: picobello
description: "picobello NoC configuration"
network_type: "narrow-wide"

routing:
  route_algo: "XY"
  use_id_table: true
  en_multicast: true

protocols:
  - name: "narrow_in"
    type: "narrow"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 5
    user_width:
      mcast_mask: 48 # Reserved bits for multicast routing
      user: 5        # Actual user bits
  # ... (other protocols defined similarly)
```

--------------------------------

### sv_struct_render(fields)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Renders a SystemVerilog struct based on a dictionary.

```APIDOC
## sv_struct_render

### Description
Declare a SystemVerilog struct based on a (nested) dictionary, where the keys of the dictionary are the field names, and the values are the actual values to assign.

### Parameters
- **fields** (dict) - Required - A dictionary representing the struct fields and their values.
```

--------------------------------

### Render SystemVerilog structs with sv_struct_render

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Creates a SystemVerilog struct assignment string from a nested dictionary.

```python
fields = {'field1': '3'd0', 'field2': {'subfield1': 'some_signal', 'subfield2': 'SomeParam'}} sv_struct_render(fields) -> '{ field1: 3'd0, field2: '{ subfield1: some_signal, subfield2: SomeParam }, }'
```

--------------------------------

### Generate SystemRDL

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates SystemRDL descriptions for endpoint address regions.

```bash
floogen rdl -c <config_file> -o <output_dir>
```

--------------------------------

### Generate Package

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates only the SystemVerilog package containing types and routing tables.

```bash
floogen pkg -c <config_file> -o <output_dir>
```

--------------------------------

### Configure Advanced Endpoints

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/complex

Sets up endpoints with multicast reception and multiple disjoint address ranges.

```yaml
endpoints:
  - name: "cluster"
    array: [4, 4]
    en_multicast: true # Enables multicast reception for this array
    # ...
  - name: "cheshire"
    addr_range:
      - start: 0x0000_0000
        end: 0x2000_0000
        desc: "internal"
      - start: 0x8000_0000
        end: 0x200_0000_0000
        desc: "external"
    # ...
```

--------------------------------

### verible_format(string, verible_fmt_bin=None, verible_fmt_args=None)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Formats a provided Verilog string using the verible-verilog-format tool.

```APIDOC
## verible_format(string, verible_fmt_bin=None, verible_fmt_args=None)

### Description
Formats the input string using the verible-verilog-format utility.

### Parameters
- **string** (str) - Required - Input string to format.
- **verible_fmt_bin** (str) - Optional - Path to the verible-verilog-format binary. If None, searches in PATH.
- **verible_fmt_args** (str) - Optional - Additional arguments to pass to the formatter.

### Returns
- **str** - The formatted string, or the original string if the formatter is not found.
```

--------------------------------

### Define Connections

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/simple

Establishes point-to-point links between endpoints and the central router.

```yaml
connections:
  - src: "cluster"
    dst: "router"
  - src: "hbm"
    dst: "router"
  - src: "serial_link"
    dst: "router"
  - src: "cva6"
    dst: "router"
  - src: "peripherals"
    dst: "router"
```

--------------------------------

### Define Basic Routing Configuration

Source: https://pulp-platform.github.io/FlooNoC/floogen/routing

Basic YAML configuration for specifying the routing algorithm and enabling the system address table.

```yaml
routing:
  route_algo: "XY"
  use_id_table: true
```

--------------------------------

### Compile Generated Testbenches

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Commands to compile generated testbenches with Bender flags.

```Makefile
make compile-vsim EXTRA_BENDER_FLAGS="-t <mesh>"
```

```bash
# Currently not supported
```

--------------------------------

### Configure Basic AXI4 Protocol

Source: https://pulp-platform.github.io/FlooNoC/floogen/protocols

Defines a standard AXI4 interface with specified data, address, and ID widths.

```yaml
protocols:
  - name: "axi_std"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 4
```

--------------------------------

### Generate Top-Level Module

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates only the structural top-level SystemVerilog module.

```bash
floogen top -c <config_file> -o <output_dir>
```

--------------------------------

### Dimension-ordered Routing Logic

Source: https://pulp-platform.github.io/FlooNoC/floonoc/route_algos

Implements XY-routing by comparing current router coordinates with destination coordinates to determine the output port.

```SystemVerilog
if (hdr.dst.x == router.x && hdr.dst.y == router.y) begin
  route_sel_id = Eject + hdr.dst.port_id;
end else if (hdr.dst.x == router.x) begin
  if (hdr.dst.y < router.y) begin
    route_sel_id = South;
  end else begin
    route_sel_id = North;
  end
end else begin
  if (hdr.dst.x < router.x) begin
    route_sel_id = West;
  end else begin
    route_sel_id = East;
  end
end
```

--------------------------------

### Configure Router Group Interconnections

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/complex

Manually connects partitioned router groups to maintain network connectivity.

```yaml
connections:
  - src: "router_left"
    dst: "router_center"
    src_range:
      - [0, 0] # X range
      - [0, 3] # Y range
    dst_range:
      - [0, 0] # X range
      - [0, 3] # Y range
    src_dir: "East"
    dst_dir: "West"
  - src: "router_center"
    dst: "router_right"
    src_range:
      - [3, 3] # X range
      - [0, 3] # Y range
    dst_range:
      - [0, 1] # X range
      - [0, 3] # Y range
    src_dir: "East"
    dst_dir: "West"
```

--------------------------------

### AXI Mesh Configuration File

Source: https://pulp-platform.github.io/FlooNoC/floogen/minimal_example

A YAML configuration defining a 4x4 mesh network with XY routing, AXI4 protocols, and endpoint connectivity.

```yaml
name: axi_mesh
description: "AXI mesh with XY routing"
network_type: "axi"

# 1. Routing Configuration
routing:
  route_algo: "XY"
  use_id_table: true

# 2. Protocol Definitions
protocols:
  - name: "axi_in"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 4
    user_width: 1
  - name: "axi_out"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 2
    user_width: 1

# 3. Endpoint Definitions
endpoints:
  - name: "cluster"
    array: [4, 4]
    addr_range:
      base: 0x0000_0000_0000
      size: 0x0000_0001_0000
    mgr_port_protocol:
      - "axi_in"
    sbr_port_protocol:
      - "axi_out"

# 4. Router Definitions
routers:
  - name: "router"
    array: [4, 4]
    degree: 5

# 5. Connectivity
connections:
  - src: "cluster"
    dst: "router"
    src_range:
      - [0, 3]
      - [0, 3]
    dst_range:
      - [0, 3]
      - [0, 3]
    dst_dir: "Eject"
```

--------------------------------

### floogen rdl

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates SystemRDL description for endpoint address regions.

```APIDOC
## floogen rdl

### Description
Generates the SystemRDL description for the endpoint address regions for system-level register automation.

### Usage
`floogen rdl -c <config_file> -o <output_dir>`
```

--------------------------------

### floogen rtl

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates both the SystemVerilog package and the top-level module for the NoC.

```APIDOC
## floogen rtl

### Description
Generates the hardware description, including the SystemVerilog package and the top-level module.

### Usage
`floogen rtl -c <config_file> -o <output_dir>`

### Options
- **-c, --config** (file) - Required - Path to the YAML NoC configuration file.
- **-o, --outdir** (dir) - Optional - Directory where generated files will be written.
- **--no-format** (flag) - Optional - Disable auto-formatting of the generated SystemVerilog.
```

--------------------------------

### Generate Traffic Job Files

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Commands to generate job files for DMA models using a traffic configuration file.

```bash
uv run floogen traffic -c floogen/examples/<floonoc_config>.yml --traffic-cfg floogen/examples/traffic/<traffic_config>.yml -o <outdir>
```

```bash
floogen traffic -c floogen/examples/<floonoc_config>.yml --traffic-cfg floogen/examples/traffic/<traffic_config>.yml -o <outdir>
```

--------------------------------

### Configure SystemRDL Generation

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Uses rdl_name and rdl_as_mem to control how address ranges are rendered in generated SystemRDL files.

```yaml
endpoints:
  - name: "cluster"
    addr_range:
      - base: 0x1000_0000
        size: 0x0004_0000
        rdl_name: "cluster_regs" # instantiate an externally-defined `cluster_regs.rdl`
      - base: 0x1000_4000
        size: 0x0000_1000
        rdl_as_mem: true # always render as `external mem`, regardless of --as-mem
    sbr_port_protocol:
      - "axi_out"
```

--------------------------------

### Configure SystemRDL Addrmap Groups

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Tags address ranges with rdl_addrmap_grp to control visibility across different generated SystemRDL addrmap views.

```yaml
endpoints:
  - name: "cluster"
    addr_range:
      - base: 0x1000_0000
        size: 0x0004_0000
        rdl_name: "cluster_regs"
        rdl_addrmap_grp: ["32b", "64b"] # visible in both the 32b and 64b addrmaps
      - base: 0x1000_4000
        size: 0x0000_1000
        rdl_name: "cluster_debug_regs"
        rdl_addrmap_grp: "64b" # only visible in the 64b addrmap
    sbr_port_protocol:
      - "axi_out"
  - name: "hbm"
    addr_range:
      base: 0x8000_0000
      size: 0x1000_0000
      rdl_name: "hbm_regs"
      rdl_addrmap_grp: "64b" # only visible in the 64b addrmap
    sbr_port_protocol:
      - "axi_out"
```

--------------------------------

### int_to_hex(value, width)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Converts an integer to a SystemVerilog-style hex string.

```APIDOC
## int_to_hex(value, width)

### Description
Converts an integer to a hex string representation.

### Parameters
- **value** (int) - Required - Input integer value.
- **width** (int) - Required - Bit width of the value.

### Returns
- **str** (str) - Hex string representation of the integer.
```

--------------------------------

### floogen visualize

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates a graphical representation of the network topology.

```APIDOC
## floogen visualize

### Description
Generates a graphical representation of the network topology. Requires the 'viz' extra to be installed.

### Usage
`floogen visualize -c <config_file> [-o <output_dir>]`

### Options
- **-c, --config** (file) - Required - Path to the YAML NoC configuration file.
- **-o, --outdir** (dir) - Optional - Path to save the plot. If omitted, opens an interactive window.
```

--------------------------------

### Declare SystemVerilog parameters with sv_param_decl

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Generates a SystemVerilog parameter or localparam declaration string.

```python
>>> sv_param_decl("Width", 8)
"localparam int unsigned Width = 8;"
>>> sv_param_decl("Depth", 16, ptype="parameter", dtype="my_type_t", array_size=4)
"parameter my_type_t [3:0] Depth = 16;"
```

--------------------------------

### Define a Basic Memory Endpoint

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Configures a subordinate memory endpoint with a specific address range and AXI output protocol.

```yaml
endpoints:
  - name: "hbm"
    addr_range:
      start: 0x8000_0000
      size: 0x1000_0000 # 256 MB
    sbr_port_protocol:
      - "axi_out"
```

--------------------------------

### Configure Heterogeneous Network Protocols

Source: https://pulp-platform.github.io/FlooNoC/floogen/protocols

Utilizes the type field to distinguish between different link types within the same network configuration.

```yaml
protocols:
  - name: "narrow_in"
    type: "narrow"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 4

  - name: "wide_in"
    type: "wide"
    protocol: "AXI4"
    data_width: 512
    addr_width: 48
    id_width: 6
```

--------------------------------

### Define Global Network Settings

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/simple

Sets the network type to narrow-wide and enables ID-based routing with a lookup table.

```yaml
name: single_cluster
description: "Single Cluster Configuration for FlooGen"
network_type: "narrow-wide"

routing:
  route_algo: "ID"
  use_id_table: true
```

--------------------------------

### Define Partitioned Router Topology

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/complex

Creates a non-uniform mesh by defining multiple router arrays with specific coordinate offsets.

```yaml
routers:
  - name: "router_left"
    array: [1, 4]
    degree: 5
  - name: "router_center"
    array: [4, 4]
    degree: 5
    xy_id_offset:
      x: 4 # Logically starts at X=4
      y: 0
  - name: "router_right"
    array: [2, 4]
    degree: 5
    xy_id_offset:
      x: 8 # Logically starts at X=8
      y: 0
```

--------------------------------

### Generate Built-in Mesh Traffic Patterns

Source: https://pulp-platform.github.io/FlooNoC/floonoc/getting_started

Command to generate predefined mesh-wide traffic patterns based on a FlooNoC configuration.

```bash
floogen traffic -c <floonoc_config>.yml --traffic-type <traffic_type> --traffic-rw <read_or_write> -o <outdir>
```

--------------------------------

### sv_param_decl(name, value, ptype='localparam', dtype='int unsigned', array_size=None)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Generates a SystemVerilog parameter declaration string.

```APIDOC
## sv_param_decl

### Description
Declare a SystemVerilog parameter.

### Parameters
- **name** (str) - Required - Name of the parameter.
- **value** (int, str) - Required - Value of the parameter.
- **ptype** (str) - Optional - Type of the parameter, either "localparam" or "parameter". Defaults to "localparam".
- **dtype** (str) - Optional - Data type of the parameter. Defaults to "int unsigned".
- **array_size** (int, str, list) - Optional - Size of the array. Can be an integer, a string (for expressions), or a list of integers/strings for multi-dimensional arrays. Defaults to None.

### Returns
- **str** (str) - SystemVerilog parameter declaration.
```

--------------------------------

### floogen template

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Renders custom Mako templates using the network model.

```APIDOC
## floogen template

### Description
Renders custom, user-provided Mako templates using the FlooGen network model.

### Usage
`floogen template -c <config_file> --template <template_file> -o <output_dir>`
```

--------------------------------

### Define Request Link Structure

Source: https://pulp-platform.github.io/FlooNoC/floonoc/links

Defines the packed struct for a request link containing valid, ready, and request channel signals.

```SystemVerilog
  typedef struct packed {
    logic valid;
    logic ready;
    floo_req_chan_t req;
  } floo_req_t;
```

--------------------------------

### Define Router Table Rules in SystemVerilog

Source: https://pulp-platform.github.io/FlooNoC/floonoc/route_algos

Defines a parameter array of routing rules mapping destination address ranges to specific output ports.

```SystemVerilog
  localparam router_rule_t [NumRules-1:0] RouterTable = '{
      '{idx: 1, start_addr: 0, end_addr: 2}, // -> port 1 for destination 0, 1
      '{idx: 2, start_addr: 2, end_addr: 3}, // -> port 2 for destination 2
      '{idx: 3, start_addr: 3, end_addr: 10} // -> port 3 for destination 3 to 9
  };
```

--------------------------------

### bool_to_sv(value)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Converts a boolean value to a SystemVerilog string representation.

```APIDOC
## bool_to_sv(value)

### Description
Converts a boolean to a SystemVerilog string.

### Parameters
- **value** (bool) - Required - Input boolean value.

### Returns
- **str** (str) - "1'b1" if True, "1'b0" if False.
```

--------------------------------

### sv_enum_typedef(name, fields_dict=None, fields_list=None)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Declare a SystemVerilog enum typedef.

```APIDOC
## sv_enum_typedef(name, fields_dict=None, fields_list=None)

### Description
Generates a SystemVerilog enum typedef declaration string.

### Parameters
- **name** (str) - Required - Name of the enum typedef.
- **fields_dict** (dict) - Optional - Dictionary of field names and their corresponding values.
- **fields_list** (list) - Optional - List of field names. Values will be assigned automatically starting from 0.

### Returns
- **str** (str) - SystemVerilog enum typedef declaration.
```

--------------------------------

### short_dir(direction)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Returns the short direction string for input/output.

```APIDOC
## short_dir(direction)

### Description
Returns the short direction string (e.g., 'in' or 'out').

### Parameters
- **direction** (str) - Required - "input" or "output".

### Returns
- **str** (str) - "in" or "out".
```

--------------------------------

### sv_typedef(name, dtype='logic', array_size=None)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Declares a SystemVerilog typedef string based on the provided name, data type, and optional array size.

```APIDOC
## sv_typedef(name, dtype='logic', array_size=None)

### Description
Generates a SystemVerilog typedef declaration string.

### Parameters
- **name** (str) - Required - Name of the typedef.
- **dtype** (str) - Optional - Data type of the typedef. Defaults to 'logic'.
- **array_size** (int) - Optional - Size of the array. If None, a scalar type is declared.

### Returns
- **str** - The SystemVerilog typedef declaration string.
```

--------------------------------

### Convert integer to hex string

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Converts an integer to a SystemVerilog-style hex string representation.

```python
>>> int_to_hex(255, 8)
"8'hff"
```

--------------------------------

### floogen top

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates only the structural top-level module.

```APIDOC
## floogen top

### Description
Generates only the structural top-level module (`*_top.sv`).

### Usage
`floogen top -c <config_file> -o <output_dir>`
```

--------------------------------

### Declare a SystemVerilog typedef

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Generates a SystemVerilog typedef string based on the provided name, data type, and optional array size.

```python
>>> sv_typedef("my_type_t", "logic", 8)
"typedef logic[7:0] my_type_t;"
```

--------------------------------

### Define Narrow-wide Interfaces

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Configures an endpoint to support multiple protocol widths for both manager and subordinate ports.

```yaml
endpoints:
  - name: "dma"
    mgr_port_protocol:
      - "narrow_in"
      - "wide_in"
    sbr_port_protocol:
      - "narrow_out"
      - "wide_out"
```

--------------------------------

### Define a 2D mesh router array

Source: https://pulp-platform.github.io/FlooNoC/floogen/routers

Generates a grid of routers with automatic mesh connections enabled by default.

```yaml
routers:
  - name: "router"
    array: [4, 4] # 4x4 Grid
    auto_connect: true # Default
```

--------------------------------

### Define Router

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/simple

Defines the central switching unit for the star topology.

```yaml
routers:
  - name: "router"
```

--------------------------------

### Define a Processor Manager Endpoint

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Configures a processor core acting as a manager that only issues requests via a narrow input protocol.

```yaml
endpoints:
  - name: "cva6"
    mgr_port_protocol:
      - "narrow_in"
```

--------------------------------

### Define Multiple Non-contiguous Address Ranges

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Allows an endpoint to map multiple distinct memory regions, each with its own description.

```yaml
endpoints:
  - name: "peripheral_block"
    addr_range:
      - start: 0x4000_0000
        size: 0x0001_0000
        desc: "Control Registers"
      - start: 0x5000_0000
        size: 0x0001_0000
        desc: "Status Registers"
    sbr_port_protocol:
      - "axi_out"
```

--------------------------------

### Define Network Endpoints

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/simple

Specifies the IP blocks in the system, including their address ranges and port protocols.

```yaml
endpoints:
  - name: "cluster"
    addr_range:
      base: 0x1000_0000
      size: 0x0004_0000
    mgr_port_protocol:
      - "narrow_in"
      - "wide_in"
    sbr_port_protocol:
      - "narrow_out"
      - "wide_out"
  - name: "hbm"
    addr_range:
      base: 0x8000_0000
      size: 0x4000_0000
    sbr_port_protocol:
      - "wide_out"
  - name: "cva6"
    mgr_port_protocol:
      - "narrow_in"
```

--------------------------------

### Compute ceiling of log2

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Calculates the ceiling of the base-2 logarithm of an integer.

```python
>>> clog2(7)
3
```

--------------------------------

### Define Network Protocols

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/simple

Configures narrow protocols for control messages and wide protocols for bulk data transfer.

```yaml
protocols:
  - name: "narrow_in"
    type: "narrow"
    protocol: "AXI4"
    data_width: 64
    # ...
  - name: "wide_in"
    type: "wide"
    protocol: "AXI4"
    data_width: 512
    # ...
```

--------------------------------

### clog2(x)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Returns the ceiling of the base-2 logarithm of x.

```APIDOC
## clog2(x)

### Description
Returns the ceiling of log2(x).

### Parameters
- **x** (int) - Required - Input value.

### Returns
- **int** (int) - Ceiling of log2(x).
```

--------------------------------

### Configure Endpoint Connections

Source: https://pulp-platform.github.io/FlooNoC/floogen/examples/complex

Stitches endpoints to specific routers using index and direction fields.

```yaml
connections:
  - src: "cluster"
    dst: "router_center"
    # Connects the 4x4 cluster array to the 4x4 center router array
    src_range: [[0, 3], [0, 3]]
    dst_range: [[0, 3], [0, 3]]
    dst_dir: "Eject"

  - src: "cheshire"
    dst: "router_right"
    dst_idx: [1, 3] # Connects to router at index [1, 3] of the 'right' array
    dst_dir: "Eject"
```

--------------------------------

### Query Internal Graph

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Queries specific values or attributes from the internal network model.

```bash
# Example: Get the number of endpoints
floogen query -c <config_file> "endpoints"

# Example: Get a specific attribute
floogen query -c <config_file> "endpoints.my_cluster.addr_range.base"
```

--------------------------------

### Define complex array mappings

Source: https://pulp-platform.github.io/FlooNoC/floogen/connections

Maps specific source ranges to destination ranges and assigns them to a specific router port.

```yaml
connections:
  - src: "hbm"       # Array of 4 HBM endpoints
    dst: "router"    # 4x4 Router mesh
    src_range:
      - [0, 3]       # Select all 4 HBMs
    dst_range:
      - [0, 3]       # Select X indices 0-3
      - [0, 0]       # Select Y index 0 (Bottom row)
    dst_dir: "South" # Connect to the South port of the routers
```

--------------------------------

### Disable auto-connect for custom topologies

Source: https://pulp-platform.github.io/FlooNoC/floogen/routers

Set auto_connect to false when defining manual connections for irregular grids or tori.

```yaml
routers:
  - name: "custom_router"
    array: [2, 2]
    auto_connect: false # Manual connections required
```

--------------------------------

### Define Endpoint Arrays

Source: https://pulp-platform.github.io/FlooNoC/floogen/endpoints

Defines arrays of endpoints for tiled architectures, where FlooGen automatically calculates address ranges based on base and size.

```yaml
endpoints:
  - name: "cluster"
    array: [4, 4] # 4x4 Grid of clusters
    addr_range:
      base: 0x1000_0000
      size: 0x0004_0000 # Size per cluster
    mgr_port_protocol:
      - "axi_in"
    sbr_port_protocol:
      - "axi_out"
  - name: "hbm_channels"
    array: [8] # 8 HBM channels
    addr_range:
      base: 0x8000_0000
      size: 0x0200_0000 # Size per channel
    sbr_port_protocol:
      - "axi_out"
```

--------------------------------

### cdiv(x, y)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Computes the ceiling of x divided by y.

```APIDOC
## cdiv(x, y)

### Description
Compute the ceiling of x / y.

### Parameters
- **x** ((int, float)) - Required - Numerator.
- **y** ((int, float)) - Required - Denominator.

### Returns
- **int** (int) - Ceiling of x / y.
```

--------------------------------

### Convert boolean to SystemVerilog string

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Converts a Python boolean into its corresponding SystemVerilog representation.

```python
>>> bool_to_sv(True)
"1'b1"
```

--------------------------------

### Compute ceiling division

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Calculates the ceiling of the division of two numbers.

```python
>>> cdiv(7, 2)
4
```

--------------------------------

### sv_struct_typedef(name, fields, union=False)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Declares a SystemVerilog struct typedef.

```APIDOC
## sv_struct_typedef

### Description
Declare a SystemVerilog struct typedef.

### Parameters
- **name** (str) - Required - Name of the typedef.
- **fields** (dict) - Required - Fields for the struct.
- **union** (bool) - Optional - Whether to declare as a union. Defaults to False.
```

--------------------------------

### Declare SystemVerilog enum typedef

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Generates a SystemVerilog enum typedef string using either an automatic list or a manual dictionary of values.

```python
>>> sv_enum_typedef("my_enum_e", fields_list=["field_one", "field_two"])
"typedef enum logic[0:0] {
    FieldOne = 0,
    FieldTwo = 1
} my_enum_e;"
>>> sv_enum_typedef("my_enum_e", fields_dict={"field_one": 4, "field_two": 6})
"typedef enum logic[2:0] {
    FieldOne = 4,
    FieldTwo = 6
} my_enum_e;"
```

--------------------------------

### Define a tree topology

Source: https://pulp-platform.github.io/FlooNoC/floogen/routers

Specifies the branching factor at each level of the tree structure.

```yaml
routers:
  - name: "tree_router"
    tree: [2, 2] # Binary tree depth definition
```

--------------------------------

### Define a range connection for arrays

Source: https://pulp-platform.github.io/FlooNoC/floogen/connections

Maps ranges of indices between source and destination arrays to avoid individual connection definitions.

```yaml
connections:
  - src: "cluster"
    dst: "router"
    src_range:
      - [0, 3] # X range
      - [0, 3] # Y range
    dst_range:
      - [0, 3]
      - [0, 3]
```

--------------------------------

### Specify router port direction

Source: https://pulp-platform.github.io/FlooNoC/floogen/connections

Assigns a connection to a specific port direction on the destination router.

```yaml
connections:
  - src: "hbm_controller"
    dst: "router_0"
    dst_dir: "West" # Connects HBM to the West port of router_0
```

--------------------------------

### Customize Generated Type Prefixes

Source: https://pulp-platform.github.io/FlooNoC/floogen/protocols

Overrides the default 'axi' prefix for generated SystemVerilog types using the type_prefix attribute.

```yaml
protocols:
  - name: "noc_link"
    protocol: "AXI4"
    data_width: 64
    addr_width: 48
    id_width: 4
    type_prefix: "floo" # Results in floo_noc_link_req_t
```

--------------------------------

### snake_to_camel(name)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Converts a snake case string to camel case.

```APIDOC
## snake_to_camel(name)

### Description
Converts an input snake case string to camel case.

### Parameters
- **name** (str) - Required - Input snake case string.

### Returns
- **str** (str) - Converted camel case string.
```

--------------------------------

### floogen traffic

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Generates DMA job files for simulating synthetic traffic loads in RTL simulation based on a network configuration file.

```APIDOC
## CLI Command: floogen traffic

### Description
Generates DMA job files for simulating synthetic traffic loads in RTL simulation. The tool uses a network configuration file to adapt traffic descriptions to specific NoC topologies.

### Usage
# Generating traffic using traffic configuration files
floogen traffic -c <config_file> --traffic-cfg <traffic_file> -o <output_dir>

# Generating traffic using built-in mesh traffic patterns
floogen traffic -c <config_file> --traffic-type <pattern> --traffic-rw <read|write> -o <output_dir>

### Common Options
- **-c, --config** (file) - Required - Path to the network (topology) YAML configuration file.
- **-o, --outdir** (dir) - Optional - Directory where the job files are written (default: jobs).
- **--traffic-name** (string) - Optional - Base name of the emitted job files.
- **-v, --verbose** (flag) - Optional - Print detailed information about the tool execution.

### Mode-specific Options
- **--traffic-cfg** (file) - Required (in config mode) - Path to the traffic configuration file.
- **--traffic-type** (string) - Required (in pattern mode) - Name of the built-in traffic pattern (e.g., hbm, uniform, shuffle).
- **--traffic-rw** (string) - Optional (in pattern mode) - Direction of the built-in traffic pattern (read or write, default: write).
- **--num-narrow-bursts** (int) - Optional - Number of narrow bursts generated per node (default: 10).
- **--num-wide-bursts** (int) - Optional - Number of wide bursts generated per node (default: 100).
- **--narrow-burst-length** (int) - Optional - Narrow burst length in beats (default: 1).
- **--wide-burst-length** (int) - Optional - Wide burst length in beats (default: 16).
```

--------------------------------

### camel_to_snake(name)

Source: https://pulp-platform.github.io/FlooNoC/floogen/reference/utils

Converts a camel case string to snake case.

```APIDOC
## camel_to_snake(name)

### Description
Converts a camel case string to snake case.

### Parameters
- **name** (str) - Required - Input camel case string.

### Returns
- **str** (str) - Converted snake case string.
```

--------------------------------

### floogen query

Source: https://pulp-platform.github.io/FlooNoC/floogen/cli

Introspection tool to query values from the internal graph representation.

```APIDOC
## floogen query

### Description
Queries specific values from the internal graph representation without generating code.

### Usage
`floogen query -c <config_file> <query_string>`
```

--------------------------------

### Override router degree

Source: https://pulp-platform.github.io/FlooNoC/floogen/routers

Explicitly set the number of input/output ports, useful for specific routing algorithms like XY-Routing.

```yaml
routers:
  - name: "router"
    array: [4, 4]
    degree: 5
```