firmware/export/kernel.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) 2002 by Björn Stenberg
  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 #ifndef _KERNEL_H_
  22 #define _KERNEL_H_
  23
  24 #include <stdbool.h>
  25 #include <inttypes.h>
  26 #include "config.h"
  27
  28 #include "thread.h"
  29
  30 /* wrap-safe macros for tick comparison */
  31 #define TIME_AFTER(a,b)         ((long)(b) - (long)(a) < 0)
  32 #define TIME_BEFORE(a,b)        TIME_AFTER(b,a)
  33
  34 #define HZ      100 /* number of ticks per second */
  35
  36 #define MAX_NUM_TICK_TASKS 8
  37
  38 #define MAX_NUM_QUEUES 32
  39 #define QUEUE_LENGTH 16 /* MUST be a power of 2 */
  40 #define QUEUE_LENGTH_MASK (QUEUE_LENGTH - 1)
  41
  42 /* System defined message ID's - |sign bit = 1|class|id| */
  43 /* Event class list */
  44 #define SYS_EVENT_CLS_QUEUE   0
  45 #define SYS_EVENT_CLS_USB     1
  46 #define SYS_EVENT_CLS_POWER   2
  47 #define SYS_EVENT_CLS_FILESYS 3
  48 #define SYS_EVENT_CLS_PLUG    4
  49 #define SYS_EVENT_CLS_MISC    5
  50 #define SYS_EVENT_CLS_PRIVATE 7 /* For use inside plugins */
  51 /* make sure SYS_EVENT_CLS_BITS has enough range */
  52
  53 /* Bit 31->|S|c...c|i...i| */
  54 #define SYS_EVENT                 ((long)(int)(1 << 31))
  55 #define SYS_EVENT_CLS_BITS        (3)
  56 #define SYS_EVENT_CLS_SHIFT       (31-SYS_EVENT_CLS_BITS)
  57 #define SYS_EVENT_CLS_MASK        (((1l << SYS_EVENT_CLS_BITS)-1) << SYS_EVENT_SHIFT)
  58 #define MAKE_SYS_EVENT(cls, id)   (SYS_EVENT | ((long)(cls) << SYS_EVENT_CLS_SHIFT) | (long)(id))
  59 /* Macros for extracting codes */
  60 #define SYS_EVENT_CLS(e)          (((e) & SYS_EVENT_CLS_MASK) >> SYS_EVENT_SHIFT)
  61 #define SYS_EVENT_ID(e)           ((e) & ~(SYS_EVENT|SYS_EVENT_CLS_MASK))
  62
  63 #define SYS_TIMEOUT               MAKE_SYS_EVENT(SYS_EVENT_CLS_QUEUE, 0)
  64 #define SYS_USB_CONNECTED         MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 0)
  65 #define SYS_USB_CONNECTED_ACK     MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 1)
  66 #define SYS_USB_DISCONNECTED      MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 2)
  67 #define SYS_USB_DISCONNECTED_ACK  MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 3)
  68 #define SYS_USB_LUN_LOCKED        MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 4)
  69 #define SYS_USB_READ_DATA         MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 5)
  70 #define SYS_USB_WRITE_DATA        MAKE_SYS_EVENT(SYS_EVENT_CLS_USB, 6)
  71 #define SYS_POWEROFF              MAKE_SYS_EVENT(SYS_EVENT_CLS_POWER, 0)
  72 #define SYS_CHARGER_CONNECTED     MAKE_SYS_EVENT(SYS_EVENT_CLS_POWER, 1)
  73 #define SYS_CHARGER_DISCONNECTED  MAKE_SYS_EVENT(SYS_EVENT_CLS_POWER, 2)
  74 #define SYS_BATTERY_UPDATE        MAKE_SYS_EVENT(SYS_EVENT_CLS_POWER, 3)
  75 #define SYS_FS_CHANGED            MAKE_SYS_EVENT(SYS_EVENT_CLS_FILESYS, 0)
  76 #define SYS_HOTSWAP_INSERTED      MAKE_SYS_EVENT(SYS_EVENT_CLS_PLUG, 0)
  77 #define SYS_HOTSWAP_EXTRACTED     MAKE_SYS_EVENT(SYS_EVENT_CLS_PLUG, 1)
  78 #define SYS_PHONE_PLUGGED         MAKE_SYS_EVENT(SYS_EVENT_CLS_PLUG, 2)
  79 #define SYS_PHONE_UNPLUGGED       MAKE_SYS_EVENT(SYS_EVENT_CLS_PLUG, 3)
  80 #define SYS_REMOTE_PLUGGED        MAKE_SYS_EVENT(SYS_EVENT_CLS_PLUG, 4)
  81 #define SYS_REMOTE_UNPLUGGED      MAKE_SYS_EVENT(SYS_EVENT_CLS_PLUG, 5)
  82 #define SYS_CAR_ADAPTER_RESUME    MAKE_SYS_EVENT(SYS_EVENT_CLS_MISC, 0)
  83 #define SYS_IAP_PERIODIC          MAKE_SYS_EVENT(SYS_EVENT_CLS_MISC, 1)
  84 #define SYS_IAP_HANDLEPKT         MAKE_SYS_EVENT(SYS_EVENT_CLS_MISC, 2)
  85 #define SYS_CALL_INCOMING         MAKE_SYS_EVENT(SYS_EVENT_CLS_MISC, 3)
  86 #define SYS_CALL_HUNG_UP          MAKE_SYS_EVENT(SYS_EVENT_CLS_MISC, 4)
  87
  88 #define IS_SYSEVENT(ev)           ((ev & SYS_EVENT) == SYS_EVENT)
  89
  90 #ifndef TIMEOUT_BLOCK
  91 #define TIMEOUT_BLOCK   -1
  92 #define TIMEOUT_NOBLOCK  0
  93 #endif
  94
  95 struct queue_event
  96 {
  97     long     id;
  98     intptr_t data;
  99 };
 100
 101 #ifdef HAVE_EXTENDED_MESSAGING_AND_NAME
 102 struct queue_sender_list
 103 {
 104     /* If non-NULL, there is a thread waiting for the corresponding event */
 105     /* Must be statically allocated to put in non-cached ram. */
 106     struct thread_entry *senders[QUEUE_LENGTH]; /* message->thread map */
 107     struct thread_entry *list;                  /* list of senders in map */
 108     /* Send info for last message dequeued or NULL if replied or not sent */
 109     struct thread_entry * volatile curr_sender;
 110 #ifdef HAVE_PRIORITY_SCHEDULING
 111     struct blocker blocker;
 112 #endif
 113 };
 114 #endif /* HAVE_EXTENDED_MESSAGING_AND_NAME */
 115
 116 #ifdef HAVE_PRIORITY_SCHEDULING
 117 #define QUEUE_GET_THREAD(q) \
 118     (((q)->send == NULL) ? NULL : (q)->send->blocker.thread)
 119 #else
 120 /* Queue without priority enabled have no owner provision _at this time_ */
 121 #define QUEUE_GET_THREAD(q) \
 122     (NULL)
 123 #endif
 124
 125 struct event_queue
 126 {
 127     struct thread_entry *queue;         /* waiter list */
 128     struct queue_event events[QUEUE_LENGTH]; /* list of events */
 129     unsigned int volatile read;         /* head of queue */
 130     unsigned int volatile write;        /* tail of queue */
 131 #ifdef HAVE_EXTENDED_MESSAGING_AND_NAME
 132     struct queue_sender_list * volatile send; /* list of threads waiting for
 133                                            reply to an event */
 134 #ifdef HAVE_PRIORITY_SCHEDULING
 135     struct blocker *blocker_p;          /* priority inheritance info
 136                                            for sync message senders */
 137 #endif
 138 #endif
 139     IF_COP( struct corelock cl; )       /* multiprocessor sync */
 140 };
 141
 142 struct mutex
 143 {
 144     struct thread_entry *queue;         /* waiter list */
 145     int recursion;                      /* lock owner recursion count */
 146 #ifdef HAVE_PRIORITY_SCHEDULING
 147     struct blocker blocker;             /* priority inheritance info
 148                                            for waiters */
 149     bool no_preempt;                    /* don't allow higher-priority thread
 150                                            to be scheduled even if woken */
 151 #else
 152     struct thread_entry *thread;        /* Indicates owner thread - an owner
 153                                            implies a locked state - same goes
 154                                            for priority scheduling
 155                                            (in blocker struct for that) */
 156 #endif
 157     IF_COP( struct corelock cl; )       /* multiprocessor sync */
 158 };
 159
 160 #ifdef HAVE_SEMAPHORE_OBJECTS
 161 struct semaphore
 162 {
 163     struct thread_entry *queue;         /* Waiter list */
 164     int count;                          /* # of waits remaining before unsignaled */
 165     int max;                            /* maximum # of waits to remain signaled */
 166     IF_COP( struct corelock cl; )       /* multiprocessor sync */
 167 };
 168 #endif
 169
 170 #ifdef HAVE_WAKEUP_OBJECTS
 171 struct wakeup
 172 {
 173     struct thread_entry *queue;         /* waiter list */
 174     bool volatile signalled;            /* signalled status */
 175     IF_COP( struct corelock cl; )       /* multiprocessor sync */
 176 };
 177 #endif
 178
 179
 180 /* global tick variable */
 181 #if defined(CPU_PP) && defined(BOOTLOADER)
 182 /* We don't enable interrupts in the iPod bootloader, so we need to fake
 183    the current_tick variable */
 184 #define current_tick (signed)(USEC_TIMER/10000)
 185
 186 static inline void call_tick_tasks(void)
 187 {
 188 }
 189 #else
 190 extern volatile long current_tick;
 191
 192 /* inline helper for implementing target interrupt handler */
 193 static inline void call_tick_tasks(void)
 194 {
 195     extern void (*tick_funcs[MAX_NUM_TICK_TASKS+1])(void);
 196     void (**p)(void) = tick_funcs;
 197     void (*fn)(void);
 198
 199     current_tick++;
 200
 201     for(fn = *p; fn != NULL; fn = *(++p))
 202     {
 203         fn();
 204     }
 205 }
 206 #endif
 207
 208 /* kernel functions */
 209 extern void kernel_init(void) INIT_ATTR;
 210 extern void yield(void);
 211 extern unsigned sleep(unsigned ticks);
 212 int tick_add_task(void (*f)(void));
 213 int tick_remove_task(void (*f)(void));
 214 extern void tick_start(unsigned int interval_in_ms) INIT_ATTR;
 215
 216 #ifdef INCLUDE_TIMEOUT_API
 217 struct timeout;
 218
 219 /* timeout callback type
 220  * tmo - pointer to struct timeout associated with event
 221  * return next interval or <= 0 to stop event
 222  */
 223 #define MAX_NUM_TIMEOUTS 8
 224 typedef int (* timeout_cb_type)(struct timeout *tmo);
 225
 226 struct timeout
 227 {
 228     timeout_cb_type callback;/* callback - returning false cancels */
 229     intptr_t        data;    /* data passed to callback */
 230     long            expires; /* expiration tick */
 231 };
 232
 233 void timeout_register(struct timeout *tmo, timeout_cb_type callback,
 234                       int ticks, intptr_t data);
 235 void timeout_cancel(struct timeout *tmo);
 236 #endif /* INCLUDE_TIMEOUT_API */
 237
 238 #define STATE_NONSIGNALED 0
 239 #define STATE_SIGNALED    1
 240
 241 #define OBJ_WAIT_TIMEDOUT     (-1)
 242 #define OBJ_WAIT_FAILED       0
 243 #define OBJ_WAIT_SUCCEEDED    1
 244
 245 extern void queue_init(struct event_queue *q, bool register_queue);
 246 extern void queue_delete(struct event_queue *q);
 247 extern void queue_wait(struct event_queue *q, struct queue_event *ev);
 248 extern void queue_wait_w_tmo(struct event_queue *q, struct queue_event *ev,
 249                              int ticks);
 250 extern void queue_post(struct event_queue *q, long id, intptr_t data);
 251 #ifdef HAVE_EXTENDED_MESSAGING_AND_NAME
 252 extern void queue_enable_queue_send(struct event_queue *q,
 253                                     struct queue_sender_list *send,
 254                                     unsigned int owner_id);
 255 extern intptr_t queue_send(struct event_queue *q, long id, intptr_t data);
 256 extern void queue_reply(struct event_queue *q, intptr_t retval);
 257 extern bool queue_in_queue_send(struct event_queue *q);
 258 #endif /* HAVE_EXTENDED_MESSAGING_AND_NAME */
 259 extern bool queue_empty(const struct event_queue* q);
 260 extern bool queue_peek(struct event_queue *q, struct queue_event *ev);
 261 extern void queue_clear(struct event_queue* q);
 262 extern void queue_remove_from_head(struct event_queue *q, long id);
 263 extern int queue_count(const struct event_queue *q);
 264 extern int queue_broadcast(long id, intptr_t data);
 265
 266 extern void mutex_init(struct mutex *m);
 267 extern void mutex_lock(struct mutex *m);
 268 extern void mutex_unlock(struct mutex *m);
 269 #ifdef HAVE_PRIORITY_SCHEDULING
 270 /* Deprecated temporary function to disable mutex preempting a thread on
 271  * unlock - firmware/drivers/fat.c and a couple places in apps/buffering.c -
 272  * reliance on it is a bug! */
 273 static inline void mutex_set_preempt(struct mutex *m, bool preempt)
 274     { m->no_preempt = !preempt; }
 275 #else
 276 /* Deprecated but needed for now - firmware/drivers/ata_mmc.c */
 277 static inline bool mutex_test(const struct mutex *m)
 278     { return m->thread != NULL; }
 279 #endif /* HAVE_PRIORITY_SCHEDULING */
 280
 281 #ifdef HAVE_SEMAPHORE_OBJECTS
 282 extern void semaphore_init(struct semaphore *s, int max, int start);
 283 extern void semaphore_wait(struct semaphore *s);
 284 extern void semaphore_release(struct semaphore *s);
 285 #endif /* HAVE_SEMAPHORE_OBJECTS */
 286
 287 #ifdef HAVE_WAKEUP_OBJECTS
 288 extern void wakeup_init(struct wakeup *w);
 289 extern int wakeup_wait(struct wakeup *w, int timeout);
 290 extern int wakeup_signal(struct wakeup *w);
 291 #endif /* HAVE_WAKEUP_OBJECTS */
 292
 293 #endif /* _KERNEL_H_ */