Subversion Repositories shark

Rev

Rev 571 | Rev 646 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 pj 1
/*
2
 * Project: S.Ha.R.K.
3
 *
4
 * Coordinators:
5
 *   Giorgio Buttazzo    <giorgio@sssup.it>
6
 *   Paolo Gai           <pj@gandalf.sssup.it>
7
 *
8
 * Authors     :
9
 *   Paolo Gai           <pj@gandalf.sssup.it>
10
 *   Massimiliano Giorgi <massy@gandalf.sssup.it>
11
 *   Luca Abeni          <luca@gandalf.sssup.it>
12
 *   (see the web pages for full authors list)
13
 *
14
 * ReTiS Lab (Scuola Superiore S.Anna - Pisa - Italy)
15
 *
16
 * http://www.sssup.it
17
 * http://retis.sssup.it
18
 * http://shark.sssup.it
19
 */
20
 
21
 
22
/**
23
 ------------
620 mauro 24
 CVS :        $Id: func.h,v 1.14 2004-05-10 18:16:00 mauro Exp $
2 pj 25
 
26
 File:        $File$
620 mauro 27
 Revision:    $Revision: 1.14 $
28
 Last update: $Date: 2004-05-10 18:16:00 $
2 pj 29
 ------------
30
 
31
Kernel functions:
32
 
33
- Debug stuff
34
 
35
- Primitives called at initialization time
36
 
37
- Kernel global functions (scheduler, queues)
38
 
39
- Kernel VM hooks
40
 
41
- IRQ, errors & exception handling
42
 
43
- System management primitives
44
 
45
- Jet management primitives
46
 
47
- Task management primitives
48
 
49
- Mutex primitives
50
 
51
**/
52
 
53
/*
54
 * Copyright (C) 2000 Paolo Gai
55
 *
56
 * This program is free software; you can redistribute it and/or modify
57
 * it under the terms of the GNU General Public License as published by
58
 * the Free Software Foundation; either version 2 of the License, or
59
 * (at your option) any later version.
60
 *
61
 * This program is distributed in the hope that it will be useful,
62
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
63
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
64
 * GNU General Public License for more details.
65
 *
66
 * You should have received a copy of the GNU General Public License
67
 * along with this program; if not, write to the Free Software
68
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
69
 *
70
 */
71
 
72
#ifndef __KERNEL_FUNC_H__
73
#define __KERNEL_FUNC_H__
74
 
75
#include <ll/ll.h>
76
#include <ll/stdio.h>
77
#include <kernel/types.h>
78
#include <kernel/model.h>
79
#include <kernel/mem.h>
80
#include <signal.h>
81
#include <kernel/var.h>
82
#include <errno.h>
83
 
84
 
85
/*---------------------------------------------------------------------*/
86
/* Debug stuff                                                         */
87
/*---------------------------------------------------------------------*/
88
 
89
/* if a source use printk() it should include log.h not func.h */
90
#include <kernel/log.h>
91
 
79 pj 92
#include "ll/sys/cdefs.h"
93
 
94
__BEGIN_DECLS
95
 
2 pj 96
/*---------------------------------------------------------------------*/
97
/* Kernel global functions: initialization & termination...            */
98
/*---------------------------------------------------------------------*/
99
 
100
/*+ this function is called by __kernel_init__.
101
    It register the modules in the system at init time +*/
102
TIME __kernel_register_levels__(void *arg);
103
 
104
/*+ This function returns a level_des **. the value returned shall be
38 pj 105
    used to register a level module.
2 pj 106
 
38 pj 107
    The function is usually called at module registration time.  The
108
    function can also be called when the system is already started, to
109
    allow the implementation of dynamic module registration.  
110
 
111
    The argument must be the size of the data block that have to be allocated
112
 
113
    The function returns the number of the descriptor allocated for the module
114
    or -1 in case there are no free descriptors.
115
 
116
    The function also reserves a descriptor with size s, initialized
117
    with default function pointers.
118
 
119
+*/
120
LEVEL level_alloc_descriptor(size_t s);
121
 
