UCS/CONFIG: Support numeric ranges for devices by guy-ealey-morag · Pull Request #11340 · openucx/ucx

guy-ealey-morag · 2026-04-14T12:40:46Z

What?

Add support numeric ranges for devices (e.g.. mlx5_[0-2]) with UCX_*_DEVICES environment variables (NET_DEVICES, SHM_DEVICES, ACC_DEVICES, SELF_DEVICES).

Why?

This makes it easier to specify multiple related devices easily, for example:
UCX_NET_DEVICES=mlx5_[1-3] instead of UCX_NET_DEVICES=mlx5_1,mlx5_2,mlx5_3

How?

Added a new config type UCS_CONFIG_TYPE_ALLOW_LIST_WITH_RANGES that detects the numeric range pattern in the list and expands it to the different items of the range.

Note:
Range expansion was originally planned to be implemented as a generic api in string and string_buffer (#11215), but due to increasing complexity in the generic implementation, it is put on hold for now and the non-generic design is prioritized instead.

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

ColinNV

If the tests pass...

ColinNV · 2026-04-15T09:03:48Z

+                                       unsigned expected_device_idx)
+    {
+        for (unsigned i = 0; i < count; ++i) {
+            std::string const device_name = build_mlx5_device_name(i);


East const?

ColinNV · 2026-04-15T09:09:20Z

+        "a[0-A]b",       "a[-]b",     "[]",         "[-1-2-]",        "[--]",
+        "[1-2][3-4]",    "[4-8][",    "[5-6]]",     "][4-5]",         "[[0-4]]",
+        "a[0-4]b[6-8]c", "a[5-2]b",   "[10-0]",     "ab[100-1]suffix"
+    };


const and "a[-4]", "[-4]", "foo[]]", "[]]", "a-]", "a[-", "a[4-]", "a[4-6" which is not exhaustive but surely sufficient (as is your list).

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

tomerg-nvidia · 2026-04-15T09:06:13Z

+    ucs_assertv(delim[0] != '\0', "delimiter cannot be empty");
+    ucs_assertv(strlen(delim) == 1, "delimiter must be a single character");


Wouldn't it be better to have delim as char instead of const char *?

This arg was actually only recently added (#11206)

Changing it to char would require putting it into a null-terminated string to be able to use it with strspn, strpbrk, ucs_string_buffer_for_each_token because they take a set of delimiters as argument.

The asserts are here to make sure there is a single delimiter given because we use it to build the output.

Let me know if you still think it's worth changing it.

brminich · 2026-04-21T11:28:00Z

-            ucs_free(str_dup);
-            return 0;
+    UCS_INIT_ONCE(&regex_init) {
+        ret = regcomp(&range_regex,


should we call regfree somewhere?

Moved the regex object to the file scope and added it to the cleanup logic

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

tvegas1 · 2026-04-21T12:39:47Z

+                      "\\[([0-9]+)-([0-9]+)\\]" /* range */
+                      "([^][]*)$" /* suffix */,
+                      REG_EXTENDED);
+        ucs_assertv(ret == 0, "failed to compile range regex: %d", ret);


always or fatal?

I expect it to never fail if it passes in CI, but I changed it to a fatal error for robustness

tvegas1 · 2026-04-21T12:40:54Z

+    pmatch[0].rm_so = 0;
+    pmatch[0].rm_eo = (regoff_t)token_len;
+
+    ret = regexec(&ucs_config_range_regex, token, 5, pmatch, REG_STARTEND);


ucs_static_array_size() for all 5

tvegas1 · 2026-04-21T12:50:59Z

+            break;
+        }
+
+        count_total += ucs_config_array_expand_range(strb, p, next - p, delim,


can we make any truncation (reaching max_elements) logged, to help quickly understanding over/mis use?

Added warning log with matching tests

tvegas1 · 2026-04-21T13:04:54Z

+
+    snprintf(buf, max,
+             "comma-separated list (use \"all\" for including all items, "
+             "\'^\' for negation, or \'prefix[start-end]suffix\' for ranges) "


maybe reverse order like: use 'all' for all items, prefic[s-e]suffix for ranges, start with ^ for negation?

tvegas1 · 2026-04-21T13:15:49Z

+    return 1;
+}
+
+static void ucs_config_array_expand_ranges(ucs_string_buffer_t *strb,


some systems have: rocep124s0, rocep193s0, rocep125s0, rocep194s0. in that case worth noting that expansion could lead to needing many entries. rocep[124-193]s0 for instance.

In this case the best we can do right now is rocep[124-125]s0,rocep[193-194]s0.
If it's very common we can think of extending this feature to support multiple ranges,
something like rocep[123-124,193-194]s0.
What do you think?

tvegas1 · 2026-04-21T13:16:54Z

+    ucs_assertv(strlen(delim) == 1, "delimiter must be a single character");
+
+    if (expand_ranges) {
+        ucs_config_array_expand_ranges(&strb, buf, delim, UCS_CONFIG_ARRAY_MAX);


for my understanding, after expansion, does it lead to output logs stating that specified devices are unknown, in case they would not be there?

Yes, it's one of the requirements to keep these warnings for ranges as well.
I updated the test test_nonexistent_device_warning to include a range as well

tvegas1 · 2026-04-21T13:30:15Z

+UCS_TEST_P(test_ucp_devices_config_mlx5, duplicate_device_warning_two_ranges)
+{
+    test_duplicate_device_warning({"mlx5_0:1", "mlx5_1:1", "mlx5_2:1"},
+                                  "mlx5_[0-1],mlx5_[1-2]", "mlx5_1");


for my understanding does range support mlx5_[0-1]:2? if yes could we add test if not already there?

Yes, but do you know if these devices exist in the CI setup?

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

…sing Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

ColinNV · 2026-04-21T17:49:09Z

+                                           const char *input, const char *delim,
+                                           size_t max_elements)
+{
+    size_t count_total = 0;


Minotr: num_elements would be more intuitive to be compared against max_elements?

guy-ealey-morag added 2 commits April 14, 2026 11:15

UCS/CONFIG: Apply changes from other branch

811a2fc

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

UCS/CONFIG: Implement range expansion and add tests

6c8d7f1

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

guy-ealey-morag requested review from ColinNV, brminich, iyastreb, tvegas1 and yosefe April 14, 2026 12:41

UCX/TEST: Revert auto-formatting

dcedc34

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

guy-ealey-morag force-pushed the support-device-ranges-refactor branch from 1a6d926 to dcedc34 Compare April 14, 2026 12:49

guy-ealey-morag added 2 commits April 14, 2026 15:21

UCS/CONFIG: Remove unused calc

9804264

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

UCS/CONFIG: Fix comment format

96eb967

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

ColinNV approved these changes Apr 15, 2026

View reviewed changes

UCS/TEST: Fix PR comments

bb73f68

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

tomerg-nvidia approved these changes Apr 15, 2026

View reviewed changes

brminich reviewed Apr 21, 2026

View reviewed changes

UCS/CONFIG: Add cleanup for range regex

71afd89

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

tvegas1 reviewed Apr 21, 2026

View reviewed changes

guy-ealey-morag added 5 commits April 21, 2026 14:47

UCS/CONFIG: Use ucs_static_array_size

a31ee43

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

UCS/CONFIG: Update help text

6cf2d42

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

UCS/CONFIG: Warn when array is truncated

546292b

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

TEST/UCS: Test warning message for truncation

08f65e5

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

TEST/UCP: Add range to nonexistent_device_warning test

64cbd9f

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

guy-ealey-morag requested review from ColinNV, brminich, tomerg-nvidia and tvegas1 April 21, 2026 16:07

guy-ealey-morag added 2 commits April 21, 2026 17:15

UCS/CONFIG: Emit truncated warning from top level, refactor preproces…

d803deb

…sing Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

UCS/CONFIG: Change assert to fatal error

966a0ae

Signed-off-by: Guy Ealey Morag <gealeymorag@nvidia.com>

ColinNV approved these changes Apr 21, 2026

View reviewed changes

		ucs_assertv(delim[0] != '\0', "delimiter cannot be empty");
		ucs_assertv(strlen(delim) == 1, "delimiter must be a single character");

Conversation

guy-ealey-morag commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Uh oh!

ColinNV left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guy-ealey-morag Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guy-ealey-morag Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guy-ealey-morag Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guy-ealey-morag Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

guy-ealey-morag commented Apr 14, 2026 •

edited

Loading

guy-ealey-morag Apr 15, 2026 •

edited

Loading

guy-ealey-morag Apr 21, 2026 •

edited

Loading

guy-ealey-morag Apr 21, 2026 •

edited

Loading

guy-ealey-morag Apr 21, 2026 •

edited

Loading