README.md - gonk - Git at Google

 # Gonk

 [TOC]

 ## Getting Started

 > **NOTE:** If you are using a `gonk_tools.zip` bundle follow the instructions in
 > the `//tools` directory:
 > https://pigweed.googlesource.com/gonk/+/refs/heads/main/tools/

 1. Clone the repo

    ```sh
    git clone https://pigweed.googlesource.com/gonk
    ```

 2. Source `bootstrap.sh` to download all compilers and tooling into the
    `environment` directory:

    ```sh
    . ./bootstrap.sh
    ```

    This should init all git submodules for you.

 3. From here on the Pigweed environment is activated. You can activate the
    environment in a new shell without re-running bootstrap by sourcing
    `activate.sh`

    ```sh
    . ./activate.sh
    ```

 ## Capture ADC samples and plot

 1. First bootstrap, run `pw build` and flash gonk using DFU.

    ```sh
    . ./bootstrap.sh
    ```

    ```sh
    pw build
    ```

    Unplug gonk from USB and replug with MODE button held down.

    Run `gonk-flash` on the MCU binary. This uses `pyfu-usb`.

    ```sh
    gonk-flash ./out/gn/arduino_size_optimized/obj/applications/gonk/gonk.bin
    ```

 2. Start capturing ADC samples with:

    ```sh
    gonk \
      --bitstream-file DEFAULT \
      --log-to-stderr
    ```

    - Press `Enter` to stop or start ADC continuous updates. It will begin automatically on startup.
    - Press `ctrl-c` to quit.

 3. Plot the logs from `gonk-csv-log.txt` with:

    ```sh
    python tools/gonk_tools/plot.py -i gonk-csv-log.txt -o plot.svg
    ```


 ## Compilation Details

 Build for the host and device by running:

 ```sh
 pw build
 ```

 This is mostly a shortcut with nice output for running `gn gen out/gn` and
 `ninja -C out/gn`.

 The build commands are defined in: `//tools/gonk_tools/build_project.py`.

 ## Gonk Verilog Build

 The Verilog build requires the following to be installed on Linux:

 ```sh
 sudo apt install fpga-icestorm nextpnr-ice40 yosys
 ```

 Running `pw build` will run the FPGA toolchain if these commands are available on the `$PATH`:

 - `icepack`
 - `icetime`
 - `nextpnr-ice40`
 - `yosys`

 The bitstream files will be written with the `.bin` extenson under
 `./out/gn/obj/fpga/*/*.bin` along with log output files.

 For example:

 ```sh
 $ ls ./out/gn/obj/fpga/toplevel/
 nextpnr-log.txt
 toplevel.asc
 toplevel.bin
 toplevel.json
 toplevel_timing_report.json
 toplevel_timing_report.txt
 yosys-log.txt
 ```

 ## Gonk Firmware Build

 Flash the stm32f7 and launch the `gonk.py` script on a bitstream file.

 ### Flash via DFU

 1. Unplug gonk from USB and replug with MODE button held down.

 1. Run `gonk-flash` which uses `pyfu-usb`. The `--bin-file` argument is optional.

    ```sh
    gonk-flash --bin-file ./out/gn/arduino_size_optimized/obj/applications/gonk/bin/gonk.elf
    ```

 ### Alternative: Flash with BlackMagic Probe

 This is more useful if you are doing firmware debugging.

 ```sh
 ./scripts/flash-with-blackmagic-probe.sh ./out/gn/arduino_size_optimized/obj/applications/gonk/bin/gonk.elf
 ```

 ## Generating the Gonk Python Bundle

 This is a distibutable python wheel that can be used without the Gonk
 source checkout or compiling anything.

 On Linux with the FPGA toolchain available run:

 ```sh
 pw build
 ```

 The zip file containing all the dependencies for the gonk python tooling is located in:

 ```sh
 out/gn/obj/gonk_bundle.zip
 ```

 Inside are the Python wheels for `gonk_dist`, `gonk_firmware`, and all
 third_party dependencies.

 ```
 gonk_bundle
 ├── python_wheels
 │   ├── appdirs-1.4.4-py2.py3-none-any.whl
 │   ├── astroid-3.0.1-py3-none-any.whl
 │   ├── ...
 │   ├── gonk_dist-0.0.1+20240305140627-py3-none-any.whl
 │   ├── gonk_firmware-0.0.1+20240305140542-py3-none-any.whl
 │   ├── ...
 │   └── wheel-0.40.0-py3-none-any.whl
 ├── requirements.txt
 ├── setup.bat
 └── setup.sh
 ```

 ## Appendix

 ### CSV Log Format

 #### Fields

 1. Host timestamp with format `%Y%m%d %H:%M:%S.%f`
 2. Delta microseconds (elapsed microseconds since the last ADC read) on the STM32 microcontroller side.
 3. 7 Voltage values
 4. 7 Current values
 5. 7 Power values
 6. Comment text

 Example separated into multiple lines (with an empty comment field)
 ```
 20240813 14:16:35.176433,
 283,
 0.8148437500000001, 0.8892578125, 5.212109375000001, 1.087109375, 0.8904296875000001, 3.3820312500000003, 1.8125,
 0.058447916666666676, 0.031546875, 0.13443125, 0.015902343750000002, 0.0009143518518518518, 0.16081250000000002, 0.004143750000000001,
 0.04762591959635418, 0.02805330505371094, 0.7006703784179689, 0.01728758697509766, 0.0008141660337094908, 0.5438729003906251, 0.007510546875000001,

 ```

 #### GPIO assert events in the CSV

 When GPIOs are pulled LOW (to ground) a line in the CSV will appear
 with delta_micros = 0 and empty measurement values. The Comment field will
 contain the GPIO assert log message.

 Example:

 ```
 20240813 14:12:32.930888, 0,
 ,,,,,,,
 ,,,,,,,
 ,,,,,,,
 Header pin assert: 2
 ```


 ### Compiling the FPGA Toolchain

 #### yosys

 See https://github.com/YosysHQ/yosys for more instructions.

 On Ubuntu/Debian install the deps:
 ```sh
 sudo apt-get install build-essential clang lld bison flex \
     libreadline-dev gawk tcl-dev libffi-dev git \
     graphviz xdot pkg-config python3 libboost-system-dev \
     libboost-python-dev libboost-filesystem-dev zlib1g-dev
 ```

 Activate the bootstrap environment `. ./bootstraph.sh` then compile yosys.

 ```sh
 git clone https://github.com/YosysHQ/yosys
 cd yosys
 git submodule update --init
 make config-clang
 make -j8
 ```

 Install it to a known directory and add it to your `$PATH`:

 ```sh
 make DESTDIR=$HOME/ice40-fpga-tools install
 export $PATH=$PATH:$HOME/ice40-fpga-tools/usr/local/bin
 ```

 #### fpga-icestorm

 TODO: Document compiling from source.

 #### nextpnr-ice40

 TODO: Document compiling from source.

 ### Updating STM32Cube

 Checkout the desired commits in each of these submodules:

 ```
 third_party/stm32cube_f7/cmsis_core
 third_party/stm32cube_f7/cmsis_device
 third_party/stm32cube_f7/hal_driver
 ```

 Then run from Gonk root:

 ```sh
 python -m pw_stm32cube_build gen_file_list third_party/stm32cube_f7
 ```

 ### Gonk Pin Maps

 #### Misc

 | Net    | STM32 Pin | STM32 Function | Function |
 |--------|-----------|----------------|----------|
 | STATUS | PB13      | GPIO_Output    | STAT LED |

 ### Top 6 pin header (0.1inch pitch 2x3)

 Visual header pin positions:

 ```
                              +-------------
 +------+--------+-----+      |
 |  2   | Ground |  6  |      |    USB-C
 +------+--------+-----+      |    Port
 |  1   |   3    | VCC |      |
 +------+--------+-----+      +-------------
 ```

 | Header Pin | Net         | STM32 Pin |
 |------------|-------------|-----------|
 |          1 | SPI_HDR_IO3 | PB0       |
 |          2 | SPI_HDR_IO1 | PA2       |
 |          3 | SPI_HDR_IO2 | PA3       |
 |          4 | GND         |           |
 |          5 | VCC_GONK    |           |
 |          6 | SPI_HDR_IO0 | PA1       |

 ### SPI Flash Connection

 | Net          | FPGA IO# | STM32 Pin | STM32 Function | Flash Pin  |
 |--------------|----------|-----------|----------------|------------|
 | ICE_SPI_SS   |       71 | PD2       | GPIO_Output    | S#         |
 | ICE_SPI_MISO |       68 | PB4       | SPI1_MISO      | DQ1        |
 | ICE_SPI_MOSI |       67 | PB5       | SPI1_MOSI      | DQ0        |
 | ICE_SPI_SCK  |       70 | PB3       | SPI1_SCK       | C          |
 | FLASH_HOLD   |       63 | PC11      | GPIO_Output    | HOLD#/DQ3  |
 | FLASH_WP     |       64 | PC12      | GPIO_Output    | W#/VPP/DQ2 |

 ### FPGA Connection

 | Net               | Function | FPGA IO# | STM32 Pin | STM32 Function | Notes               |
 |-------------------|----------|----------|-----------|----------------|---------------------|
 | FPGA_IO_SPARE_0_2 | rst_i    |      135 | PA0       | GPIO_Output    | Active high         |
 | FPGA_IO_SPARE_0_0 | mode_i   |      137 | PB11      | GPIO_Output    | FPGA operation mode |
 | DSPI_CS           | valid_o  |       75 | PB6       | GPIO_Output    | Data/Transfer Valid |
 | FPGA_IO_SPARE_1_1 | miso_i   |      101 | PC2       | SPI1_MISO      |                     |
 | FPGA_IO_SPARE_1_0 | mosi_i   |       99 | PC3       | SPI1_MOSI      |                     |
 | I2C_O_SDA         | cs_n     |       79 | PB9       | SPI1_NSS       |                     |
 | FPGA_IO_SPARE_0_1 | sclk_i   |      136 | PB10      | SPI1_SCK       |                     |
 | FPGA_IO_SPARE_2_0 |          |       49 | PA7       |                |                     |
 | FPGA_IO_SPARE_2_1 |          |       48 | PA6       |                |                     |
 | FPGA_IO_SPARE_2_2 |          |       47 | PA5       |                |                     |
 | FPGA_IO_SPARE_2_3 |          |       45 | PA4       |                |                     |
	# Gonk

	[TOC]

	## Getting Started

	> NOTE: If you are using a `gonk_tools.zip` bundle follow the instructions in
	> the `//tools` directory:
	> https://pigweed.googlesource.com/gonk/+/refs/heads/main/tools/

	1. Clone the repo

	```sh
	git clone https://pigweed.googlesource.com/gonk
	```

	2. Source `bootstrap.sh` to download all compilers and tooling into the
	`environment` directory:

	```sh
	. ./bootstrap.sh
	```

	This should init all git submodules for you.

	3. From here on the Pigweed environment is activated. You can activate the
	environment in a new shell without re-running bootstrap by sourcing
	`activate.sh`

	```sh
	. ./activate.sh
	```

	## Capture ADC samples and plot

	1. First bootstrap, run `pw build` and flash gonk using DFU.

	```sh
	. ./bootstrap.sh
	```

	```sh
	pw build
	```

	Unplug gonk from USB and replug with MODE button held down.

	Run `gonk-flash` on the MCU binary. This uses `pyfu-usb`.

	```sh
	gonk-flash ./out/gn/arduino_size_optimized/obj/applications/gonk/gonk.bin
	```

	2. Start capturing ADC samples with:

	```sh
	gonk \
	--bitstream-file DEFAULT \
	--log-to-stderr
	```

	- Press `Enter` to stop or start ADC continuous updates. It will begin automatically on startup.
	- Press `ctrl-c` to quit.

	3. Plot the logs from `gonk-csv-log.txt` with:

	```sh
	python tools/gonk_tools/plot.py -i gonk-csv-log.txt -o plot.svg
	```


	## Compilation Details

	Build for the host and device by running:

	```sh
	pw build
	```

	This is mostly a shortcut with nice output for running `gn gen out/gn` and
	`ninja -C out/gn`.

	The build commands are defined in: `//tools/gonk_tools/build_project.py`.

	## Gonk Verilog Build

	The Verilog build requires the following to be installed on Linux:

	```sh
	sudo apt install fpga-icestorm nextpnr-ice40 yosys
	```

	Running `pw build` will run the FPGA toolchain if these commands are available on the `$PATH`:

	- `icepack`
	- `icetime`
	- `nextpnr-ice40`
	- `yosys`

	The bitstream files will be written with the `.bin` extenson under
	`./out/gn/obj/fpga//.bin` along with log output files.

	For example:

	```sh
	$ ls ./out/gn/obj/fpga/toplevel/
	nextpnr-log.txt
	toplevel.asc
	toplevel.bin
	toplevel.json
	toplevel_timing_report.json
	toplevel_timing_report.txt
	yosys-log.txt
	```

	## Gonk Firmware Build

	Flash the stm32f7 and launch the `gonk.py` script on a bitstream file.

	### Flash via DFU

	1. Unplug gonk from USB and replug with MODE button held down.

	1. Run `gonk-flash` which uses `pyfu-usb`. The `--bin-file` argument is optional.

	```sh
	gonk-flash --bin-file ./out/gn/arduino_size_optimized/obj/applications/gonk/bin/gonk.elf
	```

	### Alternative: Flash with BlackMagic Probe

	This is more useful if you are doing firmware debugging.

	```sh
	./scripts/flash-with-blackmagic-probe.sh ./out/gn/arduino_size_optimized/obj/applications/gonk/bin/gonk.elf
	```

	## Generating the Gonk Python Bundle

	This is a distibutable python wheel that can be used without the Gonk
	source checkout or compiling anything.

	On Linux with the FPGA toolchain available run:

	```sh
	pw build
	```

	The zip file containing all the dependencies for the gonk python tooling is located in:

	```sh
	out/gn/obj/gonk_bundle.zip
	```

	Inside are the Python wheels for `gonk_dist`, `gonk_firmware`, and all
	third_party dependencies.

	```
	gonk_bundle
	├── python_wheels
	│ ├── appdirs-1.4.4-py2.py3-none-any.whl
	│ ├── astroid-3.0.1-py3-none-any.whl
	│ ├── ...
	│ ├── gonk_dist-0.0.1+20240305140627-py3-none-any.whl
	│ ├── gonk_firmware-0.0.1+20240305140542-py3-none-any.whl
	│ ├── ...
	│ └── wheel-0.40.0-py3-none-any.whl
	├── requirements.txt
	├── setup.bat
	└── setup.sh
	```

	## Appendix

	### CSV Log Format

	#### Fields

	1. Host timestamp with format `%Y%m%d %H:%M:%S.%f`
	2. Delta microseconds (elapsed microseconds since the last ADC read) on the STM32 microcontroller side.
	3. 7 Voltage values
	4. 7 Current values
	5. 7 Power values
	6. Comment text

	Example separated into multiple lines (with an empty comment field)
	```
	20240813 14:16:35.176433,
	283,
	0.8148437500000001, 0.8892578125, 5.212109375000001, 1.087109375, 0.8904296875000001, 3.3820312500000003, 1.8125,
	0.058447916666666676, 0.031546875, 0.13443125, 0.015902343750000002, 0.0009143518518518518, 0.16081250000000002, 0.004143750000000001,
	0.04762591959635418, 0.02805330505371094, 0.7006703784179689, 0.01728758697509766, 0.0008141660337094908, 0.5438729003906251, 0.007510546875000001,

	```

	#### GPIO assert events in the CSV

	When GPIOs are pulled LOW (to ground) a line in the CSV will appear
	with delta_micros = 0 and empty measurement values. The Comment field will
	contain the GPIO assert log message.

	Example:

	```
	20240813 14:12:32.930888, 0,
	,,,,,,,
	,,,,,,,
	,,,,,,,
	Header pin assert: 2
	```


	### Compiling the FPGA Toolchain

	#### yosys

	See https://github.com/YosysHQ/yosys for more instructions.

	On Ubuntu/Debian install the deps:
	```sh
	sudo apt-get install build-essential clang lld bison flex \
	libreadline-dev gawk tcl-dev libffi-dev git \
	graphviz xdot pkg-config python3 libboost-system-dev \
	libboost-python-dev libboost-filesystem-dev zlib1g-dev
	```

	Activate the bootstrap environment `. ./bootstraph.sh` then compile yosys.

	```sh
	git clone https://github.com/YosysHQ/yosys
	cd yosys
	git submodule update --init
	make config-clang
	make -j8
	```

	Install it to a known directory and add it to your `$PATH`:

	```sh
	make DESTDIR=$HOME/ice40-fpga-tools install
	export $PATH=$PATH:$HOME/ice40-fpga-tools/usr/local/bin
	```

	#### fpga-icestorm

	TODO: Document compiling from source.

	#### nextpnr-ice40

	TODO: Document compiling from source.

	### Updating STM32Cube

	Checkout the desired commits in each of these submodules:

	```
	third_party/stm32cube_f7/cmsis_core
	third_party/stm32cube_f7/cmsis_device
	third_party/stm32cube_f7/hal_driver
	```

	Then run from Gonk root:

	```sh
	python -m pw_stm32cube_build gen_file_list third_party/stm32cube_f7
	```

	### Gonk Pin Maps

	#### Misc

	\| Net \| STM32 Pin \| STM32 Function \| Function \|
	\|--------\|-----------\|----------------\|----------\|
	\| STATUS \| PB13 \| GPIO_Output \| STAT LED \|

	### Top 6 pin header (0.1inch pitch 2x3)

	Visual header pin positions:

	```
	+-------------
	+------+--------+-----+ \|
	\| 2 \| Ground \| 6 \| \| USB-C
	+------+--------+-----+ \| Port
	\| 1 \| 3 \| VCC \| \|
	+------+--------+-----+ +-------------
	```

	\| Header Pin \| Net \| STM32 Pin \|
	\|------------\|-------------\|-----------\|
	\| 1 \| SPI_HDR_IO3 \| PB0 \|
	\| 2 \| SPI_HDR_IO1 \| PA2 \|
	\| 3 \| SPI_HDR_IO2 \| PA3 \|
	\| 4 \| GND \| \|
	\| 5 \| VCC_GONK \| \|
	\| 6 \| SPI_HDR_IO0 \| PA1 \|

	### SPI Flash Connection

	\| Net \| FPGA IO# \| STM32 Pin \| STM32 Function \| Flash Pin \|
	\|--------------\|----------\|-----------\|----------------\|------------\|
	\| ICE_SPI_SS \| 71 \| PD2 \| GPIO_Output \| S# \|
	\| ICE_SPI_MISO \| 68 \| PB4 \| SPI1_MISO \| DQ1 \|
	\| ICE_SPI_MOSI \| 67 \| PB5 \| SPI1_MOSI \| DQ0 \|
	\| ICE_SPI_SCK \| 70 \| PB3 \| SPI1_SCK \| C \|
	\| FLASH_HOLD \| 63 \| PC11 \| GPIO_Output \| HOLD#/DQ3 \|
	\| FLASH_WP \| 64 \| PC12 \| GPIO_Output \| W#/VPP/DQ2 \|

	### FPGA Connection

	\| Net \| Function \| FPGA IO# \| STM32 Pin \| STM32 Function \| Notes \|
	\|-------------------\|----------\|----------\|-----------\|----------------\|---------------------\|
	\| FPGA_IO_SPARE_0_2 \| rst_i \| 135 \| PA0 \| GPIO_Output \| Active high \|
	\| FPGA_IO_SPARE_0_0 \| mode_i \| 137 \| PB11 \| GPIO_Output \| FPGA operation mode \|
	\| DSPI_CS \| valid_o \| 75 \| PB6 \| GPIO_Output \| Data/Transfer Valid \|
	\| FPGA_IO_SPARE_1_1 \| miso_i \| 101 \| PC2 \| SPI1_MISO \| \|
	\| FPGA_IO_SPARE_1_0 \| mosi_i \| 99 \| PC3 \| SPI1_MOSI \| \|
	\| I2C_O_SDA \| cs_n \| 79 \| PB9 \| SPI1_NSS \| \|
	\| FPGA_IO_SPARE_0_1 \| sclk_i \| 136 \| PB10 \| SPI1_SCK \| \|
	\| FPGA_IO_SPARE_2_0 \| \| 49 \| PA7 \| \| \|
	\| FPGA_IO_SPARE_2_1 \| \| 48 \| PA6 \| \| \|
	\| FPGA_IO_SPARE_2_2 \| \| 47 \| PA5 \| \| \|
	\| FPGA_IO_SPARE_2_3 \| \| 45 \| PA4 \| \| \|