122
/*+ This function release a level descriptor previously allocated using
123
  level_alloc_descriptor().
124
 
125
  The function returns 0 if the level has been freed, or -1 if someone is
126
  using it, -2 if the level has never been registered.
127
 
128
+*/
129
int level_free_descriptor(LEVEL l);
130
 
131
/* Call this if you want to say that your module is using module l
132
   (e.g., for calling its private functions) */
133
int level_use_descriptor(LEVEL l);
134
 
135
/* Call this when you no more need the module l */
136
int level_unuse_descriptor(LEVEL l);
137
 
2 pj 138
/*+ This function returns a resource_des **. the value returned shall be
139
    used to register a resource module. The function shall be called only at
140
    module registration time. It assume that the system is not yet
141
    initialized, so we shall not call sys_abort...                     +*/
142
RLEVEL resource_alloc_descriptor();
143
 
144
/*+ This function compute the command line parameters from the multiboot_info
145
    NOTE: this function modify the multiboot struct, so this function and
146
    __call_main__ are mutually exclusives!!! +*/
147
void __compute_args__(struct multiboot_info *mbi, int *_argc, char **_argv);
148
 
149
/*+ This function calls the standard C main() function, with a
150
    parameter list up to 100 parameters                        +*/
151
int __call_main__(struct multiboot_info *mb);
152
 
153
/*+ This task initialize the system and calls the main() with
154
    __call_mail__ .
155
    It should be created by a level registered in the system by
156
    __kernel_register_levels__ +*/
157
TASK __init__(void *arg);
158
 
159
/*+ Use this function to post your own exit operations
160
    (when uses some defines contained in const.h) +*/
161
int sys_atrunlevel(void (*func_code)(void *),void *parm, BYTE when);
162
 
163
/*---------------------------------------------------------------------*/
29 pj 164
/* Kernel global functions: scheduler,                                 */
2 pj 165
/*---------------------------------------------------------------------*/
166
 
167
/*+ This is the generic scheduler.
168
    The scheduler calls the appropriates level schedulers and then
169
    dispatch the task chosen. +*/
170
void scheduler(void);
171
 
172
/*+ called in the events to force the system to execute the scheduler at
173
    the end of an event list +*/
174
void event_need_reschedule();
175
 
176
void task_makefree(void *ret);
177
void check_killed_async(void);
178
 
179
int guarantee();
180
 
38 pj 181
void levels_init(void); /* see init.c */
182
 
2 pj 183
void runlevel_init();
184
void call_runlevel_func(int runlevel, int aborting);
185
 
186
// in kill.c
187
void kill_user_tasks();
188
 
189
void event_resetepilogue();
190
 
191
 
192
void call_task_specific_data_destructors();
193
void task_specific_data_init();
194
 
195
// in kill.c
196
void register_cancellation_point(int (*func)(PID p, void *arg), void *arg);
197
 
198
// in signal.c
199
void register_interruptable_point(int (*func)(PID p, void *arg), void *arg);
200
 
201
 
202
/*---------------------------------------------------------------------*/
203
/* Kernel VM hooks                                                     */
204
/*---------------------------------------------------------------------*/
205
 
206
/* this hooks redefines the VM functions to use them into the kernel...
207
 
208
   the only VM functions called directly from the kernel are VM_init and
209
   VM_end
210
*/
211
 
620 mauro 212
/* Exit mode selection */
213
#define sys_set_reboot         ll_set_reboot
214
 
2 pj 215
/* Context management routines */
216
#define kern_context_create    ll_context_create
217
#define kern_context_delete    ll_context_delete
218
 
219
extern __inline__ CONTEXT kern_context_save()
220
{
221
  cli();
222
  return ll_context_from();
223
}
224
 
225
/*+ this functions are called every time a context is changed +*/
226
void kern_after_dispatch(void);
227
 
228
/* Warning: if modified, modify also:
229
   - task_join
230
   - cond_wait
231
   - cond_timedwait
232
   - internal_sem_wait
233
*/
82 pj 234
extern __inline__ void kern_context_load(CONTEXT c)
2 pj 235
{
236
  ll_context_to(c);
237
  kern_after_dispatch();
238
  sti();
239
}
240
 
241
 
242
/* Interrupt enabling/disabling */
243
#define kern_cli          cli
244
#define kern_sti          sti
245
 
