{"id":19065401,"url":"https://github.com/newaetech/chipwhisperer-husky-fpga","last_synced_at":"2026-03-01T13:03:39.585Z","repository":{"id":40252008,"uuid":"337116286","full_name":"newaetech/chipwhisperer-husky-fpga","owner":"newaetech","description":"FPGA design and test files for ChipWhisperer-Husky.","archived":false,"fork":false,"pushed_at":"2026-02-17T19:19:03.000Z","size":419473,"stargazers_count":18,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2026-02-18T00:50:14.834Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/newaetech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-02-08T15:14:57.000Z","updated_at":"2026-01-27T19:14:46.000Z","dependencies_parsed_at":"2024-05-14T00:35:19.886Z","dependency_job_id":"474a5ffd-e433-451e-866e-ed0526fd97bf","html_url":"https://github.com/newaetech/chipwhisperer-husky-fpga","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/newaetech/chipwhisperer-husky-fpga","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newaetech%2Fchipwhisperer-husky-fpga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newaetech%2Fchipwhisperer-husky-fpga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newaetech%2Fchipwhisperer-husky-fpga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newaetech%2Fchipwhisperer-husky-fpga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/newaetech","download_url":"https://codeload.github.com/newaetech/chipwhisperer-husky-fpga/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newaetech%2Fchipwhisperer-husky-fpga/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29969700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T12:56:10.327Z","status":"ssl_error","status_checked_at":"2026-03-01T12:55:24.744Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T00:49:48.911Z","updated_at":"2026-03-01T13:03:39.565Z","avatar_url":"https://github.com/newaetech.png","language":"Verilog","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChipWhisperer-Husky\nThis repository contains the FPGA design and test files for\nChipWhisperer-Husky.\n\n# Implementation\nHusky uses a Xilinx XC7A35 FPGA; Husky Plus uses an XC7A100.  Implementation is\ndone with Vivado 2022.1.\n\nWhen opening the [Husky](fpga/vivado/cwhusky.xpr) or \n[Husky Plus](fpga/vivado/cwhusky_plus.xpr) project, Vivado will report some\n\"errors\" about missing IP that are not actually errors and can be safely\nignored (these relate to ILA modules used in development which are not\nincluded in the repository, because they're not used in the production\nbitfile).\n\nImplementation should run cleanly (no setup or hold timing violations) but\ntiming is tight and small timing failures can occur if you're unlucky. The\nobjective is to not have *any* timing violations. Sometimes this can be\nachieved by re-running with different synthesis and/or implementation\nstrategies. If the changes to the source code were minor or inconsequential,\nthis is usually sufficient to achieve clean timing.\n\nIf not, you'll have to dig a little deeper. The three main stressors for the\nimplementation are:\n1. Almost all of the block RAM is used (for ADC, LA, and trace sample\n   storage).\n2. Overall resource utilization is very high (except for Husky Plus).\n3. The SAD module is particularly large, runs on a fast clock, and can have\n   long routing delays due to its large size and interconnected logic.\n\nIf you are customizing the design, you can reduce block RAM usage by\nreducing the size of the associated FIFOs (for an example, see what happens\nwhen `TINYFIFO` is defined). You can reduce overall utilization by removing\nmodules that you do not need (e.g. SAD, glitch, trace, LA). By far the\nbiggest bang for your buck here is the SAD module, which is huge. Its size\ncan be controlled via the `pREF_SAMPLES` parameter in\n[`openadc_interface.v`](fpga/hdl/openadc_interface.v).\nRefer to the source code for more details about the SAD parameters that can\nbe adjusted. (You'll also find several different SAD implementations;\n[`esad.v`](fpga/hdl/esad.v) was chosen for having the best results --\nsmallest size for the most SAD samples -- but feel free to experiment.)\n\nBe aware that if you go the *other* way on SAD and *increase* its size (i.e.\non Husky Plus where there are sufficient FPGA resources to do so), this can\ndrive up power consumption to the point where the current draw might be too\ngreat at higher clock frequencies, and/or the FPGA overheats (yes, this can\nactually happen). The `scope.XADC` VCC and temperature alarms can be used to\nprotect the FPGA, but this limits useability.\n\nThere should be no violations at all on inter-clock paths. Husky's\n[implementation constraints](fpga/vivado/cwhusky.xdc) makes liberal use of\n`set_clock_groups -asynchronous` exceptions, and so great care must be taken\nwhen dealing with logic which uses multiple clocks (of which there are\n*many!*).\n\nOccasionally, a bitfile can be obtained where FPGA register reads/writes\nare unreliable (i.e. [`test_husky.py`'s](#on-target-testing) `test_reg_rw()`\ntest will fail), which makes the bitfile useless. Again, the solution is to\nre-compile with a different synthesis or implementation strategy. If this\noccurs, connecting to the scope object usually returns this error message:\n\"Failed to update the MMCM secondary divider(...)\". This message is a\nsymptom, not a cause -- it occurs because read/writes are not working\ncorrectly.  (The root cause of this issue is likely incorrect constraints on\nthe SAM3U/FPGA interface; this is hard to correct because Husky uses the\nSAM3U SMC interface out-of-spec to squeeze as much throughput out of it as\npossible in streaming mode.)\n\nThe only critical warnings in the implementation log file should relate to\ninconsequential missing IP modules (e.g. ILAs) and the the last three\n`dbg_hub` commands.\n\nAfter any modifications to the Husky source, thorough testing should be\ndone, both in simulation and on-target, as explained in the next section.\n\n# Testing\n\nCW-Husky is tested in two ways:\n1. Verilog simulation\n2. On-target testing\n\n## Verilog Simulation\n\n### Requirements\n* [Icarus Verilog](http://iverilog.icarus.com)\n* [cocotb](https://github.com/cocotb/cocotb)\n* [gtkwave](http://gtkwave.sourceforge.net)\n* **no commercial tools!**\n\nNote that the Vivado simulator is not supported. In theory [any simulator\nsupported by cocotb](https://docs.cocotb.org/en/stable/simulator_support.html)\nshould work; in practice, iverilog is what we use.\n\n\n### Running Simulations\nTestcases are defined in the `regress.py` script in `fpga/sim/`. Run\n`regress.py --list` to lists available testcases. \n\nTo run a particular testcase: `regress.py --test \u003ctestcase\u003e`. \n\nAdd the `--variant plus` argument to simulate the Husky Plus variant;\n``--variant pro` for the Pro.\n\nMany things are randomized when a testcase is run. To re-run a testcase with\nthe same randomizations, specify a `--seed \u003cinteger\u003e`. \n\nAdd `--dump` to generate a simulation waveform.\n\nTo run the full test suite: `regress.py --runs \u003cnumber of runs\u003e`. This\nlaunches all simulations in parallel, so start with a smaller number to\navoid making your computer totally unresponsive for a few minutes.\n\nUse `--tests` to regress a subset of the regression suite. For example,\n`regress.py --tests glitches --runs 10` will run only the testcases which\ncontain \"glitches\" in their name.\n\nFor simulations, all of the Vivado IP (MMCMs, XADC, clock and I/O\nprimitives) is bypassed with the exception of the FIFOs. This is done with\n`` `ifndef __ICARUS__`` in the Verilog source. This means that simulations\ncan't fully cover all scenarios, especially with regards to different clock\nrates and their interactions. Different clock rates are covered extensively\nby [on-target testing](#on-target-testing).\n\nSimulation models for the Xilinx FIFOs are provided\n[here](fpga/sim/vivado/), however these can sometimes be problematic as they\nare quite finicky about how resets should be applied. The testbench applies\nthe reset in a way that should satisfy the Xilinx FIFO requirements but yet\nsomehow the FIFOs can sometimes misbehave (X's propagate, status flag remain\nunvalid). \n\nFor this reason, we developed [our own FIFOs](fpga/fpga-common/hdl). Their\nbehaviour is **not** idential to the Xilinx FIFOs; in particular status flag\nlatency is different (they also do not suffer from reset bugs 🤣), and while\nthey are fully functional and *can* be used for implementation, they are (a)\nnot guaranteed to be bug-free and (b) fare worse on timing closure. However,\nin addition to not being picky about resets, they simulate *much* faster.\nSo, the Xilinx FIFOs are still used in implementation and remain the default\nin simulation; to use the faster FIFOs in simulation, add `--fast_fifo_sim`\nto `regress.py`.\n\nMore detailed notes about the testbench architecture and what it does and\ndoesn't cover can be found [here](fpga/sim/README.md).\n\n\n### TraceWhisperer\nHusky's top-level testbench does not cover trace. For this, run the\nTraceWhisperer testbench in its\n[submodule](https://github.com/newaetech/chipwhisperer-husky-fpga/tree/main/fpga).\nVerification of trace within Husky is covered by on-target testing (see\nbelow).\n\n\n## On-Target Testing\nSome things can't be verified in simulation; they must be verified on the\nFPGA itself.\n[`test_husky.py`](https://github.com/newaetech/chipwhisperer/blob/develop/tests/test_husky.py)\nruns a comprehensive series of tests automatically. Invoke it like this:\n`pytest test_husky.py`.\n\nMany of the tests can run without a target attached; others require a target\nrunning simpleserial firmware. In particular, the trace tests require a\nspecific firmware to succeed; the target should be programmed with the\nfirmware included in `hardware/victims/firmware/simpleserial-trace/`.\n\nAmong the things covered by `test_husky.py`:\n* whether reading/writing the FPGA works reliably;\n* whether data from the ADC is sampled correctly by the FPGA;\n* whether the advertised streaming rates can be achieved;\n* whether the generated glitches have the expected shape;\n* whether triggering from trace works correctly;\n* whether different clock rates works correctly.\n\n# Debugging\n\nSimulation is always best, but sometimes bugs don't show up in simulation\nbecause the simulation environment isn't a perfect reconstruction of\nreality.\n\nTo hunt down bugs on the FPGA, you can either:\n* route signals of interest to the front 20-pin header and use an external\n  logic analyzer (`scope.userio` already has a few options for this, and can\n  be extended to add additional signals);\n* use the internal `scope.LA` logic analyzer (again, several groups of\n  internal signals are already routed to it, and more can be added);\n* use Xilinx ILAs.\n\nILAs require BRAM, and Husky uses 49 of the 50 available BRAMs for storage\nof ADC samples, trace samples, and `scope.LA` samples (on Husky Plus there\nis a little bit more BRAM left to play with). To free up more, you can\nrebuild Husky with `TINYFIFO` defined: this reduces the size of the sample,\ntrace, and logic analyzer FIFOs. Just be aware that you won't be able to do\nlong captures. \n\nIf your issue involves streaming, things are a bit more complicated, since\nstreaming requires deep storage to function properly (the SAM3U reads in\nbursts of 64K samples when streaming). You'll have to get creative. One\noption is to build without the trace and logic analyzer, by removing the\ncorresponding defines in `setup.v`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewaetech%2Fchipwhisperer-husky-fpga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnewaetech%2Fchipwhisperer-husky-fpga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewaetech%2Fchipwhisperer-husky-fpga/lists"}