firmware/export/thread.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) 2002 by Ulf Ralberg
  11  *
  12  * All files in this archive are subject to the GNU General Public License.
  13  * See the file COPYING in the source tree root for full license agreement.
  14  *
  15  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  16  * KIND, either express or implied.
  17  *
  18  ****************************************************************************/
  19 #ifndef THREAD_H
  20 #define THREAD_H
  21
  22 #include "config.h"
  23 #include <inttypes.h>
  24 #include <stddef.h>
  25 #include <stdbool.h>
  26
  27 /* Priority scheduling (when enabled with HAVE_PRIORITY_SCHEDULING) works
  28  * by giving high priority threads more CPU time than less priority threads
  29  * when they need it. Priority is differential such that the priority
  30  * difference between a lower priority runnable thread and the highest priority
  31  * runnable thread determines the amount of aging nescessary for the lower
  32  * priority thread to be scheduled in order to prevent starvation.
  33  *
  34  * If software playback codec pcm buffer is going down to critical, codec
  35  * can gradually raise its own priority to override user interface and
  36  * prevent playback skipping.
  37  */
  38 #define PRIORITY_RESERVED_HIGH   0   /* Reserved */
  39 #define PRIORITY_RESERVED_LOW    32  /* Reserved */
  40 #define HIGHEST_PRIORITY         1   /* The highest possible thread priority */
  41 #define LOWEST_PRIORITY          31  /* The lowest possible thread priority */
  42 /* Realtime range reserved for threads that will not allow threads of lower
  43  * priority to age and run (future expansion) */
  44 #define PRIORITY_REALTIME_1      1
  45 #define PRIORITY_REALTIME_2      2
  46 #define PRIORITY_REALTIME_3      3
  47 #define PRIORITY_REALTIME_4      4
  48 #define PRIORITY_REALTIME        4   /* Lowest realtime range */
  49 #define PRIORITY_BUFFERING       15  /* Codec buffering thread */
  50 #define PRIORITY_USER_INTERFACE  16  /* The main thread */
  51 #define PRIORITY_RECORDING       16  /* Recording thread */
  52 #define PRIORITY_PLAYBACK        16  /* Variable between this and MAX */
  53 #define PRIORITY_PLAYBACK_MAX    5   /* Maximum allowable playback priority */
  54 #define PRIORITY_SYSTEM          18  /* All other firmware threads */
  55 #define PRIORITY_BACKGROUND      20  /* Normal application threads */
  56 #define NUM_PRIORITIES           32
  57 #define PRIORITY_IDLE            32  /* Priority representative of no tasks */
  58
  59 /* TODO: Only a minor tweak to create_thread would be needed to let
  60  * thread slots be caller allocated - no essential threading functionality
  61  * depends upon an array */
  62 #if CONFIG_CODEC == SWCODEC
  63
  64 #ifdef HAVE_RECORDING
  65 #define BASETHREADS  18
  66 #else
  67 #define BASETHREADS  17
  68 #endif
  69
  70 #else
  71 #define BASETHREADS  11
  72 #endif /* CONFIG_CODE == * */
  73
  74 #ifndef TARGET_EXTRA_THREADS
  75 #define TARGET_EXTRA_THREADS 0
  76 #endif
  77
  78 #define MAXTHREADS (BASETHREADS+TARGET_EXTRA_THREADS)
  79
  80 #define DEFAULT_STACK_SIZE 0x400 /* Bytes */
  81
  82 #ifndef SIMULATOR
  83 /* Need to keep structures inside the header file because debug_menu
  84  * needs them. */
  85 #ifdef CPU_COLDFIRE
  86 struct regs
  87 {
  88     uint32_t macsr; /*     0 - EMAC status register */
  89     uint32_t d[6];  /*  4-24 - d2-d7 */
  90     uint32_t a[5];  /* 28-44 - a2-a6 */
  91     uint32_t sp;    /*    48 - Stack pointer (a7) */
  92     uint32_t start; /*    52 - Thread start address, or NULL when started */
  93 };
  94 #elif CONFIG_CPU == SH7034
  95 struct regs
  96 {
  97     uint32_t r[7];  /*  0-24 - Registers r8 thru r14 */
  98     uint32_t sp;    /*    28 - Stack pointer (r15) */
  99     uint32_t pr;    /*    32 - Procedure register */
 100     uint32_t start; /*    36 - Thread start address, or NULL when started */
 101 };
 102 #elif defined(CPU_ARM)
 103 struct regs
 104 {
 105     uint32_t r[8];  /*  0-28 - Registers r4-r11 */
 106     uint32_t sp;    /*    32 - Stack pointer (r13) */
 107     uint32_t lr;    /*    36 - r14 (lr) */
 108     uint32_t start; /*    40 - Thread start address, or NULL when started */
 109 };
 110 #endif /* CONFIG_CPU */
 111 #else
 112 struct regs
 113 {
 114     void *t;             /* Simulator OS thread */
 115     void *s;             /* Semaphore for blocking and wakeup */
 116     void (*start)(void); /* Start function */
 117 };
 118 #endif /* !SIMULATOR */
 119
 120 /* NOTE: The use of the word "queue" may also refer to a linked list of
 121    threads being maintainted that are normally dealt with in FIFO order
 122    and not nescessarily kernel event_queue */
 123 enum
 124 {
 125     /* States without a timeout must be first */
 126     STATE_KILLED = 0,    /* Thread is killed (default) */
 127     STATE_RUNNING,       /* Thread is currently running */
 128     STATE_BLOCKED,       /* Thread is indefinitely blocked on a queue */
 129     /* These states involve adding the thread to the tmo list */
 130     STATE_SLEEPING,      /* Thread is sleeping with a timeout */
 131     STATE_BLOCKED_W_TMO, /* Thread is blocked on a queue with a timeout */
 132     /* Miscellaneous states */
 133     STATE_FROZEN,        /* Thread is suspended and will not run until
 134                             thread_thaw is called with its ID */
 135     THREAD_NUM_STATES,
 136     TIMEOUT_STATE_FIRST = STATE_SLEEPING,
 137 };
 138
 139 #if NUM_CORES > 1
 140 /* Pointer value for name field to indicate thread is being killed. Using
 141  * an alternate STATE_* won't work since that would interfere with operation
 142  * while the thread is still running. */
 143 #define THREAD_DESTRUCT ((const char *)~(intptr_t)0)
 144 #endif
 145
 146 /* Link information for lists thread is in */
 147 struct thread_entry; /* forward */
 148 struct thread_list
 149 {
 150     struct thread_entry *prev; /* Previous thread in a list */
 151     struct thread_entry *next; /* Next thread in a list */
 152 };
 153
 154 /* Small objects for core-wise mutual exclusion */
 155 #if CONFIG_CORELOCK == SW_CORELOCK
 156 /* No reliable atomic instruction available - use Peterson's algorithm */
 157 struct corelock
 158 {
 159     volatile unsigned char myl[NUM_CORES];
 160     volatile unsigned char turn;
 161 } __attribute__((packed));
 162
 163 void corelock_init(struct corelock *cl);
 164 void corelock_lock(struct corelock *cl);
 165 int corelock_try_lock(struct corelock *cl);
 166 void corelock_unlock(struct corelock *cl);
 167 #elif CONFIG_CORELOCK == CORELOCK_SWAP
 168 /* Use native atomic swap/exchange instruction */
 169 struct corelock
 170 {
 171     volatile unsigned char locked;
 172 } __attribute__((packed));
 173
 174 #define corelock_init(cl) \
 175     ({ (cl)->locked = 0; })
 176 #define corelock_lock(cl) \
 177     ({ while (test_and_set(&(cl)->locked, 1)); })
 178 #define corelock_try_lock(cl) \
 179     ({ test_and_set(&(cl)->locked, 1) ? 0 : 1; })
 180 #define corelock_unlock(cl) \
 181     ({ (cl)->locked = 0; })
 182 #else
 183 /* No atomic corelock op needed or just none defined */
 184 #define corelock_init(cl)
 185 #define corelock_lock(cl)
 186 #define corelock_try_lock(cl)
 187 #define corelock_unlock(cl)
 188 #endif /* core locking selection */
 189
 190 #ifdef HAVE_PRIORITY_SCHEDULING
 191 struct blocker
 192 {
 193     struct thread_entry *thread;   /* thread blocking other threads
 194                                       (aka. object owner) */
 195     int priority;                  /* highest priority waiter */
 196     struct thread_entry * (*wakeup_protocol)(struct thread_entry *thread);
 197 };
 198
 199 /* Choices of wakeup protocol */
 200
 201 /* For transfer of object ownership by one thread to another thread by
 202  * the owning thread itself (mutexes) */
 203 struct thread_entry *
 204     wakeup_priority_protocol_transfer(struct thread_entry *thread);
 205
 206 /* For release by owner where ownership doesn't change - other threads,
 207  * interrupts, timeouts, etc. (mutex timeout, queues) */
 208 struct thread_entry *
 209     wakeup_priority_protocol_release(struct thread_entry *thread);
 210
 211
 212 struct priority_distribution
 213 {
 214     uint8_t  hist[NUM_PRIORITIES]; /* Histogram: Frequency for each priority */
 215     uint32_t mask;                 /* Bitmask of hist entries that are not zero */
 216 };
 217
 218 #endif /* HAVE_PRIORITY_SCHEDULING */
 219
 220 /* Information kept in each thread slot
 221  * members are arranged according to size - largest first - in order
 222  * to ensure both alignment and packing at the same time.
 223  */
 224 struct thread_entry
 225 {
 226     struct regs context;       /* Register context at switch -
 227                                   _must_ be first member */
 228     uintptr_t *stack;          /* Pointer to top of stack */
 229     const char *name;          /* Thread name */
 230     long tmo_tick;             /* Tick when thread should be woken from
 231                                   timeout -
 232                                   states: STATE_SLEEPING/STATE_BLOCKED_W_TMO */
 233     struct thread_list l;      /* Links for blocked/waking/running -
 234                                   circular linkage in both directions */
 235     struct thread_list tmo;    /* Links for timeout list -
 236                                   Circular in reverse direction, NULL-terminated in
 237                                   forward direction -
 238                                   states: STATE_SLEEPING/STATE_BLOCKED_W_TMO */
 239     struct thread_entry **bqp; /* Pointer to list variable in kernel
 240                                   object where thread is blocked - used
 241                                   for implicit unblock and explicit wake
 242                                   states: STATE_BLOCKED/STATE_BLOCKED_W_TMO  */
 243 #if NUM_CORES > 1
 244     struct corelock *obj_cl;   /* Object corelock where thead is blocked -
 245                                   states: STATE_BLOCKED/STATE_BLOCKED_W_TMO */
 246 #endif
 247     struct thread_entry *queue; /* List of threads waiting for thread to be
 248                                   removed */
 249 #ifdef HAVE_EXTENDED_MESSAGING_AND_NAME
 250     #define HAVE_WAKEUP_EXT_CB
 251     void (*wakeup_ext_cb)(struct thread_entry *thread); /* Callback that
 252                                   performs special steps needed when being
 253                                   forced off of an object's wait queue that
 254                                   go beyond the standard wait queue removal
 255                                   and priority disinheritance */
 256     /* Only enabled when using queue_send for now */
 257 #endif
 258 #if defined(HAVE_EXTENDED_MESSAGING_AND_NAME) || NUM_CORES > 1
 259     intptr_t retval;           /* Return value from a blocked operation/
 260                                   misc. use */
 261 #endif
 262 #ifdef HAVE_PRIORITY_SCHEDULING
 263     /* Priority summary of owned objects that support inheritance */
 264     struct blocker *blocker;   /* Pointer to blocker when this thread is blocked
 265                                   on an object that supports PIP -
 266                                   states: STATE_BLOCKED/STATE_BLOCKED_W_TMO  */
 267     struct priority_distribution pdist; /* Priority summary of owned objects
 268                                   that have blocked threads and thread's own
 269                                   base priority */
 270     int skip_count;            /* Number of times skipped if higher priority
 271                                   thread was running */
 272 #endif
 273     unsigned short stack_size; /* Size of stack in bytes */
 274 #ifdef HAVE_PRIORITY_SCHEDULING
 275     unsigned char base_priority; /* Base priority (set explicitly during
 276                                   creation or thread_set_priority) */
 277     unsigned char priority;    /* Scheduled priority (higher of base or
 278                                   all threads blocked by this one) */
 279 #endif
 280     unsigned char state;       /* Thread slot state (STATE_*) */
 281 #ifdef HAVE_SCHEDULER_BOOSTCTRL
 282     unsigned char cpu_boost;   /* CPU frequency boost flag */
 283 #endif
 284 #if NUM_CORES > 1
 285     unsigned char core;        /* The core to which thread belongs */
 286     struct corelock waiter_cl; /* Corelock for thread_wait */
 287     struct corelock slot_cl;   /* Corelock to lock thread slot */
 288 #endif
 289 };
 290
 291 #if NUM_CORES > 1
 292 /* Operations to be performed just before stopping a thread and starting
 293    a new one if specified before calling switch_thread */
 294 enum
 295 {
 296     TBOP_CLEAR = 0,       /* No operation to do */
 297     TBOP_UNLOCK_CORELOCK, /* Unlock a corelock variable */
 298     TBOP_SWITCH_CORE,     /* Call the core switch preparation routine */
 299 };
 300
 301 struct thread_blk_ops
 302 {
 303     struct corelock *cl_p;    /* pointer to corelock */
 304     unsigned char    flags;   /* TBOP_* flags */
 305 };
 306 #endif /* NUM_CORES > 1 */
 307
 308 /* Information kept for each core
 309  * Member are arranged for the same reason as in thread_entry
 310  */
 311 struct core_entry
 312 {
 313     /* "Active" lists - core is constantly active on these and are never
 314        locked and interrupts do not access them */
 315     struct thread_entry *running;  /* threads that are running (RTR) */
 316     struct thread_entry *timeout;  /* threads that are on a timeout before
 317                                       running again */
 318     struct thread_entry *block_task; /* Task going off running list */
 319 #ifdef HAVE_PRIORITY_SCHEDULING
 320     struct priority_distribution rtr; /* Summary of running and ready-to-run
 321                                          threads */
 322 #endif
 323     long next_tmo_check;           /* soonest time to check tmo threads */
 324 #if NUM_CORES > 1
 325     struct thread_blk_ops blk_ops; /* operations to perform when
 326                                       blocking a thread */
 327 #ifdef HAVE_PRIORITY_SCHEDULING
 328     struct corelock rtr_cl;        /* Lock for rtr list */
 329 #endif
 330 #endif /* NUM_CORES */
 331 };
 332
 333 #ifdef HAVE_PRIORITY_SCHEDULING
 334 #define IF_PRIO(...)    __VA_ARGS__
 335 #define IFN_PRIO(...)
 336 #else
 337 #define IF_PRIO(...)
 338 #define IFN_PRIO(...)   __VA_ARGS__
 339 #endif
 340
 341 /* Macros generate better code than an inline function is this case */
 342 #if (defined (CPU_PP) || defined (CPU_ARM))
 343 /* atomic */
 344 #if CONFIG_CORELOCK == SW_CORELOCK
 345 #define test_and_set(a, v, cl) \
 346     xchg8((a), (v), (cl))
 347 /* atomic */
 348 #define xchg8(a, v, cl) \
 349 ({  uint32_t o;            \
 350     corelock_lock(cl);     \
 351     o = *(uint8_t *)(a);   \
 352     *(uint8_t *)(a) = (v); \
 353     corelock_unlock(cl);   \
 354     o; })
 355 #define xchg32(a, v, cl) \
 356 ({  uint32_t o;             \
 357     corelock_lock(cl);      \
 358     o = *(uint32_t *)(a);   \
 359     *(uint32_t *)(a) = (v); \
 360     corelock_unlock(cl);    \
 361     o; })
 362 #define xchgptr(a, v, cl) \
 363 ({  typeof (*(a)) o;     \
 364     corelock_lock(cl);   \
 365     o = *(a);            \
 366     *(a) = (v);          \
 367     corelock_unlock(cl); \
 368     o; })
 369 #elif CONFIG_CORELOCK == CORELOCK_SWAP
 370 /* atomic */
 371 #define test_and_set(a, v, ...) \
 372     xchg8((a), (v))
 373 #define xchg8(a, v, ...) \
 374 ({  uint32_t o;                \
 375     asm volatile(              \
 376         "swpb %0, %1, [%2]"    \
 377         : "=&r"(o)             \
 378         : "r"(v),              \
 379           "r"((uint8_t*)(a))); \
 380     o; })
 381 /* atomic */
 382 #define xchg32(a, v, ...) \
 383 ({  uint32_t o;                 \
 384     asm volatile(               \
 385         "swp %0, %1, [%2]"      \
 386         : "=&r"(o)              \
 387         : "r"((uint32_t)(v)),   \
 388           "r"((uint32_t*)(a))); \
 389     o; })
 390 /* atomic */
 391 #define xchgptr(a, v, ...) \
 392 ({  typeof (*(a)) o;        \
 393     asm volatile(           \
 394         "swp %0, %1, [%2]"  \
 395         : "=&r"(o)          \
 396         : "r"(v), "r"(a));  \
 397     o; })
 398 #endif /* locking selection */
 399 #elif defined (CPU_COLDFIRE)
 400 /* atomic */
 401 /* one branch will be optimized away if v is a constant expression */
 402 #define test_and_set(a, v, ...) \
 403 ({  uint32_t o = 0;                \
 404     if (v) {                       \
 405         asm volatile (             \
 406             "bset.b #0, (%0)"      \
 407             : : "a"((uint8_t*)(a)) \
 408             : "cc");               \
 409     } else {                       \
 410         asm volatile (             \
 411             "bclr.b #0, (%0)"      \
 412             : : "a"((uint8_t*)(a)) \
 413             : "cc");               \
 414     }                              \
 415     asm volatile ("sne.b %0"       \
 416         : "+d"(o));                \
 417     o; })
 418 #elif CONFIG_CPU == SH7034
 419 /* atomic */
 420 #define test_and_set(a, v, ...) \
 421 ({  uint32_t o;                 \
 422     asm volatile (              \
 423         "tas.b  @%2     \n"     \
 424         "mov    #-1, %0 \n"     \
 425         "negc   %0, %0  \n"     \
 426         : "=r"(o)               \
 427         : "M"((uint32_t)(v)),   /* Value of_v must be 1 */ \
 428           "r"((uint8_t *)(a))); \
 429     o; })
 430 #endif /* CONFIG_CPU == */
 431
 432 /* defaults for no asm version */
 433 #ifndef test_and_set
 434 /* not atomic */
 435 #define test_and_set(a, v, ...) \
 436 ({  uint32_t o = *(uint8_t *)(a); \
 437     *(uint8_t *)(a) = (v);        \
 438     o; })
 439 #endif /* test_and_set */
 440 #ifndef xchg8
 441 /* not atomic */
 442 #define xchg8(a, v, ...) \
 443 ({  uint32_t o = *(uint8_t *)(a); \
 444     *(uint8_t *)(a) = (v);        \
 445     o; })
 446 #endif /* xchg8 */
 447 #ifndef xchg32
 448 /* not atomic */
 449 #define xchg32(a, v, ...) \
 450 ({  uint32_t o = *(uint32_t *)(a); \
 451     *(uint32_t *)(a) = (v);        \
 452     o; })
 453 #endif /* xchg32 */
 454 #ifndef xchgptr
 455 /* not atomic */
 456 #define xchgptr(a, v, ...) \
 457 ({  typeof (*(a)) o = *(a); \
 458     *(a) = (v);             \
 459     o; })
 460 #endif /* xchgptr */
 461
 462 void core_idle(void);
 463 void core_wake(IF_COP_VOID(unsigned int core));
 464
 465 /* Initialize the scheduler */
 466 void init_threads(void);
 467
 468 /* Allocate a thread in the scheduler */
 469 #define CREATE_THREAD_FROZEN   0x00000001 /* Thread is frozen at create time */
 470 struct thread_entry*
 471     create_thread(void (*function)(void), void* stack, size_t stack_size,
 472                   unsigned flags, const char *name
 473                   IF_PRIO(, int priority)
 474                           IF_COP(, unsigned int core));
 475
 476 /* Set and clear the CPU frequency boost flag for the calling thread */
 477 #ifdef HAVE_SCHEDULER_BOOSTCTRL
 478 void trigger_cpu_boost(void);
 479 void cancel_cpu_boost(void);
 480 #else
 481 #define trigger_cpu_boost()
 482 #define cancel_cpu_boost()
 483 #endif
 484 /* Make a frozed thread runnable (when started with CREATE_THREAD_FROZEN).
 485  * Has no effect on a thread not frozen. */
 486 void thread_thaw(struct thread_entry *thread);
 487 /* Wait for a thread to exit */
 488 void thread_wait(struct thread_entry *thread);
 489 /* Exit the current thread */
 490 void thread_exit(void);
 491 #if defined(DEBUG) || defined(ROCKBOX_HAS_LOGF)
 492 #define ALLOW_REMOVE_THREAD
 493 /* Remove a thread from the scheduler */
 494 void remove_thread(struct thread_entry *thread);
 495 #endif
 496
 497 /* Switch to next runnable thread */
 498 void switch_thread(void);
 499 /* Blocks a thread for at least the specified number of ticks (0 = wait until
 500  * next tick) */
 501 void sleep_thread(int ticks);
 502 /* Indefinitely blocks the current thread on a thread queue */
 503 void block_thread(struct thread_entry *current);
 504 /* Blocks the current thread on a thread queue until explicitely woken or
 505  * the timeout is reached */
 506 void block_thread_w_tmo(struct thread_entry *current, int timeout);
 507
 508 /* Return bit flags for thread wakeup */
 509 #define THREAD_NONE     0x0 /* No thread woken up (exclusive) */
 510 #define THREAD_OK       0x1 /* A thread was woken up */
 511 #define THREAD_SWITCH   0x2 /* Task switch recommended (one or more of
 512                                higher priority than current were woken) */
 513
 514 /* A convenience function for waking an entire queue of threads. */
 515 unsigned int thread_queue_wake(struct thread_entry **list);
 516
 517 /* Wakeup a thread at the head of a list */
 518 unsigned int wakeup_thread(struct thread_entry **list);
 519
 520 #ifdef HAVE_PRIORITY_SCHEDULING
 521 int thread_set_priority(struct thread_entry *thread, int priority);
 522 int thread_get_priority(struct thread_entry *thread);
 523 #endif /* HAVE_PRIORITY_SCHEDULING */
 524 #if NUM_CORES > 1
 525 unsigned int switch_core(unsigned int new_core);
 526 #endif
 527 struct thread_entry * thread_get_current(void);
 528
 529 /* Debugging info - only! */
 530 int thread_stack_usage(const struct thread_entry *thread);
 531 #if NUM_CORES > 1
 532 int idle_stack_usage(unsigned int core);
 533 #endif
 534 void thread_get_name(char *buffer, int size,
 535                      struct thread_entry *thread);
 536 #ifdef RB_PROFILE
 537 void profile_thread(void);
 538 #endif
 539
 540 #endif /* THREAD_H */