sci.h

Go to the documentation of this file.

 
/*
summary:
  This is the Simple CAN Interface, a library that provides types and
  functions to work with a CAN bus interface in a hardware independent way.
*/
 
#ifndef SCI_H
#define SCI_H
 
/* ----------------------------------------------
 * includes
 * ---------------------------------------------- */
 
#include <limits.h>
 
/* ----------------------------------------------
 * macros
 * ---------------------------------------------- */
 
#define SCI_MAJOR_VERSION 3
 
#define SCI_MINOR_VERSION 0
 
#define SCI_VER (SCI_MAJOR_VERSION*100+SCI_MINOR_VERSION)
 
#define SCI_IDENTIFIER "LINUX,SOCAN"
 
#define SCI_PLUGPORT_START 128
/* This must be a power of 2.*/
 
#define SCI_MAX_PLUGPORTS 16
 
#define sci_object_type sci_Object_Type
 
#define sci_return sci_Return
 
#define sci_bitrate sci_Bitrate
 
#define sci_errcode sci_Errcode
 
#define sci_object sci_Object
 
#define sci_struc sci_Struc
 
#define SCI_M(err,str) {err,#err}
 
#define SCI_ERRS \
  { \
    SCI_M(SCI_NO_ERR, \
          "no error has occurred"), \
    SCI_M(SCI_PORT_ERR, \
          "the port-parameter was wrong"), \
    SCI_M(SCI_ID_ERR, \
          "the CAN-ID was wrong"), \
    SCI_M(SCI_TYPE_ERR, \
          "the object-type is unknown"), \
    SCI_M(SCI_BITRATE_ERR, \
          "a wrong bit-rate was chosen"), \
    SCI_M(SCI_SET_CALLB_ERR, \
          "callback was already defined"), \
    SCI_M(SCI_MODE_ERR, \
          "an operation was performed on an object of a type that doesn't " \
          "support that operation"), \
    SCI_M(SCI_LENGTH_ERR, \
          "an object was read or written to with a wrong length"), \
    SCI_M(SCI_ACCESS_ERR, \
          "tried to access an already owned object"), \
    SCI_M(SCI_TIMEOUT_ERR, \
          "a timeout has occurred"), \
    SCI_M(SCI_TIMEOUT_VAL_ERR, \
          "the timeout-value is out of range"), \
    SCI_M(SCI_OFF_BUS_ERR, \
          "the CAN-controller is in an off-bus state"),    SCI_M(SCI_BUS_ERR, \
          "a CAN-bus error was recognized"), \
    SCI_M(SCI_AUTHORIZE_ERR, \
          "Only the first process that accesses sci is allowed to initialize " \
          "ports"), \
    SCI_M(SCI_DVR_OPEN_ERR, \
          "the CAN-Driver couldn't be opened"), \
    SCI_M(SCI_DVR_ACCESS_ERR, \
          "the driver couldn't be accessed, this is an internal error"), \
    SCI_M(SCI_HW_INIT_ERR, \
          "general hardware initialization error"), \
    SCI_M(SCI_RESET_ERR, \
          "hardware reset failed"), \
    SCI_M(SCI_CHIP_CONF_ERR, \
          "wrong placement of CAN chip (only for certain implementations of " \
          "sci)"), \
    SCI_M(SCI_ENV_ERR, \
          "missing environment variable (only for certain implementations of " \
          "sci)"), \
    SCI_M(SCI_PLUGPORT_ERR, \
          "plug-port number is out of range (must be between " \
          "SCI_PLUGPORT_START and SCI_PLUGPORT_START+SCI_MAX_PLUGPORTS-1"), \
    SCI_M(SCI_PLUG_DEF_ERR, \
          "the plug-port was already defined or should have been defined " \
          "but wasn't"), \
    SCI_M(SCI_OBJ_UNDEF_ERR, \
          "for sci_get_object(), the CAN object is not defined"), \
    SCI_M(SCI_ERR_GENERAL, \
          "general error") \
 }
 
/* ----------------------------------------------
 * types
 * ---------------------------------------------- */
 
