Description

In the 5G Core the Policy Control Function (PCF) controls the Network Policy deployment as rules in the User Plane Function (UPF) in order to provide differing network policies for categories of network traffic.

There are two deployments envisaged by 3GPP, one where there is a single PCF in the trusted network - that can be directly addressable, and an alternative deployment where there are multiple distributed PCFs. In the latter case there is a Binding Support Function (BSF) that takes registrations from the PCFs and acts as a look up service that can map PDU session or UE connection parameters to the PCF controlling the UPF that is dealing with that PDU session or UE.

This ticket is concerned with creating a reusable library of functions that can perform a mapping of PDU session to a PCF address by using the BSF API to interogate the BSF for the answer. This library will be based on Open5GS.

Design

This library will reside in the repository in a lib/bsf subdirectory which will be included in the meson build and should produce s static library of the BSF interface functions.

Types

typedef bool (*bsf_retrieve_callback)(OpenAPI_pcf_binding_t *pcf_binding /* [transfer,null] */, void *user_data /* [null] */);

This callback is called when an event containing a BSF response is seen.

Parameters:

pcf_binding

The PcfBinding object received in the BSF response or NULL if there was a server error or timeout.

user_data

The user_data that was passed to `bsf_retrieve_pcf_binding_for_pdu_session()` when the request was generated.

Returns: true if the callback handled the BSF response or false if there was a problem with processing the pcf_binding.

Functions

bool bsf_parse_config(const char *local /* [not-null] */)

Parse the Open5GS configuration section indicated by local for the BSF communication parameters.

This should be called from the application "init" function.

This may initialise timers for communication timeouts.

This may invoke a request to the NRF for the BSF address if indicated by the configuration file.

Parameters:

local

The name of the section in the configuration file to get the BSF configuration from.

Return: true if the configuration was parsed successfully, or false if there was an error.

bool bsf_retrieve_pcf_binding_for_pdu_session(ogs_sockaddr_t *ue_address /* [not-null] */, bsf_retrieve_callback callback /* [not-null] */, void *user_data /* [null] */)

This function generates a service consumer request to the BSF

Parameters:

ue_address

The address the UE is communicating from.

callback

A function to be called with the answer to the PCF binding request when it arrives.

user_data

A user data pointer that will be passed to the callback when it is called.

Return: true if the binding request was sent or false if there was an error.

bool bsf_process_event(ogs_event_t *event /* [conditional-transfer,not-null] */)

This function should be called from the main application FSM state function to process BSF events.

If the event is recognised as a BSF response this will call the callback that was provided when the request was made.

If the event is recognised as an NRF response containing a BSF address then the BSF address is stored in the library context.

If the event is recognised as an NRF notification then the BSF address in the library context is updated.

If the event is a BSF library timeout then the timeout is logged and if the timeout was for a BSF response then the callback is called with a NULL pcf_binding parameter.

Parameters:

event

The event to be processed

Return: true if the event was handled (ownership of event has been taken) or false if the event was not recognised (event is released back to the calling function).

bool bsf_fini()

This function shall free up any context and deregister for NRF notfications if it registered for them in the bsf_parse_config() function call.

Parameters: None

Return: true if the BSF library was tidied up, or false if there was an error.

Testing

