README.md

# Matcha

## About the project

[Matcha] will be an open source SOC(system on chip) project.
<!-- TODO(pbf): Will add more project description when ready.-->

## About this repository

This repository contains hardware, software and utilities written as part of the
Matcha project. Plus it leverages the Opentitan Repository for its HW IPs,
templates and utilities.

## Documentation

The project contains comprehensive documentation of all IPs and tools. You can
access it.
<!-- TODO(pbf): Add link to documents -->.

## How to contribute

Have a look at our [GettingStarted Guide](https://spacebeaker.googlesource.com/shodan/docs/+/refs/heads/master/GettingStarted.md#developing-in-this-codebase)
for guidelines on how to contribute code to this repository.

## Licensing

Unless otherwise noted, everything in this repository is covered by the Apache
License, Version 2.0 (see [LICENSE](./LICENSE) for full text).

## Prerequisites

Development for matcha requires that the necessary tools and prerequisites be
installed.  See [GettingStarted Guide](https://spacebeaker.googlesource.com/shodan/docs/+/refs/heads/master/GettingStarted.md#developing-in-this-codebase)

To setup the build system, run following steps at root of repo:

```bash
source build/setup.sh
```

Install the prerequisites:

```bash
m prereqs
```

Install the tools used for development:

```bash
m tools
```

## Code/Repo Structure

```bash
<root_dir>/hw/matcha/
    hw/top_matcha/
        BUILD
        data/
        dv/
        formal/
        ip/
        ip_autogen/
        ip_templates/
        lint/
        rtl/
        sw/
        syn/
        util/
    hw/
        BUILD
        Makefile
    sw/
        BUILD
        device/
        hw_tests/
        Maefile
    util/
        BUILD
        topgen/
        topgen_util
        topgen_matcha.py

<root_dir>/hw/opentitan_upstream/
<root_dir>/build/
<root_dir>/Manifest/
<root_dir>/Makefile
<root_dir>/GettingStarted.md
<toot_dir>/...
```

## Quick start guide and cheat sheet

For following steps, make sure the above "Prerequisites" steps have been run if
the repo is been checked out at the first time.

Build RTL top Level and generate registers, interrupt and address map:

```bash
m matcha_hw_generate_all
```

Build verilator simulation target:

```bash
m matcha_hw_verilator_sim
```

Run matcha verilator test suite

```bash
m matcha_hw_verilator_tests
```

Run FPGA compilation flow for Nexus FPGA board:

```bash
m matcha_hw_fpga_nexus
```

## Bazel debug

Run matcha single test with messages to stdout

```bazel
bazel test --test_output=streamed //sw/device/tests:verilator_mailbox_test
```

Run matcha test suites

```bazel
bazel test --test_output=streamed //sw/device/tests:verilator_test_suite
```

Run FPGA compilation flow for Nexus FPGA board with debug commands:

```bazel
bazel build -s //hw/bitstream/vivado:fpga_nexus
```

## Simulation logs

Enable tracing on a single test

```bazel
bazel test --test_output=streamed  --test_timeout=1000000 --test_arg=--trace //sw/device/tests:verilator_cam_ctrl_test
```

*Note: `--test_timeout=1000000` sets timeout in seconds. This helps prevent timeout issues then using trace.*

Waveform dump and peripheral logs for a test located in:

```bash
<root_dir>/hw/matcha/bazel-testlogs/sw/device/tests/<test_name>/test.outputs/output.zip
    sim.fst (if tracing is enabled)
    uart0.log
    smc_uart.log
    spi0.log
    usb0.log
```

*Note: The trace_core_#.log files available in output.zip is currently a TODO
item.*

## The FPGA compiled bitstream and reports (resource utilization, pin assignment, etc) can be found in following directory:

<matcha_root_dir>/bazel-bin/hw/bitstream/vivado/build.fpga_nexus/synth-vivado/google_systems_chip_matcha_nexus_0.1.runs/impl_1/chip_matcha_nexus.bit
<matcha_root_dir>/bazel-bin/hw/bitstream/vivado/build.fpga_nexus/synth-vivado/google_systems_chip_matcha_nexus_0.1.runs/impl_1/*.rpt
<matcha_root_dir>/bazel-bin/hw/bitstream/vivado/build.fpga_nexus/synth-vivado/google_systems_chip_matcha_nexus_0.1.runs/synth_1/*.rpt

## DV flow

 [Setup DV flow](doc/getting_started/setup_dv.md)