246
/* Interrupt enabling/disabling with flag save */
247
#define kern_fsave        ll_fsave
248
#define kern_frestore     ll_frestore
249
 
250
/* interrupt handling */
251
#define kern_irq_unmask   VM_irq_unmask
252
#define kern_irq_mask     VM_irq_mask
253
 
254
extern __inline__ int kern_event_post(const struct timespec *time,
255
                                      void (*handler)(void *p),
256
                                      void *par)
257
{
258
  int e;
259
  e = event_post(*time,handler,par);
260
 
261
  if (e == -1)
262
    kern_raise(XNOMORE_EVENTS,exec_shadow);
263
 
264
  return e;
265
}
266
 
38 pj 267
#define kern_event_delete event_delete
268
 
2 pj 269
/*+ the default capacity timer used by the kernel... +*/
270
void capacity_timer(void *arg);
271
 
272
 
273
#define kern_printf message
274
 
38 pj 275
extern __inline__ TIME kern_gettime(struct timespec *t)
276
{
45 pj 277
  return ll_gettime(TIME_NEW, t);
38 pj 278
}
279
 
280
 
281
 
2 pj 282
/*---------------------------------------------------------------------*/
38 pj 283
/* Kernel global functions: IRQ handling                               */
2 pj 284
/*---------------------------------------------------------------------*/
285
 
286
/*+ Interrupt handler installation +*/
496 giacomo 287
int handler_set(int no, void (*fast)(int), PID pi, BYTE lock);
2 pj 288
 
289
/*+ Interrupt handler removal      +*/
290
int handler_remove(int no);
291
 
292
 
293
/*---------------------------------------------------------------------*/
294
/* System management primitives                                        */
295
/*---------------------------------------------------------------------*/
296
 
297
/*+ Close the system & return to HOST OS.
298
    Can be called from all the tasks...
299
    The first time it is called it jumps to the global context
300
    The second time it jumps only if there are no system task remaining
301
    The error code passed is 0... (it is saved on the first call!!!) +*/
302
void sys_end(void);
303
 
304
/*+ Close the system & return to HOST OS.
305
    Can be called from all the tasks...
306
    The first time it is called it works as the sys_end
307
    The second time it jumps every time
308
    The error code passed is 0... +*/
309
void sys_abort(int err);
310
 
571 giacomo 311
/*+ As sys_abort, but it works when the system is
312
    in shutdown mode  +*/
313
void sys_abort_shutdown(int err);
314
 
2 pj 315
/* The system implements also exit and _exit as a redefinition of sys_end
316
   This is not the correct behaviour, and should be fixed.
317
   The definitions for these functions are in kernel/kern.c
318
*/
319
 
320
/*+ Print a message then call sys_abort(333).
321
    Can be called from all the tasks...  +*/
322
void sys_panic(const char * fmt, ...) __attribute__ ((format (printf, 1, 2)));
323
 
324
/*+ prints an error message (see perror.c) +*/
325
void perror (const char *s);
326
 
327
/*+ this primitive returns the time read from the system timer +*/
328
TIME sys_gettime(struct timespec *t);
329
 
158 pj 330
/*+ this primitive can be used to set a message that will be printed
331
    at shutdown +*/
332
int sys_shutdown_message(char *fmt,...);
333
 
2 pj 334
/*---------------------------------------------------------------------*/
335
/* Jet management primitives                                           */
336
/*---------------------------------------------------------------------*/
337
 
338
/*+ This primitive returns the maximum execution time and the total
339
    execution time from the task_create or the last jet_delstat
340
    It returns also the number of instances to use to calculate the mean
341
    time and the current job execution time.
342
    The value returned is 0 if all ok, -1 if the PID is not correct or
343
    the task doesn't have the JET_ENABLE bit set.
344
+*/
345
int jet_getstat(PID p, TIME *sum, TIME *max, int *n, TIME *curr);
346
 
347
/*+ This primitive reset to 0 the maximum execution time and the mean
348
    execution time of the task p, and reset to 0 all the entries in
349
    jet_table.
350
    The value returned is 0 if all ok, -1 if the PID is not correct or
351
    the task doesn't have the JET_ENABLE bit set.                     +*/
