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  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  18  * KIND, either express or implied.
  19  *
  20  ****************************************************************************/
  21
  22 #ifndef THREAD_H
  23 #define THREAD_H
  24
  25 #include "config.h"
  26 #include <inttypes.h>
  27 #include <stddef.h>
  28 #include <stdbool.h>
  29 #include "gcc_extensions.h"
  30
  31 /* Priority scheduling (when enabled with HAVE_PRIORITY_SCHEDULING) works
  32  * by giving high priority threads more CPU time than lower priority threads
  33  * when they need it. Priority is differential such that the priority
  34  * difference between a lower priority runnable thread and the highest priority
  35  * runnable thread determines the amount of aging necessary for the lower
  36  * priority thread to be scheduled in order to prevent starvation.
  37  *
  38  * If software playback codec pcm buffer is going down to critical, codec
  39  * can gradually raise its own priority to override user interface and
  40  * prevent playback skipping.
  41  */
  42 #define PRIORITY_RESERVED_HIGH   0   /* Reserved */
  43 #define PRIORITY_RESERVED_LOW    32  /* Reserved */
  44 #define HIGHEST_PRIORITY         1   /* The highest possible thread priority */
  45 #define LOWEST_PRIORITY          31  /* The lowest possible thread priority */
  46 /* Realtime range reserved for threads that will not allow threads of lower
  47  * priority to age and run (future expansion) */
  48 #define PRIORITY_REALTIME_1      1
  49 #define PRIORITY_REALTIME_2      2
  50 #define PRIORITY_REALTIME_3      3
  51 #define PRIORITY_REALTIME_4      4
  52 #define PRIORITY_REALTIME        4   /* Lowest realtime range */
  53 #define PRIORITY_BUFFERING       15  /* Codec buffering thread */
  54 #define PRIORITY_USER_INTERFACE  16  /* The main thread */
  55 #define PRIORITY_RECORDING       16  /* Recording thread */
  56 #define PRIORITY_PLAYBACK        16  /* Variable between this and MAX */
  57 #define PRIORITY_PLAYBACK_MAX    5   /* Maximum allowable playback priority */
  58 #define PRIORITY_SYSTEM          18  /* All other firmware threads */
  59 #define PRIORITY_BACKGROUND      20  /* Normal application threads */
  60 #define NUM_PRIORITIES           32
  61 #define PRIORITY_IDLE            32  /* Priority representative of no tasks */
  62
  63 #define IO_PRIORITY_IMMEDIATE    0
  64 #define IO_PRIORITY_BACKGROUND   32
  65
  66 #if CONFIG_CODEC == SWCODEC
  67
  68 #ifdef HAVE_RECORDING
  69 #ifdef HAVE_HARDWARE_CLICK
  70 #define BASETHREADS  18
  71 #else
  72 #define BASETHREADS  17
  73 #endif
  74 #else
  75 #ifdef HAVE_HARDWARE_CLICK
  76 #define BASETHREADS  17
  77 #else
  78 #define BASETHREADS  16
  79 #endif
  80 #endif
  81
  82 #else
  83 #define BASETHREADS  11
  84 #endif /* CONFIG_CODE == * */
  85
  86 #ifndef TARGET_EXTRA_THREADS
  87 #define TARGET_EXTRA_THREADS 0
  88 #endif
  89
  90 #define MAXTHREADS (BASETHREADS+TARGET_EXTRA_THREADS)
  91
  92 /*
  93  * We need more stack when we run under a host
  94  * maybe more expensive C lib functions?
  95  *
  96  * simulator (possibly) doesn't simulate stack usage anyway but well ... */
  97
  98 #if defined(HAVE_SDL_THREADS) || defined(__PCTOOL__)
  99 struct regs
 100 {
 101     void *t;             /* OS thread */
 102     void *told;          /* Last thread in slot (explained in thead-sdl.c) */
 103     void *s;             /* Semaphore for blocking and wakeup */
 104     void (*start)(void); /* Start function */
 105 };
 106
 107 #define DEFAULT_STACK_SIZE 0x100 /* tiny, ignored anyway */
 108 #else
 109 #include "asm/thread.h"
 110 #endif /* HAVE_SDL_THREADS */
 111
 112 #ifdef CPU_PP
 113 #ifdef HAVE_CORELOCK_OBJECT
 114 /* No reliable atomic instruction available - use Peterson's algorithm */
 115 struct corelock
 116 {
 117     volatile unsigned char myl[NUM_CORES];
 118     volatile unsigned char turn;
 119 } __attribute__((packed));
 120
 121 /* Too big to inline everywhere */
 122 void corelock_init(struct corelock *cl);
 123 void corelock_lock(struct corelock *cl);
 124 int corelock_try_lock(struct corelock *cl);
 125 void corelock_unlock(struct corelock *cl);
 126 #endif /* HAVE_CORELOCK_OBJECT */
 127 #endif /* CPU_PP */
 128
 129 /* NOTE: The use of the word "queue" may also refer to a linked list of
 130    threads being maintained that are normally dealt with in FIFO order
 131    and not necessarily kernel event_queue */
 132 enum
 133 {
 134     /* States without a timeout must be first */
 135     STATE_KILLED = 0,    /* Thread is killed (default) */
 136     STATE_RUNNING,       /* Thread is currently running */
 137     STATE_BLOCKED,       /* Thread is indefinitely blocked on a queue */
 138     /* These states involve adding the thread to the tmo list */
 139     STATE_SLEEPING,      /* Thread is sleeping with a timeout */
 140     STATE_BLOCKED_W_TMO, /* Thread is blocked on a queue with a timeout */
 141     /* Miscellaneous states */
 142     STATE_FROZEN,        /* Thread is suspended and will not run until
 143                             thread_thaw is called with its ID */
 144     THREAD_NUM_STATES,
 145     TIMEOUT_STATE_FIRST = STATE_SLEEPING,
 146 };
 147
 148 #if NUM_CORES > 1
 149 /* Pointer value for name field to indicate thread is being killed. Using
 150  * an alternate STATE_* won't work since that would interfere with operation
 151  * while the thread is still running. */
 152 #define THREAD_DESTRUCT ((const char *)~(intptr_t)0)
 153 #endif
 154
 155 /* Link information for lists thread is in */
 156 struct thread_entry; /* forward */
 157 struct thread_list
 158 {
 159     struct thread_entry *prev; /* Previous thread in a list */
 160     struct thread_entry *next; /* Next thread in a list */
 161 };
 162
 163 #ifndef HAVE_CORELOCK_OBJECT
 164 /* No atomic corelock op needed or just none defined */
 165 #define corelock_init(cl)
 166 #define corelock_lock(cl)
 167 #define corelock_try_lock(cl)
 168 #define corelock_unlock(cl)
 169 #endif /* HAVE_CORELOCK_OBJECT */
 170
 171 #ifdef HAVE_PRIORITY_SCHEDULING
 172 struct blocker
 173 {
 174     struct thread_entry * volatile thread; /* thread blocking other threads
 175                                               (aka. object owner) */
 176     int priority;                  /* highest priority waiter */
 177     struct thread_entry * (*wakeup_protocol)(struct thread_entry *thread);
 178 };
 179
 180 /* Choices of wakeup protocol */
 181
 182 /* For transfer of object ownership by one thread to another thread by
 183  * the owning thread itself (mutexes) */
 184 struct thread_entry *
 185     wakeup_priority_protocol_transfer(struct thread_entry *thread);
 186
 187 /* For release by owner where ownership doesn't change - other threads,
 188  * interrupts, timeouts, etc. (mutex timeout, queues) */
 189 struct thread_entry *
 190     wakeup_priority_protocol_release(struct thread_entry *thread);
 191
 192
 193 struct priority_distribution
 194 {
 195     uint8_t  hist[NUM_PRIORITIES]; /* Histogram: Frequency for each priority */
 196     uint32_t mask;                 /* Bitmask of hist entries that are not zero */
 197 };
 198
 199 #endif /* HAVE_PRIORITY_SCHEDULING */
 200
 201 /* Information kept in each thread slot
 202  * members are arranged according to size - largest first - in order
 203  * to ensure both alignment and packing at the same time.
 204  */
 205 struct thread_entry
 206 {
 207     struct regs context;       /* Register context at switch -
 208                                   _must_ be first member */
 209     uintptr_t *stack;          /* Pointer to top of stack */
 210     const char *name;          /* Thread name */
 211     long tmo_tick;             /* Tick when thread should be woken from
 212                                   timeout -
 213                                   states: STATE_SLEEPING/STATE_BLOCKED_W_TMO */
 214     struct thread_list l;      /* Links for blocked/waking/running -
 215                                   circular linkage in both directions */
 216     struct thread_list tmo;    /* Links for timeout list -
 217                                   Circular in reverse direction, NULL-terminated in
 218                                   forward direction -
 219                                   states: STATE_SLEEPING/STATE_BLOCKED_W_TMO */
 220     struct thread_entry **bqp; /* Pointer to list variable in kernel
 221                                   object where thread is blocked - used
 222                                   for implicit unblock and explicit wake
 223                                   states: STATE_BLOCKED/STATE_BLOCKED_W_TMO  */
 224 #ifdef HAVE_CORELOCK_OBJECT
 225     struct corelock *obj_cl;   /* Object corelock where thead is blocked -
 226                                   states: STATE_BLOCKED/STATE_BLOCKED_W_TMO */
 227     struct corelock waiter_cl; /* Corelock for thread_wait */
 228     struct corelock slot_cl;   /* Corelock to lock thread slot */
 229     unsigned char core;        /* The core to which thread belongs */
 230 #endif
 231     struct thread_entry *queue; /* List of threads waiting for thread to be
 232                                   removed */
 233 #ifdef HAVE_WAKEUP_EXT_CB
 234     void (*wakeup_ext_cb)(struct thread_entry *thread); /* Callback that
 235                                   performs special steps needed when being
 236                                   forced off of an object's wait queue that
 237                                   go beyond the standard wait queue removal
 238                                   and priority disinheritance */
 239     /* Only enabled when using queue_send for now */
 240 #endif
 241 #if defined(HAVE_SEMAPHORE_OBJECTS) || \
 242     defined(HAVE_EXTENDED_MESSAGING_AND_NAME) || \
 243     NUM_CORES > 1
 244     volatile intptr_t retval;  /* Return value from a blocked operation/
 245                                   misc. use */
 246 #endif
 247 #ifdef HAVE_PRIORITY_SCHEDULING
 248     /* Priority summary of owned objects that support inheritance */
 249     struct blocker *blocker;   /* Pointer to blocker when this thread is blocked
 250                                   on an object that supports PIP -
 251                                   states: STATE_BLOCKED/STATE_BLOCKED_W_TMO  */
 252     struct priority_distribution pdist; /* Priority summary of owned objects
 253                                   that have blocked threads and thread's own
 254                                   base priority */
 255     int skip_count;            /* Number of times skipped if higher priority
 256                                   thread was running */
 257     unsigned char base_priority; /* Base priority (set explicitly during
 258                                   creation or thread_set_priority) */
 259     unsigned char priority;    /* Scheduled priority (higher of base or
 260                                   all threads blocked by this one) */
 261 #endif
 262     uint16_t id;               /* Current slot id */
 263     unsigned short stack_size; /* Size of stack in bytes */
 264     unsigned char state;       /* Thread slot state (STATE_*) */
 265 #ifdef HAVE_SCHEDULER_BOOSTCTRL
 266     unsigned char cpu_boost;   /* CPU frequency boost flag */
 267 #endif
 268 #ifdef HAVE_IO_PRIORITY
 269     unsigned char io_priority;
 270 #endif
 271 };
 272
 273 /*** Macros for internal use ***/
 274 /* Thread ID, 16 bits = |VVVVVVVV|SSSSSSSS| */
 275 #define THREAD_ID_VERSION_SHIFT      8
 276 #define THREAD_ID_VERSION_MASK  0xff00
 277 #define THREAD_ID_SLOT_MASK     0x00ff
 278 #define THREAD_ID_INIT(n)       ((1u << THREAD_ID_VERSION_SHIFT) | (n))
 279
 280 #ifdef HAVE_CORELOCK_OBJECT
 281 /* Operations to be performed just before stopping a thread and starting
 282    a new one if specified before calling switch_thread */
 283 enum
 284 {
 285     TBOP_CLEAR = 0,       /* No operation to do */
 286     TBOP_UNLOCK_CORELOCK, /* Unlock a corelock variable */
 287     TBOP_SWITCH_CORE,     /* Call the core switch preparation routine */
 288 };
 289
 290 struct thread_blk_ops
 291 {
 292     struct corelock *cl_p;    /* pointer to corelock */
 293     unsigned char    flags;   /* TBOP_* flags */
 294 };
 295 #endif /* NUM_CORES > 1 */
 296
 297 /* Information kept for each core
 298  * Members are arranged for the same reason as in thread_entry
 299  */
 300 struct core_entry
 301 {
 302     /* "Active" lists - core is constantly active on these and are never
 303        locked and interrupts do not access them */
 304     struct thread_entry *running;  /* threads that are running (RTR) */
 305     struct thread_entry *timeout;  /* threads that are on a timeout before
 306                                       running again */
 307     struct thread_entry *block_task; /* Task going off running list */
 308 #ifdef HAVE_PRIORITY_SCHEDULING
 309     struct priority_distribution rtr; /* Summary of running and ready-to-run
 310                                          threads */
 311 #endif
 312     long next_tmo_check;           /* soonest time to check tmo threads */
 313 #ifdef HAVE_CORELOCK_OBJECT
 314     struct thread_blk_ops blk_ops; /* operations to perform when
 315                                       blocking a thread */
 316     struct corelock rtr_cl;        /* Lock for rtr list */
 317 #endif /* NUM_CORES */
 318 };
 319
 320 #ifdef HAVE_PRIORITY_SCHEDULING
 321 #define IF_PRIO(...)    __VA_ARGS__
 322 #define IFN_PRIO(...)
 323 #else
 324 #define IF_PRIO(...)
 325 #define IFN_PRIO(...)   __VA_ARGS__
 326 #endif
 327
 328 void core_idle(void);
 329 void core_wake(IF_COP_VOID(unsigned int core));
 330
 331 /* Initialize the scheduler */
 332 void init_threads(void) INIT_ATTR;
 333
 334 /* Allocate a thread in the scheduler */
 335 #define CREATE_THREAD_FROZEN   0x00000001 /* Thread is frozen at create time */
 336 unsigned int create_thread(void (*function)(void),
 337                            void* stack, size_t stack_size,
 338                            unsigned flags, const char *name
 339                            IF_PRIO(, int priority)
 340                            IF_COP(, unsigned int core));
 341
 342 /* Set and clear the CPU frequency boost flag for the calling thread */
 343 #ifdef HAVE_SCHEDULER_BOOSTCTRL
 344 void trigger_cpu_boost(void);
 345 void cancel_cpu_boost(void);
 346 #else
 347 #define trigger_cpu_boost() do { } while(0)
 348 #define cancel_cpu_boost() do { } while(0)
 349 #endif
 350 /* Return thread entry from id */
 351 struct thread_entry *thread_id_entry(unsigned int thread_id);
 352 /* Make a frozed thread runnable (when started with CREATE_THREAD_FROZEN).
 353  * Has no effect on a thread not frozen. */
 354 void thread_thaw(unsigned int thread_id);
 355 /* Wait for a thread to exit */
 356 void thread_wait(unsigned int thread_id);
 357 /* Exit the current thread */
 358 void thread_exit(void) NORETURN_ATTR;
 359 #if defined(DEBUG) || defined(ROCKBOX_HAS_LOGF)
 360 #define ALLOW_REMOVE_THREAD
 361 /* Remove a thread from the scheduler */
 362 void remove_thread(unsigned int thread_id);
 363 #endif
 364
 365 /* Switch to next runnable thread */
 366 void switch_thread(void);
 367 /* Blocks a thread for at least the specified number of ticks (0 = wait until
 368  * next tick) */
 369 void sleep_thread(int ticks);
 370 /* Indefinitely blocks the current thread on a thread queue */
 371 void block_thread(struct thread_entry *current);
 372 /* Blocks the current thread on a thread queue until explicitely woken or
 373  * the timeout is reached */
 374 void block_thread_w_tmo(struct thread_entry *current, int timeout);
 375
 376 /* Return bit flags for thread wakeup */
 377 #define THREAD_NONE     0x0 /* No thread woken up (exclusive) */
 378 #define THREAD_OK       0x1 /* A thread was woken up */
 379 #define THREAD_SWITCH   0x2 /* Task switch recommended (one or more of
 380                                higher priority than current were woken) */
 381
 382 /* A convenience function for waking an entire queue of threads. */
 383 unsigned int thread_queue_wake(struct thread_entry **list);
 384
 385 /* Wakeup a thread at the head of a list */
 386 unsigned int wakeup_thread(struct thread_entry **list);
 387
 388 #ifdef HAVE_PRIORITY_SCHEDULING
 389 int thread_set_priority(unsigned int thread_id, int priority);
 390 int thread_get_priority(unsigned int thread_id);
 391 #endif /* HAVE_PRIORITY_SCHEDULING */
 392 #ifdef HAVE_IO_PRIORITY
 393 void thread_set_io_priority(unsigned int thread_id, int io_priority);
 394 int thread_get_io_priority(unsigned int thread_id);
 395 #endif /* HAVE_IO_PRIORITY */
 396 #if NUM_CORES > 1
 397 unsigned int switch_core(unsigned int new_core);
 398 #endif
 399
 400 /* Return the id of the calling thread. */
 401 unsigned int thread_self(void);
 402
 403 /* Return the thread_entry for the calling thread.
 404  * INTERNAL: Intended for use by kernel and not for programs. */
 405 struct thread_entry* thread_self_entry(void);
 406
 407 /* Debugging info - only! */
 408 int thread_stack_usage(const struct thread_entry *thread);
 409 #if NUM_CORES > 1
 410 int idle_stack_usage(unsigned int core);
 411 #endif
 412 void thread_get_name(char *buffer, int size,
 413                      struct thread_entry *thread);
 414 #ifdef RB_PROFILE
 415 void profile_thread(void);
 416 #endif
 417
 418 #endif /* THREAD_H */