Mercurial > ecos

comparison packages/kernel/current/include/kapi.h @ 0:3111d98ba7b3 ecos-v1_1-release

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial commit of eCos version 1.1
author jlarmour
date Tue, 11 May 1999 11:16:07 +0000
parents
children 443894e2e912
comparison
equal deleted inserted replaced
-1:000000000000 0:3111d98ba7b3
1 #ifndef CYGONCE_KERNEL_KAPI_H
2 #define CYGONCE_KERNEL_KAPI_H
3
4 /*==========================================================================
5 //
6 // kapi.h
7 //
8 // Native API for Kernel
9 //
10 //==========================================================================
11 //####COPYRIGHTBEGIN####
12 //
13 // -------------------------------------------
14 // The contents of this file are subject to the Cygnus eCos Public License
15 // Version 1.0 (the "License"); you may not use this file except in
16 // compliance with the License. You may obtain a copy of the License at
17 // http://sourceware.cygnus.com/ecos
18 //
19 // Software distributed under the License is distributed on an "AS IS"
20 // basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
21 // License for the specific language governing rights and limitations under
22 // the License.
23 //
24 // The Original Code is eCos - Embedded Cygnus Operating System, released
25 // September 30, 1998.
26 //
27 // The Initial Developer of the Original Code is Cygnus. Portions created
28 // by Cygnus are Copyright (C) 1998 Cygnus Solutions. All Rights Reserved.
29 // -------------------------------------------
30 //
31 //####COPYRIGHTEND####
32 //==========================================================================
33 //#####DESCRIPTIONBEGIN####
34 //
35 // Author(s): nickg, dsm
36 // Contributors: nickg
37 // Date: 1998-03-02
38 // Purpose: Native API for Kernel
39 // Description: This file describes the native API for using the kernel.
40 // It is essentially a set of C wrappers for the C++ class
41 // member functions.
42 // Usage: #include <cyg/kernel/kapi.h>
43 //
44 //####DESCRIPTIONEND####
45 //
46 //========================================================================*/
47
48 #include <pkgconf/kernel.h>
49
50 #ifdef CYGFUN_KERNEL_API_C
51 #include <cyg/infra/cyg_type.h>
52
53 /*---------------------------------------------------------------------------*/
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59 /*---------------------------------------------------------------------------*/
60 /* The following are derived types, they may have different */
61 /* definitions from these depending on configuration. */
62
63 typedef CYG_ADDRWORD cyg_addrword_t; /* May hold pointer or word */
64 typedef cyg_addrword_t cyg_handle_t; /* Object handle */
65 typedef cyg_uint32 cyg_priority_t; /* type for priorities */
66 typedef cyg_uint32 cyg_code_t; /* type for various codes */
67 typedef cyg_uint32 cyg_vector_t; /* Interrupt vector id */
68
69 typedef unsigned long long cyg_tick_count_t;
70
71 typedef int cyg_bool_t;
72
73 /* Exception handler function definition */
74 typedef void cyg_exception_handler_t(
75 cyg_addrword_t data,
76 cyg_code_t exception_number,
77 cyg_addrword_t info
78 );
79
80 /*---------------------------------------------------------------------------*/
81 struct cyg_thread;
82 typedef struct cyg_thread cyg_thread;
83
84 struct cyg_interrupt;
85 typedef struct cyg_interrupt cyg_interrupt;
86
87 struct cyg_counter;
88 typedef struct cyg_counter cyg_counter;
89
90 struct cyg_clock;
91 typedef struct cyg_clock cyg_clock;
92
93 struct cyg_alarm;
94 typedef struct cyg_alarm cyg_alarm;
95
96 struct cyg_mbox;
97 typedef struct cyg_mbox cyg_mbox;
98
99 struct cyg_mempool_var;
100 typedef struct cyg_mempool_var cyg_mempool_var;
101
102 struct cyg_mempool_fix;
103 typedef struct cyg_mempool_fix cyg_mempool_fix;
104
105 struct cyg_sem_t;
106 typedef struct cyg_sem_t cyg_sem_t;
107
108 struct cyg_flag_t;
109 typedef struct cyg_flag_t cyg_flag_t;
110
111 struct cyg_mutex_t;
112 typedef struct cyg_mutex_t cyg_mutex_t;
113
114 struct cyg_cond_t;
115 typedef struct cyg_cond_t cyg_cond_t;
116
117 /*---------------------------------------------------------------------------*/
118 /* Scheduler operations */
119
120 /* Starts scheduler with created threads. Never returns. */
121 void cyg_scheduler_start(void) __attribute__ ((noreturn));
122
123 /* Lock and unlock the scheduler. When the scheduler is */
124 /* locked thread preemption is disabled. */
125 void cyg_scheduler_lock(void);
126
127 void cyg_scheduler_unlock(void);
128
129 /*---------------------------------------------------------------------------*/
130 /* Thread operations */
131
132 typedef void cyg_thread_entry_t(cyg_addrword_t);
133
134 void cyg_thread_create(
135 cyg_addrword_t sched_info, /* scheduling info (eg pri) */
136 cyg_thread_entry_t *entry, /* entry point function */
137 cyg_addrword_t entry_data, /* entry data */
138 char *name, /* optional thread name */
139 void *stack_base, /* stack base, NULL = alloc */
140 cyg_ucount32 stack_size, /* stack size, 0 = default */
141 cyg_handle_t *handle, /* returned thread handle */
142 cyg_thread *thread /* put thread here */
143 );
144
145 void cyg_thread_exit(void);
146
147
148 void cyg_thread_suspend(cyg_handle_t thread);
149
150 void cyg_thread_resume(cyg_handle_t thread);
151
152 void cyg_thread_kill(cyg_handle_t thread);
153
154
155 void cyg_thread_yield(void);
156
157 cyg_handle_t cyg_thread_self(void);
158
159
160 /* Priority manipulation */
161
162 void cyg_thread_set_priority(cyg_handle_t thread, cyg_priority_t priority );
163
164 cyg_priority_t cyg_thread_get_priority(cyg_handle_t thread);
165
166 /* Deadline scheduling control (optional) */
167
168 void cyg_thread_deadline_wait(
169 cyg_tick_count_t start_time, /* abs earliest start time */
170 cyg_tick_count_t run_time, /* worst case execution time */
171 cyg_tick_count_t deadline /* absolute deadline */
172 );
173
174 void cyg_thread_delay(cyg_tick_count_t delay);
175
176 /*---------------------------------------------------------------------------*/
177 /* Exception handling. */
178
179 /* Replace current exception handler, this may apply to either the */
180 /* current thread, or to a global exception handler. The exception */
181 /* number may be ignored, or used to specify a particular handler. */
182
183 void cyg_exception_set_handler(
184 cyg_code_t exception_number,
185 cyg_exception_handler_t *new_handler,
186 cyg_addrword_t new_data,
187 cyg_exception_handler_t **old_handler,
188 cyg_addrword_t *old_data
189 );
190
191 /* Clear exception hander to default value */
192 void cyg_exception_clear_handler(
193 cyg_code_t exception_number
194 );
195
196 /* Invoke exception handler */
197 void cyg_exception_call_handler(
198 cyg_handle_t thread,
199 cyg_code_t exception_number,
200 cyg_addrword_t exception_info
201 );
202
203
204 /*---------------------------------------------------------------------------*/
205 /* Interrupt handling */
206 typedef void cyg_VSR_t(void);
207 typedef cyg_uint32 cyg_ISR_t(cyg_vector_t vector, cyg_addrword_t data);
208 typedef void cyg_DSR_t(
209 cyg_vector_t vector, cyg_ucount32 count, cyg_addrword_t data);
210
211
212 enum cyg_ISR_results
213 {
214 CYG_ISR_HANDLED = 1, /* Interrupt was handled */
215 CYG_ISR_CALL_DSR = 2 /* Schedule DSR */
216 };
217
218 void cyg_interrupt_create(
219 cyg_vector_t vector, /* Vector to attach to */
220 cyg_priority_t priority, /* Queue priority */
221 cyg_addrword_t data, /* Data pointer */
222 cyg_ISR_t *isr, /* Interrupt Service Routine */
223 cyg_DSR_t *dsr, /* Deferred Service Routine */
224 cyg_handle_t *handle, /* returned handle */
225 cyg_interrupt *intr /* put interrupt here */
226 );
227
228 void cyg_interrupt_delete( cyg_handle_t interrupt );
229
230 void cyg_interrupt_attach( cyg_handle_t interrupt );
231
232 void cyg_interrupt_detach( cyg_handle_t interrupt );
233
234 /* VSR manipulation */
235
236 void cyg_interrupt_get_vsr(
237 cyg_vector_t vector, /* vector to get */
238 cyg_VSR_t **vsr /* vsr got */
239 );
240
241 void cyg_interrupt_set_vsr(
242 cyg_vector_t vector, /* vector to set */
243 cyg_VSR_t *vsr /* vsr to set */
244 );
245
246 /* CPU level interrupt mask */
247 void cyg_interrupt_disable(void);
248
249 void cyg_interrupt_enable(void);
250
251 /* Interrupt controller access */
252 void cyg_interrupt_mask(cyg_vector_t vector);
253
254 void cyg_interrupt_unmask(cyg_vector_t vector);
255
256 void cyg_interrupt_acknowledge(cyg_vector_t vector);
257
258 void cyg_interrupt_configure(
259 cyg_vector_t vector, /* vector to configure */
260 cyg_bool_t level, /* level or edge triggered */
261 cyg_bool_t up /* rising/faling edge, high/low level*/
262 );
263
264 /*---------------------------------------------------------------------------*/
265 /* Counters, Clocks and Alarms */
266
267 void cyg_counter_create(
268 cyg_handle_t *handle, /* returned counter handle */
269 cyg_counter *counter /* put counter here */
270 );
271
272 void cyg_counter_delete(cyg_handle_t counter);
273
274 /* Return current value of counter */
275 cyg_tick_count_t cyg_counter_current_value(cyg_handle_t counter);
276
277 /* Set new current value */
278 void cyg_counter_set_value(
279 cyg_handle_t counter,
280 cyg_tick_count_t new_value
281 );
282
283 /* Advance counter by one tick */
284 void cyg_counter_tick(cyg_handle_t counter);
285
286
287 typedef struct
288 {
289 cyg_uint32 dividend;
290 cyg_uint32 divisor;
291 } cyg_resolution_t;
292
293 /* Create a clock object */
294 void cyg_clock_create(
295 cyg_resolution_t resolution, /* Initial resolution */
296 cyg_handle_t *handle, /* Returned clock handle */
297 cyg_clock *clock /* put clock here */
298 );
299
300 void cyg_clock_delete(cyg_handle_t clock);
301
302 /* convert a clock handle to a counter handle so we can use the */
303 /* counter API on it. */
304 void cyg_clock_to_counter(
305 cyg_handle_t clock,
306 cyg_handle_t *counter
307 );
308
309 void cyg_clock_set_resolution(
310 cyg_handle_t clock,
311 cyg_resolution_t resolution /* New resolution */
312 );
313
314 cyg_resolution_t cyg_clock_get_resolution(cyg_handle_t clock);
315
316 /* handle of real time clock */
317 cyg_handle_t cyg_real_time_clock(void);
318
319 /* returns value of real time clock's counter.
320 This is the same as:
321 (cyg_clock_to_counter(cyg_real_time_clock(), &h),
322 cyg_counter_current_value(h)) */
323 cyg_tick_count_t cyg_current_time(void);
324
325 /* Alarm handler function */
326 typedef void cyg_alarm_t(cyg_handle_t alarm, cyg_addrword_t data);
327
328 void cyg_alarm_create(
329 cyg_handle_t counter, /* Attached to this counter */
330 cyg_alarm_t *alarmfn, /* Call-back function */
331 cyg_addrword_t data, /* Call-back data */
332 cyg_handle_t *handle, /* Returned alarm object */
333 cyg_alarm *alarm /* put alarm here */
334 );
335
336 /* Disable alarm, detach from counter and invalidate handles */
337 void cyg_alarm_delete( cyg_handle_t alarm);
338
339 void cyg_alarm_initialize(
340 cyg_handle_t alarm,
341 cyg_tick_count_t trigger, /* Absolute trigger time */
342 cyg_tick_count_t interval /* Relative retrigger interval */
343 );
344
345 void cyg_alarm_enable( cyg_handle_t alarm );
346
347 void cyg_alarm_disable( cyg_handle_t alarm );
348
349 /*---------------------------------------------------------------------------*/
350 /* Mail boxes */
351 void cyg_mbox_create(
352 cyg_handle_t *handle,
353 cyg_mbox *mbox
354 );
355
356 void cyg_mbox_delete(cyg_handle_t mbox);
357
358 void *cyg_mbox_get(cyg_handle_t mbox);
359
360 #ifdef CYGFUN_KERNEL_THREADS_TIMER
361 void *cyg_mbox_timed_get(
362 cyg_handle_t mbox,
363 cyg_tick_count_t abstime
364 );
365 #endif
366
367 void *cyg_mbox_tryget(cyg_handle_t mbox);
368
369 void *cyg_mbox_peek_item(cyg_handle_t mbox);
370
371 #ifdef CYGMFN_KERNEL_SYNCH_MBOXT_PUT_CAN_WAIT
372 cyg_bool_t cyg_mbox_put(cyg_handle_t mbox, void *item);
373 #ifdef CYGFUN_KERNEL_THREADS_TIMER
374 cyg_bool_t cyg_mbox_timed_put(
375 cyg_handle_t mbox,
376 void *item,
377 cyg_tick_count_t abstime
378 );
379 #endif
380 #endif
381
382 cyg_bool_t cyg_mbox_tryput(cyg_handle_t mbox, void *item);
383
384 cyg_count32 cyg_mbox_peek(cyg_handle_t mbox);
385
386 cyg_bool_t cyg_mbox_waiting_to_get(cyg_handle_t mbox);
387
388 cyg_bool_t cyg_mbox_waiting_to_put(cyg_handle_t mbox);
389
390
391 /*-----------------------------------------------------------------------*/
392 /* Memory pools */
393
394 /* There are two sorts of memory pools. A variable size memory pool
395 is for allocating blocks of any size. A fixed size memory pool, has
396 the block size specified when the pool is created, and only provides
397 blocks of that size. */
398
399 /* Create a variable size memory pool */
400 void cyg_mempool_var_create(
401 void *base, /* base of memory to use for pool */
402 cyg_int32 size, /* size of memory in bytes */
403 cyg_handle_t *handle, /* returned handle of memory pool */
404 cyg_mempool_var *var /* space to put pool structure in */
405 );
406
407 /* Delete variable size memory pool */
408 void cyg_mempool_var_delete(cyg_handle_t varpool);
409
410 /* Allocates a block of length size. This waits if the memory is not
411 currently available. */
412 void *cyg_mempool_var_alloc(cyg_handle_t varpool, cyg_int32 size);
413
414 /* Allocates a block of length size. This waits until abstime,
415 if the memory is not already available. NULL is returned if
416 no memory is available. */
417 void *cyg_mempool_var_timed_alloc(
418 cyg_handle_t varpool,
419 cyg_int32 size,
420 cyg_tick_count_t abstime);
421
422 /* Allocates a block of length size. NULL is returned if no memory is
423 available. */
424 void *cyg_mempool_var_try_alloc(
425 cyg_handle_t varpool,
426 cyg_int32 size);
427
428 /* Frees memory back into variable size pool. */
429 void cyg_mempool_var_free(cyg_handle_t varpool, void *p);
430
431 /* Returns true if there are any threads waiting for memory in the
432 given memory pool. */
433 cyg_bool_t cyg_mempool_var_waiting(cyg_handle_t varpool);
434
435 typedef struct {
436 cyg_int32 totalmem;
437 cyg_int32 freemem;
438 void *base;
439 cyg_int32 size;
440 cyg_int32 blocksize;
441 cyg_int32 maxfree; // The largest free block
442 } cyg_mempool_info;
443
444 /* Puts information about a variable memory pool into the structure
445 provided. */
446 void cyg_mempool_var_get_info(cyg_handle_t varpool, cyg_mempool_info *info);
447
448 /* Create a fixed size memory pool */
449 void cyg_mempool_fix_create(
450 void *base, // base of memory to use for pool
451 cyg_int32 size, // size of memory in byte
452 cyg_int32 blocksize, // size of allocation in bytes
453 cyg_handle_t *handle, // handle of memory pool
454 cyg_mempool_fix *fix // space to put pool structure in
455 );
456
457 /* Delete fixed size memory pool */
458 void cyg_mempool_fix_delete(cyg_handle_t fixpool);
459
460 /* Allocates a block. This waits if the memory is not
461 currently available. */
462 void *cyg_mempool_fix_alloc(cyg_handle_t fixpool);
463
464 /* Allocates a block. This waits until abstime, if the memory
465 is not already available. NULL is returned if no memory is
466 available. */
467 void *cyg_mempool_fix_timed_alloc(
468 cyg_handle_t fixpool,
469 cyg_tick_count_t abstime);
470
471 /* Allocates a block. NULL is returned if no memory is available. */
472 void *cyg_mempool_fix_try_alloc(cyg_handle_t fixpool);
473
474 /* Frees memory back into fixed size pool. */
475 void cyg_mempool_fix_free(cyg_handle_t fixpool, void *p);
476
477 /* Returns true if there are any threads waiting for memory in the
478 given memory pool. */
479 cyg_bool_t cyg_mempool_fix_waiting(cyg_handle_t fixpool);
480
481 /* Puts information about a variable memory pool into the structure
482 provided. */
483 void cyg_mempool_fix_get_info(cyg_handle_t fixpool, cyg_mempool_info *info);
484
485 /*---------------------------------------------------------------------------*/
486 /* Semaphores */
487
488 void cyg_semaphore_init(
489 cyg_sem_t *sem, /* Semaphore to init */
490 cyg_ucount32 val /* Initial semaphore value */
491 );
492
493 void cyg_semaphore_destroy( cyg_sem_t *sem );
494
495 void cyg_semaphore_wait( cyg_sem_t *sem );
496
497 #ifdef CYGFUN_KERNEL_THREADS_TIMER
498 cyg_bool_t cyg_semaphore_timed_wait(
499 cyg_sem_t *sem,
500 cyg_tick_count_t abstime
501 );
502 #endif
503
504 cyg_bool_t cyg_semaphore_trywait( cyg_sem_t *sem );
505
506 void cyg_semaphore_post( cyg_sem_t *sem );
507
508 void cyg_semaphore_peek( cyg_sem_t *sem, cyg_ucount32 *val );
509
510 /*---------------------------------------------------------------------------*/
511 /* Flags */
512
513 typedef cyg_uint32 cyg_flag_value_t;
514 typedef cyg_uint8 cyg_flag_mode_t;
515 #define CYG_FLAG_WAITMODE_AND ((cyg_flag_mode_t)0) /* all bits must be set */
516 #define CYG_FLAG_WAITMODE_OR ((cyg_flag_mode_t)2) /* any bit must be set */
517 #define CYG_FLAG_WAITMODE_CLR ((cyg_flag_mode_t)1) /* clear when satisfied */
518
519 void cyg_flag_init(
520 cyg_flag_t *flag /* Flag to init */
521 );
522
523 void cyg_flag_destroy( cyg_flag_t *flag );
524
525 /* bitwise-or in the bits in value; awaken any waiting tasks whose
526 condition is now satisfied */
527 void cyg_flag_setbits( cyg_flag_t *flag, cyg_flag_value_t value);
528
529 /* bitwise-and with the the bits in value; this clears the bits which
530 are not set in value. No waiting task can be awoken. */
531 void cyg_flag_maskbits( cyg_flag_t *flag, cyg_flag_value_t value);
532
533 /* wait for the flag value to match the pattern, according to the mode.
534 If mode includes CLR, set the flag value to zero when
535 our pattern is matched. The return value is that which matched
536 the request, or zero for an error/timeout return.
537 Value must not itself be zero. */
538 cyg_flag_value_t cyg_flag_wait( cyg_flag_t *flag,
539 cyg_flag_value_t pattern,
540 cyg_flag_mode_t mode );
541
542 #ifdef CYGFUN_KERNEL_THREADS_TIMER
543 cyg_flag_value_t cyg_flag_timed_wait( cyg_flag_t *flag,
544 cyg_flag_value_t pattern,
545 cyg_flag_mode_t mode,
546 cyg_tick_count_t abstime );
547
548 #endif
549
550 cyg_flag_value_t cyg_flag_poll( cyg_flag_t *flag,
551 cyg_flag_value_t pattern,
552 cyg_flag_mode_t mode );
553
554 cyg_flag_value_t cyg_flag_peek( cyg_flag_t *flag );
555
556 cyg_bool_t cyg_flag_waiting( cyg_flag_t *flag );
557
558 /*---------------------------------------------------------------------------*/
559 /* Mutex */
560
561 void cyg_mutex_init(
562 cyg_mutex_t *mutex /* Mutex to init */
563 );
564
565 void cyg_mutex_destroy( cyg_mutex_t *mutex );
566
567 void cyg_mutex_lock( cyg_mutex_t *mutex );
568
569 cyg_bool_t cyg_mutex_trylock( cyg_mutex_t *mutex );
570
571 void cyg_mutex_unlock( cyg_mutex_t *mutex );
572
573 /*---------------------------------------------------------------------------*/
574 /* Condition Variables */
575
576 void cyg_cond_init(
577 cyg_cond_t *cond, /* condition variable to init */
578 cyg_mutex_t *mutex /* associated mutex */
579 );
580
581 void cyg_cond_destroy( cyg_cond_t *cond );
582
583 void cyg_cond_wait( cyg_cond_t *cond );
584
585 void cyg_cond_signal( cyg_cond_t *cond );
586
587 void cyg_cond_broadcast( cyg_cond_t *cond );
588
589 #ifdef CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT
590 cyg_bool_t cyg_cond_timed_wait(
591 cyg_cond_t *cond,
592 cyg_tick_count_t abstime
593 );
594 #endif
595
596
597 #ifdef __cplusplus
598 }
599 #endif
600
601 #include <cyg/kernel/kapidata.h>
602
603 /*---------------------------------------------------------------------------*/
604 /* EOF kapi.h */
605 #endif /* CYGFUN_KERNEL_API_C */
606 #endif /* CYGONCE_KERNEL_KAPI_H */