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   Payload: Variable length field.  Length is specified by the
  95         Payload Len field.
  96
  97   Padding: This field is 504 - Payload Len bytes long, and its content
  98         is unspecified.  This field pads the packet out to a constant
  99         512 bytes.
 100
 101
 102
 103
 104 "Control Channel" payload format:
 105 ---------------------------------
 106
 107 The control channel payload consists of a sequence of 0 or more
 108 sub-packets.
 109
 110 Each sub-packet starts on a 32-bit boundary, and consists of an 8-bit
 111 Opcode field, an 8-bit Length field, Length bytes of arguments, and 0,
 112 1, 2 or 3 bytes of padding to align the tail of the sub-packet to
 113 a 32-bit boundary.
 114
 115 Control channel packets shall be processed at the head of the queue,
 116 and shall observe the timestamp semantics described above.
 117
 118
 119 General sub-packet format:
 120 --------------------------
 121
 122    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
 123    |     Opcode    |    Length     |        <length bytes> ...    |
 124    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
 125
 126
 127 Specific sub-packet formats:
 128 ----------------------------
 129
 130   RID: 6-bit Request-ID. Copied from request sub-packet into corresponding
 131        reply sub-packet.  RID allows the host to match requests and replies.
 132
 133   Reg Number: 10-bit Register Number.
 134
 135
 136
 137 Ping Fixed Length:
 138
 139     Opcode:     OP_PING_FIXED
 140
 141    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 142    |     Opcode    |       2       |    RID    |     Ping Value    |
 143    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 144
 145
 146 Ping Fixed Length Reply:
 147
 148     Opcode:     OP_PING_FIXED_REPLY
 149
 150    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 151    |     Opcode    |       2       |    RID    |     Ping Value    |
 152    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 153
 154
 155 Write Register:
 156
 157     Opcode:     OP_WRITE_REG
 158
 159    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 160    |     Opcode    |       6       |    mbz    |     Reg Number    |
 161    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 162    |                        Register Value                         |
 163    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 164
 165
 166 Read Register:
 167
 168     Opcode:     OP_READ_REG
 169
 170    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 171    |     Opcode    |       2       |    RID    |     Reg Number    |
 172    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 173
 174
 175 Read Register Reply:
 176
 177     Opcode:     OP_READ_REG_REPLY
 178
 179    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 180    |     Opcode    |       6       |    RID    |     Reg Number    |
 181    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 182    |                        Register Value                         |
 183    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 184
 185
 186 I2C Write:
 187
 188     Opcode:     OP_I2C_WRITE
 189     I2C Addr:   7-bit I2C address
 190     Data:       The bytes to write to the I2C bus
 191     Length:     Length of Data + 2
 192
 193    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 194    |     Opcode    |    Length     |       mbz       |   I2C Addr  |
 195    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 196    |    Data ...                                                   .
 197    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 198
 199
 200 I2C Read:
 201
 202     Opcode:     OP_I2C_READ
 203     I2C Addr:   7-bit I2C address
 204     Nbytes:     Number of bytes to read from I2C bus
 205
 206    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 207    |     Opcode    |       3       |    RID    | mbz |   I2C Addr  |
 208    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 209    |     Nbytes    |              unspecified padding              |
 210    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 211
 212
 213 I2C Read Reply:
 214
 215     Opcode:     OP_I2C_READ_REPLY
 216     I2C Addr:   7-bit I2C address
 217     Data:       Length - 2 bytes of data read from I2C bus.
 218
 219    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 220    |     Opcode    |     Length    |    RID    | mbz |   I2C Addr  |
 221    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 222    |    Data ...                                                   .
 223    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 224
 225
 226 SPI Write:
 227
 228     Opcode:           OP_SPI_WRITE
 229     Enables:          Which SPI enables to assert (mask)
 230     Format:           Specifies format of SPI data and Opt Header Bytes
 231     Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format
 232     Data:             The bytes to write to the I2C bus
 233     Length:           Length of Data + 6
 234
 235    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 236    |     Opcode    |    Length     |              mbz              |
 237    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 238    |    Enables    |    Format     |        Opt Header Bytes       |
 239    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 240    |    Data ...                                                   .
 241    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 242
 243
 244 SPI Read:
 245
 246     Opcode:           OP_SPI_READ
 247     Enables:          Which SPI enables to assert (mask)
 248     Format:           Specifies format of SPI data and Opt Header Bytes
 249     Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format
 250     Nbytes:           Number of bytes to read from SPI bus.
 251
 252    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 253    |     Opcode    |       7       |    RID    |        mbz        |
 254    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 255    |    Enables    |    Format     |        Opt Header Bytes       |
 256    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 257    |     Nbytes    |              unspecified padding              |
 258    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 259
 260
 261 SPI Read Reply:
 262
 263     Opcode:   OP_SPI_READ_REPLY
 264     Data:     Length - 2 bytes of data read from SPI bus.
 265
 266    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 267    |     Opcode    |     Length    |    RID    |        mbz        |
 268    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 269    |    Data ...                                                   .
 270    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 271
 272
 273 Delay:
 274
 275     Opcode:     OP_DELAY
 276     Ticks:      16-bit unsigned delay count
 277
 278     Delay Ticks clock ticks before executing next operation.
 279
 280    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 281    |     Opcode    |       2       |            Ticks              |
 282    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 283