Confusing ADC documentation: ADC PLLs and LEDs

[patzinak]

When an ADC board with the firmware Build 7 is run in a normal regime, should LED1 ("AD clock not locked" according the documentation) be on? All ADC boards that were upgraded to the latest firmware version (two at the moment) shows the same behavior, namely, the LED1 is basically on all the time. We can switch the LED off by running the initialization script a good number of times (roughly 4-30 times) but the LED always goes on when we try to query its state or when we try to run any measurement code, i.e. whenever we read anything back from the board. The quires always return 1. We still can get quite meaningful data from the boards when we are running any tests or measurements but it is not clear whether we should trust this data. Before the upgrade, however, it was always possible to initialize and run the ADC boards (but not query them) having all LED in the off state. Are Build 1 and Build 7 anyhow different when it comes to LEDs? Overall, Build 7 feels much better but the PLL LED undermines the trustworthiness of the data. The up-to-date LabRAD (Scala-based)/Ethernet (Scala-based) and GHz FPGA servers are used.

@amopremcak, @gribeill

[patzinak]

Okay, this is how far I was able to get:

The documentation is really confusing but mostly based on AA_documentaitonAD_v6.doc, my understanding now is that LED[0] on corresponds to unlatching of the "FPGA PLL" or "external 1 GHz PLL" (which seemed to be two different things), while LED[1] on corresponds to "bad clocking phase of the AD" converters, the later is somehow also referred to as "GHz PLL" and this is really, really confusing. I can't find the circuit diagram to check whether this makes sense from the hardware design viewpoint.

There is an apparent bug in GHz FPGAs server: setting adc_register_readback does not work for ADC Build 7. The actual bug is in https://github.com/martinisgroup/servers/blob/master/fpgalib/adc.py , line 958. The suggested fix is to replace regs = self.regRun(self.RUN_MODE_REGISTER_READBACK, 0) # 0 reps? with regs = self.regRun(self.RUN_MODE_REGISTER_READBACK, {}, 0). Ping: @maffoo , @DanielSank

I also suggest to add 'dClkBits': a[1] >> 1 & 15, into the corresponding processReadback method. See McDermott-Group/servers@eb879bb .
My understanding is that when the board operates in a normal regime all four bits should report 1. While the exact meaning of these AD bits is somewhat obscure this seems like an extremely useful diagnostic feature, which helped me, and hopefully we can claim this now, partially resolve the original issue. I can do a pull request on this but it appears your group tends to pack several bug fixes/enhancements in one major update branch.

One question I have now is about adc_bringup (which is an exact duplication of pll_init setting) and adc_recalibrate. Is the following correct: during an experiment, when many data points are taken, one can always safely run pll_init or adc_bringup to get the board LED[0] and LED[1] off, while running adc_recalibrate should be avoided at all costs because it may lead to the phase jumps in the collected data?

Finally, and this needs to be explained to claim that we resolved the issue, we started seeing LED[1] going off when we inserted a 6 inch SMA cable into the ADC clock line. LED[0] is always off when the board is connected to our reference clock, SpectraDynamics FEL-10A, but LED[1] basically never goes off unless we have this little cable. A 12 inch cable does not help.

[DanielSank]

The documentation is really confusing but mostly based on AA_documentaitonAD_v6.doc, my understanding now is that LED[0] on corresponds to unlatching of the "FPGA PLL" or "external 1 GHz PLL" (which seemed to be two different things), while LED[1] on corresponds to "bad clocking phase of the AD" converters, the later is somehow also referred to as "GHz PLL" and this is really, really confusing. I can't find the circuit diagram to check whether this makes sense from the hardware design viewpoint.

@jrainbo I think this is your time to shine. Can you verify what the McDermott group is saying here? Getting their discoveries into our documentation could be very helpful.

[maffoo]

@patzinak:

I can do a pull request on this but it appears your group tends to pack several bug fixes/enhancements in one major update branch.

Please do file a PR! If we gave the impression that we prefer multiple bug fixes and/or enhancements, we need to correct that. Generally, smaller changes are better, not least because they're easier to review.

[DanielSank]

I can do a pull request on this but it appears your group tends to pack several bug fixes/enhancements in one major update branch.

Seconding @maffoo. Small commits are much, much preferred.

[patzinak]

@maffoo and @DanielSank, per your request I have opened a PR that fixes the software bug. The rest of the original issue is mostly related to the documentation, so I thought it makes sense to rename it.

[gribeill]

@DanielSank, @maffoo, etc.. Have you guys had a chance to update the ADC documentation? We'd love to get our hands on the latest revision to make sure our code is correctly using the FPGA server.

[DanielSank]

I just emailed @jrainbo with a link to this issue. Hopefully he'll help us out.

[eriklucero]

The GHzADC documentation is not in the best state. Thanks for calling out all these areas where we need to improve it. I have updated the TWiki to include the GHzADC schematic (not sure why that wasn't up there to begin with) and the latest "AAdocumentationGHzAD_v7.doc". I have also zipped the two files and included them here.
GHzADCV7doc_schems.zip

Unfortunately, the current V.7 documentation does not clear up the function of LED[0] or LED[1]. I will have a look at the FPGA code and look at what the LED[0] and LED[1] are supposed to indicate in V.7 and report back with updated documentation.

[DanielSank]

@jrainbo Please note that we've moved on from AAdocumentation to our own nice markdown files.

[eriklucero]

Thank you. So much nicer.