app: Add version file and releasing information

MarkusLassila · MarkusLassila · commit 831dcdf4aff9 · 2026-06-02T09:20:46.000+03:00
- Added version file, which is used in application rollback
  prevention.

- Changed AT#XSMVER to use VERSION_MAJOR.VERSION_MINOR.PATCHLEVEL
  from version file. The format of the #XSMVER stays the same, and
  the remainder comes from git describe as previously.

- Added information on how to modify version file and MCUboot
  monotonic counter for releases.

Signed-off-by: Markus Lassila &lt;markus.lassila@nordicsemi.no&gt;
diff --git a/app/VERSION b/app/VERSION
@@ -0,0 +1,5 @@
+VERSION_MAJOR = 1
+VERSION_MINOR = 99
+PATCHLEVEL = 0
+VERSION_TWEAK = 0
+EXTRAVERSION =
diff --git a/app/cmake/sm_version.cmake b/app/cmake/sm_version.cmake
@@ -16,7 +16,8 @@ endif()
 add_custom_target(
     generate_version_header ALL
     COMMAND ${CMAKE_COMMAND}
-            -D OUTPUT_FILE=${GENERATED_DIR}/sm_version.h
+            -DOUTPUT_FILE=${GENERATED_DIR}/sm_version.h
+            -DVERSION_FILE=${PROJECT_SOURCE_DIR}/VERSION
             -P ${PROJECT_SOURCE_DIR}/cmake/write_sm_version_header.cmake
     BYPRODUCTS ${GENERATED_DIR}/sm_version.h
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
diff --git a/app/cmake/write_sm_version_header.cmake b/app/cmake/write_sm_version_header.cmake
@@ -18,12 +18,45 @@ if(NOT GIT_RESULT EQUAL 0)
   set(GIT_DESCRIBE "unknown")
 endif()
 
-# Validate OUTPUT_FILE variable is set
 if(NOT DEFINED OUTPUT_FILE)
   message(FATAL_ERROR "OUTPUT_FILE must be defined")
 endif()
 
-# Prepare header content
+set(SM_VERSION "${GIT_DESCRIBE}")
+
+if(DEFINED VERSION_FILE)
+  file(READ "${VERSION_FILE}" VERSION_CONTENT)
+  if(VERSION_CONTENT MATCHES "VERSION_MAJOR = ([0-9]+)")
+    set(VERSION_MAJOR ${CMAKE_MATCH_1})
+  else()
+    message(FATAL_ERROR "Could not parse VERSION_MAJOR from ${VERSION_FILE}")
+  endif()
+  if(VERSION_CONTENT MATCHES "VERSION_MINOR = ([0-9]+)")
+    set(VERSION_MINOR ${CMAKE_MATCH_1})
+  else()
+    message(FATAL_ERROR "Could not parse VERSION_MINOR from ${VERSION_FILE}")
+  endif()
+  if(VERSION_CONTENT MATCHES "PATCHLEVEL = ([0-9]+)")
+    set(PATCHLEVEL ${CMAKE_MATCH_1})
+  else()
+    message(FATAL_ERROR "Could not parse PATCHLEVEL from ${VERSION_FILE}")
+  endif()
+
+  # Append git describe suffix to v{major}.{minor}.{patch} from VERSION.
+  # Drop the nearest-tag prefix; keep only distance/hash (or nothing on exact tag).
+  set(GIT_SUFFIX "")
+  # e.g. v2.0.0-preview1-67-g0b82ed3-dirty -> -67-g0b82ed3-dirty
+  if(GIT_DESCRIBE MATCHES "-[0-9]+-g[0-9a-fA-F]+(-dirty)?$")
+    string(REGEX MATCH "-[0-9]+-g[0-9a-fA-F]+(-dirty)?$" GIT_SUFFIX "${GIT_DESCRIBE}")
+  # No tags: git describe --always -> 0b82ed3[-dirty] -> -g0b82ed3[-dirty]
+  elseif(GIT_DESCRIBE MATCHES "^[0-9a-fA-F]+(-dirty)?$")
+    set(GIT_SUFFIX "-g${GIT_DESCRIBE}")
+  # Exact tag (e.g. v2.0.0) or unknown: GIT_SUFFIX stays empty -> v2.0.0
+  endif()
+
+  set(SM_VERSION "v${VERSION_MAJOR}.${VERSION_MINOR}.${PATCHLEVEL}${GIT_SUFFIX}")
+endif()
+
 set(HEADER_TEXT
 "/*
  * Copyright (c) 2025 Nordic Semiconductor ASA
@@ -34,11 +67,10 @@ set(HEADER_TEXT
 #ifndef SM_VERSION_H
 #define SM_VERSION_H
 
-#define SM_VERSION \"${GIT_DESCRIBE}\"
+#define SM_VERSION \"${SM_VERSION}\"
 
 #endif /* SM_VERSION_H */
 
 ")
 
-# Write to output file
 file(WRITE "${OUTPUT_FILE}" "${HEADER_TEXT}")
diff --git a/app/prj.conf b/app/prj.conf
@@ -13,6 +13,7 @@ CONFIG_PICOLIBC_IO_FLOAT=y
 CONFIG_RING_BUFFER=y
 CONFIG_REBOOT=y
 CONFIG_EVENTFD=y
+CONFIG_NCS_APPLICATION_BOOT_BANNER_STRING="Serial Modem"
 
 # Enable UART logging by default.
 CONFIG_UART_CONSOLE=y
diff --git a/app/src/sm_at_commands.c b/app/src/sm_at_commands.c
@@ -75,12 +75,12 @@ STATIC int handle_at_smver(enum at_parser_cmd_type cmd_type, struct at_parser *,
 
 	if (cmd_type == AT_PARSER_CMD_TYPE_SET) {
 		if (strlen(CONFIG_SM_CUSTOMER_VERSION) > 0) {
-			rsp_send("\r\n#XSMVER: %s,%s,\"%s\"\r\n",
-				 STRINGIFY(SM_VERSION), STRINGIFY(NCS_VERSION_STRING),
+			rsp_send("\r\n#XSMVER: \"%s\",\"%s\",\"%s\"\r\n",
+				 SM_VERSION, NCS_VERSION_STRING,
 				 CONFIG_SM_CUSTOMER_VERSION);
 		} else {
-			rsp_send("\r\n#XSMVER: %s,%s\r\n",
-				 STRINGIFY(SM_VERSION), STRINGIFY(NCS_VERSION_STRING));
+			rsp_send("\r\n#XSMVER: \"%s\",\"%s\"\r\n",
+				 SM_VERSION, NCS_VERSION_STRING);
 		}
 		ret = 0;
 	}
diff --git a/app/sysbuild/mcuboot/prj.conf b/app/sysbuild/mcuboot/prj.conf
@@ -27,6 +27,7 @@ CONFIG_FPROTECT=y
 CONFIG_LOG=y
 CONFIG_LOG_MODE_MINIMAL=y
 CONFIG_MCUBOOT_LOG_LEVEL_INF=y
+CONFIG_NCS_APPLICATION_BOOT_BANNER_STRING="MCUboot"
 ### Decrease footprint by ~4 KB in comparison to CBPRINTF_COMPLETE=y
 CONFIG_CBPRINTF_NANO=y
 CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT=0
diff --git a/app/tests/at_commands/CMakeLists.txt b/app/tests/at_commands/CMakeLists.txt
@@ -13,7 +13,8 @@ file(MAKE_DIRECTORY "${GENERATED_DIR}")
 add_custom_target(
     generate_version_header ALL
     COMMAND ${CMAKE_COMMAND}
-            -D OUTPUT_FILE=${GENERATED_DIR}/sm_version.h
+            -DOUTPUT_FILE=${GENERATED_DIR}/sm_version.h
+            -DVERSION_FILE=${CMAKE_CURRENT_SOURCE_DIR}/VERSION
             -P ${CMAKE_CURRENT_SOURCE_DIR}/../../cmake/write_sm_version_header.cmake
     BYPRODUCTS ${GENERATED_DIR}/sm_version.h
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../..
diff --git a/app/tests/at_commands/VERSION b/app/tests/at_commands/VERSION
@@ -0,0 +1 @@
+../../VERSION
diff --git a/app/tests/at_socket/CMakeLists.txt b/app/tests/at_socket/CMakeLists.txt
@@ -15,7 +15,8 @@ file(MAKE_DIRECTORY "${GENERATED_DIR}")
 add_custom_target(
     generate_version_header ALL
     COMMAND ${CMAKE_COMMAND}
-            -D OUTPUT_FILE=${GENERATED_DIR}/sm_version.h
+            -DOUTPUT_FILE=${GENERATED_DIR}/sm_version.h
+            -DVERSION_FILE=${CMAKE_CURRENT_SOURCE_DIR}/VERSION
             -P ${CMAKE_CURRENT_SOURCE_DIR}/../../cmake/write_sm_version_header.cmake
     BYPRODUCTS ${GENERATED_DIR}/sm_version.h
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../..
diff --git a/app/tests/at_socket/VERSION b/app/tests/at_socket/VERSION
@@ -0,0 +1 @@
+../../VERSION
diff --git a/doc/app/README.rst b/doc/app/README.rst
@@ -70,6 +70,7 @@ See the subpages for how to use the application, how to extend it, and informati
    sm_build_and_run
    sm_logging
    sm_configuration
+   sm_releasing
    sm_cellular_modem
    sm_data_mode
    sm_extending
diff --git a/doc/app/at_dfu.rst b/doc/app/at_dfu.rst
@@ -281,9 +281,9 @@ The following example shows a complete application firmware update:
 
 .. code-block:: none
 
-   // Note the current firmware version of the application
+   // Note the current application version (major.minor.patch from app/VERSION)
    AT#XSMVER
-   #XSMVER: "v2.0.0-preview1-7-gdf00f46-dirty","3.3.0-rc1"
+   #XSMVER: "v1.99.0-7-gdf00f46-dirty","3.3.0-rc1"
    OK
 
    // Initialize DFU for application firmware (total size 123456 bytes)
@@ -316,9 +316,9 @@ The following example shows a complete application firmware update:
    OK
    Ready
 
-   // Verify that the application is running the new firmware
+   // Verify the VERSION prefix increased (here 1.99.0 -> 1.99.1)
    AT#XSMVER
-   #XSMVER: "v2.0.0-preview2-8-f0gd0f46-dirty","3.3.0-rc1"
+   #XSMVER: "v1.99.1-8-gf0fd0f46-dirty","3.3.0-rc1"
    OK
 
 Delta modem firmware update
diff --git a/doc/app/at_generic.rst b/doc/app/at_generic.rst
@@ -155,6 +155,8 @@ Test command
 
 The test command is not supported.
 
+.. _SM_AT_XSMVER:
+
 |SM| version #XSMVER
 =====================
 
@@ -177,9 +179,15 @@ Response syntax
 
 ::
 
-   #XSMVER: <sm_version>,<ncs_version>[,<customer_version>]
+   #XSMVER: "<sm_version>","<ncs_version>"[,"<customer_version>"]
+
+The ``<sm_version>`` parameter is the version of the |SM| application in Git-describe style.
+The ``major.minor.patch`` prefix comes from :file:`app/VERSION`; the optional ``-N-g<hash>`` suffix (and ``-dirty``) comes from ``git describe`` in the application tree.
+Example: ``"v1.99.0-68-gb2d3dde4dfa2"`` uses ``1.99.0`` from :file:`app/VERSION` and ``-68-gb2d3dde4dfa2`` from Git.
 
-The ``<sm_version>`` parameter is the version of the |SM| application.
+Hosts can use that ``major.minor.patch`` prefix to verify that application DFU moved to a newer image (compare ``AT#XSMVER`` before and after update).
+MCUboot applies the same ordering using the sign version from :file:`app/VERSION` (``major.minor.patch+tweak``); the Git suffix is not part of that check.
+See :ref:`sm_releasing` for release version updates.
 
 The ``<ncs_version>`` parameter is a string containing the version of the |NCS|.
 
@@ -192,19 +200,29 @@ The following command example reads the versions:
 
 ::
 
-   // Released build
+   // First v2.0.0 pre-release
    AT#XSMVER
-   #XSMVER: "v0.1.0","3.1.99"
+   #XSMVER: "v1.99.0","3.3.99"
    OK
 
    // Development build
    AT#XSMVER
-   #XSMVER: "v0.1.0-73-g0c2af8c-dirty","3.1.99"
+   #XSMVER: "v1.99.0-67-ga9e396bc3d58","3.3.99"
+   OK
+
+   // Second v2.0.0 pre-release (VERSION 1.99.1)
+   AT#XSMVER
+   #XSMVER: "v1.99.1","3.3.99"
+   OK
+
+   // v2.0.0 release
+   AT#XSMVER
+   #XSMVER: "v2.0.0","3.4.0"
    OK
 
-   // Released build with customer version
+   // Pre-release with customer version
    AT#XSMVER
-   #XSMVER: "v0.1.0","3.1.99","Onomondo 2.1.0"
+   #XSMVER: "v1.99.0","3.3.99","Onomondo 2.1.0"
    OK
 
 Read command
diff --git a/doc/app/sm_releasing.rst b/doc/app/sm_releasing.rst
@@ -0,0 +1,91 @@
+.. _sm_releasing:
+
+Releasing |SM|
+##############
+
+Before each official release or pre-release, update the following version metadata.
+Each published application image must carry a higher MCUboot sign version than the previous one on the same product line.
+Increment ``CONFIG_FW_INFO_FIRMWARE_VERSION`` only when the MCUboot bootloader image changes.
+
+Application - :file:`app/VERSION`
+=================================
+
+:file:`app/VERSION` is the single source of truth for:
+
+* The ``major.minor.patchlevel`` prefix in ``AT#XSMVER`` ``<sm_version>`` (Git-describe style: ``v`` + that triplet + optional ``-N-g<hash>`` from Git).
+* The MCUboot application sign version (``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION``, ``major.minor.patchlevel+VERSION_TWEAK``), used for application downgrade prevention during DFU.
+
+See `Zephyr application VERSION`_.
+
+DFU and ``AT#XSMVER``
+---------------------
+
+For application firmware update, a host can read ``AT#XSMVER`` before and after DFU and compare the ``major.minor.patchlevel`` prefix of ``<sm_version>`` (the part from :file:`app/VERSION`, before any ``-N-g<hash>`` Git suffix).
+That value must increase when moving to a newer published image.
+MCUboot enforces the same ordering using the sign version derived from :file:`app/VERSION`.
+The Git suffix is informational only and is not used for downgrade checks.
+
+Pre-release numbering
+---------------------
+
+Before General Availability (GA) for a target ``X.Y.Z``, use a staging line below ``X.Y.Z`` and increment ``PATCHLEVEL`` for each published pre-release.
+Keep ``VERSION_TWEAK = 0`` unless you have a specific reason to use it after GA.
+
+v2.0.0 GA
+~~~~~~~~~
+
+The first v2.0.0 pre-release uses ``1.99.0``, the second ``1.99.1``, and so on.
+At GA, set the product version to ``2.0.0``.
+
+.. code-block:: none
+
+   # First v2.0.0 pre-release
+   VERSION_MAJOR = 1
+   VERSION_MINOR = 99
+   PATCHLEVEL = 0
+   VERSION_TWEAK = 0
+
+.. code-block:: none
+
+   # Second v2.0.0 pre-release
+   VERSION_MAJOR = 1
+   VERSION_MINOR = 99
+   PATCHLEVEL = 1
+   VERSION_TWEAK = 0
+
+.. code-block:: none
+
+   # v2.0.0 release
+   VERSION_MAJOR = 2
+   VERSION_MINOR = 0
+   PATCHLEVEL = 0
+   VERSION_TWEAK = 0
+
+``2.0.0+0`` must be greater than every shipped ``1.99.N+0`` pre-release.
+
+Future v2.1.0 GA
+~~~~~~~~~~~~~~~~
+
+Pre-releases before v2.1.0 GA, use the ``2.0.99`` line (for example ``2.0.99``, then ``2.0.100``), incrementing ``PATCHLEVEL`` for each published pre-release, following the same pattern as ``1.99.0``, ``1.99.1`` before v2.0.0 GA.
+At v2.1.0 GA, set ``VERSION_MAJOR``, ``VERSION_MINOR``, and ``PATCHLEVEL`` to ``2``, ``1``, and ``0``.
+
+General Availability and later
+------------------------------
+
+The following guidelines describe how to manage versioning for General Availability and later:
+
+* Set the product version and ``VERSION_TWEAK = 0`` at GA.
+* After GA, increment ``PATCHLEVEL`` for each new published application build on that line.
+* Do not update version fields for unpublished local or CI builds.
+* Record the mapping between Git tag and :file:`app/VERSION` in the release notes,
+* Confirm the version with SM_AT_XSMVER.
+
+MCUboot — ``CONFIG_FW_INFO_FIRMWARE_VERSION``
+=============================================
+
+In :file:`app/sysbuild/mcuboot/prj.conf`, increment the value only when the MCUboot bootloader image changes.
+The value is used by NSIB (B0) for MCUboot slot downgrade prevention and is independent of :file:`app/VERSION`.
+
+After an MCUboot update, ``AT#XBOOTINFO=0`` reports the active slot value.
+
+See :ref:`serial_modem_release_notes` for more information.
diff --git a/doc/app/sm_testing.rst b/doc/app/sm_testing.rst
@@ -26,7 +26,7 @@ Complete the following steps to test the functionality provided by the :ref:`SM_
       :class: highlight
 
       **AT#XSMVER**
-      #XSMVER: "v0.1.0","3.1.99"
+      #XSMVER: "v1.99.0-67-ga9e396bc3d58","3.3.99"
       OK
 
 #. Retrieve a list of all supported proprietary AT commands.
diff --git a/doc/links.txt b/doc/links.txt
@@ -102,6 +102,7 @@
 .. _`Zephyr Modem modules`: https://docs.zephyrproject.org/latest/services/modem/index.html
 .. _`zperf: Network Traffic Generator`: https://docs.zephyrproject.org/latest/connectivity/networking/api/zperf.html
 .. _`Zephyr CMUX Power Saving`: https://docs.zephyrproject.org/latest/services/modem/index.html#cmux-power-saving
+.. _`Zephyr application VERSION`: https://docs.zephyrproject.org/latest/build/version/index.html#app-version-details
 
 .. ### github.com
 
diff --git a/doc/releases/migration_notes_v2.0.0.rst b/doc/releases/migration_notes_v2.0.0.rst
@@ -28,6 +28,15 @@ Informational changes
 
 The following changes are listed for informational purposes, and many hosts will work without any changes.
 
+* Application rollback prevention - Application firmware DFU now uses MCUboot downgrade prevention (``CONFIG_MCUBOOT_DOWNGRADE_PREVENTION``).
+  The device rejects signed application images older than the version currently running.
+  Set :file:`app/VERSION` before each published build; see :ref:`sm_releasing`.
+
+* ``AT#XSMVER`` - No change to the response layout for hosts.
+  ``<sm_version>`` is still a quoted Git-describe-style string (for example ``"v2.0.0-18-g2c85d9224fca"``).
+  Existing parsers can keep using it as in v1.x.x.
+  The ``major.minor.patch`` part now follows :file:`app/VERSION` (same value used for rollback prevention), the ``-N-g<hash>`` suffix still comes from Git.
+
 * Ring Indication (RI) - Change RI from pulse (100 ms) to level triggered, meaning RI stays asserted until the host asserts DTR.
   After the Serial Modem has enabled UART, RI will be deasserted.
 * nRF Cloud transport has been changed from MQTT to CoAP.
diff --git a/doc/releases/releases.rst b/doc/releases/releases.rst
@@ -5,6 +5,8 @@ Release notes
 
 For all the notable changes to the |SM|, see the `releases on GitHub <github_release_>`_.
 
+When preparing a release or pre-release build, see :ref:`sm_releasing`.
+
 .. toctree::
    :maxdepth: 2
    :caption: Subpages:
