source: trunk/include/arm4agent.h @ 704

/**********************************************************************
 * Copyright (c) 2005-2008 David Carter <dcarter@arm4.org> and others.
 * All rights reserved.   This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 * David Carter - Initial API and implementation
 **********************************************************************/
/* Copyright (c) 2004 The Open Group                                         */
/*                                                                           */
/* Permission is hereby granted, free of charge, to any person obtaining a   */
/* copy of this software (the "Software"), to deal in the Software without   */
/* restriction, including without limitation the rights to use, copy,        */
/* modify, merge, publish, distribute, sublicense, and/or sell copies of     */
/* the Software, and to permit persons to whom the Software is furnished     */
/* to do so, subject to the following conditions:                            */
/*                                                                           */
/* The above copyright notice and this permission notice shall be included   */
/* in all copies or substantial portions of the Software.                    */
/*                                                                           */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS   */
/* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.    */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY      */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT */
/* OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR  */
/* THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                */
/*                                                                           */
/* ------------------------------------------------------------------------- */

/* ------------------------------------------------------------------------- */
/* arm4agent.h - ARM Agent Specific API Definitions                          */
/*                                                                           */
/* This header contains defines that are explicitly hidden from the          */
/* application instrumentation and most be known to an ARM Agent.            */
/*                                                                           */
/* ARM4 C agent implementors must include this header and may also           */
/* modify this header to define an agent specific correlator. The total      */
/* length of this correlator cannot exceed ARM_CORR_MAX_LENGTH bytes.        */
/* ------------------------------------------------------------------------- */

#if !defined(ARM4AGENT_H_INCLUDED)
#define ARM4AGENT_H_INCLUDED

#include "arm4.h"                              /* ARM API definitions        */

/* Data directories */
#define ARM4DATA_QUEUE_DIR                                                      "/var/run/arm4"
#define ARM4DATA_DB_DIR                                                         "/var/lib/arm4"
#define ARM4DATA_DB_BACKUP_DIR                                          "/var/lib/arm4/backup"

/* ------------------------------------------------------------------------- */
/* ------------------------- ARM agent definitions ------------------------- */
/* ------------------------------------------------------------------------- */

/* Correlator flag bit definitions */
#define ARM_CORR_FLAG_APP_TRACE         (0x40) /* Application instance trace */
                                               /* requested                  */
#define ARM_CORR_FLAG_AGENT_TRACE       (0x80) /* Agent transaction instance */
                                                                                           /* trace requested            */

/* Known ARM correlator formats: Vendor reserved arena 1-127 */
#define ARM_CORR_FORMAT_VERSION2           1   /* ARM2 Correlator format     */
#define ARM_CORR_FORMAT_VERSION3           2   /* ARM3 Correlator format     */
#define ARM_CORR_FORMAT_HP                28   /* HP's ARM correlator        */
#define ARM_CORR_FORMAT_BMC               82   /* BMC's ARM correlator       */
#define ARM_CORR_FORMAT_IBM              103   /* IBM's ARM correlator       */
#define ARM_CORR_FORMAT_TANG_IT          122   /* tang-IT's ARM correlator   */
#define ARM_CORR_FORMAT_SDK4_OUT_PROC    125   /* ARM4SDK out of process corr*/
#define ARM_CORR_FORMAT_SDK4_IN_PROC     126   /* ARM4SDK in process corr    */

#define ARM_CORR_FORMAT_INVALID          127   /* Indicates an invalid corr. */

/* Known ARM correlator formats: Vendor playground arena 128-256 */
#define ARM_CORR_FORMAT_HP_128           128   /* HP                         */
#define ARM_CORR_FORMAT_IBM_203          203   /* IBM                        */
#define ARM_CORR_FORMAT_IBM_204          204   /* IBM                        */

#define ARM_CORR_MIN_LENGTH                4   /* This is the header length  */

/* IANA Vendor ID */
/* See http://www.iana.org/assignments/enterprise-numbers */
#define IANA_VENDOR_ID_ARM4_ORG          26026

/* ------------------------------------------------------------------------- */
/* ---------------------------- data definitions --------------------------- */
/* ------------------------------------------------------------------------- */

/* Correlator header which must be the same across all implementations       */
typedef struct arm_correlator_header {
    arm_uint16_t        length;                 /* Length of correlator              */
    arm_uint8_t     format;                     /* Format of the correlator          */
    arm_uint8_t         flags;                  /* Flags                             */
} arm_correlator_header_t;

/* Correlator structure definitions */
typedef struct arm2_correlator {        /* ---- ARM 2 Correlator format ---- */
    arm_uint16_t        length;                 /* Length of correlator              */
    arm_uint8_t     format;                     /* Format of the correlator          */
    arm_uint8_t         flags;                  /* Flags                             */
    arm_uint16_t        addr_format;    /* Format of the address             */
    arm_uint16_t        vendor_id;              /* IANA Vendor id                    */
    arm_uint16_t        agent_version;  /* Agent version number              */
    arm_uint16_t        agent_instance; /* Agent instance number             */
    arm_int32_t         start_handle;   /* Transaction start handle          */
    arm_int32_t         tran_id;                /* Transaction id                    */
    arm_uint16_t        addr_length;    /* Length of the address             */
    arm_uint8_t         address[146];   /* Agent contact info                */
} arm2_correlator_t;

