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