typedef enum sci_Object_Type
  { SCI_READ,              
    SCI_WRITE,             
    SCI_REMOTE_READ,       
    SCI_REMOTE_WRITE       
  } sci_Object_Type;
 
enum sci_Return_Constants
  {
    SCI_NOTHING=0,       
    SCI_OLD_DATA=1,      
    SCI_LOST=2,          
    SCI_TMOUT=4,         
    SCI_RESETTED=8,      
    SCI_INCONSISTENT=16, 
    SCI_EXISTS=32,       
    SCI_WAIT=64,         
    SCI_ERROR=INT_MIN    
  };
 
/* bits above 15 except highest (SCI_ERROR) reserved for sci_Errcode */
/* INT_MIN is defined in limits.h */
 
typedef int sci_Return;
/* when an error occurred, the following conditions apply (be "ret" the return-
   value):
   (ret<0) and (ret & SCI_ERROR)
*/
 
typedef enum sci_Bitrate_Constants
  { SCI_1000KB, 
    SCI_500KB,  
    SCI_250KB,  
    SCI_125KB,  
    SCI_100KB,  
    SCI_66KB,   
    SCI_50KB,   
    SCI_20KB    
  } sci_Bitrate;
 
 
typedef enum sci_Errcode_Constants
  { SCI_NO_ERR,         
    SCI_PORT_ERR,       
    SCI_ID_ERR,         
    SCI_TYPE_ERR,       
    SCI_BITRATE_ERR,    
    SCI_SET_CALLB_ERR,  
    SCI_MODE_ERR,       
    SCI_LENGTH_ERR,     
    SCI_ACCESS_ERR,     
    SCI_TIMEOUT_ERR,    
    SCI_TIMEOUT_VAL_ERR,
    SCI_OFF_BUS_ERR,    
    SCI_BUS_ERR,        
    SCI_AUTHORIZE_ERR,  
    SCI_DVR_OPEN_ERR,   
    SCI_DVR_ACCESS_ERR, 
    SCI_HW_INIT_ERR,    
    SCI_RESET_ERR,      
    SCI_CHIP_CONF_ERR,  
    SCI_ENV_ERR,        
    SCI_PLUGPORT_ERR,   
    SCI_PLUG_DEF_ERR,   
    SCI_OBJ_UNDEF_ERR,  
    SCI_ERR_GENERAL     
  } sci_Errcode;
/* comprehensive list of error-codes, SCI_ERR_GENERAL is a general (not
   further specified) error */
 
#define SCI_NUM_ERRCODES (SCI_ERR_GENERAL+1)
/* this should be adapted if error codes are added after SCI_ERR_GENERAL */
 
#define SCI_ERRCODE(sci_ret) (((sci_ret) & ~SCI_ERROR) >> 16)
/* can now be used instead of sci_get_errcode */
 
#define SCI_ERR(errcode) (SCI_ERROR | ((errcode)<<16))
/* create sci_return from SCI_ERROR and an sci_errcode */
 
typedef struct sci_object_s sci_Object;
 
typedef void (*sci_Plug_Func)(int l_len, char *l_data,
                              int h_len, char *h_data);
 
typedef int (*sci_Plug_Lencalc)(int h_len, int *l_len);
 
typedef struct sci_struc_s sci_Struc;
 
/*____________________________________________________________*/
/*                        Functions                           */
/*____________________________________________________________*/
 
extern char *sci_str_status(sci_Return flag);
 
extern void sci_print_status(sci_Return flag);
 
extern char *sci_str_err(sci_Errcode err);
 
extern void sci_print_err(sci_Errcode err);
 
extern sci_Return sci_open(sci_Struc **s_struc, const char *app_name,
                           sci_Errcode *err);
 
extern sci_Return sci_close(sci_Struc **s_struc);
 
#if 0
 
/* Legacy functions not implemented here: */
 
extern sci_Return sci_init(sci_Struc *s_struc, 
                   unsigned short port, sci_Bitrate bitrate);
extern sci_Return sci_reset(sci_Struc *s_struc, unsigned short port);
#endif
 
