mirror of
https://gitea.osmocom.org/cellular-infrastructure/osmo-trx.git
synced 2025-11-02 05:03:18 +00:00
Move inband-signaling-usb documentation to UserManual
Change-Id: I4d6ef1f54f3d6c5a73ce00dc4640bd698f96842b
This commit is contained in:
Pau Espin Pedrol
303
doc/manuals/chapters/device-usrp-inband-signaling-usb.adoc
Normal file
303
doc/manuals/chapters/device-usrp-inband-signaling-usb.adoc
Normal file
@@ -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 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
----
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user