2 # Copyright 2007 Free Software Foundation, Inc.
4 # This program is free software: you can redistribute it and/or modify
5 # it under the terms of the GNU General Public License as published by
6 # the Free Software Foundation, either version 3 of the License, or
7 # (at your option) any later version.
9 # This program is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 # GNU General Public License for more details.
14 # You should have received a copy of the GNU General Public License
15 # along with this program. If not, see <http://www.gnu.org/licenses/>.
19 FIXME Needless to say, this is _very much_ a work in progress
23 This file specifies the format of ethernet packets used for in-band data
24 transmission and signaling on the USRP2.
26 IN packets are sent towards the host.
27 OUT packets are sent away from the host.
29 The layout is 32-bits wide. All data is transmitted in BIG-endian
30 format across the ethernet.
33 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
35 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
37 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
45 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
49 mbz Must be Zero: these bits must be zero in both IN and OUT packets.
51 I Send Immediately. Set on Tx data that should be transmitted now.
52 FIXME: change definition to honor 0xffffffff timestamp.
54 S Start of Burst Flag: Set in an OUT packet if the data is the
55 first segment of what is logically a continuous burst of data.
56 Must be zero in IN packets.
58 E End of Burst Flag: Set in an OUT packet if the data is the
59 last segment of what is logically a continuous burst of data.
60 Must be zero in IN packets. Underruns are not reported
61 when the FPGA runs out of samples between bursts.
64 Chan 5-bit logical channel number. Channel number 0x1f is reserved
65 for control information. See "Control Channel" below. Other
66 channels are "data channels." Each data channel is logically
67 independent of the others. A data channel payload field
68 contains a sequence of homogeneous samples. The format of the
69 samples is determined by the configuration associated with the
70 given channel. It is often the case that the payload field
71 contains 32-bit complex samples, each containing 16-bit real
72 and imaginary components.
74 Timestamp: 32-bit timestamp.
76 FIXME: update to reflect that the time is measured at the
77 time the samples inserted into or pulled out of the
78 DSP pipeline, not the A/D time. Using A/D time is problematic
79 because of group delay through filtering, etc.
81 On IN packets, the timestamp indicates the time at which the
82 first sample of the packet was produced by the A/D converter(s)
83 for that channel. On OUT packets, the timestamp specifies the
84 time at which the first sample in the packet should go out the
85 D/A converter(s) for that channel. If a packet reaches the
86 head of the transmit queue, and the current time is later than
87 the timestamp, an error is assumed to have occurred and the
88 packet is discarded. As a special case, the timestamp
89 0xffffffff is interpreted as "Now".
91 The time base is a free running 32-bit counter that is
92 incremented by the A/D sample-clock.
94 Payload: Variable length field. Length is specified by the
95 length of the containing ethernet frame.
98 // FIXME need to revisit this stuff
100 O Overrun Flag: set in an IN packet if an overrun condition was
101 detected. Must be zero in OUT packets. Overrun occurs when
102 the FPGA has data to transmit to the host and there is no
103 buffer space available. This generally indicates a problem on
104 the host. Either it is not keeping up, or it has configured
105 the FPGA to transmit data at a higher rate than the transport
108 U Underrun Flag: set in an IN packet if an underrun condition
109 was detected. Must be zero in OUT packets. Underrun occurs
110 when the FPGA runs out of samples, and it's not between
111 bursts. See the "End of Burst flag" below.
113 D Dropped Packet Flag: Set in an IN packet if the FPGA
114 discarded an OUT packet because its timestamp had already
118 RSSI 6-bit Received Strength Signal Indicator: Must be zero in OUT
119 packets. In IN packets, indicates RSSI as reported by front end.
120 FIXME The format and interpretation are to be determined.
123 Tag 4-bit tag for matching IN packets with OUT packets.
124 [FIXME, write more...]
128 "Data Channel" payload format:
129 -------------------------------
131 If Chan != 0x1f, the packet is a "data packet" and the payload is a
132 sequence of homogeneous samples. The format of the samples is
133 determined by the configuration associated with the given channel.
134 It is often the case that the payload field contains 32-bit complex
135 samples, each containing 16-bit real and imaginary components.
138 "Control Channel" payload format:
139 ---------------------------------
141 If Chan == 0x1f, the packet is a "control packet". The control channel
142 payload consists of a sequence of 0 or more sub-packets.
144 Each sub-packet starts on a 32-bit boundary, and consists of an 8-bit
145 Opcode field, an 8-bit Length field, Length bytes of arguments, and 0,
146 1, 2 or 3 bytes of padding to align the tail of the sub-packet to
149 Control channel packets shall be processed at the head of the queue,
150 and shall observe the timestamp semantics described above.
153 General sub-packet format:
154 --------------------------
156 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
157 | Opcode | Length | <length bytes> ... |
158 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
161 Specific sub-packet formats:
162 ----------------------------
164 RID: 8-bit Request-ID. Copied from request sub-packet into corresponding
165 reply sub-packet. RID allows the host to match requests and replies.
167 Reg Number: 8-bit Register Number.
175 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
176 | Opcode | 2 | RID | mbz |
177 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
184 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
185 | Opcode | 50 | RID | mbz |
186 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
187 | Mac Addr 0 | Mac Addr 1 | Mac Addr 2 | Mac Addr 3 |
188 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
189 | Mac Addr 4 | Mac Addr 5 | H/W rev major | H/W rev minor |
190 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
191 | Serial Num 0 | Serial Num 1 | Serial Num 2 | Serial Num 3 |
192 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
193 | Serial Num 4 | Serial Num 5 | Serial Num 6 | Serial Num 7 |
194 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
202 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
210 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
217 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
218 | Opcode | 6 | mbz | Reg Number |
219 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
221 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
224 Write Register Masked:
226 Opcode: OP_WRITE_REG_MASKED
228 REG[Num] = (REG[Num] & ~Mask) | (Value & Mask)
230 That is, only the register bits that correspond to 1's in the
231 mask are written with the new value.
234 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
235 | Opcode | 10 | mbz | Reg Number |
236 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
238 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
240 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
247 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
248 | Opcode | 2 | RID | Reg Number |
249 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
254 Opcode: OP_READ_REG_REPLY
256 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
257 | Opcode | 6 | RID | Reg Number |
258 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
260 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
263 // FIXME these may not be implemented...
268 I2C Addr: 7-bit I2C address
269 Data: The bytes to write to the I2C bus
270 Length: Length of Data + 2
272 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
273 | Opcode | Length | RID | I2C Addr |
274 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
276 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
281 Opcode: OP_I2C_WRITE_REPLY
284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
285 | Opcode | 2 | RID | OK |
286 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
289 OK is 1 if successful, else 0.
295 I2C Addr: 7-bit I2C address
296 Nbytes: Number of bytes to read from I2C bus
298 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
299 | Opcode | 3 | RID | I2C Addr |
300 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
301 | Nbytes | unspecified padding |
302 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
307 Opcode: OP_I2C_READ_REPLY
308 I2C Addr: 7-bit I2C address
309 Data: Length - 2 bytes of data read from I2C bus.
311 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
312 | Opcode | Length | RID | OK |
313 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
315 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
317 OK is 1 if successful, else 0
323 Enables: Which SPI enables to assert (mask)
324 Format: Specifies format of SPI data and Opt Header Bytes
325 Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format
326 Data: The bytes to write to the SPI bus
327 Length: Length of Data + 6
329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
330 | Opcode | Length | RID | mbz |
331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
332 | Enables | Format | Opt Header Bytes |
333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
335 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
340 Opcode: OP_SPI_WRITE_REPLY
343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
344 | Opcode | 2 | RID | OK |
345 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
348 OK is 1 if successful, else 0.
354 Enables: Which SPI enables to assert (mask)
355 Format: Specifies format of SPI data and Opt Header Bytes
356 Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format
357 Nbytes: Number of bytes to read from SPI bus.
359 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
360 | Opcode | 7 | RID | mbz |
361 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
362 | Enables | Format | Opt Header Bytes |
363 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
364 | Nbytes | unspecified padding |
365 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
370 Opcode: OP_SPI_READ_REPLY
371 Data: Length - 2 bytes of data read from SPI bus.
373 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
374 | Opcode | Length | RID | mbz |
375 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
377 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
383 Ticks: 16-bit unsigned delay count
385 Delay Ticks clock ticks before executing next operation.
387 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
388 | Opcode | 2 | Ticks |
389 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+