typedef struct arm3_correlator {        /* ---- ARM 3 Correlator format ---- */
    arm_uint16_t        length;                 /* Length of correlator              */
    arm_uint8_t     format;             /* Format of the correlator          */
    arm_uint8_t         flags;          /* Flags                             */
    arm_uint16_t        addr_format;    /* Format of the address             */
    arm_uint16_t        vendor_id;      /* IANA Vendor id                    */
    arm_uint16_t        agent_version;  /* Agent version number              */
    arm_uint16_t        agent_instance; /* Agent instance number             */
    arm_int64_t     tran_handle;    /* Transaction handle                */
    arm_id_t            tran_id;        /* Transaction uuid                  */
    arm_uint16_t        addr_length;    /* Length of the address             */
    arm_uint8_t     address[130];   /* Agent contact info                */
} arm3_correlator_t;

/* 64 bit equivalents of htonl and ntohl */
#define ntohll(x) (((arm_uint64_t)(ntohl((arm_uint32_t)((x << 32) >> 32))) << 32) | (arm_uint32_t)ntohl(((int)(x >> 32))))
#define htonll(x) ntohll(x)

/* Return values to indicate success or failure */
#define ARM_SUCCESS             (0)
#define ARM_FAILURE             (-1)

/* Used to record current instance status */
#define ARM_ACTIVE              (1)
#define ARM_COMPLETE    (0)
#define ARM_DISCARD             (-1)

/* More specific error codes */
/* When updating these, be sure to update ArmErrors.java as well */
#define ARM_FAILURE_INVALID_ARGUMENT            (-100)
#define ARM_FAILURE_NULL_ARGUMENT                       (-101)
#define ARM_FAILURE_UNSUPPORTED_CHARSET         (-102)
#define ARM_FAILURE_TRANSACTION_INACTIVE        (-103)
#define ARM_FAILURE_TRANSACTION_BLOCKED         (-104)
#define ARM_FAILURE_TRANSACTION_NOT_BLOCKED     (-105)
#define ARM_FAILURE_DUPLICATE_ALIAS                     (-106)
#define ARM_FAILURE_BAD_ALIAS                           (-107)

#define ARM_FAILURE_INTERNAL_ERROR                      (-500)

/* These are required to support Java floating point metric values */
#define ARM_METRIC_FORMAT_COUNTERFLOAT32        (20)
#define ARM_METRIC_FORMAT_GAUGEFLOAT32          (21)

/* Define formats for printf and scanf */
/* Needed to find out appropriate int32 and int64 types, limit.h is an       */
/* ANSI-C header file. Thus any ANSI-C compliant compiler works.             */
#ifdef __cplusplus
#include <climits>
#else
#include <limits.h>
#endif

/* set-up arm_int32_t format */
#if INT_MAX == 2147483647l
#define ARM4_FORMAT_INT32       "%d"
#define ARM4_FORMAT_UINT32      "%u"
#elif LONG_MAX == 2147483647l
#define ARM4_FORMAT_INT32       "%ld"
#define ARM4_FORMAT_UINT32      "%lu"
#else
/*#error "can't determine 32bit integer format"*/
#define ARM4_FORMAT_INT32       "%d"
#define ARM4_FORMAT_UINT32      "%u"
#endif /* INT_MAX == 2147483647l */

/* now find appropriate 64 bit integer format */
#if defined(_MSC_VER) || defined(__BORLANDC__) || defined (__WATCOMC__)
/* MSVC and compatible compiler native 64 bit types */
#define ARM4_FORMAT_INT64               __int64 // Need to check this
#define ARM4_FORMAT_UINT64              __int64

#elif (defined(LLONG_MAX) && LLONG_MAX > 2147483647l) || \
      (defined(LONGLONG_MAX) && LONGLONG_MAX > 2147483647l)
/* LLONG_MAX and LONGLONG_MAX indicate usage of long long 64 bit types       */
#define ARM4_FORMAT_INT64               "%lld"
#define ARM4_FORMAT_UINT64              "%llu"

#elif (defined(__GNUC__) && \
      (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95)))
/* GNU supports long long. To be safe just use current V 2.95 or V3.x        */
/* Older versions have to be checked first!                                  */
#define ARM4_FORMAT_INT64               "%lld"
#define ARM4_FORMAT_UINT64              "%llu"

#elif defined(__INTEL_COMPILER)
/* INTEL C compiler for Windows/Linux supports long long.                    */
#define ARM4_FORMAT_INT64               "%lld"
#define ARM4_FORMAT_UINT64              "%llu"

#elif LONG_MAX > 2147483647l
/* on 64-bit systems the normal long type could actually be a 64-bit type    */
#define ARM4_FORMAT_INT64               "%ld"
#define ARM4_FORMAT_UINT64              "%lu"

#else
/* Raise a compile-time error if unsure. Note that assuming "long long"      */
/* for int64 might get past the compilation but may cause run-time problems  */
/* if it is not exactly 64-bit.                                              */
/*#error "can't determine 64bit integer format"*/
#define ARM4_FORMAT_INT64               "%ld"
#define ARM4_FORMAT_UINT64              "%lu"

#endif /* _MSC_VER ... */

/* Define a macro to handle unused arguments in functions */
#ifdef UNUSED
#elif defined(__GNUC__)
# define UNUSED(x) UNUSED_ ## x __attribute__((unused))
#elif defined(__LCLINT__)
# define UNUSED(x) /*@unused@*/ x
#else
# define UNUSED(x) x
#endif

#endif /* ARM4AGENT_H_INCLUDED */