osmo-bts-trx: implement BCCH carrier power reduction mode

The BCCH carrier (sometimes called C0) of a BTS shall maintain
discontinuous Downlink transmission at full power in order to
stay 'visible' to the mobile stations.  Because of that, early
versions of 3GPP TS 45.008 prohibited BS power reduction on C0.

However, in the recent 3GPP TS 45.008 there is a feature called
'BCCH carrier power reduction operation'.  This is a special
mode of operation, where the variation of RF level for some
timeslots is relaxed for the purpose of energy saving.

In BCCH carrier power reduction operation, for timeslots on the
C0 carrier, except timeslots carrying BCCH/CCCH, the output power
may be lower than the output power used for timeslots carrying
BCCH/CCCH.  In this case the maximum allowed difference in output
power actually transmitted by the BTS is 6 dB.

The power reduction operation can be controlled by the BSC by
sending BS POWER CONTROL on the A-bis/RSL with the Channel Number
IE set to 0x80 (RSL_CHAN_BCCH).  This makes osmo-bts reduce the
transmission power on inactive timeslots of the BCCH carrier.

This is a non-standard, Osmocom specific extension, so indicate
support of this feature to the BSC in the feature vector.  Also
add a VTY command to allow enabling/disabling the power reduction
locally.  Add some signalling notes to the A-bis/RSL manual.

For more details, see 3GPP TS 45.008, section 7.1.

Change-Id: I3dcee6e910ccc61c5c63c728db9ea04327e2fc98
Depends: I69283b3f35988fc7a1a1dcf1a1ad3b67f08ec716
Related: SYS#4919

doc/manuals/abis/rsl.adoc

@@ -476,6 +476,26 @@ signaling for it.
 See <<OSMO_ETWS_CMD>> for the Osmocom implementation.
 
 
+=== BCCH carrier power reduction operation
+
+According to 3GPP TS 45.008, section 7.1, the BCCH carrier (sometimes called C0) of
+a BTS shall maintain discontinuous Downlink transmission at full power in order to
+stay "visible" to the mobile stations.  Because of that, early versions of this 3GPP
+document prohibited BS power reduction on C0.  However, a new feature was introduced
+version 13.0.0 (2015-11) - "BCCH carrier power reduction operation".
+
+This is a special mode of operation, in which the variation of RF power level for
+some timeslots is relaxed for the purpose of energy saving.  In other words, the
+output power on some timeslots, except the timeslot(s) carrying BCCH/CCCH, can be
+lower than the full power.  In this case the maximum allowed difference is 6 dB.
+
+Unfortunately, 3GPP did not specify in which way the BTS is instructed to activate
+and deactivate the BCCH carrier power reduction mode.  Osmocom had to invent their
+own non-standard approach: the BSC needs to send _BS POWER CONTROL_ message with
+the _Channel Number_ IE set to 0x80 (BCCH) and the _Message Discriminator_ set to
+0x06 (Common Channel Management messages).
+
+
 === Message Formats and Contents
 
 [[rsl_crcx_msg]]

include/osmo-bts/bts.h