A unit test will be created in tests/bsf that uses the Open5GS "abts" test suite components to make a bsf unit test (see subprojects/open5gs/tests/vonr/* for examples).

This test will require an NRF, PCF and BSF to be running.

The test should:

• Initialise the Open5GS SBI library (ogs_sbi_init() and ogs_sbi_parse_config() functions)
• Initialise the BSF library using bsf_parse_config("bsf")
• Create a "UE" registered with the PCF using the open5gs project libaf_dep meson variable as a dependency and call the appropriate functions from that library to register with the PCF (see subprojects/open5gs/tests/vonr/af-test.c for an example)
• Initialise the app FSM - in the FSM state routine do:
  • Call bsf_process_event(event) and return if true given as return code.
  • On OGS_FSM_ENTRY_SIG perform a request, using the library bsf_retrieve_pcf_binding_for_pdu_session() function passing in the UE details and a suitable call back function.
  • Report other events as errors.
• Wait for the exit condition (ogs_thread_cond_wait())
• Tidy using bsf_fini()
• Exit

In the call back function:

• examine the response and check the PCF is the one we registered with, log error using the ABTS_* macros.
• Use ogs_thread_cond_signal() to signal the exit condition before returning.

Relevant Specifications

• 3GPP TS 29.513 - 5G System; Policy and Charging Control signalling flows and QoS parameter mapping; Stage 3
  • Clause 8.4
• 3GPP TS 29.521 - 5G System; Binding Support Management Service; Stage 3
  • Clauses 4.2.4.2 & 5.3.2

Purpose

We wish to test our PCF service consumer library against a variety of different PCF implementations by developing a simple PCF service consumer test application.

Functional specification

1. Uses the PCF service consumer library to create (and populate with initial values) an Application Session Context in the PCF.
   • Including subscribing to receive notifications from the PCF concerning the created Application Session Context.
2. Reports any notifications that arrive until either:
   1. The PCF destroys the Application Session Context, or
   2. The user interrupts the program.
      • In this case, the Application Session Context is explicitly destroyed by the application before it exits.

Parameters

The application takes the following command line parameters:

1. The IP address of a UE registered in the 5G System.
2. The source port number (at the UE end) of an application data flow (optional).
3. PCF IP address (optional).
   • If omitted, the BSF service consumer library is invoked to discover the PCF for the given UE IP address.
   • If BSF lookup fails, the NRF is used to find a PCF.
4. List of notification events (optional).
   • If omitted, all event notifications are subscribed to.
5. Set of min/max downlink and uplink bit rate settings (optional).
   • If omitted, no initial values are populated in the Application Session Context when it is created.

Introduction

For IBC 2023 we wish to try and demonstrate QoS with media streaming. The PCF PolicyAuthorization tool can control QoS for a given UE or specific UE IP traffic. For a simple demo we'd like to use the PCF PolicyAuthorization tool to interactively control the QoS levels. At present the tool is not interactive.

Control

We'd like to add control to the tool using either a keyboard, mouse or rotary dial.

The basic controls would be to increase or decrease a QoS limit and to change which QoS limit is being controlled.

Keyboard

For keyboard control the up and down arrow keys shall be used to increase or decrease the currently selected QoS value and the Enter key shall toggle between QoS limits. This allows either a full keyboard or a smaller keypad to be used to control the demo.

Mouse

The up/down motion of a mouse shall be used to increase/decrease the QoS limit and the left mouse button shall be used to toggle through the selected QoS limit being controlled.

Rotary dial

Clockwise dial motion shall increase the currently selected QoS limit and anti-clockwise motion shall decrease the QoS limit. Pressing the dial shall toggle between the available QoS limits.

Visualisation

In order to see what the current QoS limits are we would like to have a display showing the current QoS limit settings and which QoS limit is currently selected for change.

Description

As part of the work on Network Assistance the 5GMS Application Function will need to subscribe to notifications from the PCF.

This issue covers the work needed to introduce a library which deals with PCF service consumer communications via the interface at reference point N5 (see 3GPP TS 26.501). This issue deals with implementing an interface for the PCF Policy Authorization API (3GPP TS 29.514) that will allow the application to create an AppSessionContext on the PCF and subscribe to the event notifications for that AppSessionContext.

• https://forge.3gpp.org/rep/all/5G_APIs/-/blob/TSG100-Rel17/TS29514_Npcf_PolicyAuthorization.yaml

The functionality of this library will be expanded by other issues in the repository to include communications for the other control and query aspects needed by Network Assistance and Dynamic Policies.

Design

The source for this library should reside in the repository in the lib/pcf subdirectory and it should be linked as a static library for compile time inclusion in the 5GMS Application Function and other NFs that may need to use it.

Types

typedef bool (*pcf_app_session_notification_callback_t)(pcf_app_session_t *app_session, const OpenAPI_events_notification_t *notifications, void *user_data);

A function with this callback prototype will be called when the PCF sends an event exposure notification for a registered notification.

Parameters:

app_session

The `pcf_app_session_t` the event subscription is attached to.

notifications

The PCF EventsNotification structure (TS 29.514 clause 5.6.2.9) received in the event exposure message. This structure may not persist following the return of the callback.

user_data

The user_data pointer passed to the pcf_session_create_app_session() function when the notification was registered for.

Returns: true if the notification was successfully processed by the callback or false if there was an error or the notification was ignored.

typedef void (*pcf_app_session_change_callback_t)(pcf_app_session_t *app_session, void *user_data);

A function with this callback prototype will be called when the PCF establishes a new AppSessionContext, there was a problem establishing a new AppSessionContext or the PCF sends a notification for the forced destruction of an AppSessionContext.

Parameters:

app_session

The PCF app session object created or NULL if the PCF AppSessionContext failed to be created or has been forcably destroyed by the PCF.

user_data

The user_data pointer passed to the pcf_session_create_app_session() function when the callback was registered.

typedef struct ue_network_identifier_s {
    ogs_sockaddr_t address;
    char *supi;
    char *gspi;
    char *dnn;
    char *ip_domain;
} ue_network_identifier_t;

Fields:

address

This is the address of the UE as either a AF_PACKET, AF_INET or AF_INET6 family address.

supi

This is an optional field containing the Subscription Permanent Identifier for the UE PDU session or NULL.

gpsi

This is an optional field containing the Generic Public Subscription Identifier for the UE PDU session or NULL.

dnn

This is an optional field containing the Data Network Name for the UE PDU session or NULL.

ip_domain

This is an optional field containing the IPv4 address domain for the UE PDU session or NULL.

typedef enum pcf_app_session_event_type_e {
    PCF_APP_SESSION_EVENT_TYPE_NONE = 0x00000,
    PCF_APP_SESSION_EVENT_TYPE_ACCESS_TYPE_CHANGE = 0x00001,
    PCF_APP_SESSION_EVENT_TYPE_ANI_REPORT = 0x00002,
    PCF_APP_SESSION_EVENT_TYPE_APP_DETECTION = 0x00004,
    PCF_APP_SESSION_EVENT_TYPE_CHARGING_CORRELATION = 0x00008,
    PCF_APP_SESSION_EVENT_TYPE_UP_PATH_CHG_FAILURE = 0x00010,
    PCF_APP_SESSION_EVENT_TYPE_EPS_FALLBACK = 0x00020,
    PCF_APP_SESSION_EVENT_TYPE_FAILED_QOS_UPDATE = 0x00040,
    PCF_APP_SESSION_EVENT_TYPE_FAILED_RESOURCES_ALLOCATION = 0x00080,
    PCF_APP_SESSION_EVENT_TYPE_OUT_OF_CREDIT = 0x00100,
    PCF_APP_SESSION_EVENT_TYPE_PDU_SESSION_STATUS = 0x00200,
    PCF_APP_SESSION_EVENT_TYPE_PLMN_CHG = 0x00400,
    PCF_APP_SESSION_EVENT_TYPE_QOS_NOTIF = 0x00800,
    PCF_APP_SESSION_EVENT_TYPE_QOS_MONITORING = 0x01000,
    PCF_APP_SESSION_EVENT_TYPE_RAN_NAS_CAUSE = 0x02000,
    PCF_APP_SESSION_EVENT_TYPE_REALLOCATION_OF_CREDIT = 0x04000,
    PCF_APP_SESSION_EVENT_TYPE_SAT_CATEGORY_CHG = 0x08000,
    PCF_APP_SESSION_EVENT_TYPE_SUCCESSFUL_QOS_UPDATE = 0x10000,
    PCF_APP_SESSION_EVENT_TYPE_SUCCESSFUL_RESOURCES_ALLOCATION = 0x20000,
    PCF_APP_SESSION_EVENT_TYPE_TSN_BRIDGE_INFO = 0x40000,
    PCF_APP_SESSION_EVENT_TYPE_USAGE_REPORT = 0x80000,
    PCF_APP_SESSION_EVENT_TYPE_ALL = 0xFFFFF
} pcf_app_session_event_type_t;

Functions

pcf_session_t *pcf_session_new(const ogs_sockaddr_t *pcf_address /* [not-null] */)

