ybos.h

Go to the documentation of this file.
00001 /********************************************************************\
00002 
00003   Name:         ybos.h
00004   Created by:   Pierre Amaudruz, Stefan Ritt
00005 
00006   Contents:     Declarations for ybos data format
00007 
00008   Revision history
00009   ------------------------------------------------------------------
00010   date        by    modification
00011   ---------   ---   ------------------------------------------------
00012 *  $Log: ybos.h,v $
00013 *  Revision 1.24  2004/01/13 00:51:23  pierre
00014 *  fix dox comment for vxworks
00015 *
00016 *  Revision 1.23  2004/01/08 08:40:09  midas
00017 *  Implemented standard indentation
00018 *
00019 *  Revision 1.22  2004/01/08 06:30:37  pierre
00020 *  Doxygen the file
00021 *
00022 *  Revision 1.21  2003/04/14 12:59:51  midas
00023 *  Added 'compression' in channel settings
00024 *
00025 *  Revision 1.20  2003/04/07 23:55:55  olchansk
00026 *  add c++ wrappers
00027 *
00028 *  Revision 1.19  2002/09/19 17:50:34  pierre
00029 *  remove ^m
00030 *
00031 *  Revision 1.18  2002/09/18 16:37:27  pierre
00032 *  remove bk_list()
00033 *
00034 *  Revision 1.17  2002/06/08 06:06:27  pierre
00035 *  add DSP_UNK
00036 *
00037 *  Revision 1.16  2001/12/12 17:50:50  pierre
00038 *  EVID bank handling, 1.8.3-2 doc++
00039 *
00040 *  Revision 1.15  2001/07/20 20:36:19  pierre
00041 *  -Make ybk_close_... return bank size in bytes
00042 *
00043 *  Revision 1.14  2000/07/21 18:28:06  pierre
00044 *  - Include YBOS version >4.0 support by default, otherwise use in Makefile
00045 *    -DYBOS_VERSION_3_3 for MIDAS_PREF_FLAGS
00046 *
00047 *  Revision 1.13  2000/05/04 14:50:20  midas
00048 *  Return yb_tid_size[] via new function ybos_get_tid_size()
00049 *
00050 *  Revision 1.12  2000/04/26 19:11:45  pierre
00051 *  - Moved doc++ comments to ybos.c
00052 *
00053 *  Revision 1.11  2000/04/17 17:22:24  pierre
00054 *  - First round of doc++ comments
00055 *
00056 *  Revision 1.10  1999/12/20 08:38:25  midas
00057 *  Defined ybos_event_get
00058 *
00059 *  Revision 1.9  1999/09/30 22:52:16  pierre
00060 *  - arg of yb_any_bank_display
00061 *
00062 *  Revision 1.8  1999/06/23 09:59:22  midas
00063 *  Added D8_BKTYPE
00064 *
00065 *  Revision 1.7  1999/01/19 19:56:59  pierre
00066 *  - Fix prototype
00067 *  - Added YB_UNKNOWN_FORMAT
00068 *
00069 *  Revision 1.6  1999/01/18 17:34:36  pierre
00070 *  - cleanup definitions and structures for ybos
00071 *  - Correct prototype for ybos
00072 *
00073 \********************************************************************/
00074 
00075 /**dox***************************************************************/
00076 /** @file ybos.h
00077 The YBOS include file
00078 */
00079 
00080 /** @defgroup ybosincludecode The ybos.h & ybos.c
00081  */
00082 /** @defgroup ybosdefineh YBOS #define 
00083  */
00084 /** @defgroup ybosmacroh YBOS Macros 
00085  */
00086 /** @defgroup yboserrorh YBOS error code 
00087  */
00088 
00089 /**dox***************************************************************/
00090 /** @addtogroup ybosincludecode
00091  *  
00092  *  @{  */
00093 
00094 /**dox***************************************************************/
00095 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00096 
00097 #ifdef OS_WINNT
00098 #include <io.h>
00099 #include <time.h>
00100 #endif
00101 #include <fcntl.h>
00102 #include <stdlib.h>
00103 #include <stdio.h>
00104 #include <string.h>
00105 #include <sys/stat.h>
00106 #include <sys/types.h>
00107 
00108 #ifndef EXPRT
00109 #define EXPRT
00110 #endif
00111 
00112 /**dox***************************************************************/
00113 #endif                          /* DOXYGEN_SHOULD_SKIP_THIS */
00114 
00115 /**dox***************************************************************/
00116 /** @addtogroup ybosdefineh
00117  *  
00118  *  @{  */
00119 
00120 /********************************************************************/
00121 /**
00122 General parameters
00123 */
00124 #ifdef YBOS_VERSION_3_3
00125 #define YBOS_PHYREC_SIZE        8190  /**< I*4 */
00126 #else
00127 #define YBOS_PHYREC_SIZE        8192  /**< I*4 */
00128 #endif
00129 #define YBOS_HEADER_LENGTH      4
00130 #define YBOS_BUFFER_SIZE        3*(YBOS_PHYREC_SIZE<<2) + MAX_EVENT_SIZE + 128  /**< in BYTES */
00131 
00132 #define YB_BANKLIST_MAX        32     /**< maximum number of banks to be found 
00133                                          by the ybk_list() or bk_list() */
00134 #define YB_STRING_BANKLIST_MAX          YB_BANKLIST_MAX * 4
00135                                        /**< to be used for xbk_list() */
00136 
00137 /**dox***************************************************************/
00138 /** @} */ /* end of ybosdefineh */
00139 
00140 /**dox***************************************************************/
00141 /** @addtogroup yboserrorh
00142  *  
00143  *  @{  */
00144 #define YB_SUCCESS               1     /**< Ok */
00145 #define YB_EVENT_NOT_SWAPPED     2     /**< Not swapped */
00146 #define YB_DONE                  2     /**< Operation complete */
00147 #define YB_WRONG_BANK_TYPE    -100     /**< Wrong bank type (see @ref YBOS_Bank_Types) */
00148 #define YB_BANK_NOT_FOUND     -101     /**< Bank not found */
00149 #define YB_SWAP_ERROR         -102     /**< Error swapping */
00150 #define YB_NOMORE_SLOT        -103     /**< No more space for fragment */
00151 #define YB_UNKNOWN_FORMAT     -104     /**< Unknown format (see @ref YBOS_format) */
00152 
00153 /**dox***************************************************************/
00154 /** @} */ /* end of yboserrorh */
00155 
00156 /**dox***************************************************************/
00157 /** @addtogroup ybosdefineh
00158  *  
00159  *  @{  */
00160 
00161 /**
00162 record header content */
00163 #define H_BLOCK_SIZE   0     /**< YBOS */
00164 #define H_BLOCK_NUM    1     /**< YBOS */
00165 #define H_HEAD_LEN     2     /**< YBOS */
00166 #define H_START        3     /**< YBOS */
00167 
00168 /**
00169 Display parameters */
00170 #define D_RECORD       1     /**< YBOS */
00171 #define D_HEADER       2     /**< YBOS */
00172 #define D_EVTLEN       3     /**< YBOS */
00173 
00174 /**
00175 File fragmentation */
00176 #define YB_COMPLETE       1     /**< YBOS */
00177 #define YB_INCOMPLETE     2     /**< YBOS */
00178 #define YB_NO_RECOVER    -1     /**< YBOS */
00179 #define YB_NO_RUN         0     /**< YBOS */
00180 #define YB_ADD_RUN        1     /**< YBOS */
00181 
00182 /**
00183 Display mode options */
00184 #define DSP_RAW    1  /**< Display raw data */
00185 #define DSP_BANK   2  /**<Display data in bank format */
00186 
00187 /**
00188 Display format */
00189 #define DSP_UNK    0  /**< Display format unknown */
00190 #define DSP_DEC    1  /**< Display data in decimal format*/
00191 #define DSP_HEX    2  /**< Display data in headecimal format */
00192 #define DSP_ASC    3  /**< Display data in ASCII format */
00193 
00194 /**dox***************************************************************/
00195 /** @} */ /* end of ybosdefineh */
00196 
00197 /**dox***************************************************************/
00198 /** @addtogroup ybosmacroh
00199  *  
00200  *  @{  */
00201 
00202 /*---- Macros for YBOS ------------------------*/
00203 /**
00204 word swap (I4=I21I22 -> I4=I22I21*/
00205 #define SWAP_D2WORD(_d2w) {\
00206   WORD _tmp2;                                    \
00207   _tmp2                 = *((WORD *)(_d2w));     \
00208   *((WORD *)(_d2w))     = *(((WORD *)(_d2w))+1); \
00209   *(((WORD *)(_d2w))+1) = _tmp2;                 \
00210 }
00211 
00212 /* the s for the following macros */
00213 #ifdef CHAOS_EVID_FMT
00214 extern chaos;
00215 #endif
00216 
00217 /********************************************************************/
00218 /**
00219 As soon as the Midas header is striped out from the event, the YBOS
00220 remaining  data has lost the event synchonization unless included by the
00221 user. It is therefore necessary to have a YBOS bank duplicating
00222 this information usually done in the FE by creating a
00223 "EVID" bank filled with the Midas info and other user information.
00224 
00225 Unfortunately the format of this EVID is flexible and I couldn't
00226 force user to use a default structure. For this reason, I'm
00227 introducing a preprocessor flag for selecting such format.
00228 
00229 Omitting the declaration of the pre-processor flag the EVID_TRINAT is taken by
00230 default see @ref AppendixD.
00231 
00232 Special macros are avaialbe to retrieve this information
00233 based on the EVID content and the type of EVID structure.
00234 
00235 The Macro parameter should point to the first data of the EVID bank.
00236 \code
00237   // check if EVID is present if so display its content 
00238   if ((status = ybk_find (pybos, "EVID", &bklen, &bktyp, (void *)&pybk)) == YB_SUCCESS)
00239   {
00240     pdata = (DWORD *)((YBOS_BANK_HEADER *)pybk + 1);
00241     pevent->event_id      = YBOS_EVID_EVENT_ID(pdata);
00242     pevent->trigger_mask  = YBOS_EVID_TRIGGER_MASK(pdata);
00243     pevent->serial_number = YBOS_EVID_SERIAL(pdata);
00244     pevent->time_stamp    = YBOS_EVID_TIME(pdata);
00245     pevent->data_size     = pybk->length;
00246   }
00247 \endcode
00248 
00249 The current type of EVID bank are:
00250 - [EVID_TRINAT] Specific for Trinat experiment.
00251 \code
00252   ybk_create((DWORD *)pevent, "EVID", I4_BKTYPE, (DWORD *)(&pbkdat));
00253   *((WORD *)pbkdat) = EVENT_ID(pevent);     ((WORD *)pbkdat)++;
00254   *((WORD *)pbkdat) = TRIGGER_MASK(pevent); ((WORD *)pbkdat)++;
00255   *(pbkdat)++ = SERIAL_NUMBER(pevent);
00256   *(pbkdat)++ = TIME_STAMP(pevent);
00257   *(pbkdat)++ = gbl_run_number;                // run number 
00258 \endcode
00259 - [EVID_TWIST] Specific to Twist Experiment (Triumf).
00260 \code
00261   ybk_create((DWORD *)pevent, "EVID", I4_BKTYPE, &pbkdat);
00262   *((WORD *)pbkdat) = EVENT_ID(pevent);     ((WORD *)pbkdat)++;
00263   *((WORD *)pbkdat) = TRIGGER_MASK(pevent); ((WORD *)pbkdat)++;
00264   *(pbkdat)++ = SERIAL_NUMBER(pevent);
00265   *(pbkdat)++ = TIME_STAMP(pevent);
00266   *(pbkdat)++ = gbl_run_number;                // run number 
00267   *(pbkdat)++ = *((DWORD *)frontend_name);     // frontend name 
00268   ybk_close((DWORD *)pevent, pbkdat);
00269 \endcode
00270 */
00271 #if (!defined (EVID_TRINAT) && !defined (EVID_CHAOS) && !defined (EVID_TWIST))
00272 #define EVID_TRINAT
00273 #endif
00274 
00275 #if defined(EVID_TRINAT)
00276 #define YBOS_EVID_EVENT_ID(e)      *((WORD *)(e)+1)
00277 #define YBOS_EVID_TRIGGER_MASK(e)  *((WORD *)(e)+0)
00278 #define YBOS_EVID_SERIAL(e)        *((DWORD *)(e)+1)
00279 #define YBOS_EVID_TIME(e)          *((DWORD *)(e)+2)
00280 #define YBOS_EVID_RUN_NUMBER(e)    *((DWORD *)(e)+3)
00281 #define YBOS_EVID_EVENT_NB(e)      *((DWORD *)(e)+1)
00282 #elif defined(EVID_CHAOS)
00283 #define YBOS_EVID_EVENT_ID(e)      *((WORD *)(e)+3)
00284 #define YBOS_EVID_TRIGGER_MASK(e)  *((WORD *)(e)+2)
00285 #define YBOS_EVID_SERIAL(e)        *((DWORD *)(e)+2)
00286 #define YBOS_EVID_TIME(e)          *((DWORD *)(e)+3)
00287 #define YBOS_EVID_RUN_NUMBER(e)    *((DWORD *)(e)+4)
00288 #define YBOS_EVID_EVENT_NB(e)      *((DWORD *)(e)+0)
00289 #elif defined(EVID_TWIST)
00290 #define YBOS_EVID_EVENT_ID(e)      *((WORD *)(e)+1)
00291 #define YBOS_EVID_TRIGGER_MASK(e)  *((WORD *)(e)+0)
00292 #define YBOS_EVID_SERIAL(e)        *((DWORD *)(e)+1)
00293 #define YBOS_EVID_TIME(e)          *((DWORD *)(e)+2)
00294 #define YBOS_EVID_RUN_NUMBER(e)    *((DWORD *)(e)+3)
00295 #define YBOS_EVID_EVENT_NB(e)      *((DWORD *)(e)+1)
00296 /* frontend name ignored */
00297 #endif
00298 
00299 /********************************************************************/
00300 /**
00301 pevt Evt# id/msk serial run# */
00302 #define YBOS_EVID_BANK(__a, __b, __c,   __d,   __e) {\
00303       DWORD * pbuf;\
00304       ybk_create(__a, "EVID", I4_BKTYPE, &pbuf);\
00305       *(pbuf)++ = (DWORD)__b;\
00306       *(pbuf)++ = (DWORD)__c;\
00307       *(pbuf)++ = (DWORD)__d;\
00308       *(pbuf)++ = (DWORD)ss_millitime();\
00309       *(pbuf)++ = (DWORD)__e;\
00310       ybk_close(__a, pbuf);\
00311         }
00312 
00313 /********************************************************************/
00314 /**
00315 pevt Evt# id/msk serial run# */
00316 #define MIDAS_EVID_BANK(__a, __b, __c,   __d,   __e) {\
00317       DWORD * pbuf;\
00318       bk_create(__a, "EVID", TID_DWORD, &pbuf);\
00319       *(pbuf)++ = (DWORD)__b;\
00320       *(pbuf)++ = (DWORD)__c;\
00321       *(pbuf)++ = (DWORD)__d;\
00322       *(pbuf)++ = (DWORD)ss_millitime();\
00323       *(pbuf)++ = (DWORD)__e;\
00324       bk_close(__a, pbuf);\
00325         }
00326 
00327 /**dox***************************************************************/
00328 /** @} */ /* end of ybosmacroh */
00329 
00330 /**dox***************************************************************/
00331 /** @addtogroup ybosdefineh
00332  *  
00333  *  @{  */
00334 
00335 /*---- data structures for YBOS file format ------------------------*/
00336 /**
00337 YBOS Bank types */
00338 #define I2_BKTYPE       1  /**< Signed Integer 2 bytes */
00339 #define A1_BKTYPE       2  /**< ASCII 1 byte */
00340 #define I4_BKTYPE       3  /**< Signed Interger 4bytes */
00341 #define F4_BKTYPE       4  /**< Float 4 bytes */
00342 #define D8_BKTYPE       5  /**< Double 8 bytes */
00343 #define I1_BKTYPE       8  /**< Signed Integer 1 byte */
00344 #define MAX_BKTYPE      I1_BKTYPE+1 /**< delimiter */
00345 
00346 /**dox***************************************************************/
00347 /** @} */ /* end of ybosdefineh */
00348 
00349 /**dox***************************************************************/
00350 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00351 
00352 /**
00353 YBOS logger channel ALL in 4BYTES! */
00354 typedef struct {
00355    DWORD *ptop;        /**< pointer to top of YBOS buffer */
00356    DWORD *pbuf;        /**< current data pointer for writing to buffer */
00357    DWORD *pwrt;        /**< current data pointer for writing to device */
00358    DWORD *pbot;        /**< bottom of the physical record */
00359    DWORD *pend;        /**< end of the buffer */
00360    DWORD reco;         /**< offset to first logical record 4BYTES */
00361    DWORD recn;         /**< current YBOS physical record number */
00362 } YBOS_INFO;
00363 
00364 /**
00365 YBOS Physical record header */
00366 typedef struct {
00367    DWORD rec_size;          /**< LPR Length of Physical Record (exclusive) */
00368    DWORD header_length;     /**< LPH Length of Physical Header (inclusive) */
00369    DWORD rec_num;           /**< NPR Physical Record Number (start 0) */
00370    DWORD offset;            /**< LRD Offset to 1st Logical Record 
00371                                    (=LPH for 1st Logical record) */
00372 } YBOS_PHYSREC_HEADER;
00373 
00374 /**
00375 Bank header */
00376 typedef struct {
00377    DWORD name;              /**< bank name 4ASCII */
00378    DWORD number;            /**< bank number (=1) */
00379    DWORD index;             /**< index within bank (=0) */
00380    DWORD length;            /**< bank length (I*4, exclusive ) */
00381    DWORD type;              /**< bank type refer to above */
00382 } YBOS_BANK_HEADER;
00383 
00384 /**
00385 YBOS FILE parameters */
00386 #define MAX_FILE_PATH    128
00387 #define MAX_FRAG_SIZE   2000    /* max event size for fragmented file (bytes) */
00388 #define MAX_YM_FILE        8    /* max concurrent file handling */
00389 #define NLINE              8    /* number of elements for display routine */
00390 
00391 /**
00392 YBOS control file header (private structure) */
00393 typedef struct {
00394    INT file_ID;
00395    INT size;
00396    INT fragment_size;
00397    INT total_fragment;
00398    INT current_fragment;
00399    INT current_read_byte;
00400    INT run_number;
00401    INT spare;
00402 } YM_CFILE;
00403 
00404 /**
00405 YBOS path file header (private structure) */
00406 typedef struct {
00407    char path[MAX_FILE_PATH];
00408 } YM_PFILE;
00409 
00410 /**
00411 YBOS file replay handler (for multiple file entries) */
00412 typedef struct {
00413    INT fHandle;
00414    INT file_ID;
00415    INT current_fragment;
00416    INT current_read_byte;
00417    char path[MAX_FILE_PATH];
00418 } R_YM_FILE;
00419 
00420 /*---- function declarations ---------------------------------------*/
00421 
00422 /* make functions callable from a C++ program */
00423 #ifdef __cplusplus
00424 extern "C" {
00425 #endif
00426 
00427    INT EXPRT yb_file_recompose(void *pevt, INT fmt, char *svpath, INT file_mode);
00428    INT EXPRT feodb_file_dump(EQUIPMENT * eqp, char *eqpname, char *pevent,
00429                              INT run_number, char *path);
00430 
00431    void EXPRT yb_any_bank_display(void *pmbh, void *pbk, INT fmt,
00432                                   INT dsp_mode, INT dsp_fmt);
00433    void EXPRT yb_any_event_display(void *pevt, INT data_fmt, INT dsp_mode, INT dsp_fmt);
00434    INT EXPRT yb_any_all_info_display(INT what);
00435    INT EXPRT yb_any_physrec_display(INT data_fmt);
00436 
00437    INT EXPRT yb_any_physrec_skip(INT data_fmt, INT bl);
00438    INT EXPRT yb_any_physrec_get(INT data_fmt, void **prec, DWORD * psize);
00439    INT EXPRT yb_any_file_rclose(INT data_fmt);
00440    INT EXPRT yb_any_file_ropen(char *infile, INT data_fmt);
00441    INT EXPRT yb_any_file_wopen(INT type, INT data_fmt, char *filename, INT * hDev);
00442    INT EXPRT yb_any_file_wclose(INT handle, INT type, INT data_fmt);
00443    INT EXPRT yb_any_log_write(INT handle, INT data_fmt, INT type,
00444                               void *prec, DWORD nbytes);
00445    INT EXPRT yb_any_event_swap(INT data_fmt, void *pevent);
00446    INT EXPRT yb_any_event_get(INT data_fmt, void **pevent, DWORD * psize);
00447 
00448 /* Bank manipulation */
00449    void EXPRT ybk_init(DWORD * pevent);
00450    void EXPRT ybk_create(DWORD * pevent, char *bkname, DWORD btype, void *pbkdat);
00451    INT EXPRT ybk_close(DWORD * pevent, void *pbkdat);
00452    INT EXPRT ybk_size(DWORD * pevent);
00453    INT EXPRT ybk_list(DWORD * pevent, char *bklist);
00454    INT EXPRT ybk_locate(DWORD * pevent, char *bkname, void *pdata);
00455    INT EXPRT ybk_find(DWORD * pevent, char *bkname, DWORD * bklength,
00456                       DWORD * bktype, void **pbkdata);
00457    void EXPRT ybk_create_chaos(DWORD * pevent, char *bname, DWORD btype, void *pbkdat);
00458    INT EXPRT ybk_iterate(DWORD * pevent, YBOS_BANK_HEADER ** pybkh, void **pdata);
00459    INT EXPRT ybk_close_chaos(DWORD * pevent, DWORD btype, void *pbkdat);
00460 
00461 #ifdef INCLUDE_LOGGING
00462    INT EXPRT ybos_log_open(LOG_CHN * log_chn, INT run_number);
00463    INT EXPRT ybos_write(LOG_CHN * log_chn, EVENT_HEADER * pevent, INT evt_size);
00464    INT EXPRT ybos_log_close(LOG_CHN * log_chn, INT run_number);
00465 #endif
00466 
00467    INT EXPRT ybos_event_get(DWORD ** plrl, DWORD * size);
00468    INT EXPRT ybos_get_tid_size(INT tid);
00469 
00470 #ifdef __cplusplus
00471 }
00472 #endif
00473 
00474 /*------------ END --------------------------------------------------------------*/
00475 /**dox***************************************************************/
00476 #endif                          /* DOXYGEN_SHOULD_SKIP_THIS */
00477 
00478 /**dox***************************************************************/
00479 /** @} */ /* end of ybosincludecode */

Midas DOC Version 1.9.3 ---- PSI Stefan Ritt ----
Contributions: Pierre-Andre Amaudruz - Suzannah Daviel - Doxygen - Peter Green - Greg Hackman - Gertjan Hofman - Paul Knowles - Rudi Meier - Glenn Moloney - Dave Morris - Konstantin Olchanski - Renee Poutissou - Andreas Suter - Piotr Adam Zolnierczuk