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

Initial commit of eCos version 1.1
author jlarmour
date Tue, 11 May 1999 11:16:07 +0000
parents
children 443894e2e912
line wrap: on
line diff
new file mode 100644
--- /dev/null
+++ b/packages/kernel/current/include/kapi.h
@@ -0,0 +1,606 @@
+#ifndef CYGONCE_KERNEL_KAPI_H
+#define CYGONCE_KERNEL_KAPI_H
+
+/*==========================================================================
+//
+//	kapi.h
+//
+//	Native API for Kernel
+//
+//==========================================================================
+//####COPYRIGHTBEGIN####
+//
+// -------------------------------------------
+// The contents of this file are subject to the Cygnus eCos Public License
+// Version 1.0 (the "License"); you may not use this file except in
+// compliance with the License.  You may obtain a copy of the License at
+// http://sourceware.cygnus.com/ecos
+// 
+// Software distributed under the License is distributed on an "AS IS"
+// basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See the
+// License for the specific language governing rights and limitations under
+// the License.
+// 
+// The Original Code is eCos - Embedded Cygnus Operating System, released
+// September 30, 1998.
+// 
+// The Initial Developer of the Original Code is Cygnus.  Portions created
+// by Cygnus are Copyright (C) 1998 Cygnus Solutions.  All Rights Reserved.
+// -------------------------------------------
+//
+//####COPYRIGHTEND####
+//==========================================================================
+//#####DESCRIPTIONBEGIN####
+//
+// Author(s): 	nickg, dsm
+// Contributors:	nickg
+// Date:	1998-03-02
+// Purpose:	Native API for Kernel
+// Description:	This file describes the native API for using the kernel.
+//              It is essentially a set of C wrappers for the C++ class
+//              member functions.
+// Usage:	#include <cyg/kernel/kapi.h>
+//
+//####DESCRIPTIONEND####
+//
+//========================================================================*/
+
+#include <pkgconf/kernel.h>
+
+#ifdef CYGFUN_KERNEL_API_C
+#include <cyg/infra/cyg_type.h>
+
+/*---------------------------------------------------------------------------*/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*---------------------------------------------------------------------------*/
+/* The following are derived types, they may have different                  */
+/* definitions from these depending on configuration.                        */
+
+typedef CYG_ADDRWORD cyg_addrword_t;          /* May hold pointer or word      */
+typedef cyg_addrword_t cyg_handle_t;          /* Object handle                 */
+typedef cyg_uint32   cyg_priority_t;        /* type for priorities           */
+typedef cyg_uint32   cyg_code_t;            /* type for various codes        */
+typedef cyg_uint32   cyg_vector_t;          /* Interrupt vector id           */
+
+typedef unsigned long long cyg_tick_count_t;
+
+typedef int cyg_bool_t;
+
+/* Exception handler function definition                                     */
+typedef void cyg_exception_handler_t(
+    cyg_addrword_t data,
+    cyg_code_t   exception_number,
+    cyg_addrword_t info
+);
+
+/*---------------------------------------------------------------------------*/
+struct cyg_thread;
+typedef struct cyg_thread cyg_thread;
+
+struct cyg_interrupt;
+typedef struct cyg_interrupt cyg_interrupt;
+
+struct cyg_counter;
+typedef struct cyg_counter cyg_counter;
+
+struct cyg_clock;
+typedef struct cyg_clock cyg_clock;
+
+struct cyg_alarm;
+typedef struct cyg_alarm cyg_alarm;
+
+struct cyg_mbox;
+typedef struct cyg_mbox cyg_mbox;
+
+struct cyg_mempool_var;
+typedef struct cyg_mempool_var cyg_mempool_var;
+
+struct cyg_mempool_fix;
+typedef struct cyg_mempool_fix cyg_mempool_fix;
+
+struct cyg_sem_t;
+typedef struct cyg_sem_t cyg_sem_t;
+
+struct cyg_flag_t;
+typedef struct cyg_flag_t cyg_flag_t;
+
+struct cyg_mutex_t;
+typedef struct cyg_mutex_t cyg_mutex_t;
+
+struct cyg_cond_t;
+typedef struct cyg_cond_t cyg_cond_t;
+
+/*---------------------------------------------------------------------------*/
+/* Scheduler operations */
+
+/* Starts scheduler with created threads.  Never returns. */
+void cyg_scheduler_start(void) __attribute__ ((noreturn));
+
+/* Lock and unlock the scheduler. When the scheduler is   */
+/* locked thread preemption is disabled.                  */
+void cyg_scheduler_lock(void);
+
+void cyg_scheduler_unlock(void);
+    
+/*---------------------------------------------------------------------------*/
+/* Thread operations */
+
+typedef void cyg_thread_entry_t(cyg_addrword_t);
+
+void cyg_thread_create(
+    cyg_addrword_t        sched_info,             /* scheduling info (eg pri)  */
+    cyg_thread_entry_t  *entry,                 /* entry point function      */
+    cyg_addrword_t        entry_data,             /* entry data                */
+    char                *name,                  /* optional thread name      */
+    void                *stack_base,            /* stack base, NULL = alloc  */
+    cyg_ucount32        stack_size,             /* stack size, 0 = default   */
+    cyg_handle_t        *handle,                /* returned thread handle    */
+    cyg_thread          *thread                 /* put thread here           */
+);
+    
+void cyg_thread_exit(void);
+
+
+void cyg_thread_suspend(cyg_handle_t thread);
+
+void cyg_thread_resume(cyg_handle_t thread);
+
+void cyg_thread_kill(cyg_handle_t thread);
+
+    
+void cyg_thread_yield(void);
+
+cyg_handle_t cyg_thread_self(void);
+
+
+/* Priority manipulation */
+
+void cyg_thread_set_priority(cyg_handle_t thread, cyg_priority_t priority );
+
+cyg_priority_t cyg_thread_get_priority(cyg_handle_t thread);              
+
+/* Deadline scheduling control (optional) */
+
+void cyg_thread_deadline_wait( 
+    cyg_tick_count_t    start_time,             /* abs earliest start time   */
+    cyg_tick_count_t    run_time,               /* worst case execution time */
+    cyg_tick_count_t    deadline                /* absolute deadline         */
+); 
+
+void cyg_thread_delay(cyg_tick_count_t delay);
+
+/*---------------------------------------------------------------------------*/
+/* Exception handling.                                                       */
+
+/* Replace current exception handler, this may apply to either the           */
+/* current thread, or to a global exception handler. The exception           */
+/* number may be ignored, or used to specify a particular handler.           */
+
+void cyg_exception_set_handler(
+    cyg_code_t                  exception_number,
+    cyg_exception_handler_t     *new_handler,
+    cyg_addrword_t                new_data,
+    cyg_exception_handler_t     **old_handler,
+    cyg_addrword_t                *old_data
+);
+
+/* Clear exception hander to default value                                   */
+void cyg_exception_clear_handler(
+    cyg_code_t                  exception_number
+);
+    
+/* Invoke exception handler                                                  */
+void cyg_exception_call_handler(
+    cyg_handle_t                thread,
+    cyg_code_t                  exception_number,
+    cyg_addrword_t		exception_info
+);
+
+
+/*---------------------------------------------------------------------------*/
+/* Interrupt handling                                                        */
+typedef void            cyg_VSR_t(void);
+typedef cyg_uint32      cyg_ISR_t(cyg_vector_t vector, cyg_addrword_t data);
+typedef void            cyg_DSR_t(
+    cyg_vector_t vector, cyg_ucount32 count, cyg_addrword_t data);
+
+
+enum cyg_ISR_results
+{
+    CYG_ISR_HANDLED  = 1,               /* Interrupt was handled             */
+    CYG_ISR_CALL_DSR = 2                /* Schedule DSR                      */
+};
+
+void cyg_interrupt_create(
+    cyg_vector_t        vector,         /* Vector to attach to               */
+    cyg_priority_t      priority,       /* Queue priority                    */
+    cyg_addrword_t 	data,           /* Data pointer                      */
+    cyg_ISR_t           *isr,           /* Interrupt Service Routine         */
+    cyg_DSR_t           *dsr,           /* Deferred Service Routine          */
+    cyg_handle_t        *handle,        /* returned handle                   */
+    cyg_interrupt       *intr           /* put interrupt here                */
+);
+
+void cyg_interrupt_delete( cyg_handle_t interrupt );
+
+void cyg_interrupt_attach( cyg_handle_t interrupt );
+
+void cyg_interrupt_detach( cyg_handle_t interrupt );
+    
+/* VSR manipulation */
+
+void cyg_interrupt_get_vsr(
+    cyg_vector_t        vector,         /* vector to get                     */
+    cyg_VSR_t           **vsr           /* vsr got                           */
+);
+
+void cyg_interrupt_set_vsr(
+    cyg_vector_t        vector,         /* vector to set                     */
+    cyg_VSR_t           *vsr            /* vsr to set                        */
+);
+
+/* CPU level interrupt mask                                                  */
+void cyg_interrupt_disable(void);
+
+void cyg_interrupt_enable(void);
+
+/* Interrupt controller access                                               */
+void cyg_interrupt_mask(cyg_vector_t vector);
+
+void cyg_interrupt_unmask(cyg_vector_t vector);
+
+void cyg_interrupt_acknowledge(cyg_vector_t vector);
+
+void cyg_interrupt_configure(
+    cyg_vector_t        vector,         /* vector to configure               */
+    cyg_bool_t          level,          /* level or edge triggered           */
+    cyg_bool_t          up              /* rising/faling edge, high/low level*/
+);
+
+/*---------------------------------------------------------------------------*/
+/* Counters, Clocks and Alarms                                               */
+
+void cyg_counter_create(
+    cyg_handle_t        *handle,        /* returned counter handle           */
+    cyg_counter         *counter        /* put counter here                  */
+);
+
+void cyg_counter_delete(cyg_handle_t counter);
+
+/* Return current value of counter                                           */
+cyg_tick_count_t cyg_counter_current_value(cyg_handle_t counter);
+
+/* Set new current value                                                     */
+void cyg_counter_set_value(
+    cyg_handle_t        counter,
+    cyg_tick_count_t new_value
+);
+
+/* Advance counter by one tick                                               */
+void cyg_counter_tick(cyg_handle_t counter);
+
+
+typedef struct 
+{
+    cyg_uint32  dividend;
+    cyg_uint32  divisor;
+} cyg_resolution_t;
+
+/* Create a clock object                */
+void cyg_clock_create(
+    cyg_resolution_t    resolution,     /* Initial resolution                */
+    cyg_handle_t        *handle,        /* Returned clock handle             */
+    cyg_clock           *clock          /* put clock here                    */    
+);
+
+void cyg_clock_delete(cyg_handle_t clock);
+
+/* convert a clock handle to a counter handle so we can use the              */
+/* counter API on it.                                                        */
+void cyg_clock_to_counter(
+    cyg_handle_t        clock,
+    cyg_handle_t        *counter
+);
+
+void cyg_clock_set_resolution(
+    cyg_handle_t        clock,
+    cyg_resolution_t    resolution      /* New resolution                    */
+);
+
+cyg_resolution_t cyg_clock_get_resolution(cyg_handle_t clock);
+
+/* handle of real time clock                                                 */
+cyg_handle_t cyg_real_time_clock(void);
+
+/* returns value of real time clock's counter.
+   This is the same as:
+   (cyg_clock_to_counter(cyg_real_time_clock(), &h),
+    cyg_counter_current_value(h))                                            */
+cyg_tick_count_t cyg_current_time(void);
+
+/* Alarm handler function                                                    */
+typedef void cyg_alarm_t(cyg_handle_t alarm, cyg_addrword_t data);
+
+void cyg_alarm_create(
+    cyg_handle_t        counter,        /* Attached to this counter          */
+    cyg_alarm_t         *alarmfn,       /* Call-back function                */
+    cyg_addrword_t 	data,           /* Call-back data                    */
+    cyg_handle_t        *handle,        /* Returned alarm object             */
+    cyg_alarm           *alarm          /* put alarm here                    */    
+);
+
+/* Disable alarm, detach from counter and invalidate handles                 */
+void cyg_alarm_delete( cyg_handle_t alarm);
+
+void cyg_alarm_initialize(
+    cyg_handle_t        alarm,
+    cyg_tick_count_t    trigger,        /* Absolute trigger time             */
+    cyg_tick_count_t    interval        /* Relative retrigger interval       */
+);
+
+void cyg_alarm_enable( cyg_handle_t alarm );
+
+void cyg_alarm_disable( cyg_handle_t alarm );
+
+/*---------------------------------------------------------------------------*/
+/* Mail boxes                                                                */
+void cyg_mbox_create(
+    cyg_handle_t        *handle,
+    cyg_mbox            *mbox
+);
+
+void cyg_mbox_delete(cyg_handle_t mbox);
+
+void *cyg_mbox_get(cyg_handle_t mbox);
+
+#ifdef CYGFUN_KERNEL_THREADS_TIMER
+void *cyg_mbox_timed_get(
+    cyg_handle_t mbox,
+    cyg_tick_count_t abstime
+    );
+#endif
+
+void *cyg_mbox_tryget(cyg_handle_t mbox);
+
+void *cyg_mbox_peek_item(cyg_handle_t mbox);
+
+#ifdef CYGMFN_KERNEL_SYNCH_MBOXT_PUT_CAN_WAIT
+cyg_bool_t cyg_mbox_put(cyg_handle_t mbox, void *item);
+#ifdef CYGFUN_KERNEL_THREADS_TIMER
+cyg_bool_t cyg_mbox_timed_put(
+    cyg_handle_t mbox,
+    void *item,
+    cyg_tick_count_t abstime
+    );
+#endif
+#endif
+
+cyg_bool_t cyg_mbox_tryput(cyg_handle_t mbox, void *item);
+
+cyg_count32 cyg_mbox_peek(cyg_handle_t mbox);
+
+cyg_bool_t cyg_mbox_waiting_to_get(cyg_handle_t mbox);
+
+cyg_bool_t cyg_mbox_waiting_to_put(cyg_handle_t mbox);
+
+
+/*-----------------------------------------------------------------------*/
+/* Memory pools                                                          */
+
+/* There are two sorts of memory pools.  A variable size memory pool
+   is for allocating blocks of any size.  A fixed size memory pool, has
+   the block size specified when the pool is created, and only provides
+   blocks of that size.  */
+
+/* Create a variable size memory pool */
+void cyg_mempool_var_create(
+    void            *base,              /* base of memory to use for pool */
+    cyg_int32       size,               /* size of memory in bytes        */
+    cyg_handle_t    *handle,            /* returned handle of memory pool */
+    cyg_mempool_var *var                /* space to put pool structure in */
+    );
+
+/* Delete variable size memory pool */
+void cyg_mempool_var_delete(cyg_handle_t varpool);
+
+/* Allocates a block of length size.  This waits if the memory is not
+   currently available.  */
+void *cyg_mempool_var_alloc(cyg_handle_t varpool, cyg_int32 size);
+
+/* Allocates a block of length size.  This waits until abstime,
+   if the memory is not already available.  NULL is returned if
+   no memory is available. */
+void *cyg_mempool_var_timed_alloc(
+    cyg_handle_t     varpool,
+    cyg_int32        size,
+    cyg_tick_count_t abstime);
+
+/* Allocates a block of length size.  NULL is returned if no memory is
+   available. */
+void *cyg_mempool_var_try_alloc(
+    cyg_handle_t varpool,
+    cyg_int32    size);
+
+/* Frees memory back into variable size pool. */
+void cyg_mempool_var_free(cyg_handle_t varpool, void *p);
+
+/* Returns true if there are any threads waiting for memory in the
+   given memory pool. */
+cyg_bool_t cyg_mempool_var_waiting(cyg_handle_t varpool);
+
+typedef struct {
+    cyg_int32 totalmem;
+    cyg_int32 freemem;
+    void      *base;
+    cyg_int32 size;
+    cyg_int32 blocksize;
+    cyg_int32 maxfree;                  // The largest free block
+} cyg_mempool_info;
+
+/* Puts information about a variable memory pool into the structure
+   provided. */
+void cyg_mempool_var_get_info(cyg_handle_t varpool, cyg_mempool_info *info);
+
+/* Create a fixed size memory pool */
+void cyg_mempool_fix_create(
+    void            *base,              // base of memory to use for pool
+    cyg_int32       size,               // size of memory in byte
+    cyg_int32       blocksize,          // size of allocation in bytes
+    cyg_handle_t    *handle,            // handle of memory pool
+    cyg_mempool_fix *fix                // space to put pool structure in
+    );
+
+/* Delete fixed size memory pool */
+void cyg_mempool_fix_delete(cyg_handle_t fixpool);
+
+/* Allocates a block.  This waits if the memory is not
+   currently available.  */
+void *cyg_mempool_fix_alloc(cyg_handle_t fixpool);
+
+/* Allocates a block.  This waits until abstime, if the memory
+   is not already available.  NULL is returned if no memory is
+   available. */
+void *cyg_mempool_fix_timed_alloc(
+    cyg_handle_t     fixpool,
+    cyg_tick_count_t abstime);
+
+/* Allocates a block.  NULL is returned if no memory is available. */
+void *cyg_mempool_fix_try_alloc(cyg_handle_t fixpool);
+
+/* Frees memory back into fixed size pool. */
+void cyg_mempool_fix_free(cyg_handle_t fixpool, void *p);
+
+/* Returns true if there are any threads waiting for memory in the
+   given memory pool. */
+cyg_bool_t cyg_mempool_fix_waiting(cyg_handle_t fixpool);
+
+/* Puts information about a variable memory pool into the structure
+   provided. */
+void cyg_mempool_fix_get_info(cyg_handle_t fixpool, cyg_mempool_info *info);
+
+/*---------------------------------------------------------------------------*/
+/* Semaphores                                                                */
+
+void      cyg_semaphore_init(
+    cyg_sem_t           *sem,            /* Semaphore to init                */
+    cyg_ucount32        val              /* Initial semaphore value          */
+);
+
+void cyg_semaphore_destroy( cyg_sem_t *sem );
+
+void cyg_semaphore_wait( cyg_sem_t *sem );
+
+#ifdef CYGFUN_KERNEL_THREADS_TIMER
+cyg_bool_t cyg_semaphore_timed_wait(
+    cyg_sem_t          *sem,
+    cyg_tick_count_t   abstime
+    );
+#endif
+
+cyg_bool_t cyg_semaphore_trywait( cyg_sem_t *sem );
+
+void cyg_semaphore_post( cyg_sem_t *sem );
+
+void cyg_semaphore_peek( cyg_sem_t *sem, cyg_ucount32 *val );
+
+/*---------------------------------------------------------------------------*/
+/* Flags                                                                     */
+
+typedef cyg_uint32 cyg_flag_value_t;
+typedef cyg_uint8  cyg_flag_mode_t;
+#define CYG_FLAG_WAITMODE_AND ((cyg_flag_mode_t)0) /* all bits must be set */
+#define CYG_FLAG_WAITMODE_OR  ((cyg_flag_mode_t)2) /* any bit must be set  */
+#define CYG_FLAG_WAITMODE_CLR ((cyg_flag_mode_t)1) /* clear when satisfied */
+
+void cyg_flag_init(
+    cyg_flag_t        *flag             /* Flag to init                      */
+);
+
+void cyg_flag_destroy( cyg_flag_t *flag );
+
+/* bitwise-or in the bits in value; awaken any waiting tasks whose
+   condition is now satisfied */
+void cyg_flag_setbits( cyg_flag_t *flag, cyg_flag_value_t value);
+
+/* bitwise-and with the the bits in value; this clears the bits which
+   are not set in value.  No waiting task can be awoken. */
+void cyg_flag_maskbits( cyg_flag_t *flag, cyg_flag_value_t value);
+
+/* wait for the flag value to match the pattern, according to the mode.
+   If mode includes CLR, set the flag value to zero when
+   our pattern is matched.  The return value is that which matched
+   the request, or zero for an error/timeout return.
+   Value must not itself be zero. */
+cyg_flag_value_t cyg_flag_wait( cyg_flag_t        *flag,
+                                cyg_flag_value_t   pattern, 
+                                cyg_flag_mode_t    mode );
+
+#ifdef CYGFUN_KERNEL_THREADS_TIMER
+cyg_flag_value_t cyg_flag_timed_wait( cyg_flag_t        *flag,
+                                      cyg_flag_value_t   pattern, 
+                                      cyg_flag_mode_t    mode,
+                                      cyg_tick_count_t   abstime );
+
+#endif
+
+cyg_flag_value_t cyg_flag_poll( cyg_flag_t         *flag,
+                                cyg_flag_value_t    pattern, 
+                                cyg_flag_mode_t     mode );
+
+cyg_flag_value_t cyg_flag_peek( cyg_flag_t *flag );
+
+cyg_bool_t cyg_flag_waiting( cyg_flag_t *flag );
+
+/*---------------------------------------------------------------------------*/
+/* Mutex                                                                     */
+
+void cyg_mutex_init(
+    cyg_mutex_t        *mutex          /* Mutex to init                      */
+);
+
+void cyg_mutex_destroy( cyg_mutex_t *mutex );
+
+void cyg_mutex_lock( cyg_mutex_t *mutex );
+
+cyg_bool_t cyg_mutex_trylock( cyg_mutex_t *mutex );
+
+void cyg_mutex_unlock( cyg_mutex_t *mutex );
+
+/*---------------------------------------------------------------------------*/
+/* Condition Variables                                                       */
+
+void cyg_cond_init(
+    cyg_cond_t          *cond,          /* condition variable to init        */
+    cyg_mutex_t         *mutex          /* associated mutex                  */
+);
+
+void cyg_cond_destroy( cyg_cond_t *cond );
+
+void cyg_cond_wait( cyg_cond_t *cond );
+
+void cyg_cond_signal( cyg_cond_t *cond );
+
+void cyg_cond_broadcast( cyg_cond_t *cond );
+
+#ifdef CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT
+cyg_bool_t cyg_cond_timed_wait(
+    cyg_cond_t        *cond,
+    cyg_tick_count_t  abstime
+    );
+#endif
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#include <cyg/kernel/kapidata.h>
+
+/*---------------------------------------------------------------------------*/
+/* EOF kapi.h                                                                */
+#endif /* CYGFUN_KERNEL_API_C   */
+#endif /* CYGONCE_KERNEL_KAPI_H */