aboutsummaryrefslogtreecommitdiffstats
path: root/include/osmocom/bsc/acc_ramp.h
blob: a4ce0d2d68488375cceba2488eec3c4347e41773 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
/* (C) 2018 Stefan Sperling <ssperling@sysmocom.de>
 *
 * All Rights Reserved
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef _ACC_RAMP_H_
#define _ACC_RAMP_H_

#include <stdbool.h>
#include <stdint.h>

#include <osmocom/core/timer.h>

/*
 * Access control class (ACC) ramping is used to slowly make the cell available to
 * an increasing number of MS. This avoids overload at startup time in cases where
 * a lot of MS would discover the new cell and try to connect to it all at once.
 */

#define ACC_RAMP_STEP_SIZE_MIN 1 /* allow at most 1 new ACC per ramp step */
#define ACC_RAMP_STEP_SIZE_DEFAULT ACC_RAMP_STEP_SIZE_MIN
#define ACC_RAMP_STEP_SIZE_MAX 10 /* allow all ACC in one step (effectively disables ramping) */

#define ACC_RAMP_STEP_INTERVAL_MIN 30	/* 30 seconds */
#define ACC_RAMP_STEP_INTERVAL_MAX 600	/* 10 minutes */

struct acc_ramp {
	struct gsm_bts *bts; /* backpointer to BTS using this ACC ramp */

	/*
	 * Bitmasks which keep track of access control classes that are currently denied
	 * access. These masks should be used to modulate bits from octets 2 and 3 of
	 * the RACH Control Parameters (see 3GPP 44.018 10.5.2.29).
	 * While a bit in these masks is set, the corresponding ACC is barred.
	 * Note that t2 contains bits for classes 11-15 which should always be allowed,
	 * and a bit which denies emergency calls for all ACCs from 0-9 inclusive.
	 * Ramping is only concerned with those bits which control access for ACCs 0-9.
	 */
	uint8_t barred_t2;
	uint8_t barred_t3;

	/*
	 * This controls the maximum number of ACCs to allow per ramping step (1 - 10).
	 * The compile-time default value is ACC_RAMP_STEP_SIZE_DEFAULT.
	 * This value can be changed by VTY configuration.
	 * A value of ACC_RAMP_STEP_SIZE_MAX effectively disables ramping.
	 */
	unsigned int step_size;

	/*
	 * Ramping step interval in seconds.
	 * This value depends on the current BTS channel load average, unless
	 * it has been overriden by VTY configuration.
	 */
	unsigned int step_interval_sec;
	bool step_interval_is_fixed;
	struct osmo_timer_list step_timer;
};

/*
 * Initialize an acc_ramp data structure.
 * Storage for this structure must be provided by the caller.
 *
 * The BTS which uses this ACC ramp data structure must be provided as well.
 *
 * If 'bts->acc_ramping_enabled' is true, all ACCs are denied by default.
 * A subsequent call to acc_ramp_start() will begin the ramping process.
 *
 * If 'bts->acc_ramping_enabled' is false, all ACCs will be allowed by default,
 * and there is no need to do anything else.
 */
void acc_ramp_init(struct acc_ramp *acc_ramp, struct gsm_bts *bts);

/* Change the ramping step size. Returns negative on error (step_size out of range), else zero. */
int acc_ramp_set_step_size(struct acc_ramp *acc_ramp, unsigned int step_size);

/*
 * Change the ramping step interval to a fixed value. Unless this function is called,
 * the interval is automatically scaled to the BTS channel load average.
 */
int acc_ramp_set_step_interval(struct acc_ramp *acc_ramp, unsigned int step_interval);

/*
 * Clear a previously set fixed ramping step interval, so that the interval
 * is again automatically scaled to the BTS channel load average.
 */
void acc_ramp_set_step_interval_dynamic(struct acc_ramp *acc_ramp);

/*
 * Begin the ramping process. Perform at least one ramping step to allow 'step_size' ACCs.
 * If 'step_size' is ACC_RAMP_STEP_SIZE_MAX, all ACCs will be allowed immediately.
 */
void acc_ramp_start(struct acc_ramp *acc_ramp);

/* Abort the ramping process. If the process has already finished, this function has no effect. */
void acc_ramp_abort(struct acc_ramp *acc_ramp);

/*
 * Return bitmasks which correspond to access control classes that are currently
 * denied access. Ramping is only concerned with those bits which control access
 * for ACCs 0-9, and any of the other bits will always be set to zero in these masks, i.e.
 * it is safe to OR these bitmasks with the corresponding fields in struct gsm48_rach_control.
 */
static inline uint8_t acc_ramp_get_barred_t2(struct acc_ramp *acc_ramp)
{
	return (acc_ramp->barred_t2 & 0x03);
};

static inline uint8_t acc_ramp_get_barred_t3(struct acc_ramp *acc_ramp)
{
	return acc_ramp->barred_t3;
}

#endif /* _ACC_RAMP_H_ */