This function creates a new PCF service consumer session to communicate with the PCF at the given address.

Parameters:

pcf_address

The address of the PCF to communicate with in this service consumer session.

Returns: a new pcf_session_t service consumer session context or NULL if the service consumer session creation failed.

void pcf_session_free(pcf_session_t *session /* [transfer, not-null] */)

This will free all pcf_app_session_t created by pcf_session_create_app_session() and free other service consumer session resources.

Parameters:

session

The service consumer session context as returned by `pcf_session_new()`.

bool pcf_session_process_event(pcf_session_t *session /* [not-null] */, ogs_event_t *event /* [conditional-transfer, not-null] */)

This will check if the event should be handled by this PCF service consumer session.

Upon receiving an Npcf_PolicyAuthorization_Create or Npcf_PolicyAuthorization_Subscribe response this will check if the response matches any pcf_app_session_t for the pcf_session_t and if so will register the details in the pcf_app_session_t. The change_callback is called with a pointer to the pcf_app_session_t if the call succeeded or NULL if the request failed. If the response contains event notifications these will be dispatched to the appropriate callback that was registered with pcf_session_create_app_session() or pcf_app_session_subscribe_event().

Upon receiving an Npcf_PolicyAuthorization_Notify response this will check if the response matches any pcf_app_session_t for the pcf_session_t and if so will dispatch the notification to the appropriate callbacks that were registered with pcf_session_create_app_session() or pcf_app_session_subscribe_event(). A terminate notification will cause the change_callback to be invoked with a NULL for the app_session and the pcf_app_session_t will be deleted.

