cmake: extensions: board revisions can be optional

Add a new option to `board_check_revision` that can make specifying a
board revision optional. This makes it easier to work with boards that
can come in a base variant with extensions. For example Fanstel BLE
modules that come with/without power amplifiers.

Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>

cmake/modules/extensions.cmake

@@ -863,6 +863,11 @@ endfunction()
 # command line, which means:
 # 1.0.0 == 1.0 == 1
 #
+# OPTIONAL: Revision specifier is optional. If revision is not provided the base
+# board will be used. If both `EXACT` and `OPTIONAL` are given, then
+# specifying the revision is optional, but if it is given then the
+# `EXACT` requirements apply. Mutually exclusive with `DEFAULT_REVISION`.
+#
 # EXACT: Revision is required to be an exact match. As example, available revisions are:
 # 0.1.0 and 0.3.0, and user provides 0.2.0, then an error is reported
 # when `EXACT` is given.
@@ -890,15 +895,21 @@ endfunction()
 # will be used as a valid revision for the board.
 #
 function(board_check_revision)
- set(options EXACT)
+ set(options OPTIONAL EXACT)
  set(single_args FORMAT DEFAULT_REVISION HIGHEST_REVISION)
  set(multi_args VALID_REVISIONS)
  cmake_parse_arguments(BOARD_REV "${options}" "${single_args}" "${multi_args}" ${ARGN})
 
  string(TOUPPER ${BOARD_REV_FORMAT} BOARD_REV_FORMAT)
 
+ if(DEFINED BOARD_REV_DEFAULT_REVISION AND BOARD_REV_OPTIONAL)
+ message(FATAL_ERROR "Arguments BOARD_REVISION and OPTIONAL are mutually exclusive")
+ endif()
+
  if(NOT DEFINED BOARD_REVISION)
- if(DEFINED BOARD_REV_DEFAULT_REVISION)
+ if(BOARD_REV_OPTIONAL)
+ return()
+ elseif(DEFINED BOARD_REV_DEFAULT_REVISION)
  set(BOARD_REVISION ${BOARD_REV_DEFAULT_REVISION})
  set(BOARD_REVISION ${BOARD_REVISION} PARENT_SCOPE)
  else()

doc/hardware/porting/board_porting.rst

@@ -695,7 +695,7 @@ board_check_revision() details
 .. code-block:: cmake
 
  board_check_revision(FORMAT <LETTER | NUMBER | MAJOR.MINOR.PATCH>
- [EXACT]
+ [OPTIONAL EXACT]
  [DEFAULT_REVISION <revision>]
  [HIGHEST_REVISION <revision>]
  [VALID_REVISIONS <revision> [<revision> ...]]
@@ -712,6 +712,12 @@ This function supports the following arguments:
  ambiguity, so only :file:`<board>_1_0_0.conf` and
  :file:`<board>_1_0_0.overlay` are allowed.
 
+* ``OPTIONAL``: if given, a revision is not required to be specified.
+ If the revision is not supplied, the base board is used with no overlays.
+ Can be combined with ``EXACT``, in which case providing the revision is
+ optional, but if given the ``EXACT`` rules apply. Mutually exclusive with
+ ``DEFAULT_REVISION``.
+
 * ``EXACT``: if given, the revision is required to be an exact match.
  Otherwise, the closest matching revision not greater than the user's choice
  will be selected.