kapi.h

ecos实时嵌入式操作系统

#ifndef CYGONCE_KERNEL_KAPI_H
#define CYGONCE_KERNEL_KAPI_H

/*==========================================================================
//
//      kapi.h
//
//      Native API for Kernel
//
//==========================================================================
//####ECOSGPLCOPYRIGHTBEGIN####
// -------------------------------------------
// This file is part of eCos, the Embedded Configurable Operating System.
// Copyright (C) 2002 Bart Veer
// Copyright (C) 2002 Nick Garnett
// Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
//
// eCos is free software; you can redistribute it and/or modify it under
// the terms of the GNU General Public License as published by the Free
// Software Foundation; either version 2 or (at your option) any later version.
//
// eCos is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
// for more details.
//
// You should have received a copy of the GNU General Public License along
// with eCos; if not, write to the Free Software Foundation, Inc.,
// 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
//
// As a special exception, if other files instantiate templates or use macros
// or inline functions from this file, or you compile this file and link it
// with other works to produce a work based on this file, this file does not
// by itself cause the resulting work to be covered by the GNU General Public
// License. However the source code for this file must still be made available
// in accordance with section (3) of the GNU General Public License.
//
// This exception does not invalidate any other reasons why a work based on
// this file might be covered by the GNU General Public License.
//
// Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
// at http://sources.redhat.com/ecos/ecos-license/
// -------------------------------------------
//####ECOSGPLCOPYRIGHTEND####
//==========================================================================
//#####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/system.h>
#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_int32      cyg_code_t;          /* type for various codes        */
typedef cyg_uint32     cyg_vector_t;        /* Interrupt vector id           */
typedef cyg_uint32     cyg_cpu_t;           /* CPU id type                   */

typedef cyg_uint64 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_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;

struct cyg_spinlock_t;
typedef struct cyg_spinlock_t cyg_spinlock_t;

/*---------------------------------------------------------------------------*/
/* Scheduler operations */

/* Starts scheduler with created threads.  Never returns. */
void cyg_scheduler_start(void) CYGBLD_ATTRIB_NORET;

/* Lock and unlock the scheduler. When the scheduler is   */
/* locked thread preemption is disabled.                  */
void cyg_scheduler_lock(void);

void cyg_scheduler_unlock(void);

/* Just like 'cyg_scheduler_lock()', but never take the lock higher than 1  */
/* Thus this call is safe even if the scheduler is already locked and a     */
/* subsequent call to 'cyg_scheduler_unlock()' will completely unlock.      */
void cyg_scheduler_safe_lock(void);
    
/* Read the scheduler lock value. */
cyg_ucount32 cyg_scheduler_read_lock(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);

/* It may be necessary to arrange for the victim to run for it to disappear */
cyg_bool_t cyg_thread_delete(cyg_handle_t thread); /* false if NOT deleted */

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_release(cyg_handle_t thread);    
    
void cyg_thread_yield(void);

cyg_handle_t cyg_thread_self(void);

cyg_handle_t cyg_thread_idle_thread(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);              
cyg_priority_t cyg_thread_get_current_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);

/* Stack information */
cyg_addrword_t cyg_thread_get_stack_base(cyg_handle_t thread);

cyg_uint32 cyg_thread_get_stack_size(cyg_handle_t thread);

#ifdef CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT
cyg_uint32 cyg_thread_measure_stack_usage(cyg_handle_t thread);
#endif

/*---------------------------------------------------------------------------*/
/* Thread enumeration and information                                        */
    
typedef struct
{
    cyg_handle_t        handle;
    cyg_uint16          id;
    cyg_uint32          state;
    char                *name;
    cyg_priority_t      set_pri;
    cyg_priority_t      cur_pri;
    cyg_addrword_t      stack_base;
    cyg_uint32          stack_size;
    cyg_uint32          stack_used;
} cyg_thread_info;
    
cyg_bool_t cyg_thread_get_next( cyg_handle_t *thread, cyg_uint16 *id );

cyg_bool_t cyg_thread_get_info( cyg_handle_t thread,
                                cyg_uint16 id,
                                cyg_thread_info *info );

cyg_handle_t cyg_thread_find( cyg_uint16 id );
    
/*---------------------------------------------------------------------------*/
/* Per-thread Data                                                           */

#ifdef CYGVAR_KERNEL_THREADS_DATA

cyg_ucount32 cyg_thread_new_data_index(void);

void cyg_thread_free_data_index(cyg_ucount32 index);

CYG_ADDRWORD cyg_thread_get_data(cyg_ucount32 index);

CYG_ADDRWORD *cyg_thread_get_data_ptr(cyg_ucount32 index);

void cyg_thread_set_data(cyg_ucount32 index, CYG_ADDRWORD data);

#endif
    
/*---------------------------------------------------------------------------*/
/* Thread destructors                                                        */

#ifdef CYGPKG_KERNEL_THREADS_DESTRUCTORS

typedef void (*cyg_thread_destructor_fn)(cyg_addrword_t);

cyg_bool_t cyg_thread_add_destructor( cyg_thread_destructor_fn fn,
                                      cyg_addrword_t data );
cyg_bool_t cyg_thread_rem_destructor( cyg_thread_destructor_fn fn,
                                      cyg_addrword_t data );
#endif
    
/*---------------------------------------------------------------------------*/
/* 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                                               */