API to handle Network Resource Indicator (NRI) values and ranges for MSC pooling, as in 3GPP TS 23.236. More...

#include <stdint.h>
#include <stdbool.h>
#include <osmocom/core/linuxlist.h>

Data Structures
struct	osmo_nri_range
	One range of NRI values. More...

struct	osmo_nri_ranges
	A list of struct osmo_nri_range. More...

Macros
#define	OSMO_NRI_BITLEN_MIN 1

#define	OSMO_NRI_BITLEN_MAX 15

#define	OSMO_NRI_BITLEN_DEFAULT 10

Functions
int	osmo_nri_v_validate (int16_t nri_v, uint8_t nri_bitlen)
	Validate that the given NRI is valid for a given nri_bitlen range. More...

bool	osmo_nri_v_matches_ranges (int16_t nri_v, const struct osmo_nri_ranges *nri_ranges)
	Return true when the given NRI value appears in the list of NRI ranges. More...

int	osmo_nri_v_limit_by_ranges (int16_t nri_v, const struct osmo_nri_ranges nri_ranges, uint32_t nri_bitlen)
	Modulo and shift the given NRI value so that it becomes a value present in a list of NRI ranges. More...

int	osmo_tmsi_nri_v_get (int16_t *nri_v, uint32_t tmsi, uint8_t nri_bitlen)
	Retrieve the Network Resource Indicator bits from a TMSI or p-TMSI. More...

int	osmo_tmsi_nri_v_set (uint32_t *tmsi, int16_t nri_v, uint8_t nri_bitlen)
	Write Network Resource Indicator bits into a TMSI or p-TMSI. More...

int	osmo_tmsi_nri_v_limit_by_ranges (uint32_t tmsi, const struct osmo_nri_ranges nri_ranges, uint8_t nri_bitlen)
	Apply osmo_nri_v_limit_by_ranges() in-place on the NRI value included in a TMSI. More...

int	osmo_nri_range_validate (const struct osmo_nri_range *range, uint8_t nri_bitlen)
	Validate that the given NRI range is valid for a given nri_bitlen range. More...

bool	osmo_nri_range_overlaps_ranges (const struct osmo_nri_range range, const struct osmo_nri_ranges nri_ranges)
	Return true when the given NRI range has at least one NRI value that appears in a list of other NRI ranges. More...

struct osmo_nri_ranges *	osmo_nri_ranges_alloc (void *ctx)
	Allocate an empty struct osmo_nri_ranges (list of struct osmo_nri_range). More...

void	osmo_nri_ranges_free (struct osmo_nri_ranges *nri_ranges)
	Free a struct osmo_nri_ranges. More...

int	osmo_nri_ranges_add (struct osmo_nri_ranges nri_ranges, const struct osmo_nri_range add)
	Add a range of NRI values to a list of nri_range structs. More...

int	osmo_nri_ranges_del (struct osmo_nri_ranges nri_ranges, const struct osmo_nri_range del)
	Remove a range of NRI values from a list of nri_range structs. More...

int	osmo_nri_ranges_vty_add (const char *message, struct osmo_nri_range added_range, struct osmo_nri_ranges nri_ranges, int argc, const char *argv, uint8_t nri_bitlen)
	VTY implementation for adding an NRI range to a list of ranges. More...

int	osmo_nri_ranges_vty_del (const char *message, struct osmo_nri_range removed_range, struct osmo_nri_ranges nri_ranges, int argc, const char *argv)
	VTY implementation for removing an NRI range from a list of ranges. More...

int	osmo_nri_ranges_to_str_buf (char buf, size_t buflen, const struct osmo_nri_ranges nri_ranges)
	Compose a human readable representation of a list of NRI ranges in a buffer, like "23..42,123..142". More...

char *	osmo_nri_ranges_to_str_c (void ctx, const struct osmo_nri_ranges nri_ranges)
	Compose a human readable representation of a list of NRI ranges in a talloc buffer, like "23..42,123..142". More...

Detailed Description

API to handle Network Resource Indicator (NRI) values and ranges for MSC pooling, as in 3GPP TS 23.236.

Macro Definition Documentation

◆ OSMO_NRI_BITLEN_DEFAULT

#define OSMO_NRI_BITLEN_DEFAULT 10

◆ OSMO_NRI_BITLEN_MAX

#define OSMO_NRI_BITLEN_MAX 15

◆ OSMO_NRI_BITLEN_MIN

#define OSMO_NRI_BITLEN_MIN 1

Function Documentation

◆ osmo_nri_range_overlaps_ranges()

