X-Git-Url: https://git.gag.com/?p=debian%2Fgnuradio;a=blobdiff_plain;f=usrp%2Fdoc%2Finband-signaling-usb;fp=usrp%2Fdoc%2Finband-signaling-usb;h=14f83479a69f5020ea6b589a21ccf2bc6873fe32;hp=0000000000000000000000000000000000000000;hb=8a9ddbb0675f9bfcc6e03b457fba6c79474a3693;hpb=82d471b9b4a8b389b5da44b19c69c36420828382 diff --git a/usrp/doc/inband-signaling-usb b/usrp/doc/inband-signaling-usb new file mode 100644 index 00000000..14f83479 --- /dev/null +++ b/usrp/doc/inband-signaling-usb @@ -0,0 +1,314 @@ +This file specifies the format of USB packets used for in-band data +transmission and signaling on the USRP. All packets are 512-byte long, +and are transfered using USB "bulk" transfers. + +IN packets are sent towards the host. +OUT packets are sent away from the host. + +The layout is 32-bits wide. All data is transmitted in little-endian +format across the USB. + + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |O|U|D|S|E| RSSI | Chan | mbz | Tag | Payload Len | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Timestamp | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + + + | Payload | + . . + . . + . . + | | + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ... | . + +-+-+-+-+-+-+-+ . + . . + . Padding . + . . + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + + mbz Must be Zero: these bits must be zero in both IN and OUT packets. + + O Overrun Flag: set in an IN packet if an overrun condition was + detected. Must be zero in OUT packets. Overrun occurs when + the FPGA has data to transmit to the host and there is no + buffer space available. This generally indicates a problem on + the host. Either it is not keeping up, or it has configured + the FPGA to transmit data at a higher rate than the transport + (USB) can support. + + U Underrun Flag: set in an IN packet if an underrun condition + was detected. Must be zero in OUT packets. Underrun occurs + when the FPGA runs out of samples, and it's not between + bursts. See the "End of Burst flag" below. + + D Dropped Packet Flag: Set in an IN packet if the FPGA + discarded an OUT packet because its timestamp had already + passed. + + S Start of Burst Flag: Set in an OUT packet if the data is the + first segment of what is logically a continuous burst of data. + Must be zero in IN packets. + + E End of Burst Flag: Set in an OUT packet if the data is the + last segment of what is logically a continuous burst of data. + Must be zero in IN packets. Underruns are not reported + when the FPGA runs out of samples between bursts. + + + RSSI 6-bit Received Strength Signal Indicator: Must be zero in OUT + packets. In IN packets, indicates RSSI as reported by front end. + FIXME The format and interpretation are to be determined. + + Chan 5-bit logical channel number. Channel number 0x1f is reserved + for control information. See "Control Channel" below. Other + channels are "data channels." Each data channel is logically + independent of the others. A data channel payload field + contains a sequence of homogeneous samples. The format of the + samples is determined by the configuration associated with the + given channel. It is often the case that the payload field + contains 32-bit complex samples, each containing 16-bit real + and imaginary components. + + Tag 4-bit tag for matching IN packets with OUT packets. + [FIXME, write more...] + + Payload Len: 9-bit field that specifies the length of the payload + field in bytes. Must be in the range 0 to 504 inclusive. + + Timestamp: 32-bit timestamp. + On IN packets, the timestamp indicates the time at which the + first sample of the packet was produced by the A/D converter(s) + for that channel. On OUT packets, the timestamp specifies the + time at which the first sample in the packet should go out the + D/A converter(s) for that channel. If a packet reaches the + head of the transmit queue, and the current time is later than + the timestamp, an error is assumed to have occurred and the + packet is discarded. As a special case, the timestamp + 0xffffffff is interpreted as "Now". + + The time base is a free running 32-bit counter that is + incremented by the A/D sample-clock. + + Payload: Variable length field. Length is specified by the + Payload Len field. + + Padding: This field is 504 - Payload Len bytes long, and its content + is unspecified. This field pads the packet out to a constant + 512 bytes. + + + +"Data Channel" payload format: +------------------------------- + +If Chan != 0x1f, the packet is a "data packet" and the payload is a +sequence of homogeneous samples. The format of the samples is +determined by the configuration associated with the given channel. +It is often the case that the payload field contains 32-bit complex +samples, each containing 16-bit real and imaginary components. + + +"Control Channel" payload format: +--------------------------------- + +If Chan == 0x1f, the packet is a "control packet". The control channel +payload consists of a sequence of 0 or more sub-packets. + +Each sub-packet starts on a 32-bit boundary, and consists of an 8-bit +Opcode field, an 8-bit Length field, Length bytes of arguments, and 0, +1, 2 or 3 bytes of padding to align the tail of the sub-packet to +a 32-bit boundary. + +Control channel packets shall be processed at the head of the queue, +and shall observe the timestamp semantics described above. + + +General sub-packet format: +-------------------------- + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+ + | Opcode | Length | ... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+ + + +Specific sub-packet formats: +---------------------------- + + RID: 6-bit Request-ID. Copied from request sub-packet into corresponding + reply sub-packet. RID allows the host to match requests and replies. + + Reg Number: 10-bit Register Number. + + + +Ping Fixed Length: + + Opcode: OP_PING_FIXED + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 2 | RID | Ping Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Ping Fixed Length Reply: + + Opcode: OP_PING_FIXED_REPLY + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 2 | RID | Ping Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Write Register: + + Opcode: OP_WRITE_REG + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 6 | mbz | Reg Number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Register Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Write Register Masked: + + Opcode: OP_WRITE_REG_MASKED + + REG[Num] = (REG[Num] & ~Mask) | (Value & Mask) + + That is, only the register bits that correspond to 1's in the + mask are written with the new value. + + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 10 | mbz | Reg Number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Register Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Mask Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Read Register: + + Opcode: OP_READ_REG + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 2 | RID | Reg Number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Read Register Reply: + + Opcode: OP_READ_REG_REPLY + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 6 | RID | Reg Number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Register Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +I2C Write: + + Opcode: OP_I2C_WRITE + I2C Addr: 7-bit I2C address + Data: The bytes to write to the I2C bus + Length: Length of Data + 2 + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | Length | mbz | I2C Addr | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Data ... . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +I2C Read: + + Opcode: OP_I2C_READ + I2C Addr: 7-bit I2C address + Nbytes: Number of bytes to read from I2C bus + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 3 | RID | mbz | I2C Addr | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Nbytes | unspecified padding | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +I2C Read Reply: + + Opcode: OP_I2C_READ_REPLY + I2C Addr: 7-bit I2C address + Data: Length - 2 bytes of data read from I2C bus. + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | Length | RID | mbz | I2C Addr | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Data ... . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +SPI Write: + + Opcode: OP_SPI_WRITE + Enables: Which SPI enables to assert (mask) + Format: Specifies format of SPI data and Opt Header Bytes + Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format + Data: The bytes to write to the SPI bus + Length: Length of Data + 6 + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | Length | mbz | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Enables | Format | Opt Header Bytes | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Data ... . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +SPI Read: + + Opcode: OP_SPI_READ + Enables: Which SPI enables to assert (mask) + Format: Specifies format of SPI data and Opt Header Bytes + Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format + Nbytes: Number of bytes to read from SPI bus. + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 7 | RID | mbz | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Enables | Format | Opt Header Bytes | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Nbytes | unspecified padding | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +SPI Read Reply: + + Opcode: OP_SPI_READ_REPLY + Data: Length - 2 bytes of data read from SPI bus. + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | Length | RID | mbz | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Data ... . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Delay: + + Opcode: OP_DELAY + Ticks: 16-bit unsigned delay count + + Delay Ticks clock ticks before executing next operation. + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Opcode | 2 | Ticks | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +