From 6d50df1c7458fc58026fcf073a43812d94772133 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eivind=20J=C3=B8lsgard?= Date: Wed, 2 Oct 2024 09:41:34 +0200 Subject: [PATCH] lib: lte_lc: deprecate LTE_LC_ON_CFUN MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Deprecate LTE_LC_ON_CFUN. The application should instead use the NRF_MODEM_LIB_ON_CFUN macro. Signed-off-by: Eivind Jølsgard --- doc/nrf/libraries/modem/lte_lc.rst | 34 ------------------- .../nrf_modem_lib/nrf_modem_lib_wrapper.rst | 2 +- .../migration/migration_guide_2.8.rst | 1 + .../releases/release-notes-changelog.rst | 5 +++ include/modem/lte_lc.h | 2 ++ include/modem/nrf_modem_lib.h | 3 +- lib/sms/sms.c | 4 +-- samples/cellular/modem_callbacks/README.rst | 2 +- .../cellular/modem_trace_backend/src/main.c | 2 +- samples/cellular/modem_trace_flash/src/main.c | 2 +- 10 files changed, 14 insertions(+), 43 deletions(-) diff --git a/doc/nrf/libraries/modem/lte_lc.rst b/doc/nrf/libraries/modem/lte_lc.rst index b821dc1fdc2..5ed1420bf1c 100644 --- a/doc/nrf/libraries/modem/lte_lc.rst +++ b/doc/nrf/libraries/modem/lte_lc.rst @@ -184,40 +184,6 @@ To enable modem sleep and TAU pre-warning notifications, enable the following op For additional configurations related to these features, see the API documentation. -Functional mode changes callback -================================ - -The library allows the application to define compile-time callbacks to receive the modem's functional mode changes. -These callbacks allow any part of the application to perform certain operations when the modem enters or re-enters a certain functional mode using the library :c:func:`lte_lc_func_mode_set` API. -For example, one kind of operation that the application or a library may need to perform and repeat, whenever the modem enters a certain functional mode is the subscription to AT notifications. -The application can set up a callback for modem`s functional mode changes using the :c:macro:`LTE_LC_ON_CFUN` macro. - -.. important:: - When the :c:macro:`LTE_LC_ON_CFUN` macro is used, the application must not call :c:func:`nrf_modem_at_cfun_handler_set` as that will override the handler set by the modem library integration layer. - -.. note:: - The CFUN callback is not supported with :c:func:`nrf_modem_at_cmd_async`. - -The following code snippet shows how to use the :c:macro:`LTE_LC_ON_CFUN` macro: - -.. code-block:: c - - /* Define a callback */ - LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL); - - /* Callback implementation */ - static void on_cfun(enum lte_lc_func_mode mode, void *context) - { - printk("Functional mode changed to %d\n", mode); - } - - int main(void) - { - /* Change functional mode using the LTE link control API */ - lte_lc_func_mode_set(LTE_LC_FUNC_MODE_NORMAL); - return 0; - } - Dependencies ************ diff --git a/doc/nrf/libraries/modem/nrf_modem_lib/nrf_modem_lib_wrapper.rst b/doc/nrf/libraries/modem/nrf_modem_lib/nrf_modem_lib_wrapper.rst index 1331ebcc9ab..eda3866a08d 100644 --- a/doc/nrf/libraries/modem/nrf_modem_lib/nrf_modem_lib_wrapper.rst +++ b/doc/nrf/libraries/modem/nrf_modem_lib/nrf_modem_lib_wrapper.rst @@ -40,7 +40,7 @@ The result of the initialization and the callback context are provided to these The callback can be used to perform modem and library configurations that require the modem to be turned on in offline mode. The callback cannot be used to change the modem's functional mode. Calls to :c:func:`lte_lc_connect` and ``CFUN`` AT calls are not allowed, and must be done after :c:func:`nrf_modem_lib_init` has returned. - If a library needs to perform operations after the link is up, it can use the :ref:`lte_lc_readme` and subscribe to a :c:macro:`LTE_LC_ON_CFUN` callback. + If a library needs to perform operations after the link is up, it can use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` callback. Callbacks for the macro :c:macro:`NRF_MODEM_LIB_ON_INIT` must have the signature ``void callback_name(int ret, void *ctx)``, where ``ret`` is the result of the initialization and ``ctx`` is the context passed to the macro. The callbacks registered using the :c:macro:`NRF_MODEM_LIB_ON_SHUTDOWN` macro are executed before the library is shut down. diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst index 475826f300c..bde41c4ee40 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst @@ -109,6 +109,7 @@ LTE link control library * Replace the use of the :c:func:`lte_lc_deinit` function with the :c:func:`lte_lc_power_off` function. * Replace the use of the :c:func:`lte_lc_init_and_connect` function with the :c:func:`lte_lc_connect` function. * Replace the use of the :c:func:`lte_lc_init_and_connect_async` function with the :c:func:`lte_lc_connect_async` function. + * Replace the use of the :c:macro:`LTE_LC_ON_CFUN` macro with the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro. * Remove the use of the ``CONFIG_LTE_NETWORK_USE_FALLBACK`` Kconfig option. Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead. In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option. diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index f86e0787548..24156c9cf0c 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -718,6 +718,11 @@ Modem libraries Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead. In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option. + * Deprecated: + + * The :c:macro:`LTE_LC_ON_CFUN` macro. + Use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro instead. + * Added: * A new :c:enum:`LTE_LC_EVT_RAI_UPDATE` event that is enabled with the :kconfig:option:`CONFIG_LTE_RAI_REQ` Kconfig option. diff --git a/include/modem/lte_lc.h b/include/modem/lte_lc.h index 06c739059e2..0fe00d041fa 100644 --- a/include/modem/lte_lc.h +++ b/include/modem/lte_lc.h @@ -1178,6 +1178,8 @@ struct lte_lc_cfun_cb { * @param name Callback name. * @param _callback Callback function. * @param _context User-defined context. + * + * @deprecated since v2.8.0, use @ref NRF_MODEM_LIB_ON_CFUN instead. */ #define LTE_LC_ON_CFUN(name, _callback, _context) \ static void _callback(enum lte_lc_func_mode, void *ctx); \ diff --git a/include/modem/nrf_modem_lib.h b/include/modem/nrf_modem_lib.h index 936034431f0..9127a031069 100644 --- a/include/modem/nrf_modem_lib.h +++ b/include/modem/nrf_modem_lib.h @@ -166,8 +166,7 @@ struct nrf_modem_lib_at_cfun_cb { * configurations that require the modem to be turned on in offline mode. It cannot be used to * change the modem functional mode. Calls to @c lte_lc_connect and CFUN AT calls are not * allowed, and must be done after @c nrf_modem_lib_init has returned. If a library needs to - * perform operations after the link is up, it can use the link controller and subscribe to a - * @c LTE_LC_ON_CFUN callback. + * perform operations after the link is up, it can subscribe to a @c NRF_MODEM_LIB_ON_CFUN callback. * * @param name Callback name * @param _callback Callback function name diff --git a/lib/sms/sms.c b/lib/sms/sms.c index a192758a915..8885923090a 100644 --- a/lib/sms/sms.c +++ b/lib/sms/sms.c @@ -403,8 +403,7 @@ int sms_send(const char *number, const uint8_t *data, uint16_t data_len, enum sm return sms_submit_send(number, data, data_len, type); } -#if defined(CONFIG_LTE_LINK_CONTROL) -LTE_LC_ON_CFUN(sms_cfun_hook, sms_on_cfun, NULL); +NRF_MODEM_LIB_ON_CFUN(sms_cfun_hook, sms_on_cfun, NULL); static void sms_on_cfun(enum lte_lc_func_mode mode, void *ctx) { @@ -426,4 +425,3 @@ static void sms_on_cfun(enum lte_lc_func_mode mode, void *ctx) } } } -#endif /* CONFIG_LTE_LINK_CONTROL */ diff --git a/samples/cellular/modem_callbacks/README.rst b/samples/cellular/modem_callbacks/README.rst index bd10503e87f..cb4b72b107f 100644 --- a/samples/cellular/modem_callbacks/README.rst +++ b/samples/cellular/modem_callbacks/README.rst @@ -23,7 +23,7 @@ Overview The sample performs the following operations: -1. Registers callbacks during compile time for modem initialization, functional mode changes, and shutdown using the :c:macro:`NRF_MODEM_LIB_ON_INIT`, :c:macro:`LTE_LC_ON_CFUN` and :c:macro:`NRF_MODEM_LIB_ON_SHUTDOWN` macros respectively. +1. Registers callbacks during compile time for modem initialization, functional mode changes, and shutdown using the :c:macro:`NRF_MODEM_LIB_ON_INIT`, :c:macro:`NRF_MODEM_LIB_ON_CFUN` and :c:macro:`NRF_MODEM_LIB_ON_SHUTDOWN` macros respectively. #. Initializes the :ref:`nrfxlib:nrf_modem`. #. Changes functional mode using the :c:func:`lte_lc_func_mode_set` function in the :ref:`lte_lc_readme` library #. Shuts down the :ref:`nrfxlib:nrf_modem`. diff --git a/samples/cellular/modem_trace_backend/src/main.c b/samples/cellular/modem_trace_backend/src/main.c index 7fde3abe671..ea6afa8cfa1 100644 --- a/samples/cellular/modem_trace_backend/src/main.c +++ b/samples/cellular/modem_trace_backend/src/main.c @@ -10,7 +10,7 @@ #include /* define callback */ -LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL); +NRF_MODEM_LIB_ON_CFUN(cfun_hook, on_cfun, NULL); /* callback implementation */ static void on_cfun(enum lte_lc_func_mode mode, void *context) diff --git a/samples/cellular/modem_trace_flash/src/main.c b/samples/cellular/modem_trace_flash/src/main.c index a17e58915d9..e608ff23104 100644 --- a/samples/cellular/modem_trace_flash/src/main.c +++ b/samples/cellular/modem_trace_flash/src/main.c @@ -25,7 +25,7 @@ LOG_MODULE_REGISTER(modem_trace_flash_sample, CONFIG_MODEM_TRACE_FLASH_SAMPLE_LO static const struct device *const uart_dev = DEVICE_DT_GET(UART1_DT_NODE); -LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL); +NRF_MODEM_LIB_ON_CFUN(cfun_hook, on_cfun, NULL); /* Callback for when modem functional mode is changed */ static void on_cfun(enum lte_lc_func_mode mode, void *context)