1 /* 2 * Copyright (C) 2015-2021 Alibaba Group Holding Limited 3 */ 4 5 #ifndef AOS_KERNEL_H 6 #define AOS_KERNEL_H 7 8 #include <stdlib.h> 9 #include <stddef.h> 10 #include <sys/types.h> 11 #include <stdint.h> 12 #include <stdbool.h> 13 #include <aos/osal_debug.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * @addtogroup aos_kernel kernel 21 * 提供AliOS Things内核功能的基础API. 22 * 23 * @{ 24 */ 25 26 /** 27 * @addtogroup aos_kernel_sysctrl 28 * 提供AliOS Things系统控制功能的基础API. 29 * 30 * @{ 31 */ 32 33 /* Define the AliOS-Things' Version */ 34 #define SYSINFO_KERNEL_VERSION "AOS-R-3.3.0" /**< AliOS Things内核版本信息 */ 35 36 /* Defined for API with delay time */ 37 #define AOS_WAIT_FOREVER 0xffffffffu /**< 阻塞性等待，即一直等待，直到事件发生或资源获得才返回 */ 38 #define AOS_NO_WAIT 0x0 /**< 非阻塞性等待，即若无事件发生或无资源可获得，则返回 */ 39 40 /* Define default aos task priority*/ 41 #ifndef AOS_DEFAULT_APP_PRI 42 #define AOS_DEFAULT_APP_PRI 32 /**< 任务默认优先级，当调用aos_task_new()创建任务时被内核用来设置任务优先级 */ 43 #endif 44 45 /** @} */ 46 47 /** 48 * @addtogroup aos_kernel_event 49 * 提供AliOS Things系统内核事件功能的基础API. 50 * 51 * @{ 52 */ 53 #define AOS_EVENT_AND 0x02u /**< 期望事件标志位均为1时，即等待所有事件均发生时，任务解除阻塞 */ 54 #define AOS_EVENT_AND_CLEAR 0x03u /**< 期望事件标志位均为1时，即等待所有事件均发生时，任务解除阻塞且将事件标志位清零 */ 55 #define AOS_EVENT_OR 0x00u /**< 期望任意事件标志位为1时，即等待的任意事件发生，任务解除阻塞 */ 56 #define AOS_EVENT_OR_CLEAR 0x01u /**< 期望任意事件标志位为1时，即等待的任意事件发生，任务解除阻塞且将事件标志位清零 */ 57 /** @} */ 58 59 /** 60 * @addtogroup aos_kernel_task 61 * 提供AliOS Things系统内核任务管理功能的基础API. 62 * 63 * @{ 64 */ 65 #define AOS_TASK_NONE 0x0u /**< 表示不指定任意选项，当调用aos_task_create()创建任务时，用来指定option参数 */ 66 #define AOS_TASK_AUTORUN 0x01u /**< 表示任务创建后即可被调度执行，当调用aos_task_create()创建任务时，用来指定option参数*/ 67 /** @} */ 68 69 /** 70 * @addtogroup aos_kernel_timer 71 * 提供AliOS Things系统内核定时器功能的基础API. 72 * 73 * @{ 74 */ 75 #define AOS_TIMER_NONE 0x0u /**< 表示不指定任意选项，当调用aos_timer_create()创建定时器时，用来指定option参数 */ 76 #define AOS_TIMER_AUTORUN 0x01u /**< 表示定时器创建后即启动，当调用aos_timer_create()创建定时器时，用来指定option参数*/ 77 #define AOS_TIMER_REPEAT 0x02u /**< 表示定时器是周期性的，当调用aos_timer_create()创建定时器时，用来指定option参数 */ 78 /** @} */ 79 80 /** 81 * @addtogroup aos_kernel_sysctrl 82 * 提供AliOS Things系统控制功能的基础API. 83 * 84 * @{ 85 */ 86 87 /* Define the handle for all aos module */ 88 typedef void * aos_hdl_t; /**< AOS内核对象句柄通用类型 */ 89 /** @} */ 90 91 /** 92 * @addtogroup aos_kernel_task 93 * 提供AliOS Things系统内核任务管理功能的基础API. 94 * 95 * @{ 96 */ 97 /* Define the main handle for task module */ 98 typedef aos_hdl_t aos_task_t; /**< AOS任务对象句柄类型 */ 99 /** @} */ 100 101 /** 102 * @addtogroup aos_kernel_mutex 103 * 提供AliOS Things系统内核互斥量功能的基础API. 104 * 105 * @{ 106 */ 107 /* Define the main handle for mutex module */ 108 typedef aos_hdl_t aos_mutex_t; /**< AOS互斥量对象句柄类型 */ 109 /** @} */ 110 111 /** 112 * @addtogroup aos_kernel_sem 113 * 提供AliOS Things系统内核信号量功能的基础API. 114 * 115 * @{ 116 */ 117 /* Define the main handle for sem module */ 118 typedef aos_hdl_t aos_sem_t; /**< AOS信号量对象句柄类型 */ 119 /** @} */ 120 121 /** 122 * @addtogroup aos_kernel_event 123 * 提供AliOS Things系统内核事件功能的基础API. 124 * 125 * @{ 126 */ 127 /* Define the main handle for queue module */ 128 typedef aos_hdl_t aos_event_t; /**< AOS信号量对象句柄类型 */ 129 /** @} */ 130 131 /** 132 * @addtogroup aos_kernel_queue 133 * 提供AliOS Things系统内核消息队列功能的基础API. 134 * 135 * @{ 136 */ 137 /* Define the main handle for event module */ 138 typedef aos_hdl_t aos_queue_t; /**< AOS消息队列对象句柄类型 */ 139 /** @} */ 140 141 /** 142 * @addtogroup aos_kernel_timer 143 * 提供AliOS Things系统内核定时器功能的基础API. 144 * 145 * @{ 146 */ 147 /* Define the main handle for timer module */ 148 typedef aos_hdl_t aos_timer_t; /**< AOS定时器对象句柄类型 */ 149 /** @} */ 150 151 /** 152 * @addtogroup aos_kernel_workqueue 153 * 提供AliOS Things系统内核任务队列功能的基础API. 154 * 155 * @{ 156 */ 157 158 /* Define the main handle for workqueue module */ 159 typedef struct { 160 aos_hdl_t hdl; /**< internel rhino handle */ 161 void *stk; /**< workqueue task stack start addr */ 162 } aos_workqueue_t; 163 164 /* Define the main handle for work of workqueue module */ 165 typedef aos_hdl_t aos_work_t; /**< AOS任务队列中任务的对象句柄类型 */ 166 /** @} */ 167 168 /** 169 * @addtogroup aos_kernel_task 170 * 提供AliOS Things系统内核任务管理功能的基础API. 171 * 172 * @{ 173 */ 174 /* Define the data type for task key index */ 175 typedef uint32_t aos_task_key_t; /**< AOS任务私有数据对象句柄类型 */ 176 /** @} */ 177 178 /** 179 * @addtogroup aos_kernel_sysctrl 180 * 提供AliOS Things系统控制功能的基础API. 181 * 182 * @{ 183 */ 184 /* Define the data type for function return */ 185 typedef int32_t aos_status_t; /**< AOS返回值状态类型 */ 186 /** @} */ 187 188 /** 189 * @addtogroup aos_kernel_spinlock 190 * 提供AliOS Things系统内核自旋锁功能的基础API. 191 * 192 * @{ 193 */ 194 /* Define the main handle for spinlock module */ 195 typedef struct { 196 volatile uint32_t owner; /* cpu index of owner */ 197 } aos_spinlock_t; 198 199 /* Define the data type for spinlock irq save value */ 200 typedef long aos_irqsave_t; 201 /** @} */ 202 203 /** 204 * @defgroup aos_kernel_task 任务管理 205 * 提供AliOS Things系统内核任务管理功能的基础API. 206 * 207 * @{ 208 */ 209 210 /** 211 * 创建任务，该接口为创建任务分配TCB（任务控制块）并且根据指定的执行体、任务名称、栈大小来初始化对应成员. 212 * 该接口任务栈是由内核分配的。 213 * 214 * @par 使用约束 215 * 该接口不能在中断上下文中调用 216 * 217 * @par 错误处理 218 * 如果任务执行体入口函数为NULL，或任务名为NULL，或任务句柄为NULL，则返回错误码-EINVAL \n 219 * 如果栈大小为零，则返回错误 \n 220 * 如果任务优先级超过配置上限或等于IDLE任务优先级，则返回错误码-EINVAL \n 221 * 222 * @param[in] task 任务对象句柄. 223 * @param[in] name 任务名称.若任务名称为空，则使用默认任务名“default_name”。 224 * @param[in] fn 任务执行体入口函数。 225 * @param[in] arg 任务执行体入口函数的参数。 226 * @param[in] stack_buf 栈空间地址，如果地址为空则内核根据stack_size为任务分配栈空间. 227 * @param[in] stack_size 栈大小（字节为单位）。 228 * @param[in] prio 任务优先级，最大指由配置参数RHINO_CONFIG_USER_PRI_MAX(默认为60)决定. 229 * @param[in] options 任务创建选项,当前支持选项：\n 230 * @ref AOS_TASK_AUTORUN 任务创建后自动加入就绪队列，可被调度器调度执行. \n 231 * 232 * @return 状态码 233 * @retval 0 创建任务成功 234 * @retval -EINVAL 输入非法参数导致失败 235 * @retval -ENOMEM 内存不足导致失败 236 * @retval -1 其他原因导致的失败 237 */ 238 aos_status_t aos_task_create(aos_task_t *task, const char *name, void (*fn)(void *), 239 void *arg,void *stack_buf, size_t stack_size, int32_t prio, uint32_t options); 240 241 /** 242 * 挂起任务，该接口将已创建的任务挂起，暂时不执行，挂起的对象既可以是任务自身也可以是其他任务，\n 243 * 但不允许挂起IDLE任务。 244 * 245 * @par 使用约束 246 * 该接口不能在中断上下文中调用 247 * 248 * @par 错误处理 249 * 如果任务句柄为NULL，则返回错误码-EINVAL\n 250 * 如果挂起任务为IDLE，则返回错误码-EPERM \n 251 * 252 * @param[in] task 任务对象句柄. 253 * 254 * @return 状态码 255 * @retval 0 挂起任务成功 256 * @retval -EINVAL 输入非法参数导致失败 257 * @retval -EPERM 尝试挂起IDLE任务导致失败 258 * @retval -1 其他原因导致的失败 259 */ 260 aos_status_t aos_task_suspend(aos_task_t *task); 261 262 /** 263 * 恢复任务，该接口将挂起任务恢复，取消暂时不执行状态。 264 * 265 * @par 使用约束 266 * 该接口不能在中断上下文中调用 267 * 268 * @par 错误处理 269 * 如果任务句柄为NULL，则返回错误码-EINVAL\n 270 * 271 * @param[in] task 任务对象句柄. 272 * 273 * @return 状态码 274 * @retval 0 恢复任务成功 275 * @retval -EINVAL 输入非法参数导致失败 276 * @retval -1 其他原因导致的失败 277 */ 278 aos_status_t aos_task_resume(aos_task_t *task); 279 280 /** 281 * 任务退出，该接口功能是任务删除自身，且IDLE任务不允许删除。 282 * 283 * @par 使用约束 284 * 该接口不能在中断上下文中调用 285 * 286 * @par 错误处理 287 * 如果挂起任务为IDLE，则直接返回 \n 288 * 289 * @param[in] code 未使用. 290 * 291 * @return 无 292 * 293 */ 294 void aos_task_exit(int32_t code); 295 296 /** 297 * 删除任务，该接口删除一个任务并回收任务资源，不允许删除IDLE任务。 298 * 299 * @par 使用约束 300 * 该接口不能在中断上下文中调用 301 * 302 * @par 错误处理 303 * 如果任务句柄为NULL，则返回错误码-EINVAL\n 304 * 如果删除的任务为IDLE，则返回错误码-EPERM \n 305 * 306 * @param[in] task 任务对象句柄. 307 * 308 * @return 状态码 309 * @retval 0 恢复任务成功 310 * @retval -EINVAL 输入非法参数导致失败 311 * @retval -EPERM 尝试删除IDLE任务导致失败 312 * @retval -1 其他原因导致的失败 313 */ 314 aos_status_t aos_task_delete(aos_task_t *task); 315 316 /** 317 * 当前任务让出CPU资源，该接口将当前任务唤出，放入就绪队列对尾，暂时放弃CPU的使用权。 318 * 319 * @par 使用约束 320 * 该接口不能在中断上下文中调用 321 * 322 * @par 错误处理 323 * 如果任务句柄为NULL，则返回错误码-EINVAL\n 324 * 325 * @param[in] 无. 326 * 327 * @return 状态码 328 * @retval 0 恢复任务成功 329 * @retval -EINVAL 输入非法参数导致失败 330 * @retval -1 其他原因导致的失败 331 */ 332 aos_status_t aos_task_yield(void); 333 334 /** 335 * 获取任务名称，该接口将指定任务的任务名称拷贝到用户缓冲区。 336 * 337 * @par 使用约束 338 * 该接口不能在中断上下文中调用 339 * 340 * @par 错误处理 341 * 如果任务句柄为NULL，则返回错误码-EINVAL\n 342 * 如果用户缓冲区地址参数为NULL，则返回错误码-EINVAL\n 343 * 如果用户缓冲区大小为0，则返回错误码-EINVAL\n 344 * 345 * @param[in] task 任务对象句柄 346 * @param[out] buf 输出任务名的用户缓冲区地址 347 * @param[in] buf_size 输出任务名的用户缓冲区大小 348 * @return 状态码 349 * @retval 0 恢复任务成功 350 * @retval -EINVAL 输入非法参数导致失败 351 * @retval -1 其他原因导致的失败 352 */ 353 aos_status_t aos_task_name_get(aos_task_t *task, char *buf, size_t buf_size); 354 355 /** 356 * 获取当前任务的任务对象句柄。 357 * 358 * @par 使用约束 359 * 无。 360 * 361 * @par 错误处理 362 * 无。 363 * 364 * @param[in] 无。 365 * 366 * @return 任务对象句柄 367 * 368 */ 369 aos_task_t aos_task_self(void); 370 371 /** 372 * Create a task key. 373 * 374 * @param[out] key pointer of key object. 375 * 376 * @return 0: success, -EINVAL: error. 377 */ 378 aos_status_t aos_task_key_create(aos_task_key_t *key); 379 380 /** 381 * Delete a task key. 382 * 383 * @param[in] key key object. 384 * 385 * @return none. 386 */ 387 void aos_task_key_delete(aos_task_key_t key); 388 389 /** 390 * Associate a task-specific value with a key. 391 * 392 * @param[in] key key object. 393 * @param[in] vp pointer of a task-specific value. 394 * 395 * @return the check status, 0: OK, -1: indicates key invalid. 396 */ 397 aos_status_t aos_task_setspecific(aos_task_key_t key, void *vp); 398 399 /** 400 * Get the value currently bound to the specified key. 401 * 402 * @param[in] key key object. 403 * 404 * @return NULL: get fail, otherwise: get succeed. 405 */ 406 void *aos_task_getspecific(aos_task_key_t key); 407 408 /** @} */ 409 410 /** 411 * @defgroup aos_kernel_mutex 互斥量 412 * 提供AliOS Things系统内核互斥量功能的基础API. 413 * 414 * @{ 415 */ 416 417 /** 418 * 创建互斥量，该接口在内核中创建一个互斥量对象，并返回该对象的句柄。 419 * 420 * @par 错误处理 421 * 如果互斥量对象句柄为NULL，则返回-EINVAL。 422 * 如果在创建的过程中内存不足，则返回-ENOMEM。 423 * 424 * @param[out] mutex 互斥量对象句柄，该接口会创建一个互斥量对象，成功后把对象的地址通过此参数返回。 425 * @param[in] options 创建互斥量的选项，目前还没有支持的选项，待后续扩展。 426 * 427 * @return 状态码 428 * @retval 0 创建互斥量成功 429 * @retval -EINVAL 传入的参数非法 430 * @retval -ENOMEM 内存不足 431 */ 432 aos_status_t aos_mutex_create(aos_mutex_t *mutex, uint32_t options); 433 434 /** 435 * 销毁互斥量，该接口释放互斥量对象的资源，唤醒所有阻塞在该互斥量的任务。 436 * 437 * @par 错误处理 438 * 如果互斥量对象句柄参数为NULL， 或者互斥量对象非法（没有成功创建或者对象类型不是互斥量），则返回-EINVAL。 439 * 440 * @param[in] mutex 互斥量对象句柄 441 * 442 * @return 无 443 */ 444 void aos_mutex_free(aos_mutex_t *mutex); 445 446 /** 447 * 锁定互斥量，该接口申请获得一把互斥量锁，常被用于任务之间保护共享资源。 448 * 如果该互斥量锁当前没有其他任务持有，则当前任务能够立即获取这把锁并成功返回。 449 * 如果该互斥量锁当前被其他任务持有，同时指定AOS_NO_WAIT，则不等待立即返回错误-1。 450 * 如果该互斥量锁当前被其他任务持有，同时指定AOS_WAIT_FOREVER，则永远等待直到获得该互斥量锁。 451 * 等待时当前任务处于阻塞状态，等待该互斥量锁。 452 * 453 * @note 注意内核中允许互斥量嵌套，如果任务再次获得自身持有的互斥量锁，则返回成功。 454 * 455 * @par 错误处理 456 * 如果互斥量对象句柄参数为NULL， 或者互斥量对象非法（没有成功创建或者对象类型不是互斥量），则返回-EINVAL。 457 * 458 * @param[in] mutex 互斥量对象句柄。 459 * @param[in] timeout 超时时间（单位：ms）@ref AOS_WAIT_FOREVER: 永远等待。 @ref AOS_NO_WAIT: 不等待。 460 * 461 * @return 状态码 462 * @retval 0 返回成功，此时当前任务获得这把互斥量锁。 463 * @retval -EINVAL 参数非法 464 * @retval -ETIMEDOUT 等待超时 465 * @retval -1 其他操作 466 */ 467 aos_status_t aos_mutex_lock(aos_mutex_t *mutex, uint32_t timeout); 468 469 /** 470 * 解锁互斥量，该接口释放自身持有的互斥量锁。 如果此时有其他任务阻塞在该互斥量锁上， 471 * 则从阻塞任务队列中挑选一个优先级最高的任务唤醒，使其继续。 472 * 473 * @note 任务只能释放自身持有的互斥量锁，否则返回错误-EPERM。 474 * 内核中允许互斥量锁嵌套，如果进行过多次的互斥量锁定操作，注意需要进行相同次数的解锁操作，否则其他竞争的任务会一直阻塞。 475 * 476 * @par 错误处理 477 * 如果互斥量对象句柄参数为NULL， 或者互斥量对象非法（没有成功创建或者对象类型不是互斥量），则返回-EINVAL。 478 * 479 * @param[in] mutex 互斥量对象句柄。 480 * 481 * @return 状态码 482 * @retval 0 返回成功， 483 * @retval -EINVAL 参数非法 484 * @retval -EPERM 权限不够（释放其他任务持有的互斥量锁） 485 */ 486 aos_status_t aos_mutex_unlock(aos_mutex_t *mutex); 487 488 /** @} */ 489 490 /** 491 * @defgroup aos_kernel_sem 信号量 492 * 提供AliOS Things系统内核信号量功能的基础API. 493 * 494 * @{ 495 */ 496 497 /** 498 * Alloc a semaphore. 499 * 500 * @param[out] sem pointer of semaphore object, semaphore object must be 501 * alloced, hdl pointer in aos_sem_t will refer a kernel obj internally. 502 * @param[in] count initial semaphore counter. 503 * 504 * @param[in] options reserved. 505 * @return 0:success. 506 */ 507 aos_status_t aos_sem_create(aos_sem_t *sem, uint32_t count, uint32_t options); 508 /** 509 * Destroy a semaphore. 510 * 511 * @param[in] sem pointer of semaphore object, mem refered by hdl pointer 512 * in aos_sem_t will be freed internally. 513 */ 514 void aos_sem_free(aos_sem_t *sem); 515 516 /** 517 * Acquire a semaphore. 518 * 519 * @param[in] sem semaphore object, it contains kernel obj pointer 520 * which aos_sem_new alloced. 521 * @param[in] timeout waiting until timeout in milliseconds. 522 * 523 * @return 0: success. 524 */ 525 aos_status_t aos_sem_wait(aos_sem_t *sem, uint32_t timeout); 526 527 /** 528 * Release a semaphore. 529 * 530 * @param[in] sem semaphore object, it contains kernel obj pointer which aos_sem_new alloced. 531 */ 532 void aos_sem_signal(aos_sem_t *sem); 533 534 /** 535 * Release all semaphore. 536 * 537 * @param[in] sem semaphore object, it contains kernel obj pointer which aos_sem_new alloced. 538 */ 539 void aos_sem_signal_all(aos_sem_t *sem); 540 541 /** @} */ 542 543 /** 544 * @defgroup aos_kernel_event 事件 545 * 提供AliOS Things系统内核事件功能的基础API. 546 * 547 * @{ 548 */ 549 550 /** 551 * Alloc a event. 552 * 553 * @param[out] sem pointer of event object, event object must be 554 * alloced, hdl pointer in aos_sem_t will refer a kernel obj internally. 555 * @param[in] value initial event value. 556 * 557 * @param[in] options reserved. 558 * @return 0:success. 559 */ 560 aos_status_t aos_event_create(aos_event_t *event, uint32_t value, uint32_t options); 561 562 /** 563 * Destroy a event. 564 * 565 * @param[in] event pointer of event object, mem refered by hdl pointer 566 * in aos_hdl_t will be freed internally. 567 */ 568 void aos_event_free(aos_event_t *event); 569 570 571 /** 572 * Get a event. 573 * 574 * @param[in] event event object. 575 * @param[in] value Expect value. 576 * @param[in] opt Mode of operation, one of AND/AND_CLEAR/OR/OR_CLEAR 577 * @param[OUT] actl_value Actual acquired value 578 * @param[in] timeout waiting until timeout in milliseconds. 579 * 580 * * @return 0:success. 581 */ 582 aos_status_t aos_event_get(aos_event_t *event, uint32_t value, uint32_t opt, uint32_t *actl_value, uint32_t timeout); 583 584 /** 585 * Set a event. 586 * 587 * @param[in] event event object. 588 * 589 * @param[in] value The value to set. 590 * 591 * @param[in] opt Mode of operation, one of AND/AND_CLEAR/OR/OR_CLEAR 592 * 593 * @param[in] timeout waiting until timeout in milliseconds. 594 * 595 * @return 0:success. 596 */ 597 aos_status_t aos_event_set(aos_event_t *event, uint32_t value, uint32_t opt); 598 599 /** @} */ 600 601 602 /** 603 * @defgroup aos_kernel_queue 消息队列 604 * 提供AliOS Things系统内核消息队列功能的基础API. 605 * 606 * @{ 607 */ 608 609 /** 610 * This function will create a queue. 611 * 612 * @param[in] queue pointer to the queue(the space is provided by user). 613 * @param[in] size the bytes of the buf. 614 * @param[in] max_msg the max size of the msg. 615 * @param[in] options reserved. 616 * @return 0: success. 617 */ 618 aos_status_t aos_queue_create(aos_queue_t *queue, size_t size, size_t max_msg, uint32_t options); 619 /** 620 * This function will delete a queue. 621 * 622 * @param[in] queue pointer to the queue. 623 */ 624 void aos_queue_free(aos_queue_t *queue); 625 626 /** 627 * This function will send a msg to the front of a queue. 628 * 629 * @param[in] queue pointer to the queue. 630 * @param[in] msg msg to send. 631 * @param[in] size size of the msg. 632 * 633 * @return 0: success. 634 */ 635 aos_status_t aos_queue_send(aos_queue_t *queue, void *msg, size_t size); 636 637 /** 638 * This function will receive msg from a queue. 639 * 640 * @param[in] queue pointer to the queue. 641 * @param[in] ms ms to wait before receive. 642 * @param[out] msg buf to save msg. 643 * @param[out] size size of the msg. 644 * 645 * @return 0: success. 646 */ 647 aos_status_t aos_queue_recv(aos_queue_t *queue, uint32_t ms, void *msg, size_t *size); 648 649 /** 650 * Get number of queued messages in a message queue. 651 * 652 * @param[in] queue message queue handle to operate. 653 * 654 * @return number of queued messages.negative indicates error code. 655 */ 656 aos_status_t aos_queue_get_count(aos_queue_t *queue); 657 658 /** @} */ 659 660 /** 661 * @defgroup aos_kernel_timer 定时器 662 * 提供AliOS Things系统内核定时器功能的基础API. 663 * 664 * @{ 665 */ 666 667 /** 668 * This function will create a timer. 669 * 670 * @param[in] timer pointer to the timer. 671 * @param[in] fn callbak of the timer. 672 * @param[in] arg the argument of the callback. 673 * @param[in] ms ms of the normal timer triger. 674 * @param[in] options option settings, can be set to AOS_TIMER_AUTORUN|AOS_TIMER_REPEAT 675 * @note fn first arg: timer->hdl, not aos_timer_t *timer; second arg: user param arg. 676 * @return 0: success. 677 */ 678 aos_status_t aos_timer_create(aos_timer_t *timer, void (*fn)(void *, void *), void *arg, 679 uint32_t ms, uint32_t options); 680 681 /** 682 * This function will delete a timer. 683 * 684 * @param[in] timer pointer to a timer. 685 */ 686 void aos_timer_free(aos_timer_t *timer); 687 688 /** 689 * This function will start a timer. 690 * 691 * @param[in] timer pointer to the timer. 692 * 693 * @return 0: success. 694 */ 695 aos_status_t aos_timer_start(aos_timer_t *timer); 696 697 /** 698 * This function will stop a timer. 699 * 700 * @param[in] timer pointer to the timer. 701 * 702 * @return 0: success. 703 */ 704 aos_status_t aos_timer_stop(aos_timer_t *timer); 705 706 /** 707 * This function will change attributes of a timer. 708 * 709 * @param[in] timer pointer to the timer. 710 * @param[in] ms ms of the timer triger. 711 * 712 * @note change the timer attributes should follow 713 * the sequence as timer_stop->timer_change->timer_start 714 * 715 * @return 0: success. 716 */ 717 aos_status_t aos_timer_change(aos_timer_t *timer, uint32_t ms); 718 719 /** 720 * This function will change attributes of a timer once. 721 * 722 * @param[in] timer pointer to the timer. 723 * @param[in] ms ms of the timer triger. 724 * 725 * @note change the timer attributes should follow 726 * the sequence as timer_stop->timer_change->timer_start 727 * 728 * @return 0: success. 729 */ 730 aos_status_t aos_timer_change_once(aos_timer_t *timer, uint32_t ms); 731 732 /** 733 * This function will check if timer is valid. 734 * Deprecated, not Recommended. 735 * 736 * @param[in] timer pointer to the timer. 737 * 738 * @return false: invalid, true: valid. 739 */ 740 bool aos_timer_is_valid(aos_timer_t *timer); 741 742 /** @} */ 743 744 /** 745 * @defgroup aos_kernel_workqueue 任务队列 746 * 提供AliOS Things系统内核任务队列功能的基础API. 747 * 748 * @{ 749 */ 750 751 /** 752 * 创建任务队列. 753 * 754 * @param[in] workqueue 被创建任务队列地址. 755 * @param[in] name 任务队列名称. 756 * @param[in] pri 任务优先级. 757 * @param[in] stack_buffer 任务队列的任务栈地址，若为NULL，则系统内部动态分配. 758 * @param[in] stack_size 任务栈大小. 759 * 760 * @return 0: 成功, 其他: 失败。 761 */ 762 aos_status_t aos_workqueue_create(aos_workqueue_t *workqueue, const char *name, int32_t prio, void *stack_buffer, size_t stack_size); 763 764 /** 765 * 删除任务队列. 766 * 767 * @param[in] workqueue 待删除的任务队列. 768 */ 769 void aos_workqueue_del(aos_workqueue_t *workqueue); 770 771 /** 772 * 初始化一个预在任务队列中执行的任务. 773 * 774 * @param[in] work 已初始化的任务（针对任务队列）. 775 * @param[in] fn 任务执行函数. 776 * @param[in] arg 任务执行函数的参数. 777 * @param[in] dly 运行前延迟毫秒数. 778 * 779 * @return 0: 成功, 其他: 失败. 780 */ 781 aos_status_t aos_work_init(aos_work_t *work, void (*fn)(void *), void *arg, int dly); 782 783 /** 784 * 销毁一个任务队列中的任务. 785 * 786 * @param[in] work 待销毁的任务（针对任务队列）. 787 * 788 * @return none. 789 */ 790 void aos_work_destroy(aos_work_t *work); 791 792 /** 793 * 将任务添加到任务队列中运行. 794 * 795 * @param[in] workqueue 执行目标任务的任务队列. 796 * @param[in] work 待执行的任务. 797 * 798 * @return 0: 成功, 其他: 失败. 799 */ 800 aos_status_t aos_work_run(aos_workqueue_t *workqueue, aos_work_t *work); 801 802 /** 803 * 将任务放入默认任务队列执行. 804 * 805 * @param[in] work 待执行的任务. 806 * 807 * @return 0: 成功, 其他: 失败. 808 */ 809 aos_status_t aos_work_sched(aos_work_t *work); 810 811 /** 812 * 取消默认任务队列中的一个任务. 813 * 814 * @param[in] work 待取消的任务. 815 * 816 * @return 0: 成功, 其他: 失败. 817 */ 818 aos_status_t aos_work_cancel(aos_work_t *work); 819 820 /** @} */ 821 822 /** 823 * @defgroup aos_kernel_spinlock 自旋锁 824 * 提供AliOS Things系统内核自旋锁功能的基础API. 825 * 826 * @{ 827 */ 828 829 /** 830 * Init a spinlock. 831 * 832 * @param[in] spinlock pointer of spinlock object,spinlock object must be 833 * alloced. 834 */ 835 void aos_spin_lock_init(aos_spinlock_t *spinlock); 836 837 /** 838 * Lock a spinlock. 839 * 840 * @param[in] spinlock spinlock object. 841 */ 842 void aos_spin_lock(aos_spinlock_t *spinlock); 843 844 /** 845 * Unlock a spinlock. 846 * 847 * @param[in] spinlock spinlock object. 848 */ 849 void aos_spin_unlock(aos_spinlock_t *spinlock); 850 851 /** 852 * Lock a spinlock in ISR. 853 * 854 * @param[in] spinlock spinlock object. 855 * 856 * @return CPSR value. 857 */ 858 aos_irqsave_t aos_spin_lock_irqsave(aos_spinlock_t *spinlock); 859 860 /** 861 * Unlock a spinlock in ISR. 862 * 863 * @param[in] spinlock spinlock object. 864 * @param[in] flag CPSR value. 865 * 866 */ 867 void aos_spin_unlock_irqrestore(aos_spinlock_t *spinlock, aos_irqsave_t flag); 868 869 /** @} */ 870 871 /** 872 * @defgroup aos_kernel_memory 内存管理 873 * 提供AliOS Things系统内核内存管理功能的基础API. 874 * 875 * @{ 876 */ 877 878 /** 879 * Realloc memory. 880 * 881 * @param[in] mem current memory address point. 882 * @param[in] size new size of the mem to remalloc. 883 * 884 * @return NULL: error. 885 */ 886 void *aos_realloc(void *mem, size_t size); 887 888 /** 889 * Alloc memory. 890 * 891 * @param[in] size size of the mem to malloc. 892 * 893 * @return NULL: error. 894 */ 895 void *aos_malloc(size_t size); 896 897 /** 898 * Alloc memory and clear to zero. 899 * 900 * @param[in] nitems number of items to malloc. 901 * @param[in] size size of one item to malloc. 902 * 903 * @return NULL: error. 904 */ 905 void *aos_calloc(size_t nitems, size_t size); 906 907 /** 908 * Alloc memory and clear to zero. 909 * 910 * @param[in] size size of the mem to malloc. 911 * 912 * @return NULL: error. 913 */ 914 void *aos_zalloc(size_t size); 915 916 /** 917 * Trace alloced mems. 918 * 919 * @param[in] addr pointer of the mem alloced by malloc. 920 * @param[in] allocator buildin_address. 921 */ 922 void aos_alloc_trace(void *addr, uintptr_t allocator); 923 924 /** 925 * Free memory. 926 * 927 * @param[in] ptr address point of the mem. 928 * 929 * @return none. 930 */ 931 void aos_free(void *mem); 932 933 /** @} */ 934 935 /** 936 * @defgroup aos_kernel_time 时间管理 937 * 提供AliOS Things系统内核时间管理功能的基础API. 938 * 939 * @{ 940 */ 941 942 /** 943 * Set calendar time. 944 * @param[in] now_ms the calender time (unit:ms) to set, for example, 945 * the number of milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). 946 */ 947 void aos_calendar_time_set(uint64_t now_ms); 948 949 /** 950 * Get calendar time. 951 * 952 * @return current calendar time (unit:ms), for example, 953 * the number of milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). 954 */ 955 uint64_t aos_calendar_time_get(void); 956 957 /** 958 * Get calendar time with utc offset. 959 * 960 * @return current calendar time with utc offset (unit:ms). 961 */ 962 uint64_t aos_calendar_localtime_get(void); 963 964 /** 965 * Get current time in nanoseconds. 966 * 967 * @return elapsed time in nanoseconds from system starting. 968 */ 969 uint64_t aos_now(void); 970 971 /** 972 * Get current time in milliseconds. 973 * 974 * @return elapsed time in milliseconds from system starting. 975 */ 976 uint64_t aos_now_ms(void); 977 978 /** 979 * @brief Retrieves the timer string. Under RTOS w/o RTC, this fucntion will 980 * return the UTC time string that consider boot-up as 01-01 00:00:00.000. 981 * Under Linuxhost and compile option "vall=posix", this function will 982 * get the local time which considering time zone. 983 * 984 * @param[out] buf give buffer to save timer string 985 * @param[in] len the length of buffer, recommand 19, right a terminating 986 * null-character is appended in last. 987 * 988 * @return 0: success. 989 * 990 */ 991 aos_status_t aos_now_time_str(char *buffer, size_t len); 992 993 /** 994 * Msleep. 995 * 996 * @param[in] ms sleep time in milliseconds. 997 */ 998 void aos_msleep(uint32_t ms); 999 1000 /** @} */ 1001 1002 /** 1003 * @defgroup aos_kernel_sysctrl 系统管理 1004 * 提供AliOS Things系统控制功能的基础API. 1005 * 1006 * @{ 1007 */ 1008 1009 /** 1010 * srand function. 1011 * 1012 * @param[in] seed The seed number to use to generate the random sequence. 1013 * 1014 * @return none. 1015 */ 1016 void aos_srand(uint32_t seed); 1017 1018 /** 1019 * rand function. 1020 * 1021 * @return random value. 1022 */ 1023 int32_t aos_rand(void); 1024 1025 /** 1026 * Reboot AliOS. 1027 * 1028 * @return none. 1029 */ 1030 void aos_reboot(void); 1031 1032 /** 1033 * Get HZ(ticks per second). 1034 * 1035 * @return RHINO_CONFIG_TICKS_PER_SECOND. 1036 */ 1037 int32_t aos_get_hz(void); 1038 1039 /** 1040 * Get kernel version string. 1041 * 1042 * @param[in] len the size of the @buf in bytes 1043 * @param[out] buf buffer pointer to copy kernel version string 1044 * 1045 * @return On succuess, return the buf pointer, else return NULL. 1046 * @note If the actual kernel version string length is larger than 1047 * the buffer len-1, than only len-1 bytes are copied into 1048 * the buffer, and set the last byte of the buf to zero. 1049 * Else, copy the whole kernel version string into the buf. 1050 */ 1051 aos_status_t aos_version_str_get(char *buf, size_t len); 1052 1053 /** 1054 * Initialize system 1055 */ 1056 void aos_init(void); 1057 1058 /** 1059 * Start system. 1060 */ 1061 void aos_start(void); 1062 1063 /** @} */ 1064 1065 1066 /* The following APIs is marked deprecated and is not recommended */ 1067 1068 /** 1069 * @addtogroup aos_kernel_task 1070 * 提供AliOS Things系统内核任务管理功能的基础API. 1071 * 1072 * @{ 1073 */ 1074 1075 /** 1076 * Create a task. 1077 * Deprecated, not Recommended. 1078 * 1079 * @param[in] name task name. 1080 * @param[in] fn function to run. 1081 * @param[in] arg argument of the function. 1082 * @param[in] stacksize stack-size in bytes. 1083 * 1084 * @return 0: success, otherwise: fail. 1085 */ 1086 aos_status_t aos_task_new(const char *name, void (*fn)(void *), void *arg, size_t stack_size); 1087 1088 /** 1089 * Create a task. 1090 * Deprecated, not Recommended. 1091 * 1092 * @param[in] task handle. 1093 * @param[in] name task name. 1094 * @param[in] fn task function. 1095 * @param[in] arg argument of the function.. 1096 * @param[in] stack_size stack-size in bytes. 1097 * @param[in] prio priority value, the max is RHINO_CONFIG_USER_PRI_MAX(default 60). 1098 * 1099 * @return 0: success. 1100 */ 1101 aos_status_t aos_task_new_ext(aos_task_t *task, const char *name, void (*fn)(void *), 1102 void *arg, size_t stack_size, int32_t prio); 1103 1104 /** @} */ 1105 1106 /** 1107 * @addtogroup aos_kernel_mutex 1108 * 提供AliOS Things系统内核互斥量功能的基础API. 1109 * 1110 * @{ 1111 */ 1112 1113 /** 1114 * Alloc a mutex. 1115 * Deprecated, not Recommended. 1116 * 1117 * @param[in] mutex pointer of mutex object, mutex object must be alloced, 1118 * hdl pointer in aos_mutex_t will refer a kernel obj internally. 1119 * 1120 * @return 0: success. 1121 */ 1122 aos_status_t aos_mutex_new(aos_mutex_t *mutex); 1123 1124 /** 1125 * This function will check if mutex is valid. 1126 * Deprecated, not Recommended. 1127 * 1128 * @param[in] mutex pointer to the mutex. 1129 * 1130 * @return false: invalid, true: valid. 1131 */ 1132 bool aos_mutex_is_valid(aos_mutex_t *mutex); 1133 1134 /** @} */ 1135 1136 /** 1137 * @addtogroup aos_kernel_sem 1138 * 提供AliOS Things系统内核信号量功能的基础API. 1139 * 1140 * @{ 1141 */ 1142 1143 /** 1144 * Alloc a semaphore. 1145 * Deprecated, not Recommended. 1146 * 1147 * @param[out] sem pointer of semaphore object, semaphore object must be 1148 * alloced, hdl pointer in aos_sem_t will refer a kernel obj internally. 1149 * @param[in] count initial semaphore counter. 1150 * 1151 * @return 0:success. 1152 */ 1153 aos_status_t aos_sem_new(aos_sem_t *sem, uint32_t count); 1154 1155 /** 1156 * This function will check if semaphore is valid. 1157 * Deprecated, not Recommended. 1158 * 1159 * @param[in] sem pointer to the sem. 1160 * 1161 * @return false: invalid, true: valid. 1162 */ 1163 bool aos_sem_is_valid(aos_sem_t *sem); 1164 1165 /** @} */ 1166 1167 /** 1168 * @addtogroup aos_kernel_event 1169 * 提供AliOS Things系统内核事件功能的基础API. 1170 * 1171 * @{ 1172 */ 1173 1174 /** 1175 * Alloc a event. 1176 * Deprecated, not Recommended. 1177 * 1178 * @param[out] event pointer of event object, event object must be 1179 * alloced, hdl pointer in aos_hdl_t will refer a kernel obj internally. 1180 * @param[in] value initial event value. 1181 * 1182 * @return 0:success. 1183 */ 1184 aos_status_t aos_event_new(aos_event_t *event, uint32_t value); 1185 1186 /** 1187 * This function will check if event is valid. 1188 * Deprecated, not Recommended. 1189 * 1190 * @param[in] event pointer to the event. 1191 * 1192 * @return false: invalid, true: valid. 1193 */ 1194 bool aos_event_is_valid(aos_event_t *event); 1195 1196 /** 1197 * This function will create a queue. 1198 * Deprecated, not Recommended. 1199 * 1200 * @param[in] queue pointer to the queue(the space is provided by user). 1201 * @param[in] buf buf of the queue(provided by user). 1202 * @param[in] size the bytes of the buf. 1203 * @param[in] max_msg the max size of the msg. 1204 * 1205 * @return 0: success. 1206 */ 1207 aos_status_t aos_queue_new(aos_queue_t *queue, void *buf, size_t size, size_t max_msg); 1208 1209 /** 1210 * This function will check if queue is valid. 1211 * Deprecated, not Recommended. 1212 * 1213 * @param[in] queue pointer to the queue. 1214 * 1215 * @return false: invalid, true: valid. 1216 */ 1217 bool aos_queue_is_valid(aos_queue_t *queue); 1218 1219 /** 1220 * This function will return buf start ptr if queue is inited. 1221 * Deprecated, not Recommended. 1222 * 1223 * @param[in] queue pointer to the queue. 1224 * 1225 * @return NULL: error. 1226 */ 1227 void *aos_queue_buf_ptr(aos_queue_t *queue); 1228 1229 /** @} */ 1230 1231 /** 1232 * @addtogroup aos_kernel_timer 1233 * 提供AliOS Things系统内核定时器功能的基础API. 1234 * 1235 * @{ 1236 */ 1237 1238 /** 1239 * This function will create a timer and run auto. 1240 * Deprecated, not Recommended. 1241 * 1242 * @param[in] timer pointer to the timer. 1243 * @param[in] fn callbak of the timer. 1244 * @param[in] arg the argument of the callback. 1245 * @param[in] ms ms of the normal timer triger. 1246 * @param[in] repeat repeat or not when the timer is created. 1247 * @note fn first arg: timer->hdl, not aos_timer_t *timer; second arg: user param arg. 1248 * @return 0: success. 1249 */ 1250 aos_status_t aos_timer_new(aos_timer_t *timer, void (*fn)(void *, void *), void *arg, 1251 uint32_t ms, bool repeat); 1252 1253 /** 1254 * This function will create a timer. 1255 * Deprecated, not Recommended. 1256 * 1257 * @param[in] timer pointer to the timer. 1258 * @param[in] fn callbak of the timer. 1259 * @param[in] arg the argument of the callback. 1260 * @param[in] ms ms of the normal timer triger. 1261 * @param[in] repeat repeat or not when the timer is created. 1262 * @param[in] autorun auto run. 1263 * @note fn first arg: timer->hdl, not aos_timer_t *timer; second arg: user param arg. 1264 * @return 0: success. 1265 */ 1266 aos_status_t aos_timer_new_ext(aos_timer_t *timer, void (*fn)(void *, void *), void *arg, 1267 uint32_t ms, bool repeat, bool autorun); 1268 1269 /** @} */ 1270 1271 /** @} */ 1272 1273 #ifdef __cplusplus 1274 } 1275 #endif 1276 1277 #endif /* AOS_KERNEL_H */ 1278