dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame^] | 1 | This file specifies the format of USB packets used for in-band data |
| 2 | transmission and signaling on the USRP. All packets are 512-byte long, |
| 3 | and are transfered using USB "bulk" transfers. |
| 4 | |
| 5 | IN packets are sent towards the host. |
| 6 | OUT packets are sent away from the host. |
| 7 | |
| 8 | The layout is 32-bits wide. All data is transmitted in little-endian |
| 9 | format across the USB. |
| 10 | |
| 11 | |
| 12 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 13 | |O|U|D|S|E| RSSI | Chan | mbz | Tag | Payload Len | |
| 14 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 15 | | Timestamp | |
| 16 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 17 | | | |
| 18 | + + |
| 19 | | Payload | |
| 20 | . . |
| 21 | . . |
| 22 | . . |
| 23 | | | |
| 24 | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 25 | | ... | . |
| 26 | +-+-+-+-+-+-+-+ . |
| 27 | . . |
| 28 | . Padding . |
| 29 | . . |
| 30 | | | |
| 31 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 32 | |
| 33 | |
| 34 | mbz Must be Zero: these bits must be zero in both IN and OUT packets. |
| 35 | |
| 36 | O Overrun Flag: set in an IN packet if an overrun condition was |
| 37 | detected. Must be zero in OUT packets. Overrun occurs when |
| 38 | the FPGA has data to transmit to the host and there is no |
| 39 | buffer space available. This generally indicates a problem on |
| 40 | the host. Either it is not keeping up, or it has configured |
| 41 | the FPGA to transmit data at a higher rate than the transport |
| 42 | (USB) can support. |
| 43 | |
| 44 | U Underrun Flag: set in an IN packet if an underrun condition |
| 45 | was detected. Must be zero in OUT packets. Underrun occurs |
| 46 | when the FPGA runs out of samples, and it's not between |
| 47 | bursts. See the "End of Burst flag" below. |
| 48 | |
| 49 | D Dropped Packet Flag: Set in an IN packet if the FPGA |
| 50 | discarded an OUT packet because its timestamp had already |
| 51 | passed. |
| 52 | |
| 53 | S Start of Burst Flag: Set in an OUT packet if the data is the |
| 54 | first segment of what is logically a continuous burst of data. |
| 55 | Must be zero in IN packets. |
| 56 | |
| 57 | E End of Burst Flag: Set in an OUT packet if the data is the |
| 58 | last segment of what is logically a continuous burst of data. |
| 59 | Must be zero in IN packets. Underruns are not reported |
| 60 | when the FPGA runs out of samples between bursts. |
| 61 | |
| 62 | |
| 63 | RSSI 6-bit Received Strength Signal Indicator: Must be zero in OUT |
| 64 | packets. In IN packets, indicates RSSI as reported by front end. |
| 65 | FIXME The format and interpretation are to be determined. |
| 66 | |
| 67 | Chan 5-bit logical channel number. Channel number 0x1f is reserved |
| 68 | for control information. See "Control Channel" below. Other |
| 69 | channels are "data channels." Each data channel is logically |
| 70 | independent of the others. A data channel payload field |
| 71 | contains a sequence of homogeneous samples. The format of the |
| 72 | samples is determined by the configuration associated with the |
| 73 | given channel. It is often the case that the payload field |
| 74 | contains 32-bit complex samples, each containing 16-bit real |
| 75 | and imaginary components. |
| 76 | |
| 77 | Tag 4-bit tag for matching IN packets with OUT packets. |
| 78 | [FIXME, write more...] |
| 79 | |
| 80 | Payload Len: 9-bit field that specifies the length of the payload |
| 81 | field in bytes. Must be in the range 0 to 504 inclusive. |
| 82 | |
| 83 | Timestamp: 32-bit timestamp. |
| 84 | On IN packets, the timestamp indicates the time at which the |
| 85 | first sample of the packet was produced by the A/D converter(s) |
| 86 | for that channel. On OUT packets, the timestamp specifies the |
| 87 | time at which the first sample in the packet should go out the |
| 88 | D/A converter(s) for that channel. If a packet reaches the |
| 89 | head of the transmit queue, and the current time is later than |
| 90 | the timestamp, an error is assumed to have occurred and the |
| 91 | packet is discarded. As a special case, the timestamp |
| 92 | 0xffffffff is interpreted as "Now". |
| 93 | |
| 94 | The time base is a free running 32-bit counter that is |
| 95 | incremented by the A/D sample-clock. |
| 96 | |
| 97 | Payload: Variable length field. Length is specified by the |
| 98 | Payload Len field. |
| 99 | |
| 100 | Padding: This field is 504 - Payload Len bytes long, and its content |
| 101 | is unspecified. This field pads the packet out to a constant |
| 102 | 512 bytes. |
| 103 | |
| 104 | |
| 105 | |
| 106 | "Data Channel" payload format: |
| 107 | ------------------------------- |
| 108 | |
| 109 | If Chan != 0x1f, the packet is a "data packet" and the payload is a |
| 110 | sequence of homogeneous samples. The format of the samples is |
| 111 | determined by the configuration associated with the given channel. |
| 112 | It is often the case that the payload field contains 32-bit complex |
| 113 | samples, each containing 16-bit real and imaginary components. |
| 114 | |
| 115 | |
| 116 | "Control Channel" payload format: |
| 117 | --------------------------------- |
| 118 | |
| 119 | If Chan == 0x1f, the packet is a "control packet". The control channel |
| 120 | payload consists of a sequence of 0 or more sub-packets. |
| 121 | |
| 122 | Each sub-packet starts on a 32-bit boundary, and consists of an 8-bit |
| 123 | Opcode field, an 8-bit Length field, Length bytes of arguments, and 0, |
| 124 | 1, 2 or 3 bytes of padding to align the tail of the sub-packet to |
| 125 | a 32-bit boundary. |
| 126 | |
| 127 | Control channel packets shall be processed at the head of the queue, |
| 128 | and shall observe the timestamp semantics described above. |
| 129 | |
| 130 | |
| 131 | General sub-packet format: |
| 132 | -------------------------- |
| 133 | |
| 134 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+ |
| 135 | | Opcode | Length | <length bytes> ... | |
| 136 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+ |
| 137 | |
| 138 | |
| 139 | Specific sub-packet formats: |
| 140 | ---------------------------- |
| 141 | |
| 142 | RID: 6-bit Request-ID. Copied from request sub-packet into corresponding |
| 143 | reply sub-packet. RID allows the host to match requests and replies. |
| 144 | |
| 145 | Reg Number: 10-bit Register Number. |
| 146 | |
| 147 | |
| 148 | |
| 149 | Ping Fixed Length: |
| 150 | |
| 151 | Opcode: OP_PING_FIXED |
| 152 | |
| 153 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 154 | | Opcode | 2 | RID | Ping Value | |
| 155 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 156 | |
| 157 | |
| 158 | Ping Fixed Length Reply: |
| 159 | |
| 160 | Opcode: OP_PING_FIXED_REPLY |
| 161 | |
| 162 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 163 | | Opcode | 2 | RID | Ping Value | |
| 164 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 165 | |
| 166 | |
| 167 | Write Register: |
| 168 | |
| 169 | Opcode: OP_WRITE_REG |
| 170 | |
| 171 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 172 | | Opcode | 6 | mbz | Reg Number | |
| 173 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 174 | | Register Value | |
| 175 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 176 | |
| 177 | |
| 178 | Write Register Masked: |
| 179 | |
| 180 | Opcode: OP_WRITE_REG_MASKED |
| 181 | |
| 182 | REG[Num] = (REG[Num] & ~Mask) | (Value & Mask) |
| 183 | |
| 184 | That is, only the register bits that correspond to 1's in the |
| 185 | mask are written with the new value. |
| 186 | |
| 187 | |
| 188 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 189 | | Opcode | 10 | mbz | Reg Number | |
| 190 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 191 | | Register Value | |
| 192 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 193 | | Mask Value | |
| 194 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 195 | |
| 196 | |
| 197 | Read Register: |
| 198 | |
| 199 | Opcode: OP_READ_REG |
| 200 | |
| 201 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 202 | | Opcode | 2 | RID | Reg Number | |
| 203 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 204 | |
| 205 | |
| 206 | Read Register Reply: |
| 207 | |
| 208 | Opcode: OP_READ_REG_REPLY |
| 209 | |
| 210 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 211 | | Opcode | 6 | RID | Reg Number | |
| 212 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 213 | | Register Value | |
| 214 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 215 | |
| 216 | |
| 217 | I2C Write: |
| 218 | |
| 219 | Opcode: OP_I2C_WRITE |
| 220 | I2C Addr: 7-bit I2C address |
| 221 | Data: The bytes to write to the I2C bus |
| 222 | Length: Length of Data + 2 |
| 223 | |
| 224 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 225 | | Opcode | Length | mbz | I2C Addr | |
| 226 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 227 | | Data ... . |
| 228 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 229 | |
| 230 | |
| 231 | I2C Read: |
| 232 | |
| 233 | Opcode: OP_I2C_READ |
| 234 | I2C Addr: 7-bit I2C address |
| 235 | Nbytes: Number of bytes to read from I2C bus |
| 236 | |
| 237 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 238 | | Opcode | 3 | RID | mbz | I2C Addr | |
| 239 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 240 | | Nbytes | unspecified padding | |
| 241 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 242 | |
| 243 | |
| 244 | I2C Read Reply: |
| 245 | |
| 246 | Opcode: OP_I2C_READ_REPLY |
| 247 | I2C Addr: 7-bit I2C address |
| 248 | Data: Length - 2 bytes of data read from I2C bus. |
| 249 | |
| 250 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 251 | | Opcode | Length | RID | mbz | I2C Addr | |
| 252 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 253 | | Data ... . |
| 254 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 255 | |
| 256 | |
| 257 | SPI Write: |
| 258 | |
| 259 | Opcode: OP_SPI_WRITE |
| 260 | Enables: Which SPI enables to assert (mask) |
| 261 | Format: Specifies format of SPI data and Opt Header Bytes |
| 262 | Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format |
| 263 | Data: The bytes to write to the SPI bus |
| 264 | Length: Length of Data + 6 |
| 265 | |
| 266 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 267 | | Opcode | Length | mbz | |
| 268 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 269 | | Enables | Format | Opt Header Bytes | |
| 270 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 271 | | Data ... . |
| 272 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 273 | |
| 274 | |
| 275 | SPI Read: |
| 276 | |
| 277 | Opcode: OP_SPI_READ |
| 278 | Enables: Which SPI enables to assert (mask) |
| 279 | Format: Specifies format of SPI data and Opt Header Bytes |
| 280 | Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format |
| 281 | Nbytes: Number of bytes to read from SPI bus. |
| 282 | |
| 283 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 284 | | Opcode | 7 | RID | mbz | |
| 285 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 286 | | Enables | Format | Opt Header Bytes | |
| 287 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 288 | | Nbytes | unspecified padding | |
| 289 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 290 | |
| 291 | |
| 292 | SPI Read Reply: |
| 293 | |
| 294 | Opcode: OP_SPI_READ_REPLY |
| 295 | Data: Length - 2 bytes of data read from SPI bus. |
| 296 | |
| 297 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 298 | | Opcode | Length | RID | mbz | |
| 299 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 300 | | Data ... . |
| 301 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 302 | |
| 303 | |
| 304 | Delay: |
| 305 | |
| 306 | Opcode: OP_DELAY |
| 307 | Ticks: 16-bit unsigned delay count |
| 308 | |
| 309 | Delay Ticks clock ticks before executing next operation. |
| 310 | |
| 311 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 312 | | Opcode | 2 | Ticks | |
| 313 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 314 | |