RFC: Subsystem: A new API for managing the lifecycle of software services

[vytvir]

Problem Description

I frequently need to implement common patterns for managing the lifecycle (e.g., starting, stopping, suspending) of distinct software components or modules. Currently, this is handled through ad-hoc, application-specific mechanisms, often involving custom message queues or direct function calls.

This leads to duplicated effort across different applications and a lack of a standardized, reusable approach within the Zephyr Project. Similar to how Zephyr provides a Power Management subsystem for hardware devices, a comparable framework for managing the state of software components would provide significant value.

Proposed Change (Summary)

The proposal is to introduce a new, optional subsystem called the Services API. It would provide a lightweight, iterable (via iterable sections) and configurable framework for defining self-contained software modules, referred to as "services".

Initially, it should be sufficient to provide:

• A SERVICE_DEFINE(...) macro, analogous to SYS_INIT(...), for declaring a new service.
• A standardized API to set and get the state of any services.
• A method for a service to expose a custom, service-specific API.

Alongside this, an optional Supervisor component can be included. It could be set to automatically start any services that are configured for autostart during the system's boot sequence.

In the future, the subsystem could be expanded with more features, including (in no specific order):

• Dependency Management.
• Health Monitoring.
• Resource Monitoring (e.g. Stack / CPU usage).
• State Notifications.
• Shell Integration.

PS. I'm not great at naming software components, so if you have a good suggestion - please share!

Proposed Change (Detailed)

Here is a very rough mock-up of what the first iteration of this could look like:

/* SPDX-License-Identifier: Apache-2.0 */

#ifndef SERVICES_H_
#define SERVICES_H_

#include <zephyr/kernel.h>
#include <zephyr/linker/sections.h>

struct service;

/* Standardized service states and requests */
typedef enum {
    SERVICE_STATE_STOPPED,
    SERVICE_STATE_RUNNING,
    SERVICE_STATE_SUSPENDED,
    SERVICE_STATE_ERROR,
} service_state_t;

typedef enum {
    SERVICE_REQUEST_START,
    SERVICE_REQUEST_STOP,
    SERVICE_REQUEST_SUSPEND,
} service_request_t;

/* The common API that every service must implement */
struct service_api {
    int (*set_state)(const struct service *svc, service_request_t request);
    service_state_t (*get_state)(const struct service *svc);
    const void *(*get_api)(const struct service *svc);
};

/* The common configuration for all services */
struct service_config {
    bool autostart;
};

/* The main registration struct for a service */
struct service {
    const char *name;
    const struct service_api *api;
    const struct service_config *config;
};

/**
 * @brief Defines and registers a new service.
 *
 * @param _handle       A unique C identifier for this service instance.
 * @param _name_str     The service's unique name string (from Kconfig).
 * @param _api_ptr      Pointer to the service_api struct.
 * @param _config_ptr   Pointer to the service_config struct.
 */
#define SERVICE_DEFINE(_handle, _name_str, _api_ptr, _config_ptr) \
	static const STRUCT_SECTION_ITERABLE(service, _service_##_handle) = { \
		.name = _name_str, \
		.api = _api_ptr, \
		.config = _config_ptr, \
	}

/**
 * @brief Retrieves a service instance by its string name.
 */
const struct service *services_get_by_name(const char *name);

/**
 * @brief Callback for iterating over services. Return true to continue.
 */
typedef bool (*service_visitor_t)(const struct service *svc, void *user_data);

/**
 * @brief Iterates over all registered services.
 */
void services_foreach(service_visitor_t visitor, void *user_data);

#endif /* SERVICES_H_ */

Example Kconfig.template.service:

# SPDX-License-Identifier: Apache-2.0

config $(module)_NAME
	string "Service Name"
	default "$(module | tolower)"
	help
	  Specifies the unique string name for this service.

config $(module)_AUTOSTART
	bool "Autostart $(module-str) service at boot"
	default y
	help
	  If enabled, the supervisor will automatically start this
	  service during system initialization.

