components/esp_timer/include/esp_timer.h (ESP-IDF)

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

/* * SPDX-FileCopyrightText: 2017-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once /** * @file esp_timer.h * @brief microsecond-precision 64-bit timer API, replacement for ets_timer * * esp_timer APIs allow components to receive callbacks when a hardware timer * reaches certain value. The timer provides microsecond accuracy and * up to 64 bit range. Note that while the timer itself provides microsecond * accuracy, callbacks are dispatched from an auxiliary task. Some time is * needed to notify this task from timer ISR, and then to invoke the callback. * If more than one callback needs to be dispatched at any particular time, * each subsequent callback will be dispatched only when the previous callback * returns. Therefore, callbacks should not do much work; instead, they should * use RTOS notification mechanisms (queues, semaphores, event groups, etc.) to * pass information to other tasks. * * To be implemented: it should be possible to request the callback to be called * directly from the ISR. This reduces the latency, but has potential impact on * all other callbacks which need to be dispatched. This option should only be * used for simple callback functions, which do not take longer than a few * microseconds to run. * * Timer callbacks are called from a task running on CPU0. * On chips with multiple cores, CPU0 (default) can be changed using * the Kconfig option CONFIG_ESP_TIMER_TASK_AFFINITY. */ #include <stdint.h> #include <stdio.h> #include <stdbool.h> #include "esp_err.h" #include "esp_etm.h" #include "sdkconfig.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Opaque type representing a single timer handle */ typedef struct esp_timer* esp_timer_handle_t; /** * @brief Timer callback function type * @param arg pointer to opaque user-specific data */ typedef void (*esp_timer_cb_t)(void* arg); /** * @brief Method to dispatch timer callback */ typedef enum { ESP_TIMER_TASK, //!< Callback is dispatched from esp_timer task #if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || __DOXYGEN__ ESP_TIMER_ISR, //!< Callback is dispatched from interrupt handler #endif ESP_TIMER_MAX, //!< Sentinel value for the number of callback dispatch methods } esp_timer_dispatch_t; /** * @brief Timer configuration passed to esp_timer_create() */ typedef struct { esp_timer_cb_t callback; //!< Callback function to execute when timer expires void* arg; //!< Argument to pass to callback esp_timer_dispatch_t dispatch_method; //!< Dispatch callback from task or ISR; if not specified, esp_timer task // !< is used; for ISR to work, also set Kconfig option // !< `CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD` const char* name; //!< Timer name, used in esp_timer_dump() function bool skip_unhandled_events; //!< Setting to skip unhandled events in light sleep for periodic timers } esp_timer_create_args_t; /** * @brief Minimal initialization of esp_timer * * @note This function is called from startup code. Applications do not need * to call this function before using other esp_timer APIs. * * This function can be called very early in startup process, after this call * only esp_timer_get_time() function can be used. * * @return * - ESP_OK on success */ esp_err_t esp_timer_early_init(void); /** * @brief Initialize esp_timer library * * @note This function is called from startup code. Applications do not need * to call this function before using other esp_timer APIs. * Before calling this function, esp_timer_early_init() must be called by the * startup code. * * This function will be called from startup code on every core. * If Kconfig option `CONFIG_ESP_TIMER_ISR_AFFINITY` is set to `NO_AFFINITY`, * it allocates the timer ISR on MULTIPLE cores and * creates the timer task which can be run on any core. * * @return * - ESP_OK on success * - ESP_ERR_NO_MEM if allocation has failed * - ESP_ERR_INVALID_STATE if already initialized * - other errors from interrupt allocator */ esp_err_t esp_timer_init(void); /** * @brief De-initialize esp_timer library * * @note Normally this function should not be called from applications * * @return * - ESP_OK on success * - ESP_ERR_INVALID_STATE if not yet initialized */ esp_err_t esp_timer_deinit(void); /** * @brief Create an esp_timer instance * * @note When timer no longer needed, delete it using esp_timer_delete(). * * @param create_args Pointer to a structure with timer creation arguments. * Not saved by the library, can be allocated on the stack. * @param[out] out_handle Output, pointer to esp_timer_handle_t variable that * holds the created timer handle. * * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if some of the create_args are not valid * - ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet * - ESP_ERR_NO_MEM if memory allocation fails */ esp_err_t esp_timer_create(const esp_timer_create_args_t* create_args, esp_timer_handle_t* out_handle); /** * @brief Start a one-shot timer * * Timer represented by `timer` should not be running when this function is called. * * @param timer timer handle created using esp_timer_create() * @param timeout_us timer timeout, in microseconds relative to the current moment * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if the handle is invalid * - ESP_ERR_INVALID_STATE if the timer is already running */ esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us); /** * @brief Start a periodic timer * * Timer represented by `timer` should not be running when this function is called. * This function starts the timer which will trigger every `period` microseconds. * * @param timer timer handle created using esp_timer_create() * @param period timer period, in microseconds * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if the handle is invalid * - ESP_ERR_INVALID_STATE if the timer is already running */ esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period); /** * @brief Restart a currently running timer * * Type of `timer` | Action * --------------- | ------ * One-shot timer | Restarted immediately and times out once in `timeout_us` microseconds * Periodic timer | Restarted immediately with a new period of `timeout_us` microseconds * * @param timer timer handle created using esp_timer_create() * @param timeout_us Timeout in microseconds relative to the current time. * In case of a periodic timer, also represents the new period. * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if the handle is invalid * - ESP_ERR_INVALID_STATE if the timer is not running */ esp_err_t esp_timer_restart(esp_timer_handle_t timer, uint64_t timeout_us); /** * @brief Stop a running timer * * This function stops the timer previously started using esp_timer_start_once() * or esp_timer_start_periodic(). * * @param timer timer handle created using esp_timer_create() * @return * - ESP_OK on success * - ESP_ERR_INVALID_STATE if the timer is not running */ esp_err_t esp_timer_stop(esp_timer_handle_t timer); /** * @brief Delete an esp_timer instance * * The timer must be stopped before deleting. A one-shot timer which has expired * does not need to be stopped. * * @param timer timer handle created using esp_timer_create() * @return * - ESP_OK on success * - ESP_ERR_INVALID_STATE if the timer is running */ esp_err_t esp_timer_delete(esp_timer_handle_t timer); /** * @brief Get time in microseconds since boot * @return Number of microseconds since the initialization of ESP Timer */ int64_t esp_timer_get_time(void); /** * @brief Get the timestamp of the next expected timeout * @return Timestamp of the nearest timer event, in microseconds. * The timebase is the same as for the values returned by esp_timer_get_time(). */ int64_t esp_timer_get_next_alarm(void); /** * @brief Get the timestamp of the next expected timeout excluding those timers * that should not interrupt light sleep (such timers have * ::esp_timer_create_args_t::skip_unhandled_events enabled) * @return Timestamp of the nearest timer event, in microseconds. * The timebase is the same as for the values returned by esp_timer_get_time(). */ int64_t esp_timer_get_next_alarm_for_wake_up(void); /** * @brief Get the period of a timer * * This function fetches the timeout period of a timer. * For a one-shot timer, the timeout period will be 0. * * @param timer timer handle created using esp_timer_create() * @param period memory to store the timer period value in microseconds * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if the arguments are invalid */ esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period); /** * @brief Get the expiry time of a one-shot timer * * This function fetches the expiry time of a one-shot timer. * * @note Passing the timer handle of a periodic timer will result in an error. * * @param timer timer handle created using esp_timer_create() * @param expiry memory to store the timeout value in microseconds * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if the arguments are invalid * - ESP_ERR_NOT_SUPPORTED if the timer type is periodic */ esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry); /** * @brief Dump the list of timers to a stream * * By default, this function prints the list of active (running) timers. The output format is: * * | Name | Period | Alarm | * * - Name — timer pointer * - Period — period of timer in microseconds, or 0 for one-shot timer * - Alarm - time of the next alarm in microseconds since boot, or 0 if the timer is not started * * To print the list of all created timers, enable Kconfig option `CONFIG_ESP_TIMER_PROFILING`. * In this case, the output format is: * * | Name | Period | Alarm | Times_armed | Times_trigg | Times_skip | Cb_exec_time | * * - Name — timer name * - Period — same as above * - Alarm — same as above * - Times_armed — number of times the timer was armed via esp_timer_start_X * - Times_triggered - number of times the callback was triggered * - Times_skipped - number of times the callback was skipped * - Callback_exec_time - total time taken by callback to execute, across all calls * * @param stream stream (such as stdout) to which to dump the information * @return * - ESP_OK on success * - ESP_ERR_NO_MEM if can not allocate temporary buffer for the output */ esp_err_t esp_timer_dump(FILE* stream); #if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || defined __DOXYGEN__ /** * @brief Requests a context switch from a timer callback function. * * This only works for a timer that has an ISR dispatch method. * The context switch will be called after all ISR dispatch timers have been processed. */ void esp_timer_isr_dispatch_need_yield(void); #endif // CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || defined __DOXYGEN__ /** * @brief Returns status of a timer, active or not * * This function is used to identify if the timer is still active (running) or not. * * @param timer timer handle created using esp_timer_create() * @return * - 1 if timer is still active (running) * - 0 if timer is not active */ bool esp_timer_is_active(esp_timer_handle_t timer); /** * @brief Get the ETM event handle of esp_timer underlying alarm event * * @note The created ETM event object can be deleted later using esp_etm_del_event() * * @note The ETM event is generated by the underlying hardware - systimer; * therefore, if the esp_timer is not clocked by systimer, then no ETM event will be generated. * * @param[out] out_event Returned ETM event handle * @return * - ESP_OK Success * - ESP_ERR_INVALID_ARG Parameter error */ esp_err_t esp_timer_new_etm_alarm_event(esp_etm_event_handle_t *out_event); #ifdef __cplusplus } #endif