Upon receiving an Npcf_PolicyAuthorization_Unsubscribe response this will check if the response matches any pcf_app_session_t for the pcf_session_t and if so will remove all event notification information from pct_app_session_t.

Upon receiving a timeout for a Npcf_PolicyAuthorization_Create request this will check if the timeout matches a request made for any pcf_app_session_t for the pcf_session_t and if so will store the failure information in the pcf_app_session_t and will call the callback registered with the pcf_session_create_app_session() function with a NULL pointer for the notification to alert the application of the failure.

Upon receiving a timeout for a Npcf_PolicyAuthorization_Subscribe request this will check if the timeout matches a request made for any pcf_app_session_t for the pcf_session_t and if so will store the failure information in the pcf_app_session_t and will call the callback registered with the pcf-app_session_subscribe_event() function with a NULL pointer for the notification to alert the application of the failure.

Parameters:

session

The service consumer session context as returned by `pcf_session_new()`.

event

The Open5GS event to process.

Return: true if the event was dealt with (this function takes ownership of the event and frees it), or false if the event was unrecognised (ownership of the event remains with the caller).

bool pcf_session_create_app_session(pcf_session_t *session /* [not-null] */,
                const ue_network_identifier_t *ue_connection /* [not-null] */, int events,
                OpenAPI_media_component_t *media_component,
                pcf_app_session_notification_callback_t notify_callback /* [not-null] */, void *notify_user_data,
                pcf_app_session_change_callback_t change_callback /* [not-null] */, void *change_user_data)

This will request the creation of an AppSessionContext from the PCF with the events already subscribed to using the default values. For more control over event subscriptions please see pcf_app_session_subscribe_event(). This is done by sending an Npcf_PolicyAuthorization_Create request to the PCF.

When an event notification is later received from the PCF the callback is called to report the event notification to the application. If the response to the Npcf_PolicyAuthorization_Create from the PCF, upon creating the AppSessionContext, contains event notifications the callback routine will be called for each one.

Parameters:

session

The service consumer session context to request the creation of an application session context on.

ue_connection

The UE connection details to create the Application Session Context for.

events

The events to subscribe to when creating the app context session, this is an ORed set of values from the pcf_app_session_event_type_t enumeration.

media_component

The MediaComponent describing the network policy to apply.

notify_callback

Callback to call when an event is generated on the app session context.

notify_user_data

The user_data parameter to use when calling the notify_callback.

change_callback

Callback to call when there is a change in the app session context (PCF AppSessionContext created or destroyed).

change_user_data

The user_data parameter to use when calling the change_callback.

void pcf_app_session_free(pcf_app_session_t *app_session /* [transfer, not-null] */)

This will request the deletion of the AppSessionContext from the PCF by sending an Npcf_PolicyAuthorization_Delete request and free the application session resources for the app_session and remove the pcf_app_session_t from the associated pcf_session_t.

Parameters:

app_session

The application session context as returned by `pcf_session_create_app_session()`.

bool pcf_app_session_subscribe_event(pcf_app_session_t *app_session /* [not-null] */,
                OpenAPI_events_subsc_req_data *evt_subsc_req, pcf_app_session_notification_callback_t callback /* [not-null] */,
                void *user_data)

This will add a subscription for events to the PCF AppSessionContext. This will record the notification information (events being requested, callback and user_data) in the app_session, merging the evt_subsc_req with the existing one in the AppSessionContext and updating it by sending an Npcf_PolicyAuthorization_Subscribe request to PCF for the AppSessionContext.

When a notification is received from the PCF the callback is called to report the event notification to the application. If the subscription response from the PCF contains event notifications the callback routine is called for each one.

Parameters:

app_session

The application session context to update event subscriptions for.

evt_subsc_req

The event subscription information to use

callback

Callback to call when an event is generated on the app session context.

user_data

The user_data parameter to use when calling the callback

Return: true if the subscription update was sent, false if there was a problem.

bool pcf_app_session_unsubscribe_events(pcf_app_session_t *app_session /* [not-null] */,
                OpenAPI_events_subsc_req_data *evt_subsc_req)

TODO: Describe removing callbacks and issuing updated Npcf_PolicyAuthorization_Subscribe request.

bool pcf_app_session_unsubscribe_all_events(pcf_app_session_t *app_session /* [not-null] */)

TODO: Describe using Npcf_PolicyAuthorization_Unsubscribe to remove all events and callbacks from the pcf_app_session_t.

Relevant Specifications

3GPP TS 29.514