Example service Kconfig:

# SPDX-License-Identifier: Apache-2.0

config SERVICE_MQTT
	bool "Enable MQTT Service"
	depends on SERVICES
	help
	  Enable this example MQTT service.

if SERVICE_MQTT

module = SERVICE_MQTT
module-str = "MQTT Service"

source "subsys/services/Kconfig.template.service"
source "subsys/logging/Kconfig.template.log_config"

endif # SERVICE_MQTT

We could also provide a default service supervisor. E.g.:

#if defined(CONFIG_SERVICES_SUPERVISOR_AUTOSTART)

#include <zephyr/logging/log.h>
LOG_MODULE_REGISTER(supervisor, CONFIG_SERVICES_SUPERVISOR_LOG_LEVEL);

/**
 * @brief Visitor function to autostart a single service.
 */
static bool autostart_visitor(const struct service *svc, void *user_data)
{
	if (svc->config && svc->config->autostart) {
		LOG_INF("Autostarting service: %s", svc->name);
		int err = svc->api->set_state(svc, SERVICE_REQUEST_START);
		if (err) {
			LOG_ERR("Failed to request start for service '%s' (err %d)",
				svc->name, err);
		}
	}

	/* Return true to continue iterating over other services */
	return true;
}

/**
 * @brief The SYS_INIT function for the default supervisor.
 */
static int services_supervisor_init(void)
{
	LOG_INF("Default services supervisor initializing...");
	services_foreach(autostart_visitor, NULL);
	return 0;
}

SYS_INIT(services_supervisor_init, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);

#endif /* CONFIG_SERVICES_SUPERVISOR_AUTOSTART */

Dependencies

This proposal shouldn't interfere with any existing components.

Concerns and Unresolved Questions

Without having a global enum with a service list, I currently rely on a configured-name (see _name_str below) to identify a service. Ideally, this could be some global unique number-based identifier, but I am not sure how to implement this.

#define SERVICE_DEFINE(_handle, _name_str, _api_ptr, _config_ptr)         \
	static const STRUCT_SECTION_ITERABLE(service, _service_##_handle) = { \
		.name = _name_str,                                                \
		.api = _api_ptr,                                                  \
		.config = _config_ptr,                                            \
	}

Alternatives Considered

I tried browsing through the Discord/Issues list, but I was not able to find anything similar discussed previously.

[github-actions]

Hi @vytvir! We appreciate you submitting your first issue for our open-source project. 🌟

Even though I'm a bot, I can assure you that the whole community is genuinely grateful for your time and effort. 🤖💙

[mbolivar]

Interesting. In my opinion it would be good to figure out the relationship with https://docs.zephyrproject.org/apidoc/latest/group__resource__mgmt__onoff__apis.html and see if we need to fold that into this, or go the other way around, or decide that they are orthogonal and document why, ...

[jukkar]

Isn't this somewhat similar as #97330

[vytvir]

Isn't this somewhat similar as #97330

From #79340

The new service API is extremely minimal as it is meant to just replace SYS_INIT where relevant (like, say: net_init, and not all the places where SYS_INIT should not have been used). BUT: it will grow, there are plenty of rooms for improvements. We could start/stop/pause a service if needed, etc etc...

So I guess I should sync-up with the author of that PR , it looks like there was some thought in this direction already, so perhaps I can expand upon his work.

@tbursztyka Thoughts?

[tbursztyka]

Hi @vytvir, while working on #79340 I indeed foresaw that the services could expand to something similar as your needs. But before we get to that, priority must disappear and we should get an easy way to bind hw/sw dependencies when relevant. Thus #79340. That one bit-rotted since, the proposal was perhaps too big at once. People are slow buyers sometime, which can be understandable, and the process to make such changes in Zephyr can be a tough one.

