git.gag.com Git - debian/gnuradio/blob - usrp2/doc/inband-signaling-eth

   1 #
   2 # Copyright 2007 Free Software Foundation, Inc.
   3 #
   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.
   8 #
   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.
  13 #
  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/>.
  16 #
  17
  18
  19 FIXME Needless to say, this is _very much_ a work in progress
  20
  21
  22
  23 This file specifies the format of ethernet packets used for in-band data
  24 transmission and signaling on the USRP2.
  25
  26 IN packets are sent towards the host.
  27 OUT packets are sent away from the host.
  28
  29 The layout is 32-bits wide.  All data is transmitted in BIG-endian
  30 format across the ethernet.
  31
  32
  33    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  34    |  Chan   |                     mbz                       |I|S|E|
  35    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  36    |                           Timestamp                           |
  37    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  38    |                                                               |
  39    +                                                               +
  40    |                            Payload                            |
  41    .                                                               .
  42    .                                                               .
  43    .                                                               .
  44    |                                                               |
  45    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  46
  47
  48
  49   mbz   Must be Zero: these bits must be zero in both IN and OUT packets.
  50
  51   I     Send Immediately. Set on Tx data that should be transmitted now.
  52         FIXME: change definition to honor 0xffffffff timestamp.
  53
  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.
  57
  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.
  62
  63
  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.
  73
  74   Timestamp: 32-bit timestamp.
  75
  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.
  80
  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".
  90
  91         The time base is a free running 32-bit counter that is
  92         incremented by the A/D sample-clock.
  93
  94   Payload: Variable length field.  Length is specified by the
  95         length of the containing ethernet frame.
  96
  97
  98 // FIXME need to revisit this stuff
  99
 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
 106         (USB) can support.
 107
 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.
 112
 113   D     Dropped Packet Flag: Set in an IN packet if the FPGA
 114         discarded an OUT packet because its timestamp had already
 115         passed.
 116
 117
 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.
 121
 122
 123   Tag   4-bit tag for matching IN packets with OUT packets.
 124         [FIXME, write more...]
 125
 126
 127
 128 "Data Channel" payload format:
 129 -------------------------------
 130
 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.
 136
 137
 138 "Control Channel" payload format:
 139 ---------------------------------
 140
 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.
 143
 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
 147 a 32-bit boundary.
 148
 149 Control channel packets shall be processed at the head of the queue,
 150 and shall observe the timestamp semantics described above.
 151
 152
 153 General sub-packet format:
 154 --------------------------
 155
 156    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
 157    |     Opcode    |    Length     |        <length bytes> ...    |
 158    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
 159
 160
 161 Specific sub-packet formats:
 162 ----------------------------
 163
 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.
 166
 167   Reg Number: 8-bit Register Number.
 168
 169
 170
 171 Identify:
 172
 173     Opcode:     OP_ID
 174
 175    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 176    |     Opcode    |       2       |       RID     |      mbz      |
 177    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 178
 179
 180 Identify Reply:
 181
 182     Opcode:     OP_ID_REPLY
 183
 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    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 195    |                                                               |
 196    +                                                               +
 197    |                                                               |
 198    +                         FPGA MD5SUM                           +
 199    |                                                               |
 200    +                                                               +
 201    |                                                               |
 202    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 203    |                                                               |
 204    +                                                               +
 205    |                                                               |
 206    +                          S/W MD5SUM                           +
 207    |                                                               |
 208    +                                                               +
 209    |                                                               |
 210    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 211
 212
 213 Write Register:
 214
 215     Opcode:     OP_WRITE_REG
 216
 217    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 218    |     Opcode    |       6       |      mbz      |   Reg Number  |
 219    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 220    |                        Register Value                         |
 221    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 222
 223
 224 Write Register Masked:
 225
 226     Opcode:     OP_WRITE_REG_MASKED
 227
 228     REG[Num] = (REG[Num] & ~Mask) | (Value & Mask)
 229
 230     That is, only the register bits that correspond to 1's in the
 231     mask are written with the new value.
 232
 233
 234    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 235    |     Opcode    |      10       |      mbz      |   Reg Number  |
 236    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 237    |                         Register Value                        |
 238    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 239    |                           Mask Value                          |
 240    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 241
 242
 243 Read Register:
 244
 245     Opcode:     OP_READ_REG
 246
 247    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 248    |     Opcode    |       2       |      RID      |   Reg Number  |
 249    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 250
 251
 252 Read Register Reply:
 253
 254     Opcode:     OP_READ_REG_REPLY
 255
 256    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 257    |     Opcode    |       6       |      RID      |   Reg Number  |
 258    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 259    |                        Register Value                         |
 260    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 261
 262
 263 // FIXME these may not be implemented...
 264
 265 I2C Write:
 266
 267     Opcode:     OP_I2C_WRITE
 268     I2C Addr:   7-bit I2C address
 269     Data:       The bytes to write to the I2C bus
 270     Length:     Length of Data + 2
 271
 272    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 273    |     Opcode    |    Length     |      RID      |    I2C Addr   |
 274    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 275    |    Data ...                                                   .
 276    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 277
 278
 279 I2C Write Reply:
 280
 281     Opcode:     OP_I2C_WRITE_REPLY
 282     Length:     2
 283
 284    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 285    |     Opcode    |       2       |      RID      |      OK       |
 286    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 287
 288
 289 OK is 1 if successful, else 0.
 290
 291
 292 I2C Read:
 293
 294     Opcode:     OP_I2C_READ
 295     I2C Addr:   7-bit I2C address
 296     Nbytes:     Number of bytes to read from I2C bus
 297
 298    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 299    |     Opcode    |       3       |      RID      |    I2C Addr   |
 300    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 301    |     Nbytes    |              unspecified padding              |
 302    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 303
 304
 305 I2C Read Reply:
 306
 307     Opcode:     OP_I2C_READ_REPLY
 308     I2C Addr:   7-bit I2C address
 309     Data:       Length - 2 bytes of data read from I2C bus.
 310
 311    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 312    |     Opcode    |     Length    |      RID      |      OK       |
 313    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 314    |    Data ...                                                   .
 315    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 316
 317 OK is 1 if successful, else 0
 318
 319
 320 SPI Write:
 321
 322     Opcode:           OP_SPI_WRITE
 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
 328
 329    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 330    |     Opcode    |     Length    |      RID      |      mbz      |
 331    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 332    |    Enables    |    Format     |        Opt Header Bytes       |
 333    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 334    |    Data ...                                                   .
 335    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 336
 337
 338 SPI Write Reply:
 339
 340     Opcode:     OP_SPI_WRITE_REPLY
 341     Length:     2
 342
 343    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 344    |     Opcode    |       2       |      RID      |      OK       |
 345    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 346
 347
 348 OK is 1 if successful, else 0.
 349
 350
 351 SPI Read:
 352
 353     Opcode:           OP_SPI_READ
 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.
 358
 359    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 360    |     Opcode    |       7       |      RID      |      mbz      |
 361    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 362    |    Enables    |    Format     |        Opt Header Bytes       |
 363    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 364    |     Nbytes    |              unspecified padding              |
 365    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 366
 367
 368 SPI Read Reply:
 369
 370     Opcode:   OP_SPI_READ_REPLY
 371     Data:     Length - 2 bytes of data read from SPI bus.
 372
 373    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 374    |     Opcode    |     Length    |    RID    |        mbz        |
 375    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 376    |    Data ...                                                   .
 377    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 378
 379
 380 Delay:
 381
 382     Opcode:     OP_DELAY
 383     Ticks:      16-bit unsigned delay count
 384
 385     Delay Ticks clock ticks before executing next operation.
 386
 387    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 388    |     Opcode    |       2       |            Ticks              |
 389    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 390