extern sci_Return sci_get_bitrate(sci_Struc *s_struc, 
                          unsigned short port, sci_Bitrate *bitrate);
 
extern sci_Return sci_get_errcode(sci_Struc *s_struc, sci_Errcode *errcode);
 
extern sci_Return sci_get_object(sci_Struc *s_struc, sci_Object **object,
                     unsigned short port, int id);
 
extern void *sci_get_user(sci_Object *object);
 
extern sci_Return sci_get_info(sci_Struc *s_struc, sci_Object *object,
                unsigned short *port, int *id, int *length,
                int *timeout, sci_Object_Type *type);
 
extern sci_Return sci_get_timestamp(sci_Struc *s_struc, sci_Object *object,
                                    unsigned long long *pstamp, int *pvalid,
                                    unsigned char *mode, unsigned char *irq_cnt);
 
extern sci_Return sci_obj_dump_buf(char *buf,
                                   sci_Struc *s_struc, sci_Object *object);
#if 0
extern sci_Return sci_obj_dump(sci_Struc *s_struc, sci_Object *object);
    /*               object-initialization            */
extern sci_Return sci_link_object(sci_Struc *s_struc,
                   unsigned short read_port , int read_id,
                                  unsigned short write_port, int write_id,
                   int length, int timeout,
                                  void *read_user, void *write_user);
#endif
 
extern sci_Return sci_init_object(sci_Struc *s_struc, sci_Object **object,
                   unsigned short port, int id, int length,
                   int timeout, sci_Object_Type type, void *userp);
#if 0
extern sci_Return sci_dup_object(sci_Struc *s_struc, sci_Object **dup_object,
                  sci_Object *object, void *userp);
#endif
 
extern sci_Return sci_delete_object(sci_Struc *s_struc, sci_Object **object);
 
extern sci_Return sci_set_inhibit(sci_Struc *s_struc, sci_Object *object,
                   unsigned long inhibit_time);
 
extern sci_Return sci_read_now(sci_Struc *s_struc, sci_Object *object,
                    char *data);
#if 0
extern sci_Return sci_read_new(sci_Struc *s_struc, sci_Object *object,
                    char *data);
#endif
 
extern sci_Return sci_read(sci_Struc *s_struc, sci_Object *object,
                char *data);
 
extern sci_Return sci_write(sci_Struc *s_struc, sci_Object *object,
                 char *data);
 
extern sci_Return sci_write_inhibit(sci_Struc *s_struc, sci_Object *object,
                         char *data, unsigned long *rest_time);
 
extern sci_Return sci_set_callback(sci_Struc *s_struc, sci_Object *object,
                    void *f);
 
extern sci_Return sci_queue_read(sci_Struc *s_struc, sci_Object **object,
                  char *data);
 
extern sci_Return sci_def_plug_in(unsigned short plug_port,
                   unsigned short real_port,
                                  sci_Plug_Func h2l, sci_Plug_Func l2h,
                                  sci_Plug_Lencalc lcalc,
                                  sci_Errcode *err);
 
#if 0
extern int sci_predef_dump(void);
extern void sci_monitor_enable(void);
extern void sci_monitor_disable(void);
extern void sci_monitor_wait_enable(void);
extern void sci_monitor_wait_disable(void);
extern int sci_set_monitor(int id, int port, int do_monitor);
extern char *sci_str_status(sci_Return flag);
extern void sci_print_status(sci_Return flag);
extern char *sci_str_err(sci_Errcode err);
extern void sci_print_err(sci_Errcode err);
extern char *sci_str_bitrate(sci_Bitrate bitrate);
extern void sci_print_bitrate(sci_Bitrate bitrate);
extern void sci_print_obj_struc(sci_Object *object);
extern void sci_print_thread_struc(sci_Struc *s_struc);
extern void sci_print_thread_strucs(void);
extern sci_Struc *get_sci_Struc(int index);
extern int sci_show_dbg(void);
extern int sci_help(void);
extern void sci_dbg_out(char *str);
extern void sci_dbg_assert(int i);
extern void sci_dbg_flush(int i);
extern void sci_dbg_tracelevel(int i);
#endif
 
#endif