352
int jet_delstat(PID p);
353
 
354
/*+ This primitive returns the last n values of the task execution time
355
    recorded after the last call to jet_gettable or jet_delstat.
356
    If n is
357
    <0 it will be set only the last values inserted in the table
358
       since the last call of jet_gettable.
359
    >0 it will be set up to JET_TABLE_DIM datas.
360
 
361
    The value returned is -1 if the PID is not correct or
362
    the task doesn't have the JET_ENABLE bit set, otherwise it returns the
363
    number of values set in the parameter table.
364
    (can be from 0 to JET_TABLE_DIM-1)
365
+*/
366
int jet_gettable(PID p, TIME *table, int n);
367
 
368
/*+ This function updates the jet information. +*/
369
void jet_update_slice(TIME t);
370
 
371
/*+ This function updates the jet information at the task end period
372
    it is called in task_endcycle and task_sleep +*/
373
void jet_update_endcycle();
374
 
375
/*---------------------------------------------------------------------*/
38 pj 376
/* Internal Macros                                                     */
377
/*---------------------------------------------------------------------*/
378
 
379
extern __inline__ void kern_epilogue_macro(void)
380
{
381
  TIME tx;    /* a dummy used for time computation             */
382
  struct timespec ty; /* a dummy used for time computation     */
383
 
384
  kern_gettime(&schedule_time);
385
 
386
  /* manage the capacity event */
387
  SUBTIMESPEC(&schedule_time, &cap_lasttime, &ty);
388
  tx = TIMESPEC2USEC(&ty);
393 giacomo 389
  if (proc_table[exec_shadow].control & CONTROL_CAP) proc_table[exec_shadow].avail_time -= tx;
38 pj 390
  jet_update_slice(tx);
391
 
392
  /* if the event didn't fire before, we delete it. */
393
  if (cap_timer != NIL) {
394
    kern_event_delete(cap_timer);
395
    cap_timer = NIL;
396
  }
397
}
398
 
399
/* This function is called by the kernel into kern.c to register a default
400
   exception handler */
401
int set_default_exception_handler(void);
567 giacomo 402
int remove_default_exception_handler(void);
38 pj 403
 
404
/*---------------------------------------------------------------------*/
2 pj 405
/* Task management primitives                                          */
406
/*---------------------------------------------------------------------*/
407
 
408
 
409
/*+ This primitive:
410
    - Reserve a task descriptor
411
    - Create the task based on the task model passed
412
    - Initialize the resources used by the task
413
    - Guarantees the task set
414
+*/
415
PID task_createn(char *name,      /*+ the symbolic name of the task +*/
416
                 TASK (*body)(),  /*+ a pointer to the task body    +*/
417
                 TASK_MODEL *m,   /*+ the task model                +*/
418
                                  /*+ the resources models, a list  +*/
419
                 ...);            /*+ of models terminated by NULL  +*/
420
 
421
 
422
/*+ a redefinition of task_createn +*/
423
extern __inline PID task_create(char *name, TASK (*body)(),
424
                                void *m, void *r)
425
{
426
   return task_createn(name, body, (TASK_MODEL *)m, (RES_MODEL *)r, NULL);
427
}
428
 
429
 
430
/* This function allow to create a set of tasks without guarantee.
431
   It must be called with interrupts disabled and it must be used with
432
   group_create_accept and group_create_reject.
433
 
434
   This function allocates a task descriptor and fills it.
435
   After that, the guarantee() function should be called to check for task(s)
436
   admission.
437
   Next, each task created with group_create must be accepted with a call to
438
   group_create_accept() or rejected with a call to group_create_reject.
439
 
440
   The function returns the PID of the allocated descriptor, or NIL(-1)
441
   if the descriptor cannot be allocated or some problems arises the creation.
442
   If -1 is returned, errno is set to a value that represent the error:
443
      ENO_AVAIL_TASK       -> no free descriptors available
444
      ENO_AVAIL_SCHEDLEVEL -> there were no scheduling modules that can handle
445
                              the TASK_MODEL *m passed as parameter
446
      ETASK_CREATE         -> there was an error during the creation of the
447
                              task into the scheduling module
448
      ENO_AVAIL_RESLEVEL   -> there were no resource modules that can handle
449
                              one of the RES_MODEL * passed as parameter
450
*/
451
PID group_create(char *name,
452
                 TASK (*body)(),
453
                 TASK_MODEL *m,
454
                 ...);
