lib: lte_lc: Integrate PDN library

Copies the PDN functionality from the PDN library that is about
to be deprecated, and adds it as a module in the LTE link
controller library.

The functionality is the same, but with naming changes to types
and APIs to align with the rest of LTE link controller.
In addition, PDN events are now part of the LTE LC events, and
there is no longer need for a separate event handler.

Signed-off-by: Jan Tore Guggedal <[email protected]>

Author: jtguggedal

doc/nrf/libraries/modem/lte_lc.rst

@@ -165,6 +165,30 @@ Environment Evaluation:
   * :c:func:`lte_lc_env_eval`
   * :c:func:`lte_lc_env_eval_cancel`
 
+PDN (Packet Data Network):
+  Use the :kconfig:option:`CONFIG_LTE_LC_PDN_MODULE` Kconfig option to enable all the following functionalities related to PDP context and PDN connection management:
+
+  * :c:enumerator:`LTE_LC_EVT_PDN_ACTIVATED` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_DEACTIVATED` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_IPV6_UP` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_IPV6_DOWN` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_NETWORK_DETACH` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_APN_RATE_CONTROL_ON` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_APN_RATE_CONTROL_OFF` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_CTX_DESTROYED` events
+  * :c:enumerator:`LTE_LC_EVT_PDN_ESM_ERROR` events
+  * :c:func:`lte_lc_pdn_ctx_create`
+  * :c:func:`lte_lc_pdn_ctx_configure`
+  * :c:func:`lte_lc_pdn_ctx_auth_set`
+  * :c:func:`lte_lc_pdn_activate`
+  * :c:func:`lte_lc_pdn_deactivate`
+  * :c:func:`lte_lc_pdn_ctx_destroy`
+  * :c:func:`lte_lc_pdn_id_get`
+  * :c:func:`lte_lc_pdn_dynamic_info_get`
+  * :c:func:`lte_lc_pdn_ctx_default_apn_get`
+  * :c:func:`lte_lc_pdn_esm_strerror`
+  * :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULTS_OVERRIDE`
+
 For more information on the callback events received in :c:type:`lte_lc_evt_handler_t` and data associated with each event, see the documentation on :c:struct:`lte_lc_evt`.
 For more information on the functions and data associated with each, refer to the API documentation.
 
@@ -275,6 +299,201 @@ The :c:func:`lte_lc_env_eval` function starts the environment evaluation for the
 When the environment evaluation is complete, an :c:enumerator:`LTE_LC_EVT_ENV_EVAL_RESULT` event with the evaluation results is received.
 For each found PLMN, the :c:struct:`lte_lc_conn_eval_params` structure is populated with the evaluation results.
 
