Change in ...osmo-gsm-manuals[master]: common: trx_if.adoc: Improve documentation

pespin gerrit-no-reply at lists.osmocom.org
Thu Jul 25 15:38:53 UTC 2019


pespin has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14938


Change subject: common: trx_if.adoc: Improve documentation
......................................................................

common: trx_if.adoc: Improve documentation

Several fixes and improvements to the documentation.
This documentation still doesn't contain infrmation about TRXDv1, it
will be added in a follow-up commit.

Change-Id: I36e6206b90435964842f9f1ebd982cdaf9777018
---
M common/chapters/trx_if.adoc
1 file changed, 85 insertions(+), 43 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/38/14938/1

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

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14938
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Change-Id: I36e6206b90435964842f9f1ebd982cdaf9777018
Gerrit-Change-Number: 14938
Gerrit-PatchSet: 1
Gerrit-Owner: pespin <pespin at sysmocom.de>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20190725/f0d404b1/attachment.html>


More information about the gerrit-log mailing list