bool osmo_nri_range_overlaps_ranges	(	const struct osmo_nri_range *	range,
		const struct osmo_nri_ranges *	nri_ranges
	)

Return true when the given NRI range has at least one NRI value that appears in a list of other NRI ranges.

Parameters

[in]	range	NRI range to look for.
[in]	nri_ranges	List NRI ranges.

Returns: true iff any NRI value from 'range' appears anywhere in nri_ranges.

References osmo_nri_ranges::entries, entry, llist_for_each_entry, and nri_range_overlaps_range().

◆ osmo_nri_range_validate()

int osmo_nri_range_validate	(	const struct osmo_nri_range *	range,
		uint8_t	nri_bitlen
	)

Validate that the given NRI range is valid for a given nri_bitlen range.

Parameters

[in]	nri_range	NRI value range to validate.
[in]	nri_bitlen	Valid NRI range in nr of bits used. If nri_bitlen > OSMO_NRI_BITLEN_MAX, the NRI range is only validated to be first <= last and non-negative, not checked to fit a bit length range,

Returns: 0 if valid, -1 or 1 if range->first is invalid, -2 or 2 if range->last is invalid, -3 if first > last.

References osmo_nri_range::first, osmo_nri_range::last, and osmo_nri_v_validate().

Referenced by osmo_nri_ranges_add(), osmo_nri_ranges_del(), osmo_nri_ranges_vty_add(), and osmo_nri_v_limit_by_ranges().

◆ osmo_nri_ranges_add()

int osmo_nri_ranges_add	(	struct osmo_nri_ranges *	nri_ranges,
		const struct osmo_nri_range *	add
	)

Add a range of NRI values to a list of nri_range structs.

Intelligently add and/or combine the entries in a list of NRI ranges to also include the NRI range given in 'add'. The list remains sorted by 'first' values.

Parameters

[in,out]	nri_ranges	List of talloc allocated struct osmo_nri_range entries to add the new range to.
[in]	add	NRI range to add to 'nri_ranges'.

Returns: 0 on success, negative on error (if the range in 'add' is invalid).

References osmo_nri_ranges::entries, entry, osmo_nri_range::entry, llist_del(), llist_for_each_entry, llist_for_each_entry_safe, nri_range_extend(), nri_range_touches(), nri_ranges_add_entry_sorted(), OSMO_ASSERT, and osmo_nri_range_validate().

Referenced by osmo_nri_ranges_vty_add().

◆ osmo_nri_ranges_alloc()

struct osmo_nri_ranges * osmo_nri_ranges_alloc ( void * ctx )

Allocate an empty struct osmo_nri_ranges (list of struct osmo_nri_range).

Parameters

ctx	Talloc context to allocate from.

Returns: allocated empty list.

References osmo_nri_ranges::entries, INIT_LLIST_HEAD, and OSMO_ASSERT.

◆ osmo_nri_ranges_del()

int osmo_nri_ranges_del	(	struct osmo_nri_ranges *	nri_ranges,
		const struct osmo_nri_range *	del
	)

Remove a range of NRI values from a list of nri_range structs.

Intelligently drop and/or cut or split the entries in a list of NRI ranges to no longer include the NRI range given in 'del'. Note that after this, the list may have more entries than before, if a range was split into two smaller ranges.

Parameters

[in,out]	nri_ranges	List of talloc allocated struct osmo_nri_range entries to remove values from.
[in]	del	NRI range to remove from 'nri_ranges'.

Returns: 0 on success, negative on error (if the range in 'del' is invalid).

References osmo_nri_ranges::entries, entry, osmo_nri_range::entry, osmo_nri_range::first, osmo_nri_range::last, llist_add(), llist_del(), llist_for_each_entry_safe, nri_range_overlaps_range(), nri_v_matches_range(), OSMO_ASSERT, and osmo_nri_range_validate().

Referenced by osmo_nri_ranges_vty_del().

◆ osmo_nri_ranges_free()

void osmo_nri_ranges_free ( struct osmo_nri_ranges * nri_ranges )

Free a struct osmo_nri_ranges.

Parameters

nri_ranges The list to discard.

◆ osmo_nri_ranges_to_str_buf()

int osmo_nri_ranges_to_str_buf	(	char *	buf,
		size_t	buflen,
		const struct osmo_nri_ranges *	nri_ranges
	)

Compose a human readable representation of a list of NRI ranges in a buffer, like "23..42,123..142".

Parameters

[out]	buf	Target buffer.
[in]	buflen	sizeof(buf).
[in]	nri_ranges	List NRI ranges.

Returns: strlen() of string that would be written if the buffer is large enough, like snprintf().

