1/*
2 * Copyright (c) 2026 Deveritec GmbH.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 *
7 */
8
9/**
10 * @file
11 * @brief Public DECT NR+ Radio Scheduler API
12 *
13 * @attention This file contains pseudo code for demonstration purposes.
14 * Definitions may be missing and in that case are only place
15 * holders for types representing related objects.
16 */
17
18#ifndef DECTNRP_SDLR_H_
19#define DECTNRP_SDLR_H_
20
21#include <net/net_pkt.h>
22#include "dectnrp_resources.h"
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28/**
29 * @defgroup dectnrp_sdlr DECT NR+ Scheduler
30 * @version 0.0.1
31 * @ingroup dectnrp
32 *
33 * @brief DECT NR+ scheduler API
34 *
35 * @details This API provides a common representation of implementation-specific
36 * schedulers of DECT NR+ L2.
37 * **Application developers should never interface directly with this API.** It
38 * is of interest to l2/dectnrp maintainers only.
39 *
40 * Implementing the basic scheduler API will ensure integration with the native L2
41 * stack.
42 *
43 * @note References are to the ETSI TS 103 636 DECTNRP NR+ V2.1.1 (2024-10) standard
44 * If not further noted all references in this file refer to ETSI TS 103 636-4.
45 *
46 * @{
47 */
48
49/**
50 * @brief Enumerate all events notified via dectnrp_sdlr_event_cb_t.
51 */
52enum dectnrp_sdlr_event {
53 /** Frame sync event. */
54 DECTNRP_EVENT_FRAME,
55 /** A message has been received. */
56 DECTNRP_EVENT_MSG_RX,
57 /** A message tx has been completed. */
58 DECTNRP_EVENT_MSG_TX_COMPL,
59};
60
61union dectnrp_sdlr_event_data {
62 union {
63 /** DECTNRP_EVENT_FRAME */
64 struct {
65 uint32_t frame_count;
66 /* More meta data */
67 } frame_sync;
68 /** DECTNRP_EVENT_MESSAGE_RECEIVED */
69 struct {
70 struct net_pkt *pkt;
71 const struct dectnrp_resource *resource;
72 /* More meta data */
73 int status;
74 } msg_recv;
75 /** DECTNRP_EVENT_MESSAGE_TX_COMPLETE */
76 struct {
77 struct net_pkt *pkt;
78 const struct dectnrp_resource *resource;
79 /* More meta data */
80 int status;
81 } msg_compl;
82 };
83};
84
85/** Event callback function */
86typedef void (*dectnrp_sdlr_event_cb_t)(struct dectnrp_context *ctx, enum dectnrp_sdlr_event evt,
87 union dectnrp_sdlr_event_data *event_data);
88
89/**
90 * @name DECTNRP scheduler interface API.
91 * @{
92 */
93
94/**
95 * @brief DECTNRP scheduler initialization.
96 * *
97 * @param sdlr Scheduler instance
98 * @param ctx The common dectnrp context the scheduler is running in.
99 * @param callback Callback used by the scheduler to notify events back.
100 *
101 */
102void dectnrp_sdlr_init(struct dectnrp_sdlr *sdlr, struct dectnrp_context *ctx,
103 dectnrp_sdlr_event_cb_t callback);
104
105/**
106 * @brief Returns the current state of the scheduler.
107 *
108 * @param sdlr Scheduler instance
109 * @return enum dectnrp_sdlr_state
110 */
111enum dectnrp_sdlr_state dectnrp_sdlr_get_state(struct dectnrp_sdlr *sdlr);
112
113/**
114 * @brief Schedules a rssi1 scan.
115 *
116 * @param sdlr Scheduler instance
117 * @return int success or negative error code
118 */
119int dectnrp_sdlr_schedule_rssi1scan(struct dectnrp_sdlr *sdlr);
120
121#if defined CONFIG_NET_L2_DECTNRP_FT
122
123/**
124 * @brief Returns current state of beaconing.
125 *
126 * @param sdlr Scheduler instance
127 * @return enum dectnrp_beaconing_state
128 */
129enum dectnrp_beaconing_state dectnrp_sdlr_get_beaconing_state(struct dectnrp_sdlr *sdlr);
130
131/**
132 * @brief Scheduler starts beaconing process and schedules first beacon.
133 *
134 * @param sdlr Scheduler instance
135 * @return int success or negative error code
136 */
137int dectnrp_sdlr_beaconing_start(struct dectnrp_sdlr *sdlr);
138
139/**
140 * @brief Scheduler stops beaconing process
141 *
142 * @param sdlr Scheduler instance
143 */
144int dectnrp_sdlr_beaconing_stop(struct dectnrp_sdlr *sdlr);
145
146#endif /* defined CONFIG_NET_L2_DECTNRP_FT */
147
148#if defined CONFIG_NET_L2_DECTNRP_PT
149
150/**
151 * @brief Returns the current state of the beacon-scan.
152 *
153 * @param sdlr Scheduler instance
154 * @return enum dectnrp_beaconscan_state
155 */
156enum dectnrp_beaconscan_state dectnrp_sdlr_get_beaconscan_state(struct dectnrp_sdlr *sdlr);
157
158/**
159 * @brief Scheduler starts beacon-scan process and schedules first beacon-scan.
160
161 * @param sdlr Scheduler instance
162 * @return int success or negative error code
163 */
164int dectnrp_sdlr_start_beaconscan(struct dectnrp_sdlr *sdlr);
165
166/**
167 * @brief Scheduler stops beacon-scan process.
168
169 * @param sdlr Scheduler instance
170 * @return int success or negative error code
171 */
172int dectnrp_sdlr_start_beaconscan(struct dectnrp_sdlr *sdlr);
173
174#endif /* defined CONFIG_NET_L2_DECTNRP_PT */
175
176/**
177 * @brief Creates a new tx operation with the given message packet @p pkt
178 * and put into into related tx message queue to wait for its scheduling.
179 *
180 * @param sdlr
181 * @param pkt the packet containing the tx buffer to be sent.
182 *
183 * @return int success or negative error code
184 */
185int dectnrp_sdlr_message_put(struct dectnrp_sdlr *sdlr, struct net_pkt *pkt
186 /* More meta data */ );
187
188/** @} */
189
190/** @} */
191
192#ifdef __cplusplus
193}
194#endif
195
196#endif /* DECTNRP_SDLR_H_ */