<p>fixeria has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmocom-bb/+/24017">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">trx_toolkit/data_msg.py: remove obsolete documentation<br><br>We do have TRXC/TRXD documentation in osmo-gsm-manuals repository.<br>These big comments are out of sync with what we have in the manuals,<br>so let's better remove them to avoid maintaining docs in several places.<br><br>Change-Id: I47786cf3039f712efadc85bc4e1c3ae89e79ff25<br>Related: OS#4006, SYS#4895<br>---<br>M src/target/trx_toolkit/data_msg.py<br>1 file changed, 3 insertions(+), 170 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmocom-bb refs/changes/17/24017/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/src/target/trx_toolkit/data_msg.py b/src/target/trx_toolkit/data_msg.py</span><br><span>index 1222e52..c62db35 100644</span><br><span>--- a/src/target/trx_toolkit/data_msg.py</span><br><span>+++ b/src/target/trx_toolkit/data_msg.py</span><br><span>@@ -60,67 +60,7 @@</span><br><span> return None</span><br><span> </span><br><span> class DATAMSG(abc.ABC):</span><br><span style="color: hsl(0, 100%, 40%);">- """ TRXD (DATA) message codec (common part).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- The DATA messages are used to carry bursts in both directions</span><br><span style="color: hsl(0, 100%, 40%);">- between L1 and TRX. There exist two kinds of them:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- - L12TRX (L1 -> TRX) - to be transmitted bursts,</span><br><span style="color: hsl(0, 100%, 40%);">- - TRX2L1 (TRX -> L1) - received bursts.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- Both of them have quite similar structure, and start with</span><br><span style="color: hsl(0, 100%, 40%);">- the common fixed-size message header (no TLVs):</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +---------------+-----------------+------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | common header | specific header | burst bits |</span><br><span style="color: hsl(0, 100%, 40%);">- +---------------+-----------------+------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- while the message specific headers and bit types are different.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- The common header is represented by this class, which is the</span><br><span style="color: hsl(0, 100%, 40%);">- parent of both DATAMSG_L12TRX and DATAMSG_TRX2L2 (see below),</span><br><span style="color: hsl(0, 100%, 40%);">- and has the following fields:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+----------------+-------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | VER (1/2 octet) | TN (1/2 octet) | FN (4 octets, BE) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+----------------+-------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- where:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- - VER is the header version indicator (1/2 octet MSB),</span><br><span style="color: hsl(0, 100%, 40%);">- - TN is TDMA time-slot number (1/2 octet LSB), and</span><br><span style="color: hsl(0, 100%, 40%);">- - FN is TDMA frame number (4 octets, big endian).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Header version indication</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- It may be necessary to extend the message specific header</span><br><span style="color: hsl(0, 100%, 40%);">- with more information. Since this is not a TLV-based</span><br><span style="color: hsl(0, 100%, 40%);">- protocol, we need to include the header format version.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | 7 6 5 4 3 2 1 0 | bit numbers |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | X X X X . . . . | header version (0..15) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . . . . . X X X | TDMA TN (0..7) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . . . . X . . . | RESERVED (0) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- Instead of prepending an additional byte, it was decided to use</span><br><span style="color: hsl(0, 100%, 40%);">- 4 MSB bits of the first octet, which used to be zero-initialized</span><br><span style="color: hsl(0, 100%, 40%);">- due to the value range of TDMA TN. Therefore, the legacy header</span><br><span style="color: hsl(0, 100%, 40%);">- format has implicit version 0x00.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- Otherwise Wireshark (or trx_sniff.py) would need to guess the</span><br><span style="color: hsl(0, 100%, 40%);">- header version, or alternatively follow the control channel</span><br><span style="color: hsl(0, 100%, 40%);">- looking for the version setting command.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- The reserved bit number 3 can be used in the future to extend</span><br><span style="color: hsl(0, 100%, 40%);">- the TDMA TN range to (0..15), in case anybody would need</span><br><span style="color: hsl(0, 100%, 40%);">- to transfer UMTS bursts.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- """</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' TRXD (DATA) message coding API (common part). '''</span><br><span> </span><br><span> # NOTE: up to 16 versions can be encoded</span><br><span> CHDR_VERSION_MAX = 0b1111</span><br><span>@@ -289,26 +229,7 @@</span><br><span> self.burst = None</span><br><span> </span><br><span> class DATAMSG_L12TRX(DATAMSG):</span><br><span style="color: hsl(0, 100%, 40%);">- """ L12TRX (L1 -> TRX) message codec.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- This message represents a Downlink burst on the BTS side,</span><br><span style="color: hsl(0, 100%, 40%);">- or an Uplink burst on the MS side, and has the following</span><br><span style="color: hsl(0, 100%, 40%);">- message specific fixed-size header preceding the burst bits:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Versions 0x00, 0x01</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +-----+--------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | PWR | hard-bits (1 or 0) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----+--------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- where PWR (1 octet) is relative (to the full-scale amplitude)</span><br><span style="color: hsl(0, 100%, 40%);">- transmit power level in dB. The absolute value is set on</span><br><span style="color: hsl(0, 100%, 40%);">- the control interface.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- Each hard-bit (1 or 0) of the burst is represented using one</span><br><span style="color: hsl(0, 100%, 40%);">- byte (0x01 or 0x00 respectively).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- """</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' L12TRX (L1 -> TRX) message coding API. '''</span><br><span> </span><br><span> # Constants</span><br><span> PWR_MIN = 0x00</span><br><span>@@ -435,95 +356,7 @@</span><br><span> return msg</span><br><span> </span><br><span> class DATAMSG_TRX2L1(DATAMSG):</span><br><span style="color: hsl(0, 100%, 40%);">- """ TRX2L1 (TRX -> L1) message codec.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- This message represents an Uplink burst on the BTS side,</span><br><span style="color: hsl(0, 100%, 40%);">- or a Downlink burst on the MS side, and has the following</span><br><span style="color: hsl(0, 100%, 40%);">- message specific fixed-size header preceding the burst bits:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Version 0x00</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +------+-----+--------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | RSSI | ToA | soft-bits (254..0) |</span><br><span style="color: hsl(0, 100%, 40%);">- +------+-----+--------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Version 0x01</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +------+-----+-----+-----+--------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | RSSI | ToA | MTS | C/I | soft-bits (254..0) |</span><br><span style="color: hsl(0, 100%, 40%);">- +------+-----+-----+-----+--------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- where:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- - RSSI (1 octet) - Received Signal Strength Indication</span><br><span style="color: hsl(0, 100%, 40%);">- encoded without the negative sign.</span><br><span style="color: hsl(0, 100%, 40%);">- - ToA (2 octets) - Timing of Arrival in units of 1/256</span><br><span style="color: hsl(0, 100%, 40%);">- of symbol (big endian).</span><br><span style="color: hsl(0, 100%, 40%);">- - MTS (1 octet) - Modulation and Training Sequence info.</span><br><span style="color: hsl(0, 100%, 40%);">- - C/I (2 octets) - Carrier-to-Interference ratio (big endian).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Coding of MTS: Modulation and Training Sequence info</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- 3GPP TS 45.002 version 15.1.0 defines several modulation types,</span><br><span style="color: hsl(0, 100%, 40%);">- and a few sets of training sequences for each type. The most</span><br><span style="color: hsl(0, 100%, 40%);">- common are GMSK and 8-PSK (which is used in EDGE).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | 7 6 5 4 3 2 1 0 | bit numbers (value range) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | X . . . . . . . | IDLE / nope frame indication (0 or 1) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . X X X X . . . | Modulation, TS set number (see below) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . . . . . X X X | Training Sequence Code (0..7) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- The bit number 7 (MSB) is set to high when either nothing has been</span><br><span style="color: hsl(0, 100%, 40%);">- detected, or during IDLE frames, so we can deliver noise levels,</span><br><span style="color: hsl(0, 100%, 40%);">- and avoid clock gaps on the L1 side. Other bits are ignored,</span><br><span style="color: hsl(0, 100%, 40%);">- and should be set to low (0) in this case.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Coding of modulation and TS set number</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- GMSK has 4 sets of training sequences (see tables 5.2.3a-d),</span><br><span style="color: hsl(0, 100%, 40%);">- while 8-PSK (see tables 5.2.3f-g) and the others have 2 sets.</span><br><span style="color: hsl(0, 100%, 40%);">- Access and Synchronization bursts also have several synch.</span><br><span style="color: hsl(0, 100%, 40%);">- sequences.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | 7 6 5 4 3 2 1 0 | bit numbers (value range) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . 0 0 X X . . . | GMSK, 4 TS sets (0..3) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . 0 1 0 X . . . | 8-PSK, 2 TS sets (0..1) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . 0 1 1 X . . . | AQPSK, 2 TS sets (0..1) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . 1 0 0 X . . . | 16QAM, 2 TS sets (0..1) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . 1 0 1 X . . . | 32QAM, 2 TS sets (0..1) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">- | . 1 1 1 X . . . | RESERVED (0) |</span><br><span style="color: hsl(0, 100%, 40%);">- +-----------------+---------------------------------------+</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == C/I: Carrier-to-Interference ratio</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- The C/I value can be computed from the training sequence of each</span><br><span style="color: hsl(0, 100%, 40%);">- burst, where we can compare the "ideal" training sequence with</span><br><span style="color: hsl(0, 100%, 40%);">- the actual training sequence and then express that in centiBels.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- == Coding of the burst bits</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- Unlike the transmitted bursts, the received bursts are designated</span><br><span style="color: hsl(0, 100%, 40%);">- using the soft-bits notation, so the receiver can indicate its</span><br><span style="color: hsl(0, 100%, 40%);">- assurance from 0 to -127 that a given bit is 1, and from 0 to +127</span><br><span style="color: hsl(0, 100%, 40%);">- that a given bit is 0. The Viterbi algorithm allows to approximate</span><br><span style="color: hsl(0, 100%, 40%);">- the original sequence of hard-bits (1 or 0) using these values.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- Each soft-bit (-127..127) of the burst is encoded as an unsigned</span><br><span style="color: hsl(0, 100%, 40%);">- value in range (0..255) respectively using the constant shift.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- """</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' TRX2L1 (TRX -> L1) message coding API. '''</span><br><span> </span><br><span> # rxlev2dbm(0..63) gives us [-110..-47], plus -10 dbm for noise</span><br><span> RSSI_MIN = -120</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmocom-bb/+/24017">change 24017</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmocom-bb/+/24017"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmocom-bb </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I47786cf3039f712efadc85bc4e1c3ae89e79ff25 </div>
<div style="display:none"> Gerrit-Change-Number: 24017 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: fixeria <vyanitskiy@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>