Document bitfiles

[sneakers-the-rat]

Continuing #19

The stream daq relies on bitfiles - i believe these are the "programs" that run on the FPGA, but i actually have no idea.

We need to

• Document what bitfiles are - user facing documentation, so people know how their cameras and DAQs work
• Document how they are generated - developer facing documentation, so people can debug, modify, make their own, contribute to the project, etc.

This probably goes along with needing to document FPGA stuff generally, so i'll defer basically all of the "how" this gets done to @phildong - i am not sure what the plans are for release of that stuff, and if there are plans for making separate documentation for FPGA that we can just link to, or if that should all live here.

at the moment we are sort of operating with a manual, black box dependency, and it would be nice to make that more explicit -- like we will probably need to make updates to the FPGA code at some point, and it would be nice to be able to declare that version compatibility. e.g. if we change miniscope-io code to use some new features or new behavior of FPGA code, there would currently not be a good way for us to tell a user that the new version is incompatible with their existing FPGA code, etc. That's a separate discussion, but raising it here because it underscores the need for us to document what the bitfiles are and how they relate to the rest of the FPGA system. We are currently public pre-alpha on this project, but i think the FPGA stuff is all still private? so that would be a bridge i'd rather cross sooner than in a rush while the paper is coming together.

[t-sasatani]

I'd be happy to take over this part if @phildong is too busy and can take questions. I'm no expert in FPGA, so I would need some help and time, but it'll be better if I can modify this part in the long run.

[phildong]

Hey sorry I'm slow to take action on this. I've just transferred the ownership of the repo https://github.com/Aharoni-Lab/wireless_fpga_daq, so it can be public whenever we feel ready.
The repo had some minimal documentation on which file is which. I certainly agree we need much more content, but it's currently hard for me to think of exactly what needs to be added. I just need some trigger/hint, so it will definitely be helpful if @t-sasatani could provide something like a list of questions, and maybe I can go from there?

[t-sasatani]

No problem, and sure, that sounds great. I'll post notes as I re-run the synthesis on my end (probably around the end of this year).

[sneakers-the-rat]

finally just tried looking it up, this is helpful - http://lastweek.io/fpga/bitstream/

constraining this to just bitfiles for now (rather than all FPGA/wireless daq documentation which will basically be "document it like any project, how do we set it up, how do we use it, etc."), some starting points:

• What does the bitfile do? I am assuming that it is "the program" that runs on the FPGA, is that correct?
• What is configured in the bitfile? e.g. this config refers to a bitstream that has 8.33mHz, J2.2, 3v3, and IEEE in the name. What are the fields that can vary in the bitfield? We should make this into a model s.t. we can specify it like this:

bitstream:
  file: location/of/file.bit
  frequency:
    value: 8.33
    unit: MHz
 # ... etc.

• What are the compatibility constraints with other non-bitfile config parameters? that config file has "200px" in the name, is that 200px intrinsic to the bitfile? What needs to match between the config and the bitfile, or is the config just a reflection of the values in the bitfile itself?
• Do we have one single .bit file or are we providing a set of them that people might want to use in different contexts? If the latter, we should set up some make action that generates all the combinations of available config values.
• Can people generate their own? Should they need to?
• What hardware can the bitfile be run on? is it exclusive to that one single xem7310 model?

[phildong]

finally just tried looking it up, this is helpful - http://lastweek.io/fpga/bitstream/

constraining this to just bitfiles for now (rather than all FPGA/wireless daq documentation which will basically be "document it like any project, how do we set it up, how do we use it, etc."), some starting points:

• What does the bitfile do? I am assuming that it is "the program" that runs on the FPGA, is that correct?
• What is configured in the bitfile? e.g. this config refers to a bitstream that has 8.33mHz, J2.2, 3v3, and IEEE in the name. What are the fields that can vary in the bitfield? We should make this into a model s.t. we can specify it like this:

bitstream:
  file: location/of/file.bit
  frequency:
    value: 8.33
    unit: MHz
 # ... etc.

• What are the compatibility constraints with other non-bitfile config parameters? that config file has "200px" in the name, is that 200px intrinsic to the bitfile? What needs to match between the config and the bitfile, or is the config just a reflection of the values in the bitfile itself?
• Do we have one single .bit file or are we providing a set of them that people might want to use in different contexts? If the latter, we should set up some make action that generates all the combinations of available config values.
• Can people generate their own? Should they need to?
• What hardware can the bitfile be run on? is it exclusive to that one single xem7310 model?

1. It's basically the "program" that runs on the FPGA. I guess technically it's a binary file that defines how the little components in FPGA (LUTs, RAMs etc.) are connected/configured to realize certain function. But honestly "the program that runs on FPGA" is good enough.
2. Since it's the "program", the bitfile defines literally every single aspects of FPGA behavior. However the four parameters @sneakers-the-rat mentioned are the most frequently changed/relevant ones so far. I can imagine something like this:

bitstream:
  manchester_freq:
    value: 8.33
  io_port:
    value: J2_2
  io_vcc:
    value: 3.3
  manchester_polarity:
    value: IEEE

I do want to mention since .bit is a binary file, there is no "fields" in the file. So something like this will be for documentation purpose only and won't be very helpful to constrain/automate testing for the actual file. The actual source "fields" that correspond to these parameters spans multiple files in the source (not bitfile) and some of them are black-box to me as well (since they use vivado IP).
4. I'm not sure what's 200px and my guess is it's certainly not intrinsic to bitfile.
5. If we plan to give user the capability to change any of the above parameters (which in my opinion should not happen in the end), then we need multiple bitfile. Setting up automation for synthesis could be very challenging as it depends on proprietary AMD/Xilinx software.
6. They can generate their own if they obtain a copy of vivado (proprietary software but free for students/community). In my opinion they shouldn't need to when miniscope-io is released.
7. It's exclusive to one single particular model.

[t-sasatani]

4. I'm not sure what's 200px and my guess is it's certainly not intrinsic to bitfile.

This parameter is used in the I/O code and unrelated to this bitfile. Actually, none of the fields in the YAML file except the device and bitfile is related to the FPGA.

[sneakers-the-rat]

Great! That makes sense.

re (2): I think the idea is mostly for the sake of documentation - having those values split out in a way where their meaning can be described and aren't just in the filename. So when someone bundles up their data for publication they can include that as an unambiguous way to refer what was running in their experiment. I can handle that change after i finish up the current changes.

Just talked with Takuya about this, writing it down so we have it here when it comes to to do the docs: the only parameter that really should need to be varied is the frequency, and it's loosely coupled to the image resolution in the sense that if one were to increase the resolution (in some hypothetical future device, for example) then one would need to increase the frequency.