455
 
456
 
457
/*
458
  This function should be called when a task created with group_create
459
  is successfully guaranteed and accepted in the system.
460
  This function finish the creation process allocating the last resources
461
  for the task (i.e., the stack and the context).
462
  it returns:
463
 
464
  -1 if something goes wrong. In this case, THE TASK IS AUTOMATICALLY REJECTED
465
     AND THE GROUP_CREATE_REJECT MUST NOT BE CALLED.
466
     errno is set to a value that explains the problem occurred:
467
 
468
     ENO_AVAIL_STACK_MEM -> No stack memory available for the task
469
     ENO_AVAIL_TSS       -> No context available for the task (This is a
470
                            CRITICAL error, and usually never happens...)
471
*/
472
int group_create_accept(PID i, TASK_MODEL *m);
473
 
474
/*
475
  This function should be called when a task created with group_create
476
  can not be successfully guaranteed.
477
  This function reject the task from the system.
478
  You cannot use the PID of a rejected task after this call.
479
*/
480
void group_create_reject(PID i);
481
 
482
/*+
483
  It blocks all explicit activation of a task made with task_activate and
484
  group_activate. These activations are registered in an internal counter,
485
  returned by task_unblock_activation.
486
  it returns 0 if all ok, or -1 otherwise. errno is set accordingly.
487
+*/
488
int task_block_activation(PID p);
489
 
490
/*+
491
  It unblocks all explicit activations of a task, and returns the number of
492
  "frozen" activations. It not call the task_activate!!!!
493
  it returns -1 if an error occurs. errno is set accordingly.
494
+*/
495
int task_unblock_activation(PID p);
496
 
497
 
498
/*+ Activate a task specified via pid returned from task_create +*/
499
int task_activate(PID pid);
500
 
501
/*+ Kill a task specified via pid returned from task_create +*/
502
int task_kill(PID pid);
503
 
504
/*+
505
  This primitive autokills the excuting task; it was used to avoid
506
  that returning from a task cause a jmp to an unpredictable location.
507
 
508
  Now it is obsolete, the task_create_stub do all the works.
509
 
510
  It is used by the Posix layer to implement pthread_exit
511
+*/
512
void task_abort(void *returnvalue);
513
 
514
/*+ Creates a cancellation point in the calling task +*/
515
void task_testcancel(void);
516
 
517
/*+ Set the cancellation state of the task +*/
518
int task_setcancelstate(int state, int *oldstate);
519
 
520
/*+ Set the cancellation type of the task +*/
521
int task_setcanceltype(int type, int *oldtype);
522
 
523
/*+ this function suspends execution of the calling task until the target
524
    task terminates, unless the target task has already terminated.
525
    It works like the pthread_join +*/
526
int task_join(PID p, void **value);
527
 
528
/*+ this function set the detach state of a task to joinable. This function
529
    is not present in Posix standard...
530
    returns ESRCH if p is non correct +*/
531
int task_joinable(PID p);
532
 
533
/*+ this function set the detach state of a task to detached. This function
534
    works as the posix's pthread_detach
535
    returns EINVAL if p can't be joined (or currently a task has done a
536
    join on it (condition not provided in posix)
537
    ESRCH if p is not correct +*/
538
int task_unjoinable(PID p);
539
 
540
/*+ Disable the preemption mechanism on the task.
541
    This primitive is very dangerous!!!!         +*/
542
void task_nopreempt(void);
543
 
544
/*+ Enable the preemption mechanism on the task. +*/
545
void task_preempt(void);
546
 
38 pj 547
/*+ sends a message to the scheduling module that is handling the task +*/
208 giacomo 548
int task_message(void *m, PID p, int reschedule);
38 pj 549
 
2 pj 550
/*+ This function signals to the kernel that the current istance of
551
    the task (periodic or aperiodic) is ended; so the task can be
552
    suspended until it is activated again. Pending activations may be saved
553
    depending on the task model +*/
