GME: mgk60.h Source File

00001 /***
00002  *** MGK60.H
00003  ***    Multigraph Kernel include file (v 6.0)
00004  ***    Copyright 1986-1996, Vanderbilt University. All rights reserved.
00005  ***    This copyright notice is included for precautionary purposes
00006  ***    and does not constitute an admission that the material to
00007  ***    which it has been affixed has been made public or otherwise
00008  ***    disclosed without restriction.
00009  ***/
00010 
00011 #ifndef __MGK60_H_INCLUDED__
00012 #define __MGK60_H_INCLUDED__
00013 
00014 /* ===== kernel error codes/error handling ===== */
00015 #ifndef DEFERROR
00016 #define DEFERROR(a,b)           a,
00017 #define LASTERROR               E_NUMERRORS
00018 enum __mgk_error_codes {
00019 #endif
00020 
00021   DEFERROR(E_GENERROR = -1, "general error code")
00022   DEFERROR(E_SUCCESS = 0, "")
00023   DEFERROR(E_SCRIPTNOTFOUND, "script not found")
00024   DEFERROR(E_NOTNODE, "not a node")
00025   DEFERROR(E_NOTBUFFER, "not a buffer")
00026   DEFERROR(E_BUFFERUSED, "buffer in use")
00027   DEFERROR(E_NOTHOST, "not a host descriptor")
00028   DEFERROR(E_BADPORTIX, "port index outside index range")
00029   DEFERROR(E_BADTRIGGER, "invalid trigger mode")
00030   DEFERROR(E_PORTCONN, "selected port is (is not) connected")
00031   DEFERROR(E_BADDATA, "bad data type propagated")
00032   DEFERROR(E_NOMEM, "insufficient memory")
00033   DEFERROR(E_NOTRUNNING, "no node is executing")
00034   DEFERROR(E_COMM, "communication or protocol error")
00035   LASTERROR
00036 
00037 };
00038 
00039 #define MGK_I_BADVAL            \
00040         (-1)                    /* returned by int functions on error */
00041 #define MGK_U_BADVAL            \
00042         ((unsigned int)(-1))    /* same for unsigned int fns */
00043 #define MGK_P_BADVAL            \
00044         (0)                     /* returned by pointer funs on error */
00045 
00046 typedef enum __mgk_error_codes mgk_error_code;
00047 extern mgk_error_code mgk_errno;
00048 
00049 /* ===== remote connection stuff ===== */
00050 
00051 #ifndef __LIBMGK_H_INCLUDED__
00052 typedef void *mgk_hostp;        /* handle to host descriptor */
00053 #endif
00054 
00055 typedef struct {                /* host info structure (all chars => no bitrev) */
00056   char name[100];               /* host name */
00057   char cpuname[100];            /* architecture */
00058   char opsys[100];              /* op sys name */
00059   char revbytes;                /* byte order */
00060   char ieeefloat;               /* IEEE floating pt format ? */
00061   char bitsperbyte;             /* how many bits in a (char) */
00062   char bitsperword;             /* how many bits in a (short) */
00063   char bitsperlong;             /* how many bits in a (long) */
00064   char bitsperfloat;            /* how many bits in a (float) */
00065   char bitsperdouble;           /* how many bits in a (double) */
00066   char alignment;               /* how to align things */
00067 } mgk_hostinfo;
00068 
00069 int  mgk_get_number_of_hosts(void);
00070 int mgk_local_host_index(void);
00071 mgk_hostp mgk_get_host(unsigned int which);
00072 mgk_error_code mgk_get_host_info(mgk_hostp host);
00073 int   mgk_is_a_host(mgk_hostp host);
00074 mgk_hostp mgk_local_host(void);
00075 
00076 #define MGK_LOCALHOST           ((mgk_hostp)(0))
00077 
00078 /* ===== propagated data types + buffer stuff ===== */
00079 
00080 typedef unsigned int mgk_data_type, *mgk_data_typep;
00081 
00082 #define T_NODATA        (unsigned int)(-1)
00083 #define T_UNKNOWN       0U      /* unspecified (only valid OR-ed to T_BUFFER) */
00084 #define T_CHAR          1U      /* propagated data types: character */
00085 #define T_SHORTINT      2U      /* short integer */
00086 #define T_INTEGER       4U      /* integer */
00087 #define T_LONGINT       5U      /* long integer */
00088 #define T_FLOAT         6U      /* short float */
00089 #define T_DOUBLE        7U      /* double precision */
00090 #define T_BUFFER        32U     /* buffer (OR-able with scalar types) */
00091 #define T_ARRAY(items)  (64U | (items << 8))
00092                                 /* array (MUST be OR-ed with a scalar type) */
00093                                 /* kernel will convert to buffer upon send */
00094                                 /* receiver will see (T_BUFFER | TYPE) */
00095 #define T_STRING        (T_CHAR | T_ARRAY(-1))
00096                                 /* see above, but use 'strlen' to get size */
00097 
00098 /* ===== buffer allocate/free ===== */
00099 void *  mgk_allocate_buffer(unsigned int size, int do_zero);
00100 void *  mgk_copy_buffer(void *buffer);
00101 mgk_error_code mgk_free_buffer(void *buffer);
00102 int  mgk_is_a_buffer(void *buffer);
00103 unsigned int mgk_buffer_size(void *buffer);
00104 
00105 /* ===== data flow graph nodes ===== */
00106 
00107 #ifndef _MSC_VER
00108 #include <values.h>
00109 #else
00110 #define BITS(type)              (sizeof(type) * 8)
00111 #endif
00112 
00113 #define MGK_MAX_PORT_COUNT      256
00114 #define MGK_MAX_NODE_PRIORITY   255
00115 #define MGK_NODE_STOP_PRIORITY  0
00116 
00117 #ifndef __LIBMGK_H_INCLUDED__
00118 typedef void *mgk_nodep;        /* handle to node descriptor */
00119 #endif
00120 
00121 typedef void (*mgk_script) (void);
00122 void mgk_register_script(mgk_script fn, char *name);
00123 
00124 typedef enum {
00125   AT_IFALL,
00126   AT_IFANY,
00127   AT_SPEC                       /* special ==> uses bitmask */
00128 } mgk_trigger_mode;
00129 
00130 typedef int mgk_portmask[(MGK_MAX_PORT_COUNT + BITS(int) - 1) / BITS(int)];
00131 
00132 #define mgk_portmask_bit(m,i)                                   \
00133    (((m)[(i) / BITS(int)] & (1 << ((i) % BITS(int)))) ? 1 : 0)
00134 #define mgk_set_portmask_bit(m,i,v)                             \
00135    ((v) ?                                                       \
00136     (((m)[(i) / BITS(int)] |= (1 << ((i) % BITS(int)))),1) :    \
00137     (((m)[(i) / BITS(int)] &= ~(1 << ((i) % BITS(int)))),0))
00138 
00139 
00140 mgk_nodep
00141 mgk_create_node(mgk_script fn,
00142                 unsigned int nin,
00143                 unsigned int nout,
00144                 unsigned int priority,
00145                 mgk_trigger_mode tmode);
00146 mgk_nodep
00147 mgk_create_node_indirect(char *scriptname,
00148                          unsigned int nin,
00149                          unsigned int nout,
00150                          unsigned int priority,
00151                          mgk_trigger_mode tmode,
00152                          mgk_hostp host);
00153 
00154 mgk_error_code
00155 mgk_add_node_trigger_mask(mgk_nodep node,
00156                           mgk_portmask mask);
00157 mgk_error_code
00158 mgk_add_node_trigger_mask_disp(mgk_nodep node,
00159                                mgk_portmask mask,
00160                                mgk_script fn);
00161 mgk_error_code
00162 mgk_add_node_trigger_mask_disp_indirect(mgk_nodep node,
00163                                         mgk_portmask mask,
00164                                         char *scriptname);
00165 
00166 mgk_error_code
00167 mgk_set_node_priority(mgk_nodep node,
00168                       unsigned int priority);
00169 unsigned int
00170   mgk_node_priority(mgk_nodep node);
00171 
00172 mgk_error_code
00173 mgk_set_node_context(mgk_nodep node,
00174                      void *context,
00175                      mgk_data_type type);
00176 void *
00177   mgk_node_context(mgk_nodep node,
00178                    mgk_data_typep typep);
00179 
00180 /* ===== connect/disconnect nodes ===== */
00181 
00182 mgk_error_code mgk_connect_nodes(mgk_nodep src, unsigned int srcport,
00183                   mgk_nodep dst, unsigned int dstport);
00184 mgk_error_code mgk_connect_nodes_len(mgk_nodep src, unsigned int srcport,
00185                       mgk_nodep dst, unsigned int dstport,
00186                       unsigned int maxlen);
00187 unsigned int   mgk_set_default_connection_length(unsigned int newlen);
00188 mgk_error_code mgk_disconnect_nodes(mgk_nodep src, unsigned int srcport,
00189                      mgk_nodep dst, unsigned int dstport);
00190 
00191 /* ===== inspect graph topology ===== */
00192 
00193 unsigned int   mgk_node_input_count(mgk_nodep node);
00194 unsigned int   mgk_node_output_count(mgk_nodep node);
00195 
00196 unsigned int   mgk_node_input_connection_count(mgk_nodep node,
00197                                   unsigned int port);
00198 unsigned int  mgk_node_output_connection_count(mgk_nodep node,
00199                                    unsigned int port);
00200 mgk_nodep mgk_node_input_connection(mgk_nodep node,
00201                           unsigned int port,
00202                           unsigned int whichconn,
00203                           unsigned int *connport);
00204 mgk_nodep mgk_node_output_connection(mgk_nodep node,
00205                            unsigned int port,
00206                            unsigned int whichconn,
00207                            unsigned int *connport);
00208 
00209 /* ===== "manual" data insertion/removel/inspect calls ===== */
00210 
00211 #define MGK_ALL_OUTPUT_CONNECTIONS      (unsigned int)(-1)
00212 
00213 mgk_error_code mgk_write_node_input_port(void *data,
00214                           mgk_data_type type,
00215                           mgk_nodep node,
00216                           unsigned int port);
00217 mgk_error_code mgk_write_node_output_port(void *data,
00218                            mgk_data_type type,
00219                            mgk_nodep node,
00220                            unsigned int port,
00221                            unsigned int whichconn);
00222 
00223 mgk_error_code mgk_clear_node_input_port(mgk_nodep node,
00224                           unsigned int port,
00225                           unsigned int count);
00226 mgk_error_code mgk_clear_node_output_port(mgk_nodep node,
00227                            unsigned int port,
00228                            unsigned int whichconn,
00229                            unsigned int count);
00230 
00231 unsigned int   mgk_node_input_port_length(mgk_nodep node,
00232                              unsigned int port);
00233 unsigned int   mgk_node_output_port_length(mgk_nodep node,
00234                               unsigned int port,
00235                               unsigned int whichconn);
00236 
00237 void *   mgk_peek_node_input_port(mgk_nodep node,
00238                            unsigned int port,
00239                            unsigned int streampos,
00240                            mgk_data_typep typep);
00241 
00242 void *  mgk_peek_node_output_port(mgk_nodep node,
00243                             unsigned int port,
00244                             unsigned int whichconn,
00245                             unsigned int streampos,
00246                             mgk_data_typep typep);
00247 
00248 /* ====== node script interface ===== */
00249 
00250 mgk_nodep mgk_current_node(void);
00251 void *  mgk_receive(unsigned int port,
00252               mgk_data_typep typep);
00253 mgk_error_code mgk_propagate(unsigned int port,
00254               void *data,
00255               mgk_data_type type);
00256 
00257 mgk_error_code mgk_protect_buffer(void *buffer);
00258 mgk_error_code mgk_unprotect_buffer(void *buffer);
00259 
00260 void   mgk_abort_node(int code);
00261 unsigned int   mgk_ifany_trigger(void);
00262 mgk_error_code mgk_trigger_mask(mgk_portmask mask);
00263 
00264 /* ===== tracing/exception handling ===== */
00265 
00266 #define TRC_PROPAG      1       /* debug mask bits: data propagation */
00267 #define TRC_SCHED       2       /* dataflow scheduling */
00268 #define TRC_BUFFER      4       /* buffer allocation/free */
00269 #define TRC_BCHECK      8       /* buffer check (buff. list traversal) */
00270 #define TRC_MALLOC      16      /* any Kernel memory allocation/free */
00271 #define TRC_COMMUN      32      /* remote calls/communications */
00272 #define TRC_LOWCOMM     64      /* low-level communication (msg hex dumps) */
00273 #define TRC_CQUEUE      128     /* communication queues */
00274 #define TRC_USER        256     /* user script trace messages */
00275 #define TRC_MISC        512     /* anything else */
00276 #define TRC_ALL         1023    /* all of the above */
00277 #define TRC_DEFAULT     (TRC_ALL & ~(TRC_BCHECK | TRC_LOWCOMM | TRC_CQUEUE))
00278 
00279 typedef void  (*mgk_actor_abort_handler) (mgk_nodep node,                             int code);
00280 typedef void  (*mgk_port_overflow_handler) (mgk_nodep node,
00281                                 int port,
00282                                 int outflag,
00283                                 int outdest,
00284                                 int curlen,
00285                                 int maxlen);
00286 void  mgk_perror(char *);
00287 void  mgk_set_node_abort_handler(mgk_actor_abort_handler hd);
00288 void  mgk_set_overflow_handler(mgk_port_overflow_handler hd);
00289 void  mgk_set_tracing(int tmode, int stepflag);
00290 void  mgk_enable_warnings(int flag);
00291 
00292 /* ===== execution ===== */
00293 mgk_error_code mgk_initialize(int *argc, char ***argv);
00294 unsigned int  mgk_run(unsigned int num_nodes_to_run);
00295 void  mgk_set_comm_priority(unsigned int commpri);
00296 void  mgk_wait_for_comm_event(void);
00297 
00298 #endif