+.. _lte_lc_pdn:
+
+PDN management
+==============
+
+The LTE link control library provides functionality to manage Packet Data Protocol (PDP) contexts and Packet Data Network (PDN) connections.
+
+The PDN functionality provides the following capabilities:
+
+* Creating and configuring PDP contexts
+* Receiving events pertaining to PDN connections
+* Managing PDN connections
+* Retrieving PDN connection information
+
+To enable PDN functionality, set the :kconfig:option:`CONFIG_LTE_LC_PDN_MODULE` Kconfig option to ``y``.
+
+AT commands used
+----------------
+
+The PDN functionality uses several AT commands, and it relies on the following two types of AT notifications to work:
+
+* Packet domain events notifications (``+CGEV``) - Subscribed by using the ``AT+CGEREP=1`` command.
+  See the `AT+CGEREP set command`_ section in the nRF9160 AT Commands Reference Guide or the `nRF91x1 AT+CGEREP set command`_  section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.
+* Notifications for unsolicited reporting of error codes sent by the network (``+CNEC``) - Subscribed by using the ``AT+CNEC=16`` command.
+  See the `AT+CNEC set command`_ section in the nRF9160 AT Commands Reference Guide or the `nRF91x1 AT+CNEC set command`_  section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.
+
+The LTE link control library automatically subscribes to the necessary AT notifications.
+This includes automatically resubscribing to the notifications upon functional mode changes.
+
+.. note::
+   The subscription to AT notifications is lost upon changing the functional mode of the modem to ``+CFUN=0``.
+   If the application subscribes to these notifications manually, it must also take care of resubscription.
+
+Following are the AT commands that are used by the PDN functionality:
+
+* ``AT%XNEWCID`` - To create a PDP context
+* ``AT+CGDCONT`` - To configure or destroy a PDP context
+* ``AT+CGACT`` - To activate or deactivate a PDN connection
+* ``AT%XGETPDNID`` - To retrieve the PDN ID for a given PDP context
+* ``AT+CGAUTH`` - To set the PDN connection authentication parameters
+
+For more information about these commands, see `Packet Domain AT commands`_ in the nRF9160 AT Commands Reference Guide or the `nRF91x1 packet Domain AT commands`_ section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.
+
+Creating and managing PDN connections
+--------------------------------------
+
+The application can create PDP contexts by using the :c:func:`lte_lc_pdn_ctx_create` function.
+PDN events are sent to all registered LTE link control event handlers.
+The application can use the :c:func:`lte_lc_register_handler` function to register an event handler for events pertaining to all PDP contexts, including the default PDP context.
+
+A PDN connection is identified by an ID as reported by ``AT%XGETPDNID``, and it is distinct from the PDP context ID (CID).
+The modem creates a PDN connection for a PDP context as necessary.
+Multiple PDP contexts might share the same PDN connection if they are configured similarly.
+
+The application can use the following functions to manage PDP contexts and PDN connections:
+
+* :c:func:`lte_lc_pdn_ctx_create` - Creates a PDP context.
+* :c:func:`lte_lc_register_handler` - Registers an event handler for events pertaining to all PDP contexts, including the default PDP context.
+* :c:func:`lte_lc_pdn_ctx_configure` - Configures a PDP context with address family, access point name, and optional additional configuration options.
+* :c:func:`lte_lc_pdn_ctx_auth_set` - Sets authentication parameters for a PDP context.
+* :c:func:`lte_lc_pdn_activate` - Activates a PDN connection for a PDP context.
+* :c:func:`lte_lc_pdn_deactivate` - Deactivates a PDN connection.
+* :c:func:`lte_lc_pdn_ctx_destroy` - Destroys a PDP context.
+  The PDN connection must be inactive when the PDP context is destroyed.
+* :c:func:`lte_lc_pdn_id_get` - Retrieves the PDN ID for a given PDP context.
+  The PDN ID can be used to route traffic through a specific PDN connection.
+* :c:func:`lte_lc_pdn_dynamic_info_get` - Retrieves dynamic parameters such as DNS addresses and MTU sizes for a given PDN connection.
+* :c:func:`lte_lc_pdn_ctx_default_apn_get` - Retrieves the default Access Point Name (APN) of the default PDP context (CID 0).
+
+PDN events
+----------
+
+The following PDN events are sent to registered LTE link control event handlers:
+
+* :c:enumerator:`LTE_LC_EVT_PDN_ACTIVATED` - PDN connection activated
+* :c:enumerator:`LTE_LC_EVT_PDN_DEACTIVATED` - PDN connection deactivated
+* :c:enumerator:`LTE_LC_EVT_PDN_IPV6_UP` - PDN has IPv6 connectivity
+* :c:enumerator:`LTE_LC_EVT_PDN_IPV6_DOWN` - PDN has lost IPv6 connectivity
+* :c:enumerator:`LTE_LC_EVT_PDN_NETWORK_DETACH` - PDN connection lost due to network detach
+* :c:enumerator:`LTE_LC_EVT_PDN_APN_RATE_CONTROL_ON` - APN rate control is active
+* :c:enumerator:`LTE_LC_EVT_PDN_APN_RATE_CONTROL_OFF` - APN rate control is inactive
+* :c:enumerator:`LTE_LC_EVT_PDN_CTX_DESTROYED` - PDP context destroyed
+* :c:enumerator:`LTE_LC_EVT_PDN_ESM_ERROR` - ESM error occurred
+
+The associated payload for PDN events is the :c:member:`lte_lc_evt.pdn` member of type :c:struct:`lte_lc_pdn_evt`.
+This structure contains the PDP context ID (CID) and, for :c:enumerator:`LTE_LC_EVT_PDN_ESM_ERROR` events, the ESM error code.
+
+PDN configuration
+-----------------
+
+The LTE link control library can override the default PDP context configuration automatically after the :ref:`nrfxlib:nrf_modem` is initialized, if the :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULTS_OVERRIDE` Kconfig option is set.
+The default PDP context configuration consists of the following parameters, each controlled with a Kconfig setting:
+
+* Access point name - :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_APN`
+* Address family - :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_FAM_IPV4`, :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_FAM_IPV6`, :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_FAM_IPV4V6`, or :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_FAM_NONIP`
+* Authentication method - :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_AUTH_NONE`, :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_AUTH_PAP`, or :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_AUTH_CHAP`
+* Authentication credentials - :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_USERNAME` and :kconfig:option:`CONFIG_LTE_LC_PDN_DEFAULT_PASSWORD`
+
+.. note::
+   The default PDP context configuration must be overridden before the device is registered with the network.
+
+Additional configuration options:
+
+* :kconfig:option:`CONFIG_LTE_LC_PDN_LEGACY_PCO` - Use legacy PCO mode instead of ePCO during PDN connection establishment
+* :kconfig:option:`CONFIG_LTE_LC_PDN_ESM_TIMEOUT` - Timeout for waiting for an ESM notification when activating a PDN
+* :kconfig:option:`CONFIG_LTE_LC_PDN_ESM_STRERROR` - Compile a table with textual descriptions of ESM error reasons
+
+PDN usage example
+-----------------
+
+The following code snippet demonstrates how to use the PDN functionality:
+
+.. code-block:: c
+
+   #include <zephyr/kernel.h>
+   #include <modem/lte_lc.h>
+
+   static void lte_handler(const struct lte_lc_evt *const evt)
+   {
+           switch (evt->type) {
+           case LTE_LC_EVT_PDN_ACTIVATED:
+                   printk("PDN context %d activated\n", evt->pdn.cid);
+                   break;
+           case LTE_LC_EVT_PDN_DEACTIVATED:
+                   printk("PDN context %d deactivated\n", evt->pdn.cid);
+                   break;
+           case LTE_LC_EVT_PDN_ESM_ERROR:
+                   printk("PDN context %d ESM error: %d\n",
+                          evt->pdn.cid, evt->pdn.esm_err);
+                   break;
+           default:
+                   break;
+           }
+   }
+
+   int main(void)
+   {
+           int err;
+           uint8_t cid;
+           int esm;
+           char apn[32];
+           int pdn_id;
+
+           err = lte_lc_register_handler(lte_handler);
+           if (err) {
+                   LOG_ERR("Registration failed, error: %d", err);
+
+                   return err;
+           }
+
+           err = lte_lc_connect();
+           if (err) {
+                   return err;
+           }
+
+           /* Get default APN */
+           err = lte_lc_pdn_ctx_default_apn_get(apn, sizeof(apn));
+           if (err) {
+                   return err;
+           }
+
+           /* Create a new PDP context */
+           err = lte_lc_pdn_ctx_create(&cid);
+           if (err) {
+                   return err;
+           }
+
+           /* Configure the PDP context */
+           err = lte_lc_pdn_ctx_configure(cid, apn, LTE_LC_PDN_FAM_IPV4V6, NULL);
+           if (err) {
+                   return err;
+           }
+
+           /* Activate the PDN connection */
+           err = lte_lc_pdn_activate(cid, &esm, NULL);
+           if (err) {
+                   LOG_ERR("Activation failed, ESM error: %d", esm);
+
+                   return err;
+           }
+
+           /* Get PDN ID */
+           pdn_id = lte_lc_pdn_id_get(cid);
+           if (pdn_id < 0) {
+                   return pdn_id;
+           }
+
+           LOG_INF("PDN connection activated with PDN ID: %d", pdn_id);
+
+           /* Continue execution... */
+   }
+
+.. note::
+   You have to register the event handler for LTE events before the device is registered to the network (``CFUN=1``) to receive the first activation event.
+
 Limitations
 ***********
 

doc/nrf/nrf.doxyfile.in

@@ -2465,7 +2465,9 @@ PREDEFINED             = __DOXYGEN__ \
                          "CONFIG_LTE_LC_RAI_MODULE=y" \
                          "CONFIG_LTE_LC_MODEM_SLEEP_MODULE=y" \
                          "CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE=y" \
-                         "CONFIG_LTE_LC_ENV_EVAL_MODULE=y"
+                         "CONFIG_LTE_LC_ENV_EVAL_MODULE=y" \
+                         "CONFIG_LTE_LC_PDN_MODULE=y"
+
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -907,6 +907,8 @@ Modem libraries
     * Description of new features supported by mfw_nrf91x1 and mfw_nrf9151-ntn in receive only functional mode.
     * Sending of the ``LTE_LC_EVT_PSM_UPDATE`` event with ``tau`` and ``active_time`` set to ``-1`` when registration status is ``LTE_LC_NW_REG_NOT_REGISTERED``.
     * New registration statuses and functional modes for the ``mfw_nrf9151-ntn`` modem firmware.
+    * Support for PDP context and PDN connection management.
+      The functionality is available when the :kconfig:option:`CONFIG_LTE_LC_PDN_MODULE` Kconfig option is enabled.
 
   * Updated: