git.gag.com Git - debian/gnuradio/blob - usrp/doc/inband-signaling-usb

   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