References osmo_strbuf::buf, osmo_strbuf::chars_needed, osmo_nri_ranges::entries, entry, osmo_nri_range::first, osmo_nri_range::last, llist_empty(), llist_for_each_entry, and OSMO_STRBUF_PRINTF.

Referenced by osmo_nri_ranges_to_str_c().

◆ osmo_nri_ranges_to_str_c()

char * osmo_nri_ranges_to_str_c	(	void *	ctx,
		const struct osmo_nri_ranges *	nri_ranges
	)

Compose a human readable representation of a list of NRI ranges in a talloc buffer, like "23..42,123..142".

Parameters

[in]	ctx	Talloc context.
[in]	nri_ranges	List of NRI ranges.

Returns: a talloc allocated string.

References OSMO_NAME_C_IMPL, and osmo_nri_ranges_to_str_buf().

◆ osmo_nri_ranges_vty_add()

int osmo_nri_ranges_vty_add	(	const char **	message,
		struct osmo_nri_range *	added_range,
		struct osmo_nri_ranges *	nri_ranges,
		int	argc,
		const char **	argv,
		uint8_t	nri_bitlen
	)

VTY implementation for adding an NRI range to a list of ranges.

Parse one or, if present, two argv arguments, which must be numbers representing the first and last value to add to the list of NRI ranges, in decimal format ("511") or hexadecimal with leading "0x" ("0x1ff"). If the range values surpass the nri_bitlen, return a warning in 'message', but still add the values to the list.

Parameters

[out]	message	Returned string constant to alert the user with, or NULL if all is well.
[out]	added_range	If not NULL, write the range parsing result to this location.
[in]	nri_ranges	List NRI ranges to add to.
[in]	argc	Argument count.
[in]	argv	Argument list.
[in]	nri_bitlen	Valid NRI range in nr of bits used.

Returns: 0 on success, -1 on error, 1 for a warning (if adding was successful but the added range surpasses nri_bitlen).

References argc, argv, OSMO_NRI_BITLEN_MAX, osmo_nri_parse_range(), osmo_nri_range_validate(), and osmo_nri_ranges_add().

◆ osmo_nri_ranges_vty_del()

int osmo_nri_ranges_vty_del	(	const char **	message,
		struct osmo_nri_range *	removed_range,
		struct osmo_nri_ranges *	nri_ranges,
		int	argc,
		const char **	argv
	)

VTY implementation for removing an NRI range from a list of ranges.

Parse one or, if present, two argv arguments, which must be numbers representing the first and last value to remove from the list of NRI ranges, in decimal format ("511") or hexadecimal with leading "0x" ("0x1ff").

Parameters

[out]	message	Returned string constant to alert the user with, or NULL if all is well.
[out]	removed_range	If not NULL, write the range parsing result to this location.
[in]	nri_ranges	List of NRI ranges to remove from.
[in]	argc	Argument count.
[in]	argv	Argument list.

Returns: 0 on success, -1 on error, 1 for a warning.

References argc, argv, osmo_nri_parse_range(), and osmo_nri_ranges_del().

◆ osmo_nri_v_limit_by_ranges()

int osmo_nri_v_limit_by_ranges	(	int16_t *	nri_v,
		const struct osmo_nri_ranges *	nri_ranges,
		uint32_t	nri_bitlen
	)

Modulo and shift the given NRI value so that it becomes a value present in a list of NRI ranges.

Only range values within nri_bitlen are used.

Parameters

[in,out]	nri_v	The NRI value to limit, e.g. random bits or an increment counter value.
[in]	nri_ranges	List of NRI ranges indicating valid NRI values, where no entries may overlap in range values, and all entries must be valid (first <= last).

Returns: 0 on success, negative on error.

References osmo_nri_ranges::entries, entry, osmo_nri_range::first, osmo_nri_range::last, len, llist_for_each_entry, OSMO_MIN, and osmo_nri_range_validate().

Referenced by osmo_tmsi_nri_v_limit_by_ranges().

◆ osmo_nri_v_matches_ranges()

bool osmo_nri_v_matches_ranges	(	int16_t	nri_v,
		const struct osmo_nri_ranges *	nri_ranges
	)

Return true when the given NRI value appears in the list of NRI ranges.

Parameters

[in]	nri_v	NRI value to look for.
[in]	nri_ranges	List NRI ranges.

Returns: true iff nri_v appears anywhere in nri_ranges.

References osmo_nri_ranges::entries, entry, llist_for_each_entry, and nri_v_matches_range().

◆ osmo_nri_v_validate()

int osmo_nri_v_validate	(	int16_t	nri_v,
		uint8_t	nri_bitlen
	)