38 pj 554
extern __inline__ void task_endcycle(void)
555
{
210 giacomo 556
  task_message(NULL, NIL, 1);
38 pj 557
}
2 pj 558
 
208 giacomo 559
/*+ This function signals to the kernel that the current istance of
560
    the task (periodic or aperiodic) is ended; so the task can be
561
    suspended until it is activated again. Pending activations may be saved
562
    depending on the task model +*/
563
extern __inline__ void task_disable(PID p)
564
{
565
  task_message((void *)(1), p, 0);
566
}
567
 
2 pj 568
/*+ This primitives refers the group id which is supplied
569
    by the application, not by the kernel                 +*/
570
int group_activate(WORD g);
571
int group_kill(WORD g);
572
 
573
 
574
/*---------------------------------------------------------------------*/
575
/* Mutex primitives                                                    */
576
/*---------------------------------------------------------------------*/
577
 
578
/* This primitives manages a mutex in the system.
579
   The behavior of the functions is similar to the POSIX ones. */
580
 
581
 
582
/*+ Alloc a mutex descriptor +*/
583
int mutex_init(mutex_t *mutex, const mutexattr_t *attr);
584
 
585
/*+ Free a mutex descriptor  +*/
586
int mutex_destroy(mutex_t *mutex);
587
 
588
/*+ Block wait               +*/
589
int mutex_lock(mutex_t *mutex);
590
 
591
/*+ Non-block wait           +*/
592
int mutex_trylock(mutex_t *mutex);
593
 
594
/*+ unlock primitive +*/
595
int mutex_unlock(mutex_t *mutex);
596
 
597
/*---------------------------------------------------------------------*/
598
/* Condition variables                                                 */
599
/*---------------------------------------------------------------------*/
600
 
601
/*+ Initialization of the condition variable +*/
602
int cond_init(cond_t *cond);
603
 
604
/*+ free a condition variable descriptor +*/
605
int cond_destroy(cond_t *cond);
606
 
607
/*+ signal on a condition variable, it unlocks only one task +*/
608
int cond_signal(cond_t *cond);
609
 
610
/*+ broadcast on a condition variable, it unlocks all the blocked tasks +*/
611
int cond_broadcast(cond_t *cond);
612
 
613
/*+ wait on a condition variable +*/
614
int cond_wait(cond_t *cond, mutex_t *mutex);
615
 
616
/*+ wait on a condition variable (with timer) +*/
617
int cond_timedwait(cond_t *cond, mutex_t *mutex,
618
                   const struct timespec *abstime);
619
 
620
/*---------------------------------------------------------------------*/
621
/* Task specific data primitives                                       */
622
/*---------------------------------------------------------------------*/
623
 
624
/* they are similar to the POSIX standard */
625
 
626
int task_key_create(task_key_t *key, void (*destructor)(void *));
627
void *task_getspecific(task_key_t key);
628
int task_setspecific(task_key_t key, const void *value);
629
int task_key_delete(task_key_t key);
630
 
631
/*---------------------------------------------------------------------*/
632
/* Task cancellation handlers                                          */
633
/*---------------------------------------------------------------------*/
634
 
635
/*+ push the specified cancellation cleanup handler routine onto
636
    the cancellation cleanup stack
637
void task_cleanup_push(void (*routine)(void *), void *arg); +*/
638
#define task_cleanup_push(rtn,arg) { \
639
        struct _task_handler_rec __cleanup_handler, **__head; \
640
        __cleanup_handler.f = rtn; \
641
        __cleanup_handler.a = arg; \
642
        __head = task_getspecific(0); \
643
        __cleanup_handler.next = *__head; \
644
        *__head = &__cleanup_handler;
645
 
646
/*+
647
    removes the routine at the top of the cancellation cleanup stack
648
    of the calling thread
649
void task_cleanup_pop(int execute); +*/
650
#define task_cleanup_pop(ex) \
651
        *__head = __cleanup_handler.next; \
652
        if (ex) (*__cleanup_handler.f) (__cleanup_handler.a); \
653
}
654
 
79 pj 655
__END_DECLS
2 pj 656
#endif /* __FUNC_H__ */