@@ -331,6 +331,9 @@ struct gsm_bts {
 	struct gsm_power_ctrl_params bs_dpc_params; /* BS Dynamic Power Control */
 	struct gsm_power_ctrl_params ms_dpc_params; /* MS Dynamic Power Control */
 
+	/* Maximum BCCH carrier power reduction */
+	uint8_t c0_power_red_db;
+
 	/* used by the sysmoBTS to adjust band */
 	uint8_t auto_band;
 
@@ -410,4 +413,6 @@ int32_t bts_get_avg_fn_advance(const struct gsm_bts *bts);
 /* return the gsm_lchan for the CBCH (if it exists at all) */
 struct gsm_lchan *gsm_bts_get_cbch(struct gsm_bts *bts);
 
+int bts_set_c0_pwr_red(struct gsm_bts *bts, const uint8_t red);
+
 #endif /* _BTS_H */

include/osmo-bts/gsm_data.h

@@ -451,6 +451,9 @@ struct gsm_bts_trx_ts {
 	/* Training Sequence Set (range 0..3) */
 	uint8_t tsc_set;
 
+	/* Actual BCCH carrier power reduction */
+	uint8_t c0_power_red_db;
+
 	/* Frequency hopping parameters (configured via OML) */
 	struct {
 		bool enabled;

src/common/bts.c

@@ -948,3 +948,58 @@ struct gsm_lchan *gsm_bts_get_cbch(struct gsm_bts *bts)
 
 	return lchan;
 }
+
+/* BCCH carrier power reduction (see 3GPP TS 45.008, section 7.1) */
+int bts_set_c0_pwr_red(struct gsm_bts *bts, const uint8_t red)
+{
+	struct gsm_bts_trx *c0 = bts->c0;
+	unsigned int tn;
+
+	if (!osmo_bts_has_feature(bts->features, BTS_FEAT_BCCH_POWER_RED)) {
+		LOGPTRX(c0, DRSL, LOGL_ERROR, "BCCH carrier power reduction "
+			"is not supported by this BTS model\n");
+		return -ENOTSUP;
+	}
+
+	if (red > 6 || red % 2 != 0) {
+		LOGPTRX(c0, DRSL, LOGL_ERROR, "BCCH carrier power reduction "
+			"value (%u dB) is incorrect or out of range\n", red);
+		return -EINVAL;
+	}
+
+	LOGPTRX(c0, DRSL, LOGL_NOTICE, "BCCH carrier power reduction: "
+		"%u dB (%s)\n", red, red ? "enabled" : "disabled");
+
+	/* Timeslot 0 is always transmitting BCCH/CCCH */
+	c0->ts[0].c0_power_red_db = 0;
+
+	for (tn = 1; tn < ARRAY_SIZE(c0->ts); tn++) {
+		struct gsm_bts_trx_ts *ts = &c0->ts[tn];
+		struct gsm_bts_trx_ts *prev = ts - 1;
+
+		switch (ts_pchan(ts)) {
+		/* Not allowed on CCCH/BCCH */
+		case GSM_PCHAN_CCCH:
+			/* Preceeding timeslot shall not exceed 2 dB */
+			if (prev->c0_power_red_db > 0)
+				prev->c0_power_red_db = 2;
+			/* fall-through */
+		/* Not recommended on SDCCH/8 */
+		case GSM_PCHAN_SDCCH8_SACCH8C:
+		case GSM_PCHAN_SDCCH8_SACCH8C_CBCH:
+			ts->c0_power_red_db = 0;
+			break;
+		default:
+			ts->c0_power_red_db = red;
+			break;
+		}
+	}
+
+	/* Timeslot 7 is always preceding BCCH/CCCH */
+	if (c0->ts[7].c0_power_red_db > 0)
+		c0->ts[7].c0_power_red_db = 2;
+
+	bts->c0_power_red_db = red;
+
+	return 0;
+}

src/common/rsl.c

@@ -2179,6 +2179,7 @@ static int rsl_rx_bs_pwr_ctrl(struct msgb *msg)
 {
 	struct abis_rsl_dchan_hdr *dch = msgb_l2(msg);
 	struct gsm_lchan *lchan = msg->lchan;
+	struct gsm_bts_trx *trx = msg->trx;
 	const struct tlv_p_entry *ie;
 	struct tlv_parsed tp;
 	uint8_t old, new;
@@ -2187,22 +2188,34 @@ static int rsl_rx_bs_pwr_ctrl(struct msgb *msg)
 
 	/* 9.3.4 BS Power (M) */
 	if (!TLVP_PRES_LEN(&tp, RSL_IE_BS_POWER, 1))
-		return rsl_tx_error_report(msg->trx, RSL_ERR_MAND_IE_ERROR, &dch->chan_nr, NULL, msg);
+		return rsl_tx_error_report(trx, RSL_ERR_MAND_IE_ERROR, &dch->chan_nr, NULL, msg);
 
 	if (*TLVP_VAL(&tp, RSL_IE_BS_POWER) & (1 << 4)) {
 		LOGPLCHAN(lchan, DRSL, LOGL_NOTICE, "Fast Power Control is not supported\n");
-		return rsl_tx_error_report(msg->trx, RSL_ERR_SERV_OPT_UNIMPL, &dch->chan_nr, NULL, msg);
+		return rsl_tx_error_report(trx, RSL_ERR_SERV_OPT_UNIMPL, &dch->chan_nr, NULL, msg);
 	}
 
 	new = BS_POWER2DB(*TLVP_VAL(&tp, RSL_IE_BS_POWER));
 	old = lchan->bs_power_ctrl.current;
 
+	/* Osmocom specific extension for BCCH carrier power reduction */
+	if (dch->chan_nr == RSL_CHAN_BCCH) {
+		int rc = bts_set_c0_pwr_red(trx->bts, new);
+		if (rc != 0) {
+			const uint8_t cause = (rc == -ENOTSUP) ?
+				RSL_ERR_SERV_OPT_UNIMPL : RSL_ERR_IE_CONTENT;
+			return rsl_tx_error_report(trx, cause, &dch->chan_nr, NULL, msg);
+		}
+
+		return 0;
+	}
+
 	/* 9.3.32 (TLV) BS Power Parameters IE (vendor specific) */
 	if ((ie = TLVP_GET(&tp, RSL_IE_BS_POWER_PARAM)) != NULL) {
 		struct gsm_power_ctrl_params *params = &lchan->bs_dpc_params;
 
 		/* Parsed parameters will override per-TRX defaults */
-		memcpy(params, msg->trx->bs_dpc_params, sizeof(*params));
+		memcpy(params, trx->bs_dpc_params, sizeof(*params));
 
 		/* Parsed parameters will override per-TRX defaults */
 		if (ie->len && parse_power_ctrl_params(params, ie->val, ie->len) != 0) {
@@ -3555,6 +3568,10 @@ static int rsl_rx_cchan(struct gsm_bts_trx *trx, struct msgb *msg)
 	case RSL_MT_OSMO_ETWS_CMD:
 		ret = rsl_rx_osmo_etws_cmd(trx, msg);
 		break;
+	/* Osmocom specific extension for BCCH carrier power reduction */
+	case RSL_MT_BS_POWER_CONTROL:
+		ret = rsl_rx_bs_pwr_ctrl(msg);
+		break;
 	default:
 		LOGPLCHAN(msg->lchan, DRSL, LOGL_NOTICE, "undefined RSL cchan msg_type 0x%02x\n",
 			  cch->c.msg_type);

src/common/scheduler.c

@@ -1318,6 +1318,8 @@ void _sched_dl_burst(struct l1sched_ts *l1ts, struct trx_dl_burst_req *br)
 	/* BS Power reduction (in dB) per logical channel */
 	if (l1cs->lchan != NULL)
 		br->att = l1cs->lchan->bs_power_ctrl.current;
+	else /* Ensure no attenuation in the absence of lchan (e.g. on PDCH) */
+		br->att = 0;
 
 	/* encrypt */
 	if (br->burst_len && l1cs->dl_encr_algo) {

src/common/vty.c

@@ -1106,6 +1106,10 @@ static void bts_dump_vty(struct vty *vty, const struct gsm_bts *bts)
 		vty_out(vty, "  Radio Link Timeout (OVERRIDE): %s%s",
 			stringify_radio_link_timeout(bts->radio_link_timeout.current), VTY_NEWLINE);
 	}
+	if (bts->c0_power_red_db > 0) {
+		vty_out(vty, "  BCCH carrier power reduction: %u dB%s",
+			bts->c0_power_red_db, VTY_NEWLINE);
+	}
 
 	llist_for_each_entry(trx, &bts->trx_list, list) {
 		const struct phy_instance *pinst = trx_phy_instance(trx);
@@ -1264,6 +1268,39 @@ DEFUN_HIDDEN(radio_link_timeout, radio_link_timeout_cmd, "bts <0-0> radio-link-t
 	return CMD_SUCCESS;
 }
 
+DEFUN(bts_c0_power_red,
+      bts_c0_power_red_cmd,
+      "bts <0-255> c0-power-red <0-6>",
+      "BTS Specific Commands\n" BTS_NR_STR
+      "BCCH carrier power reduction operation\n"
+      "Power reduction value (in dB, even numbers only)\n")
+{
+	struct gsm_network *net = gsmnet_from_vty(vty);
+	const int bts_nr = atoi(argv[0]);
+	const int red = atoi(argv[1]);
+	struct gsm_bts *bts;
+
+	bts = gsm_bts_num(net, atoi(argv[0]));
+	if (bts == NULL) {
+		vty_out(vty, "%% No such BTS (%d)%s", bts_nr, VTY_NEWLINE);
+		return CMD_WARNING;
+	}
+
+	if (red % 2 != 0) {
+		vty_out(vty, "%% Incorrect BCCH power reduction value, "
+			"an even number is expected%s", VTY_NEWLINE);
+		return CMD_WARNING;
+	}
+
+	if (bts_set_c0_pwr_red(bts, red) != 0) {
+		vty_out(vty, "%% BCCH carrier power reduction operation mode "
+			"is not supported for BTS (%d)%s", bts_nr, VTY_NEWLINE);
+		return CMD_WARNING;
+	}
+
+	return CMD_SUCCESS;
+}
+
 /* TODO: generalize and move indention handling to libosmocore */
 #define cfg_out(vty, fmt, args...) \
 	vty_out(vty, "%*s" fmt, indent, "", ##args)
@@ -2391,6 +2428,7 @@ int bts_vty_init(void *ctx)
 	install_element(ENABLE_NODE, &bts_t_t_l_power_ctrl_current_max_cmd);
 	install_element(ENABLE_NODE, &test_send_failure_event_report_cmd);
 	install_element(ENABLE_NODE, &radio_link_timeout_cmd);
+	install_element(ENABLE_NODE, &bts_c0_power_red_cmd);
 
 	install_element(CONFIG_NODE, &cfg_phy_cmd);
 	install_node(&phy_node, config_write_phy);

src/osmo-bts-trx/main.c

@@ -147,6 +147,7 @@ int bts_model_init(struct gsm_bts *bts)
 	osmo_bts_set_feature(bts->features, BTS_FEAT_ACCH_REP);
 	osmo_bts_set_feature(bts->features, BTS_FEAT_MULTI_TSC);
 	osmo_bts_set_feature(bts->features, BTS_FEAT_VAMOS);
+	osmo_bts_set_feature(bts->features, BTS_FEAT_BCCH_POWER_RED);
 
 	bts_internal_flag_set(bts, BTS_INTERNAL_FLAG_MEAS_PAYLOAD_COMB);
 

src/osmo-bts-trx/scheduler_trx.c

@@ -195,9 +195,13 @@ static void bts_sched_init_buffers(struct gsm_bts *bts, const uint32_t fn)
 	for (tn = 0; tn < ARRAY_SIZE(trx->ts); tn++) {
 		struct phy_instance *pinst = bts->c0->pinst;
 		struct trx_dl_burst_req *br = &pinst->u.osmotrx.br[tn];
+		const struct gsm_bts_trx_ts *ts = &bts->c0->ts[tn];
 
 		memcpy(br->burst, _sched_dummy_burst, GSM_BURST_LEN);
 		br->burst_len = GSM_BURST_LEN;
+
+		/* BCCH carrier power reduction for this timeslot */
+		br->att = ts->c0_power_red_db;
 	}
 }