IRC: colemole9595 on libera.chat
Slack: colemole9595 in the CHIPS Alliance Workspace
Click here for the markdown document that this proposal is generated from. It has working footnotes.
The AMD/Xilinx Spartan 6 series of FPGAs is immensely popular and has found itself in a number of open source projects1 and low cost development boards23. A quick search yields many results4567 from as early as last year where people express interest about an open source Spartan 6 flow. The aim of this proposal is to build upon Project X-Ray's success with the Series7 and extend it to support the Spartan 6 series.
The smallest part in the series, the XC6SLX4 has 2,731,488 bits of configuration data. Even if the tools allowed for it, decoding the bitstream by manipulating and observing the changes to individual bits would be infeasible. Statistical techniques in addition to exploiting the regular nature of the FPGA tiles are the most practical method to discover the meaning behind the bits.
Reverse engineering a bitstream is a monumental task. At the time of writing this, prjxray has over 3,500 commits from over 39 contributors. My ideal outcome for this project is the creation of a well documented base that allows for as many contributors to add effort as easily as possible.
As the main idea is to extend Project X-Ray to add support for the Spartan 6 series, I will use this section to explain the methodology that will be borrowed. Devices support will be limited to those under the free ISE WebPACK Edition license (6SLX4 to 6SLX75T). I want to further limit the devices to just one fabric, the XC6SLX9, as I have one on hand. Thanks to some recent work by @tmichalak, the infrastructure to read and write the bitstreams to and from a textual representation already exists.
After setting up the basic infrastructure that is init-db, parts-yaml and tilegrid fuzzers, the next step would be to create minitests and experiments that inform the creation of fuzzers for a particular tile type. I expect some of the fuzzers to transfer over without issue from Project X-Ray.
My top priority is successfully completing the GSoC project and hitting all mandatory milestones. In order to make success more likely, I have placed the core milestones at the front of the queue and placed the stretch goals deeper into the timeline. This way the risk can be reduced and when things eventually don't go to plan I will have some time to course correct.
- Part Fuzzer: This component is responsible for extracting information about configuration rows, columns and their frame counts.
- Tilegrid Fuzzer: This component is responsible for fuzzing individual tiles and adding information about the base address to the bitsteam database. It consists of a sub-fuzzer for each tile type (such as BRAM, DSP, CLB, etc).
- A dozen tile types will be localized in the bit stream.
- BRAM data fuzzing using data2mem.
- Deep dive into Xilinx docs and Project X-Ray's internals.
- Study archived experiments in https://github.com/SymbiFlow/prjxray-experiments-archive-2017/ and try to recreate a few observations.
- Investigate the use of
data2memto obtain the BRAM data mapping. - Investigate the output of
xdl -reportfor details about architecture.
- Tool can perform database creation for mask, segbits and ppips given a part/fabric.
- Work on Part Fuzzer begins.
- Part Fuzzer is able to extract information about the structure of the FPGA configuration and classify address ranges by frame type such as Core, Block RAM and IOB.
- Minitest for LOC and observation of CLB behaviour in bitstream.
- Work on tilegrid fuzzer begins.
- Tilegrid fuzzer is able to extract address information given a generate.tcl, Makefile and top.py.
- Extract tilegrid information about CLBs.
- Extract tilegrid information about IOBs.
- Extract tilegrid information about PLLs.
- Extract tilegrid information about BRAMs.
- Extract tilegrid information about DSPs.
- Extract tilegrid information about GCLKs.
- Extract tilegrid information about BUFGs and BUFGMUXs.
- Extract tilegrid information about BUFHs.
- Write article explaining progress so far.
- Core milestones should be achieved by this week.
- Buffer week.
- Extract tilegrid information about O/ISERDES2s.
- Extract tilegrid information about CARRY4.
- Extract tilegrid information about DPRAM32.
- Extract tilegrid information about SLICEX.
- Extract tilegrid information about SLICEL.
- Extract tilegrid information about SLICEM.
- Write a detailed tutorial for writing custom fuzzers that includes at least two worked out examples.
- Write a retrospective article about the experience.
- Buffer period to tie up loose ends.
- Buffer period to tie up loose ends.
- One of the most significant risks faced by this project is inconsistent/incorrect vendor tools and documentation. I have already come across incorrect vendor documentation regarding
bitgen's ability to produce a debug bitstream for the Spartan 6 series and unexplained discrepancies in the Frame Length register's values in valid real world bitstreams. - Another significant risk is if some of the techniques used in Project X-Ray won't be applicable to the Spartan 6 parts due to the use of a different toolchain. For example, if a bug such as MUXF8 vivado compatibility were to present itself in ISE, then a whole load of fuzzers would not be transferable between the projects.
- Transformed the output of `partgen -p spartan6 -nopkgfile' into a devices.yaml file.
- Opened a pull request to fix a small issue with int_maketodo's verbose logging.
- Opened a pull request to add disk reporting functionality to run_fuzzer.py.
- Wrote a quick and dirty Kaitai parser definition to visualize XC6LX9 bitstreams.
- I have a Spartan 6 LX9 based development board (a Numato Mimas) that might come in handy to try to uncover what some of the undocumented registers do.
- I have a desktop that can act as a CI runner to offload long fuzzing sessions from my laptop.
I came across Claire's video8 about the iceStorm project while browsing the Chaos Communication Congress's video page and was blown away by the talk. I had no idea that something like that was possible and had always assumed that FPGAs and the software that powered them were black magic. Up to this point, my only interaction with FPGAs was with a Digilent board I played with in the university makerspace. I was fascinated by the capabilities of the hardware and went on to slowly teach myself how to use it. As a regularly user of open source software, I want to contribute back to the community. I also very much enjoy the act of taking apart something to understand it. I will no doubt feel great joy reverse engineering the bitstream format.
I'm Anmol. I'm currently living in Bengaluru, a city in India. I graduated in 2016 with a Bachelors in Mechanical Engineering from the Birla Institute of Technology and Science, Pilani.
-
BASH, cmake, C++11/14, ISE, Python, Verilog, Vivado: I am comfortable with these languages/tools. I took a walk through the experiments, minitests and fuzzers and did not find that they were too advanced for me.
-
Tcl, Github CI : I don't have as much experience with these and will need to learn.