<p>pespin has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14938">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">common: trx_if.adoc: Improve documentation<br><br>Several fixes and improvements to the documentation.<br>This documentation still doesn't contain infrmation about TRXDv1, it<br>will be added in a follow-up commit.<br><br>Change-Id: I36e6206b90435964842f9f1ebd982cdaf9777018<br>---<br>M common/chapters/trx_if.adoc<br>1 file changed, 85 insertions(+), 43 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/38/14938/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/common/chapters/trx_if.adoc b/common/chapters/trx_if.adoc</span><br><span>index b684b7b..f55c886 100644</span><br><span>--- a/common/chapters/trx_if.adoc</span><br><span>+++ b/common/chapters/trx_if.adoc</span><br><span>@@ -1,44 +1,53 @@</span><br><span> [[trx_if]]</span><br><span> == TRX Manager UDP socket interface</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-This is the protocol used between `osmo-trx` and `osmo-bts-trx`.</span><br><span style="color: hsl(120, 100%, 40%);">+This is the protocol used between `osmo-trx` (the transceiver) and</span><br><span style="color: hsl(120, 100%, 40%);">+`osmo-bts-trx` (The BTS or core).</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Each TRX Manager UDP socket interface represents a single ARFCN. Each of these</span><br><span style="color: hsl(0, 100%, 40%);">-per-ARFCN interfaces is a pair of UDP sockets, one for control and one for data.</span><br><span style="color: hsl(0, 100%, 40%);">-Given a base port B (5700), the master clock interface is at port P=B. The</span><br><span style="color: hsl(0, 100%, 40%);">-TRX-side control interface for C(N) is on port P=B+2N+1 and the data interface</span><br><span style="color: hsl(0, 100%, 40%);">-is on an odd numbered port P=B+2N+2. The corresponding core-side interface for</span><br><span style="color: hsl(0, 100%, 40%);">-every socket is at P+100. For any given build, the number of ARFCN interfaces</span><br><span style="color: hsl(0, 100%, 40%);">-can be fixed.</span><br><span style="color: hsl(120, 100%, 40%);">+Each TRX Manager UDP socket interface represents a single transceiver (ARFCN).</span><br><span style="color: hsl(120, 100%, 40%);">+Each of these channels is a pair of UDP sockets, one for control (`TRXC`) and</span><br><span style="color: hsl(120, 100%, 40%);">+one for data (`TRXD`). Additionally, there's a separate global socket managing</span><br><span style="color: hsl(120, 100%, 40%);">+the Master Clock Interface, shared among all channel.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Given a base port `B` (5700), and a set of channels `0..N`, the ports related to</span><br><span style="color: hsl(120, 100%, 40%);">+a channel `0 <= X <= N` are:</span><br><span style="color: hsl(120, 100%, 40%);">+* The Master clock interface is located on port `P=B`.</span><br><span style="color: hsl(120, 100%, 40%);">+* The `TRXC` interface for channel `X` is located on port `P=B+2N+1`</span><br><span style="color: hsl(120, 100%, 40%);">+* The `TRXD` interface for channel `X` is located on port `P=B+2N+2`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The corresponding interface for every socket is at `P+100` on the BTS side.</span><br><span> </span><br><span> [[trx_if_clock_ind]]</span><br><span> === Indications on the Master Clock Interface</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The master clock interface is output only (from the radio).</span><br><span style="color: hsl(120, 100%, 40%);">+The master clock interface is output only (uplink, from the radio to the BTS).</span><br><span> Messages are "indications".</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-CLOCK gives the current value of the transceiver clock to be used by the core.</span><br><span style="color: hsl(0, 100%, 40%);">-This message is sent whenever a trasmission packet arrives that is too late or</span><br><span style="color: hsl(0, 100%, 40%);">-too early. The clock value is NOT the current transceiver time. It is a time</span><br><span style="color: hsl(0, 100%, 40%);">-setting the the core should use to give better packet arrival times.</span><br><span style="color: hsl(120, 100%, 40%);">+CLOCK gives the current value of the transceiver clock to be used by the BTS.</span><br><span style="color: hsl(120, 100%, 40%);">+This message is usually sent around once per second (217 GSM frames), but can be</span><br><span style="color: hsl(120, 100%, 40%);">+sent at any time. The clock value is NOT the current transceiver time. It is a</span><br><span style="color: hsl(120, 100%, 40%);">+time setting that the BTS should use to give better packet arrival times. The</span><br><span style="color: hsl(120, 100%, 40%);">+initial clock value is taken randomly, and then increased over time as the</span><br><span style="color: hsl(120, 100%, 40%);">+transceiver submits downlink packets to the radio.</span><br><span> ----</span><br><span> IND CLOCK <totalFrames></span><br><span> ----</span><br><span> </span><br><span> [[trx_if_control]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== Commands on the Per-ARFCN Control Interface</span><br><span style="color: hsl(120, 100%, 40%);">+=== TRXC protocol</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The per-ARFCN control interface uses a command-reponse protocol. Commands are</span><br><span style="color: hsl(0, 100%, 40%);">-NULL-terminated ASCII strings, one per UDP socket. Each command has a</span><br><span style="color: hsl(0, 100%, 40%);">-corresponding response.</span><br><span style="color: hsl(120, 100%, 40%);">+The per-ARFCN control interface uses a command-response protocol. Each command</span><br><span style="color: hsl(120, 100%, 40%);">+has a corresponding response. Commands are sent in downlink direction (BTS -></span><br><span style="color: hsl(120, 100%, 40%);">+TRX), and responses are sent in uplink direction (TRX -> BTS). Commands and</span><br><span style="color: hsl(120, 100%, 40%);">+responses are NULL-terminated ASCII strings.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Every command is of the form:</span><br><span style="color: hsl(120, 100%, 40%);">+Every command is structured this way:</span><br><span> ----</span><br><span> CMD <cmdtype> [params]</span><br><span> ----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> The `<cmdtype>` is the actual command.</span><br><span> Parameters are optional depending on the commands type.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> Every response is of the form:</span><br><span> ----</span><br><span> RSP <cmdtype> <status> [result]</span><br><span>@@ -46,7 +55,6 @@</span><br><span> The `<status>` is 0 for success and a non-zero error code for failure.</span><br><span> Successful responses may include results, depending on the command type.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> ==== Power Control</span><br><span> </span><br><span> `POWEROFF` shuts off transmitter power and stops the demodulator.</span><br><span>@@ -55,11 +63,11 @@</span><br><span> RSP POWEROFF <status></span><br><span> ----</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-`POWERON` starts the transmitter and starts the demodulator. Initial power</span><br><span style="color: hsl(120, 100%, 40%);">+`POWERON` starts the transmitter and starts the demodulator. Initial power</span><br><span> level is very low. This command fails if the transmitter and receiver are not</span><br><span> yet tuned. This command fails if the transmit or receive frequency creates a</span><br><span> conflict with another ARFCN that is already running. If the transceiver is</span><br><span style="color: hsl(0, 100%, 40%);">-already on, it response with success to this command.</span><br><span style="color: hsl(120, 100%, 40%);">+already on, it answers successfully to this command.</span><br><span> ----</span><br><span> CMD POWERON</span><br><span> RSP POWERON <status></span><br><span>@@ -102,7 +110,7 @@</span><br><span> </span><br><span> ==== Timeslot Control</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-`SETSLOT` sets the format of the uplink timeslots in the ARFCN.</span><br><span style="color: hsl(120, 100%, 40%);">+`SETSLOT` sets the format of a given uplink timeslot in the ARFCN.</span><br><span> The `<timeslot>` indicates the timeslot of interest.</span><br><span> The `<chantype>` indicates the type of channel that occupies the timeslot.</span><br><span> A chantype of zero indicates the timeslot is off.</span><br><span>@@ -111,11 +119,33 @@</span><br><span> RSP SETSLOT <status> <timeslot> <chantype></span><br><span> ----</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-=== Messages on the per-ARFCN Data Interface</span><br><span style="color: hsl(120, 100%, 40%);">+Here's the list of channel combinations and related values (`<chantype>`):</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.List of channel combinations and related values (`<chantype>`)</span><br><span style="color: hsl(120, 100%, 40%);">+[options="header"]</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+| value | Channel Combination</span><br><span style="color: hsl(120, 100%, 40%);">+|0| Channel is transmitted, but unused</span><br><span style="color: hsl(120, 100%, 40%);">+|1| TCH/FS</span><br><span style="color: hsl(120, 100%, 40%);">+|2| TCH/HS, idle every other slot</span><br><span style="color: hsl(120, 100%, 40%);">+|3| TCH/HS</span><br><span style="color: hsl(120, 100%, 40%);">+|4| Downlink: FCCH + SCH + CCCH + BCCH, Uplink: RACH</span><br><span style="color: hsl(120, 100%, 40%);">+|5| Downlink: FCCH + SCH + CCCH + BCCH + SDCCH/4 + SACCH/4, Uplink: RACH+SDCCH/4</span><br><span style="color: hsl(120, 100%, 40%);">+|6| Downlink: CCCH+BCCH, Uplink: RACH</span><br><span style="color: hsl(120, 100%, 40%);">+|7| SDCCH/8 + SACCH/8</span><br><span style="color: hsl(120, 100%, 40%);">+|8| TCH/F + FACCH/F + SACCH/M</span><br><span style="color: hsl(120, 100%, 40%);">+|9| TCH/F + SACCH/M</span><br><span style="color: hsl(120, 100%, 40%);">+|10| TCH/FD + SACCH/MD</span><br><span style="color: hsl(120, 100%, 40%);">+|11| PBCCH+PCCCH+PDTCH+PACCH+PTCCH</span><br><span style="color: hsl(120, 100%, 40%);">+|12| PCCCH+PDTCH+PACCH+PTCCH</span><br><span style="color: hsl(120, 100%, 40%);">+|13| PDTCH+PACCH+PTCCH</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== TRXD protocol</span><br><span> </span><br><span> Messages on the data interface carry one radio burst per UDP message.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-==== Received Data Burst</span><br><span style="color: hsl(120, 100%, 40%);">+==== Uplink Data Burst</span><br><span> </span><br><span> [packetdiag]</span><br><span> ----</span><br><span>@@ -123,21 +153,29 @@</span><br><span> colwidth = 32</span><br><span> node_height = 40</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- 0: T</span><br><span style="color: hsl(0, 100%, 40%);">- 1-4: FN</span><br><span style="color: hsl(0, 100%, 40%);">- 5: A</span><br><span style="color: hsl(0, 100%, 40%);">- 6-7: C</span><br><span style="color: hsl(0, 100%, 40%);">- 8-155: Payload</span><br><span style="color: hsl(120, 100%, 40%);">+ 0-2: TN</span><br><span style="color: hsl(120, 100%, 40%);">+ 3: RES</span><br><span style="color: hsl(120, 100%, 40%);">+ 4-7: VER</span><br><span style="color: hsl(120, 100%, 40%);">+ 8-39: FN</span><br><span style="color: hsl(120, 100%, 40%);">+ 40-47: RSSI</span><br><span style="color: hsl(120, 100%, 40%);">+ 48-55: TOA256</span><br><span style="color: hsl(120, 100%, 40%);">+ 56-95: ...Payload...</span><br><span style="color: hsl(120, 100%, 40%);">+ 96-97: PAD</span><br><span> }</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-* _T_: timeslot index</span><br><span style="color: hsl(120, 100%, 40%);">+* _TN_: timeslot number.</span><br><span style="color: hsl(120, 100%, 40%);">+* _RES_: Reserved, shall be 0.</span><br><span style="color: hsl(120, 100%, 40%);">+* _VER_: TRXD header version, shall be 0.</span><br><span> * _FN_: GSM frame number, big endian</span><br><span style="color: hsl(0, 100%, 40%);">-* _A_: RSSI in -dBm</span><br><span style="color: hsl(0, 100%, 40%);">-* _C_: correlator timing offset in 1/256 symbol steps, 2's-comp, big endian</span><br><span style="color: hsl(0, 100%, 40%);">-* _Payload_: 148 bytes soft symbol estimates, 0 -> definite "0", 255 -> definite "1"</span><br><span style="color: hsl(120, 100%, 40%);">+* _RSSI_: RSSI in -dBm</span><br><span style="color: hsl(120, 100%, 40%);">+* _TOA236_: correlator timing offset in 1/256 symbol steps, 2's-comp, big endian</span><br><span style="color: hsl(120, 100%, 40%);">+* _Payload_: 148 bytes soft symbol estimates, 0 -> definite "0", 255 -> definite</span><br><span style="color: hsl(120, 100%, 40%);">+ "1". If packet contains an EDGE burst, then payload is 444 bytes.</span><br><span style="color: hsl(120, 100%, 40%);">+* _PAD_: Optional 2 bit padding at the end, historical reasons (OpenBTS</span><br><span style="color: hsl(120, 100%, 40%);">+ inheritance). Bits can take any value, but 0 is preferred.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-==== Transmit Data Burst</span><br><span style="color: hsl(120, 100%, 40%);">+==== Downlink Data Burst</span><br><span> </span><br><span> [packetdiag]</span><br><span> ----</span><br><span>@@ -145,14 +183,18 @@</span><br><span> colwidth = 32</span><br><span> node_height = 40</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- 0: T</span><br><span style="color: hsl(0, 100%, 40%);">- 1-4: FN</span><br><span style="color: hsl(0, 100%, 40%);">- 5: A</span><br><span style="color: hsl(0, 100%, 40%);">- 6-153: Payload</span><br><span style="color: hsl(120, 100%, 40%);">+ 0-3: TN</span><br><span style="color: hsl(120, 100%, 40%);">+ 4: RES</span><br><span style="color: hsl(120, 100%, 40%);">+ 5-8: VER</span><br><span style="color: hsl(120, 100%, 40%);">+ 9-39: FN</span><br><span style="color: hsl(120, 100%, 40%);">+ 40-47: RSSI</span><br><span style="color: hsl(120, 100%, 40%);">+ 48-95: ...Payload...</span><br><span> }</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-* _T_: timeslot index</span><br><span style="color: hsl(0, 100%, 40%);">-* _FN_ GSM frame number, big endian</span><br><span style="color: hsl(0, 100%, 40%);">-* _A_: transmit level wrt ARFCN max, -dB (attenuation)</span><br><span style="color: hsl(0, 100%, 40%);">-* _Payload_: 148 bytes output symbol values, 0 & 1</span><br><span style="color: hsl(120, 100%, 40%);">+* _TN_: timeslot number.</span><br><span style="color: hsl(120, 100%, 40%);">+* _RES_: Reserved, shall be 0.</span><br><span style="color: hsl(120, 100%, 40%);">+* _VER_: TRXD header version, shall be 0.</span><br><span style="color: hsl(120, 100%, 40%);">+* _FN_: GSM frame number, big endian.</span><br><span style="color: hsl(120, 100%, 40%);">+* _RSSI_: RSSI in -dBm.</span><br><span style="color: hsl(120, 100%, 40%);">+* _Payload_: 148 bytes output symbol values, 0 & 1. 444 bytes in case of EDGE burst.</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14938">change 14938</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/osmo-gsm-manuals/+/14938"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-gsm-manuals </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I36e6206b90435964842f9f1ebd982cdaf9777018 </div>
<div style="display:none"> Gerrit-Change-Number: 14938 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>