Validate that the given NRI is valid for a given nri_bitlen range.

Parameters

[in]	nri_v	NRI value to validate.
[in]	nri_bitlen	Valid NRI range in nr of bits used; if nri_bitlen > OSMO_NRI_BITLEN_MAX, nri_v is only checked to not be marked invalid.

Returns: 0 if valid, <0 if the NRI is <0, >0 if the NRI surpasses the range.

References OSMO_NRI_BITLEN_MAX, and OSMO_NRI_BITLEN_MIN.

Referenced by osmo_nri_range_validate().

◆ osmo_tmsi_nri_v_get()

int osmo_tmsi_nri_v_get	(	int16_t *	nri_v,
		uint32_t	tmsi,
		uint8_t	nri_bitlen
	)

Retrieve the Network Resource Indicator bits from a TMSI or p-TMSI.

Useful for MSC pooling as described by 3GPP TS 23.236.

Parameters

[out]	nri_v	Write the extracted NRI value to this location (if non-NULL). If 0 is returned, it is guaranteed that nri_v >= 0. On non-zero return code, nri_v == -1.
[in]	tmsi	TMSI value containing NRI bits.
[in]	nri_bitlen	Length of the NRI value in number of bits, OSMO_NRI_BITLEN_MIN <= nri_bitlen <= * OSMO_NRI_BITLEN_MAX.

Returns: 0 on success, negative on error (i.e. if nri_bitlen is not in the valid range).

References OSMO_NRI_BITLEN_MAX.

Referenced by osmo_tmsi_nri_v_limit_by_ranges().

◆ osmo_tmsi_nri_v_limit_by_ranges()

int osmo_tmsi_nri_v_limit_by_ranges	(	uint32_t *	tmsi,
		const struct osmo_nri_ranges *	nri_ranges,
		uint8_t	nri_bitlen
	)

Apply osmo_nri_v_limit_by_ranges() in-place on the NRI value included in a TMSI.

Extract the NRI value from the TMSI, limit that to be part of the ranges given in 'nri_ranges', and place the resulting NRI value back in the TMSI.

Parameters

[in,out]	tmsi	TMSI value of which to modify the NRI bits, e.g. fresh randomized bits.
[in]	nri_ranges	List of NRI ranges indicating valid NRI values, where no entries may overlap in range values, and all entries must be valid (first <= last).
[in]	nri_bitlen	Valid NRI range in nr of bits used.

Returns: 0 on success, negative on error.

References osmo_nri_v_limit_by_ranges(), osmo_tmsi_nri_v_get(), and osmo_tmsi_nri_v_set().

◆ osmo_tmsi_nri_v_set()

int osmo_tmsi_nri_v_set	(	uint32_t *	tmsi,
		int16_t	nri_v,
		uint8_t	nri_bitlen
	)

Write Network Resource Indicator bits into a TMSI or p-TMSI.

Overwrite the NRI bits with a given NRI value in a TMSI or p-TMSI. Useful for MSC pooling as described by 3GPP TS 23.236.

Parameters

[in,out]	tmsi	A base TMSI or p-TMSI to replace the NRI value in, result is written back to this location.
[in]	nri_v	The NRI value to place in the tmsi.
[in]	nri_bitlen	Length of the NRI value in number of bits, OSMO_NRI_BITLEN_MIN <= nri_bitlen <= * OSMO_NRI_BITLEN_MAX.

Returns: 0 on success, negative on error (i.e. if nri_bitlen is not in the valid range or if tmsi is NULL).

References OSMO_NRI_BITLEN_MAX.

Referenced by osmo_tmsi_nri_v_limit_by_ranges().

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ OSMO_NRI_BITLEN_DEFAULT

◆ OSMO_NRI_BITLEN_MAX

◆ OSMO_NRI_BITLEN_MIN

Function Documentation

◆ osmo_nri_range_overlaps_ranges()

◆ osmo_nri_range_validate()

◆ osmo_nri_ranges_add()

◆ osmo_nri_ranges_alloc()

◆ osmo_nri_ranges_del()

◆ osmo_nri_ranges_free()

◆ osmo_nri_ranges_to_str_buf()

◆ osmo_nri_ranges_to_str_c()

◆ osmo_nri_ranges_vty_add()

◆ osmo_nri_ranges_vty_del()

◆ osmo_nri_v_limit_by_ranges()

◆ osmo_nri_v_matches_ranges()

◆ osmo_nri_v_validate()

◆ osmo_tmsi_nri_v_get()

◆ osmo_tmsi_nri_v_limit_by_ranges()

◆ osmo_tmsi_nri_v_set()