I am working on a new version on the side of my job, most of the work being making sure not breaking legacy features (even though they'll be obsoleted afterwards, and removed accordingly after 2-3 releases). And things is being done more iteratively (like #97330 to introduce the new object).

[vytvir]

@tbursztyka I wanted to discuss with you the potential API we could have for these services. Are you available on Discord, or should we have the discussion here?

[tbursztyka]

Let's discuss here, I am never on discord actually.

First things, looking at your proposal above, let's ditch the services_supervisor_init and let's go on with what I am proposing already. I.e.: integrating services into the init system.

This is way more flexible than a dedicated launcher, since it would keep the ability to manage dependency relations between services and devices. All possibilities would be tackled directly. For instance: the uart console needs the dedicated uart to be initialized first, then the shell needs the uart console, but also needs the device D to be initialized as the shell is going to expose commands about that device. etc...
That's basically what I am focusing on which, in turn, is going to remove the hardcoded init priority for all and for good.

After that, all is yours. start/stop/pause/...
About @mbolivar's idea, perhaps it makes sense to add the possibility to plug into on-off API but I would make it optional then (not everyone will need that). At least it would avoid redoing the wheel about notification etc..

Note that by integrating into the init system, we would benefit right away with runtime dependency management. So let's say you want to stop service X, but it requires service Y to be started first: it would do it automatically.

[vytvir]

@tbursztyka

let's ditch the services_supervisor_init and let's go on with what I am proposing already

Note that by integrating into the init system, we would benefit right away with runtime dependency management. So let's say you want to stop service X, but it requires service Y to be started first: it would do it automatically.

I fully agree. I just did not notice your PR's / Issues prior to creating the RFC, so I thought I was in uncharted waters. I am glad I can piggy-back on an already existing initiative.

This is way more flexible than a dedicated launcher, since it would keep the ability to manage dependency relations between services and devices.

I'm not too familiar with the implementation details of your proposal - how would this dependency management work? Is the intention to define services in Device Tree Config?

After that, all is yours. start/stop/pause/...

Should I work on top of your changes in #97330 ?

Another issue that I don't know how to resolve is the C handle (see excerpt from my example below):

#define SERVICE_DEFINE(_handle, _name_str, _api_ptr, _config_ptr)

In my original proposal, I used the _name_str to allow for a service_find_by_name(...). Ideally, we could drop the _name_str and reference a service via its handle, but I am not sure how to implement this in practice, such that we wouldn't need to hard-code the service name every time. E.g. service_find_by_name("mqtt_service", ...). Thoughts?

perhaps it makes sense to add the possibility to plug into on-off API

@mbolivar Reading the commits associated with the on-off API, it seems to me that it was primarily geared towards hardware devices. As I have never used it before, could you perhaps share an example use-case where it would fit into the service API?

[tbursztyka]

I'm not too familiar with the implementation details of your proposal - how would this dependency management work? Is the intention to define services in Device Tree Config?

No, that would go against DTC purposes. It's adding the possibility to express a dependency between a software node and a hardware one, via a concise yaml file, only if relevant. But in the end, no more hardcoded priority will be ever necessary: these will be computed automatically.

After that, all is yours. start/stop/pause/...

Should I work on top of your changes in #97330 ?

Sure

Another issue that I don't know how to resolve is the C handle (see excerpt from my example below):

#define SERVICE_DEFINE(_handle, _name_str, _api_ptr, _config_ptr)

In my original proposal, I used the _name_str to allow for a service_find_by_name(...). Ideally, we could drop the _name_str and reference a service via its handle, but I am not sure how to implement this in practice, such that we wouldn't need to hard-code the service name every time. E.g. service_find_by_name("mqtt_service", ...). Thoughts?

For this it will require the update I am planning on #79340 as such handles would be generated prior to compilation, exactly the same way as DT does. So for the time being just have a fixed name and a runtime look-up function. All in all, the service additions you want will take some time to fine-tune (and approved) and hopefully the update on #79340 will be in already. Let's see