diff options
author | Pau Espin Pedrol <pespin@sysmocom.de> | 2019-07-30 17:37:37 +0200 |
---|---|---|
committer | Pau Espin Pedrol <pespin@sysmocom.de> | 2019-08-01 13:46:00 +0200 |
commit | 7758542087239cff32a32d94f204fa6e7a1483b2 (patch) | |
tree | e8c3f9553086cbbaf9d08d6e02e0f282f80a5945 /doc | |
parent | 68a78099a06ac6ad3d4ebc8fc6c6a7c357e183dd (diff) |
Move inband-signaling-usb documentation to UserManual
Change-Id: I4d6ef1f54f3d6c5a73ce00dc4640bd698f96842b
Diffstat (limited to 'doc')
-rw-r--r-- | doc/manuals/chapters/device-usrp-inband-signaling-usb.adoc | 303 | ||||
-rw-r--r-- | doc/manuals/chapters/trx-devices.adoc | 2 |
2 files changed, 305 insertions, 0 deletions
diff --git a/doc/manuals/chapters/device-usrp-inband-signaling-usb.adoc b/doc/manuals/chapters/device-usrp-inband-signaling-usb.adoc new file mode 100644 index 0000000..dac77e0 --- /dev/null +++ b/doc/manuals/chapters/device-usrp-inband-signaling-usb.adoc @@ -0,0 +1,303 @@ +[[dev_USRP1_inband_signaling_usb]] +==== USRP1 in-band USB protocol + +This section specifies the format of USB packets used for in-band data +transmission and signaling on the USRP1. 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 | <length bytes> ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+ +---- + +===== 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:: +Only the register bits that correspond to 1's in the mask are written +with the new value. `REG[Num] = (REG[Num] & ~Mask) | (Value & Mask)` + +* Opcode: OP_WRITE_REG_MASKED +---- ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| 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 | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +---- diff --git a/doc/manuals/chapters/trx-devices.adoc b/doc/manuals/chapters/trx-devices.adoc index 10c8529..3c21e59 100644 --- a/doc/manuals/chapters/trx-devices.adoc +++ b/doc/manuals/chapters/trx-devices.adoc @@ -29,6 +29,8 @@ flags, which can be found in each subsection relative to each backend below. The binary _osmo-trx-usrp1_ is used to drive this device, see <<backend_usrp1>>. +include::./device-usrp-inband-signaling-usb.adoc[] + [[dev_ettus_b200]] === Ettus B200 |