diff --git a/doc/nrf/libraries/modem/pdn.rst b/doc/nrf/libraries/modem/pdn.rst index 3664dced02e..bb091ff7d86 100644 --- a/doc/nrf/libraries/modem/pdn.rst +++ b/doc/nrf/libraries/modem/pdn.rst @@ -7,7 +7,7 @@ PDN :local: :depth: 2 -The PDN library can be used to manage Packet Data Protocol (PDP) contexts and PDN connections. +The PDN library can be used to manage Packet Data Protocol (PDP) contexts and Packet Data Network (PDN) connections. It provides an API for the following purposes: * Creating and configuring PDP contexts @@ -42,7 +42,7 @@ The application can create PDP contexts by using the :c:func:`pdn_ctx_create` fu The application can use the :c:func:`pdn_default_ctx_cb_reg` function to register an event handler for events pertaining the default PDP context, and the :c:func:`pdn_default_ctx_cb_dereg` to deregister it. The library stores 12 bytes of memory on the system heap for each PDP context created using :c:func:`pdn_ctx_create` and for each event handler for the default PDP context. The maximum number of PDP contexts that can be created is limited by the maximum number of PDP context supported by the nRF91 Series modem firmware and the amount of system heap memory available. -The :c:func:`pdn_ctx_configure` function is used to configure a PDP context, which can be configured with a family, access point name, and optional authentication parameters. +The :c:func:`pdn_ctx_configure` function is used to configure a PDP context, which can be configured with address family, access point name, and optional authentication parameters. The :c:func:`pdn_activate` function activates a PDN connection for a 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. @@ -55,7 +55,7 @@ The PDN library overrides the default PDP context configuration automatically af The default PDP context configuration consists of the following parameters, each controlled with a Kconfig setting: * Access point name, :kconfig:option:`CONFIG_PDN_DEFAULT_APN` -* Family, :kconfig:option:`CONFIG_PDN_DEFAULT_FAM` +* Address family, :kconfig:option:`CONFIG_PDN_DEFAULT_FAM` * Authentication method, :kconfig:option:`CONFIG_PDN_DEFAULT_AUTH` * Authentication credentials, :kconfig:option:`CONFIG_PDN_DEFAULT_USERNAME` and :kconfig:option:`CONFIG_PDN_DEFAULT_PASSWORD` diff --git a/include/modem/pdn.h b/include/modem/pdn.h index 58a382dd474..4c9719ba7c8 100644 --- a/include/modem/pdn.h +++ b/include/modem/pdn.h @@ -18,20 +18,20 @@ extern "C" { /** * @file pdn.h - * @brief Public APIs for the PDN library. + * @brief Public APIs for the Packet Data Network (PDN) library. * @defgroup pdn PDN library * @{ */ -/** @brief PDN family */ +/** @brief Address family */ enum pdn_fam { - PDN_FAM_IPV4 = 0, /**< IPv4 family */ - PDN_FAM_IPV6 = 1, /**< IPv6 family */ - PDN_FAM_IPV4V6 = 2, /**< IPv4 and IPv6 family */ - PDN_FAM_NONIP = 3, /**< Non-IP family */ + PDN_FAM_IPV4 = 0, /**< IPv4 */ + PDN_FAM_IPV6 = 1, /**< IPv6 */ + PDN_FAM_IPV4V6 = 2, /**< IPv4 and IPv6 */ + PDN_FAM_NONIP = 3, /**< Non-IP */ }; -/** @brief Additional PDP Context configuration options */ +/** @brief Additional Packet Data Protocol (PDP) context configuration options */ struct pdn_pdp_opt { /** * @brief IPv4 address allocation. @@ -55,9 +55,9 @@ struct pdn_pdp_opt { }; /** - * @brief PDN context dynamic information structure. + * @brief PDN connection dynamic information structure. * - * This structure holds dynamic information about the PDN context. + * This structure holds dynamic information about the PDN connection. */ struct pdn_dynamic_info { /** @@ -100,32 +100,33 @@ enum pdn_event { PDN_EVENT_IPV6_DOWN, /** Network detached */ PDN_EVENT_NETWORK_DETACH, - /** APN rate control is ON for given PDN */ + /** APN rate control is ON for the given PDN */ PDN_EVENT_APN_RATE_CONTROL_ON, - /** APN rate control is OFF for given PDN */ + /** APN rate control is OFF for the given PDN */ PDN_EVENT_APN_RATE_CONTROL_OFF, - /** PDP context is destroyed for given PDN. + /** PDP context is destroyed for the given PDN. * This happens if modem is switched to minimum functionality mode. */ PDN_EVENT_CTX_DESTROYED, }; -/** @brief PDN authentication method */ +/** @brief Authentication method */ enum pdn_auth { PDN_AUTH_NONE = 0, /**< No authentication */ - PDN_AUTH_PAP = 1, /**< Password authentication protocol */ - PDN_AUTH_CHAP = 2, /**< Challenge handshake authentication protocol */ + PDN_AUTH_PAP = 1, /**< Password Authentication Protocol (PAP) */ + PDN_AUTH_CHAP = 2, /**< Challenge-Handshake Authentication Protocol (CHAP) */ }; /** * @typedef pdn_event_handler_t * - * Event handler for PDN events. + * @brief Event handler for PDN events. + * * If assigned during PDP context creation, the event handler will receive - * status information relative to the Packet Data Network connection, + * status information relative to the PDN connection, * as reported by the AT notifications +CNEC and +GGEV. * - * This handler is executed by the same context that dispatches AT notifications. + * This handler is executed in the same context that dispatches AT notifications. * * @param cid The PDP context ID. * @param event The event. @@ -134,88 +135,95 @@ enum pdn_auth { typedef void (*pdn_event_handler_t)(uint8_t cid, enum pdn_event event, int reason); /** - * @brief Create a Packet Data Protocol (PDP) context. + * @brief Create a PDP context. * * If a callback is provided via the @p cb parameter, the library will * generate events from the +CNEC and +GGEV AT notifications to report - * state of the Packet Data Network (PDN) connection. + * state of the PDN connection. * * @param[out] cid The ID of the new PDP context. * @param cb Optional event handler. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_ctx_create(uint8_t *cid, pdn_event_handler_t cb); /** - * @brief Configure a Packet Data Protocol context. + * @brief Configure a PDP context. * * The PDN connection must be inactive when the PDP context is configured. * - * @param cid The PDP context to configure. - * @param apn The Access Point Name to configure the PDP context with. - * @param family The family to configure the PDN context for. - * @param opts Optional additional configuration options. + * @param cid The PDP context ID. + * @param apn The Access Point Name. + * @param family The address family. + * @param opts Additional configuration options. Optional, can be NULL. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_ctx_configure(uint8_t cid, const char *apn, enum pdn_fam family, struct pdn_pdp_opt *opts); /** - * @brief Set PDN connection authentication parameters. + * @brief Set PDP context authentication parameters. * - * @param cid The PDP context to set authentication parameters for. + * @param cid The PDP context ID. * @param method The desired authentication method. * @param user The username to use for authentication. * @param password The password to use for authentication. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_ctx_auth_set(uint8_t cid, enum pdn_auth method, const char *user, const char *password); /** - * @brief Destroy a Packet Data Protocol context. + * @brief Destroy a PDP context. * * The PDN connection must be inactive when the PDP context is destroyed. * - * @param cid The PDP context to destroy. + * @param cid The PDP context ID. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_ctx_destroy(uint8_t cid); /** - * @brief Activate a Packet Data Network (PDN) connection. + * @brief Activate a PDN connection. * - * @param cid The PDP context ID to activate a connection for. + * @param cid The PDP context ID. * @param[out] esm If provided, the function will block to return the ESM error reason. * @param[out] family If provided, the function will block to return @c PDN_FAM_IPV4 if only IPv4 * is supported, or @c PDN_FAM_IPV6 if only IPv6 is supported. * Otherwise, this value will remain unchanged. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_activate(uint8_t cid, int *esm, enum pdn_fam *family); /** - * @brief Deactivate a Packet Data Network (PDN) connection. + * @brief Deactivate a PDN connection. * * @param cid The PDP context ID. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_deactivate(uint8_t cid); /** - * @brief Retrieve the PDN ID for a given PDP Context. + * @brief Retrieve the PDN ID for a given PDP context. + * + * The PDN ID can be used to route traffic through a PDN connection. * - * The PDN ID can be used to route traffic through a Packet Data Network. + * @param cid The PDP context ID. * - * @param cid The context ID of the PDN connection. * @return int A non-negative PDN ID on success, or a negative errno otherwise. */ int pdn_id_get(uint8_t cid); /** - * @brief Retrieve dynamic parameters of a given PDP context. + * @brief Retrieve dynamic parameters of a given PDN connection. * - * @deprecated Use pdn_dynamic_info_get instead. + * @deprecated Use #pdn_dynamic_info_get instead. * * @param cid The PDP context ID. * @param[out] dns4_pri The address of the primary IPv4 DNS server. Optional, can be NULL. @@ -225,12 +233,12 @@ int pdn_id_get(uint8_t cid); * @return Zero on success or an error code on failure. */ __deprecated int pdn_dynamic_params_get(uint8_t cid, struct in_addr *dns4_pri, - struct in_addr *dns4_sec, unsigned int *ipv4_mtu); + struct in_addr *dns4_sec, unsigned int *ipv4_mtu); /** - * @brief Retrieve dynamic parameters of a given PDN context. + * @brief Retrieve dynamic parameters of a given PDN connection. * - * @param[in] cid The PDN context ID. + * @param[in] cid The PDP context ID. * @param[out] pdn_info PDN dynamic info. * * @return Zero on success or an error code on failure. @@ -242,8 +250,9 @@ int pdn_dynamic_info_get(uint32_t cid, struct pdn_dynamic_info *pdn_info); * * The default APN is the APN of the default PDP context (zero). * - * @param[out] buf The buffer to copy the APN into. + * @param[out] buf The buffer to copy the APN into. The string is null-terminated. * @param len The size of the output buffer. + * * @return int Zero on success or a negative errno otherwise. */ int pdn_default_apn_get(char *buf, size_t len); @@ -252,6 +261,8 @@ int pdn_default_apn_get(char *buf, size_t len); * @brief Register a callback for events pertaining to the default PDP context (zero). * * @param cb The PDN event handler. + * + * @return int Zero on success or a negative errno otherwise. */ int pdn_default_ctx_cb_reg(pdn_event_handler_t cb); @@ -259,6 +270,8 @@ int pdn_default_ctx_cb_reg(pdn_event_handler_t cb); * @brief Deregister a callback for events pertaining to the default PDP context (zero). * * @param cb The PDN event handler. + * + * @return int Zero on success or a negative errno otherwise. */ int pdn_default_ctx_cb_dereg(pdn_event_handler_t cb); @@ -268,6 +281,7 @@ int pdn_default_ctx_cb_dereg(pdn_event_handler_t cb); * @brief Retrieve a statically allocated textual description for a given ESM error reason. * * @param reason ESM error reason. + * * @return const char* ESM error reason description. * If no textual description for the given error is found, * a placeholder string is returned instead. diff --git a/lib/pdn/Kconfig b/lib/pdn/Kconfig index e621e8b47d5..172bdbf8207 100644 --- a/lib/pdn/Kconfig +++ b/lib/pdn/Kconfig @@ -38,15 +38,15 @@ config PDN_DEFAULT_APN string "Access point name (APN)" choice - prompt "Family" + prompt "Address family" default PDN_DEFAULT_FAM_IPV4V6 config PDN_DEFAULT_FAM_IPV4 - bool "IPV4" + bool "IPv4" config PDN_DEFAULT_FAM_IPV6 - bool "IPV6" + bool "IPv6" config PDN_DEFAULT_FAM_IPV4V6 - bool "IPV4V6" + bool "IPv4v6" config PDN_DEFAULT_FAM_NONIP bool "Non-IP" diff --git a/lib/pdn/esm.c b/lib/pdn/esm.c index 6c02aecc2a5..1baf61a74ca 100644 --- a/lib/pdn/esm.c +++ b/lib/pdn/esm.c @@ -7,8 +7,8 @@ #include /* From the specification: - * 3GPP TS 24.301 version 8.7.0 - * EMM cause, 9.9.3.9 + * 3GPP TS 24.301 version 14.10.0 + * ESM cause information element, table 9.9.4.4.1 */ static const struct { @@ -49,7 +49,6 @@ static const struct { { 0x3a, "PDN type non IP only allowed" }, { 0x3b, "Unsupported QCI value" }, { 0x3c, "Bearer handling not supported" }, - { 0x3d, "PDN type Ethernet only allowed" }, { 0x41, "Maximum number of EPS bearers reached" }, { 0x42, "Requested APN not supported in current RAT and PLMN combination" }, { 0x51, "Invalid PTI value" },