doc/fpga_arm_notes.md

   1 # Notes on ARM & FPGA comms
   2
   3
   4 https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/original_proxmark3/proxmark3.pdf
   5
   6 INTERFACE FROM THE ARM TO THE FPGA
   7 ==================================
   8
   9 The FPGA and the ARM can communicate in two main ways: using the ARM's
  10 general-purpose synchronous serial port (the SSP), or using the ARM's
  11 SPI port. The SPI port is used to configure the FPGA. The ARM writes a
  12 configuration word to the FPGA, which determines what operation will
  13 be performed (e.g. read 13.56 MHz vs. read 125 kHz vs. read 134 kHz
  14 vs...). The SPI is used exclusively for configuration.
  15
  16 The SSP is used for actual data sent over the air. The ARM's SSP can
  17 work in slave mode, which means that we can send the data using clocks
  18 generated by the FPGA (either from the PCK0 clock, which the ARM itself
  19 supplies, or from the 13.56 MHz clock, which is certainly not going to
  20 be synchronous to anything in the ARM), which saves synchronizing logic
  21 in the FPGA. The SSP is bi-directional and full-duplex.
  22
  23
  24 The FPGA communicates with the ARM through either
  25 1)  SPI port (the ARM is the master)
  26 2)  SSC synchronous serial port (the ARM is the master).
  27
  28
  29 opamps,     (*note, this affects source code in ARM, calculating actual voltage from antenna.  Manufacturers never report what they use to much frustration)
  30 comparators
  31 coil drivers
  32
  33 LF analog path (MCP6294 opamp. This has a GBW of 10 MHz),  all 'slow' signals.  Used for low frequency signals. Follows the peak detector. Signal centered around generated voltage Vmid.
  34
  35
  36 ## FPGA
  37 Since the SPARTAN II is a old outdated FPGA, thus is very limited resource there was a need to split LF and HF functionality into two separate FPGA images.  Which are stored in ARM flash memory as bitstreams.
  38
  39 We swap between these images by flashing fpga from ARM on the go.  It takes about 1sec.   Hence its usually a bad idea to program your device to continuously execute LF alt HF commands.
  40
  41 The FPGA images is precompiled and located inside the /fpga folder.
  42   - fpga_hf.bit
  43   - fpga_lf.bit
  44
  45 There is very rarely changes to the images so there is no need to setup a fpga tool chain to compile it yourself.
  46 Since the FPGA is very old,  the Xilinx WebPack ISE 10.1  is the last working tool chain.  You can download this legacy development on Xilinx and register for a free product installation id.
  47 Or use mine  `11LTAJ5ZJK3PXTUBMF0C0J6C4`    The package to download is about 7Gb and linux based.   Though I recently managed to install it on WSL for Windows 10.
  48
  49 In order to save space,  these fpga images are LZ4 compressed and included in the fullimage.elf file when compiling the ARM SRC.  `make armsrc`
  50 This means we save some precious space on the ARM but its a bit more complex when flashing to fpga since it has to decompress on the fly.
  51
  52
  53 ### FPGA modes.
  54  - Major modes
  55  - Minor modes
  56
  57 ## ARM FPGA communications.
  58
  59 The ARM talks with FPGA over the Synchronous Serial Port (SSC)  rx an tx.
  60
  61 ARM, send a 16bit configuration with fits the select major mode.
  62
  63
  64
  65 ## ARM GPIO setup
  66
  67 ```
  68     // First configure the GPIOs, and get ourselves a clock.
  69     AT91C_BASE_PIOA->PIO_ASR =
  70         GPIO_SSC_FRAME  |
  71         GPIO_SSC_DIN    |
  72         GPIO_SSC_DOUT   |
  73         GPIO_SSC_CLK;
  74     AT91C_BASE_PIOA->PIO_PDR = GPIO_SSC_DOUT;
  75
  76     AT91C_BASE_PMC->PMC_PCER = (1 << AT91C_ID_SSC);
  77
  78     // Now set up the SSC proper, starting from a known state.
  79     AT91C_BASE_SSC->SSC_CR = AT91C_SSC_SWRST;
  80
  81     // RX clock comes from TX clock, RX starts on Transmit Start,
  82     // data and frame signal is sampled on falling edge of RK
  83     AT91C_BASE_SSC->SSC_RCMR = SSC_CLOCK_MODE_SELECT(1) | SSC_CLOCK_MODE_START(1);
  84
  85     // 8, 16 or 32 bits per transfer, no loopback, MSB first, 1 transfer per sync
  86     // pulse, no output sync
  87     if ((FPGA_mode & FPGA_MAJOR_MODE_MASK) == FPGA_MAJOR_MODE_HF_READER && FpgaGetCurrent() == FPGA_BITSTREAM_HF) {
  88         AT91C_BASE_SSC->SSC_RFMR = SSC_FRAME_MODE_BITS_IN_WORD(16) | AT91C_SSC_MSBF | SSC_FRAME_MODE_WORDS_PER_TRANSFER(0);
  89     } else {
  90         AT91C_BASE_SSC->SSC_RFMR = SSC_FRAME_MODE_BITS_IN_WORD(8) | AT91C_SSC_MSBF | SSC_FRAME_MODE_WORDS_PER_TRANSFER(0);
  91     }
  92
  93     // TX clock comes from TK pin, no clock output, outputs change on rising edge of TK,
  94     // TF (frame sync) is sampled on falling edge of TK, start TX on rising edge of TF
  95     AT91C_BASE_SSC->SSC_TCMR = SSC_CLOCK_MODE_SELECT(2) | SSC_CLOCK_MODE_START(5);
  96
  97     // tx framing is the same as the rx framing
  98     AT91C_BASE_SSC->SSC_TFMR = AT91C_BASE_SSC->SSC_RFMR;
  99
 100 ```
 101
 102 ## FPGA Setup
 103
 104 // Set up DMA to receive samples from the FPGA. We will use the PDC, with
 105 // a single buffer as a circular buffer (so that we just chain back to
 106
 107
 108
 109 # HARDWARE OVERVIEW
 110
 111 ## ADC (ANALOG TO DIGITAL CONVERTER)
 112 The analogue signal that comes from the antenna circuit is fed into an 8-bit Analogue to Digital Converter
 113 (ADC). This delivers 8 output bits in parallel which represent the current voltage retrieved from the field.
 114
 115
 116 ## FIELD PROGRAMMABLE GATE ARRAY, FPGA
 117 The 8 output pins from the ADC are connected to 8 pins of the Field Programmable Gate Array (FPGA). An
 118 FPGA has a great advantage over a normal microcontroller in the sense that it emulates hardware. A
 119 hardware description can be compiled and flashed into an FPGA.
 120
 121 Because basic arithmetic functions can be performed fast and in parallel by an FPGA it is faster than an
 122 implementation on a normal microcontroller. Only a real hardware implementation would be faster but
 123 this lacks the flexibility of an FPGA.
 124
 125 The FPGA can therefore be seen as dynamic hardware. It is possible to make a hardware design and flash
 126 it into the memory of the FPGA. This gives some major advantages:
 127
 128
 129  - "Hardware" errors can be corrected; the FPGA can be flashed with a new hardware design.
 130  - Although not as fast as a real hardware implementation, an FPGA is faster than its equivalent on microprocessor. That is, it is specialized for one job.
 131
 132 The FPGA has two main tasks. The first task is to demodulate the signal received from the ADC and relay
 133 this as a digital encoded signal to the ARM. Depending on the task this might be the demodulation of a
 134 100% Amplitude Shift Keying (ASK) signal from the reader or the load modulation of a card. The encoding
 135 schemes used to communicate the signal to the ARM are Modified Miller for the reader and Manchester
 136 encoding for the card signal.
 137
 138 The second task is to modulate an encoded signal that is received from the ARM into the field of the
 139 antenna. This can be both the encoding of reader messages or card messages. For reader messages the
 140 FPGA generates an electromagnetic field on power hi and drops the amplitude for short periods.
 141
 142
 143 ## MICROCONTROLLER
 144 The microcontroller is responsible for the protocol management. It receives the digital encoded signals
 145 from the FPGA and decodes them. The decoded signals can just be copied to a buffer in the EEPROM
 146 memory. Additionally, an answer to the received message can be send by encoding a reply and
 147 communicating this to the FPGA.
 148
 149 The microcontroller (ARM) implements the transport layer. First it decodes the samples received from
 150 the FPGA. These samples are stored in a Direct Memory Access (DMA) buffer. The samples are binary
 151 sequences that represent whether the signal was high or low. The software on the ARM tries to decode
 152 these samples. When the Proxmark is in sniffing mode this is done for both the Manchester and Modified
 153 Miller at the same time. Whenever one of the decoding procedures returns a valid message, this message
 154 is stored in another buffer (BigBuf) and both decoding procedures are set to an un-synced state. The
 155 BigBuf is limited to the available memory on the ARM. The current firmware has 2 KB of memory
 156 reserved for traces (Besides the trace, the buffer also stores some temporary data that is needed in the
 157 processing). When the BigBuf buffer is full the function normally returns. A new function call from the
 158 client is needed to download the BigBuf contents to the computer. The BigBuf is especially useful for
 159 protocol investigation. Every single message is stored in this buffer. When a card is emulated or when the
 160 Proxmark is used as a reader the BigBuf can be used to store status messages or protocol exceptions.
 161
 162 ```
 163 HF PATH
 164  -- ANTENNA -> rectifying -> lowpass filter -> ADC -> FPGA -> ARM -> USB/CDC | FPC -> CLIENT
 165        |             |                          |      |
 166      induct     peak detect                   (8bit)   -- modes:
 167                 via circuit                                HF - peak-detected
 168                                                            HF - RAW
 169                                                            HF -
 170 ```
 171
 172
 173 ```
 174 LF PATH
 175
 176  -- ANTENNA -> rectifying -> lowpass filter -> ADC -> FPGA -> ARM -> USB/CDC | FPC -> CLIENT
 177        |             |                          |      |
 178      induct     peak detect                   (8bit)   -- modes:
 179                 via circuit                                LF - peak-detected
 180                                                            LF - RAW
 181 ```
 182 Problems:
 183  1.  dynamic range of signal.   Ie:  High Carrier signal (reader)  and low
 184
 185
 186 ##
 187
 188 ## To behave like a READER.
 189 By driving all of the buffers LOW, it is possible to make the antenna
 190 look to the receive path like a parallel LC circuit; this provides a
 191 high-voltage output signal. This is typically what will be done when we
 192 are not actively transmitting a carrier (i.e., behaving as a reader).
 193
 194 ## To behave like a TAG
 195 On the receive side, there are two possibilities, which are selected by
 196 RLY1. A mechanical relay is used, because the signal from the antenna is
 197 likely to be more positive or negative than the highest or lowest supply
 198 voltages on-board. In the usual case (PEAK-DETECTED mode), the received
 199 signal is peak-detected by an analog circuit, then filtered slightly,
 200 and then digitized by the ADC. This is the case for both the low- and
 201 high-frequency paths, although the details of the circuits for the
 202 two cases are somewhat different. This receive path would typically
 203 be selected when the device is behaving as a reader, or when it is
 204 eavesdropping at close range.
 205
 206 It is also possible to digitize the signal from the antenna directly (RAW
 207 mode), after passing it through a gain stage. This is more likely to be
 208 useful in reading signals at long range, but the available dynamic range
 209 will be poor, since it is limited by the 8-bit A/D.
 210
 211 In either case, an analog signal is digitized by the ADC, and
 212 from there goes in to the FPGA. The FPGA is big enough that it
 213 can perform DSP operations itself. For some high-frequency standards,
 214 the subcarriers are fast enough that it would be inconvenient to do all
 215 the math on a general-purpose CPU. The FPGA can therefore correlate for
 216 the desired signal itself, and simply report the total to the ARM. For
 217 low-frequency tags, it probably makes sense just to pass data straight
 218 through to the ARM.
 219
 220 The FPGA communicates with the ARM through either its SPI port (the ARM
 221 is the master) or its generic synchronous serial port (again, the ARM
 222 is the master). The ARM connects to the outside world over USB.
 223
 224 ## To sniff traffic
 225
 226
 227
 228 ##  FPGA purpose
 229 Digital signal processing.
 230 In short,  apply low pass / hi pass filtering,   peak detect,  correlate signal meaning IQ pair collecting.
 231
 232 IQ means measure at In-phase and 90 phase shift later Quadrature-phase,    with IQ samples you can plot the signal on a vector plan.
 233
 234
 235 ```
 236 IQ1 =   1,1 :  1, -1  (rising)
 237 IQ2 =  -1,1 :  1, 1   (falling)
 238
 239
 240
 241    -1,1      |         1,1
 242              |   (q2)
 243       (i2)   |    (i1)
 244              |
 245    ----------0------------>
 246              |
 247              |     (q1)
 248   -1,-1      |         1, -1
 249 ```