gdb/tracepoint.h

   1 /* Data structures associated with tracepoints in GDB.
   2    Copyright (C) 1997-2013 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #if !defined (TRACEPOINT_H)
  20 #define TRACEPOINT_H 1
  21
  22 #include "breakpoint.h"
  23 #include "target.h"
  24 #include "memrange.h"
  25 #include "gdb_vecs.h"
  26
  27 /* A trace state variable is a value managed by a target being
  28    traced.  A trace state variable (or tsv for short) can be accessed
  29    and assigned to by tracepoint actions and conditionals, but is not
  30    part of the program being traced, and it doesn't have to be
  31    collected.  Effectively the variables are scratch space for
  32    tracepoints.  */
  33
  34 struct trace_state_variable
  35   {
  36     /* The variable's name.  The user has to prefix with a dollar sign,
  37        but we don't store that internally.  */
  38     const char *name;
  39
  40     /* An id number assigned by GDB, and transmitted to targets.  */
  41     int number;
  42
  43     /* The initial value of a variable is a 64-bit signed integer.  */
  44     LONGEST initial_value;
  45
  46     /* 1 if the value is known, else 0.  The value is known during a
  47        trace run, or in tfind mode if the variable was collected into
  48        the current trace frame.  */
  49     int value_known;
  50
  51     /* The value of a variable is a 64-bit signed integer.  */
  52     LONGEST value;
  53
  54     /* This is true for variables that are predefined and built into
  55        the target.  */
  56     int builtin;
  57    };
  58
  59 /* The trace status encompasses various info about the general state
  60    of the tracing run.  */
  61
  62 enum trace_stop_reason
  63   {
  64     trace_stop_reason_unknown,
  65     trace_never_run,
  66     tstop_command,
  67     trace_buffer_full,
  68     trace_disconnected,
  69     tracepoint_passcount,
  70     tracepoint_error
  71   };
  72
  73 struct trace_status
  74 {
  75   /* If the status is coming from a file rather than a live target,
  76      this points at the file's filename.  Otherwise, this is NULL.  */
  77   const char *filename;
  78
  79   /* This is true if the value of the running field is known.  */
  80   int running_known;
  81
  82   /* This is true when the trace experiment is actually running.  */
  83   int running;
  84
  85   enum trace_stop_reason stop_reason;
  86
  87   /* If stop_reason is tracepoint_passcount or tracepoint_error, this
  88      is the (on-target) number of the tracepoint which caused the
  89      stop.  */
  90   int stopping_tracepoint;
  91
  92   /* If stop_reason is tstop_command or tracepoint_error, this is an
  93      arbitrary string that may describe the reason for the stop in
  94      more detail.  */
  95
  96   char *stop_desc;
  97
  98   /* Number of traceframes currently in the buffer.  */
  99
 100   int traceframe_count;
 101
 102   /* Number of traceframes created since start of run.  */
 103
 104   int traceframes_created;
 105
 106   /* Total size of the target's trace buffer.  */
 107
 108   int buffer_size;
 109
 110   /* Unused bytes left in the target's trace buffer.  */
 111
 112   int buffer_free;
 113
 114   /* 1 if the target will continue tracing after disconnection, else
 115      0.  If the target does not report a value, assume 0.  */
 116
 117   int disconnected_tracing;
 118
 119   /* 1 if the target is using a circular trace buffer, else 0.  If the
 120      target does not report a value, assume 0.  */
 121
 122   int circular_buffer;
 123
 124   /* The "name" of the person running the trace.  This is an
 125      arbitrary string.  */
 126
 127   char *user_name;
 128
 129   /* "Notes" about the trace.  This is an arbitrary string not
 130      interpreted by GDBserver in any special way.  */
 131
 132   char *notes;
 133
 134   /* The calendar times at which the trace run started and stopped,
 135      both expressed in microseconds of Unix time.  */
 136
 137   LONGEST start_time;
 138   LONGEST stop_time;
 139 };
 140
 141 struct trace_status *current_trace_status (void);
 142
 143 extern char *default_collect;
 144
 145 /* Struct to collect random info about tracepoints on the target.  */
 146
 147 struct uploaded_tp
 148 {
 149   int number;
 150   enum bptype type;
 151   ULONGEST addr;
 152   int enabled;
 153   int step;
 154   int pass;
 155   int orig_size;
 156
 157   /* String that is the encoded form of the tracepoint's condition.  */
 158   char *cond;
 159
 160   /* Vectors of strings that are the encoded forms of a tracepoint's
 161      actions.  */
 162   VEC(char_ptr) *actions;
 163   VEC(char_ptr) *step_actions;
 164
 165   /* The original string defining the location of the tracepoint.  */
 166   char *at_string;
 167
 168   /* The original string defining the tracepoint's condition.  */
 169   char *cond_string;
 170
 171   /* List of original strings defining the tracepoint's actions.  */
 172   VEC(char_ptr) *cmd_strings;
 173
 174   /* The tracepoint's current hit count.  */
 175   int hit_count;
 176
 177   /* The tracepoint's current traceframe usage.  */
 178   ULONGEST traceframe_usage;
 179
 180   struct uploaded_tp *next;
 181 };
 182
 183 /* Struct recording info about trace state variables on the target.  */
 184
 185 struct uploaded_tsv
 186 {
 187   const char *name;
 188   int number;
 189   LONGEST initial_value;
 190   int builtin;
 191   struct uploaded_tsv *next;
 192 };
 193
 194 /* Struct recording info about a target static tracepoint marker.  */
 195
 196 struct static_tracepoint_marker
 197 {
 198   struct gdbarch *gdbarch;
 199   CORE_ADDR address;
 200
 201   /* The string ID of the marker.  */
 202   char *str_id;
 203
 204   /* Extra target reported info associated with the marker.  */
 205   char *extra;
 206 };
 207
 208 struct trace_file_writer;
 209
 210 /* Operations to write trace frames to a specific trace format.  */
 211
 212 struct trace_frame_write_ops
 213 {
 214   /* Write a new trace frame.  The tracepoint number of this trace
 215      frame is TPNUM.  */
 216   void (*start) (struct trace_file_writer *self, uint16_t tpnum);
 217
 218   /* Write an 'R' block.  Buffer BUF contains its contents and SIZE is
 219      its size.  */
 220   void (*write_r_block) (struct trace_file_writer *self,
 221                          gdb_byte *buf, int32_t size);
 222
 223   /* Write an 'M' block, the header and memory contents respectively.
 224      The header of 'M' block is composed of the start address and the
 225      length of memory collection, and the memory contents contain
 226      the collected memory contents in tracing.
 227      For extremely large M block, GDB is unable to get its contents
 228      and write them into trace file in one go, due to the limitation
 229      of the remote target or the size of internal buffer, we split
 230      the operation to 'M' block to two operations.  */
 231   /* Write the head of 'M' block.  ADDR is the start address of
 232      collected memory and LENGTH is the length of memory contents.  */
 233   void (*write_m_block_header) (struct trace_file_writer *self,
 234                                 uint64_t addr, uint16_t length);
 235   /* Write the memory contents of 'M' block.  Buffer BUF contains
 236      its contents and LENGTH is its length.  This method can be called
 237      multiple times to write large memory contents of a single 'M'
 238      block.  */
 239   void (*write_m_block_memory) (struct trace_file_writer *self,
 240                                 gdb_byte *buf, uint16_t length);
 241
 242   /* Write a 'V' block.  NUM is the trace variable number and VAL is
 243      the value of the trace variable.  */
 244   void (*write_v_block) (struct trace_file_writer *self, int32_t num,
 245                          uint64_t val);
 246
 247   /* The end of the trace frame.  */
 248   void (*end) (struct trace_file_writer *self);
 249 };
 250
 251 /* Operations to write trace buffers to a specific trace format.  */
 252
 253 struct trace_file_write_ops
 254 {
 255   /* Destructor.  Releases everything from SELF (but not SELF
 256      itself).  */
 257   void (*dtor) (struct trace_file_writer *self);
 258
 259   /*  Save the data to file or directory NAME of desired format in
 260       target side.  Return true for success, otherwise return
 261       false.  */
 262   int (*target_save) (struct trace_file_writer *self,
 263                       const char *name);
 264
 265   /* Write the trace buffers to file or directory NAME.  */
 266   void (*start) (struct trace_file_writer *self,
 267                  const char *name);
 268
 269   /* Write the trace header.  */
 270   void (*write_header) (struct trace_file_writer *self);
 271
 272   /* Write the type of block about registers.  SIZE is the size of
 273      all registers on the target.  */
 274   void (*write_regblock_type) (struct trace_file_writer *self,
 275                                int size);
 276
 277   /* Write trace status TS.  */
 278   void (*write_status) (struct trace_file_writer *self,
 279                         struct trace_status *ts);
 280
 281   /* Write the uploaded TSV.  */
 282   void (*write_uploaded_tsv) (struct trace_file_writer *self,
 283                               struct uploaded_tsv *tsv);
 284
 285   /* Write the uploaded tracepoint TP.  */
 286   void (*write_uploaded_tp) (struct trace_file_writer *self,
 287                              struct uploaded_tp *tp);
 288
 289   /* Write to mark the end of the definition part.  */
 290   void (*write_definition_end) (struct trace_file_writer *self);
 291
 292   /* Write the data of trace buffer without parsing.  The content is
 293      in BUF and length is LEN.  */
 294   void (*write_trace_buffer) (struct trace_file_writer *self,
 295                               gdb_byte *buf, LONGEST len);
 296
 297   /* Operations to write trace frames.  The user of this field is
 298      responsible to parse the data of trace buffer.  Either field
 299      'write_trace_buffer' or field ' frame_ops' is NULL.  */
 300   const struct trace_frame_write_ops *frame_ops;
 301
 302   /* The end of writing trace buffers.  */
 303   void (*end) (struct trace_file_writer *self);
 304 };
 305
 306 /* Trace file writer for a given format.  */
 307
 308 struct trace_file_writer
 309 {
 310   const struct trace_file_write_ops *ops;
 311 };
 312
 313 extern void parse_static_tracepoint_marker_definition
 314   (char *line, char **pp,
 315    struct static_tracepoint_marker *marker);
 316 extern void release_static_tracepoint_marker (struct static_tracepoint_marker *);
 317 extern void free_current_marker (void *arg);
 318
 319 /* A hook used to notify the UI of tracepoint operations.  */
 320
 321 extern void (*deprecated_trace_find_hook) (char *arg, int from_tty);
 322 extern void (*deprecated_trace_start_stop_hook) (int start, int from_tty);
 323
 324 /* Returns the current traceframe number.  */
 325 extern int get_traceframe_number (void);
 326
 327 /* Make the traceframe NUM be the current GDB trace frame number, and
 328    do nothing more.  In particular, this does not flush the
 329    register/frame caches or notify the target about the trace frame
 330    change, so that is can be used when we need to momentarily access
 331    live memory.  Targets lazily switch their current traceframe to
 332    match GDB's traceframe number, at the appropriate times.  */
 333 extern void set_traceframe_number (int);
 334
 335 /* Make the traceframe NUM be the current trace frame, all the way to
 336    the target, and flushes all global state (register/frame caches,
 337    etc.).  */
 338 extern void set_current_traceframe (int num);
 339
 340 struct cleanup *make_cleanup_restore_current_traceframe (void);
 341 struct cleanup *make_cleanup_restore_traceframe_number (void);
 342
 343 void free_actions (struct breakpoint *);
 344
 345 extern const char *decode_agent_options (const char *exp);
 346
 347 extern void encode_actions (struct breakpoint *t, struct bp_location *tloc,
 348                             char ***tdp_actions, char ***stepping_actions);
 349
 350 extern void validate_actionline (const char *, struct breakpoint *);
 351 extern void validate_trace_state_variable_name (const char *name);
 352
 353 extern struct trace_state_variable *find_trace_state_variable (const char *name);
 354 extern struct trace_state_variable *create_trace_state_variable (const char *name);
 355
 356 extern int encode_source_string (int num, ULONGEST addr,
 357                                  char *srctype, char *src,
 358                                  char *buf, int buf_size);
 359
 360 extern void parse_trace_status (char *line, struct trace_status *ts);
 361
 362 extern void parse_tracepoint_status (char *p, struct breakpoint *tp,
 363                                      struct uploaded_tp *utp);
 364
 365 extern void parse_tracepoint_definition (char *line,
 366                                          struct uploaded_tp **utpp);
 367 extern void parse_tsv_definition (char *line, struct uploaded_tsv **utsvp);
 368
 369 extern struct uploaded_tp *get_uploaded_tp (int num, ULONGEST addr,
 370                                             struct uploaded_tp **utpp);
 371 extern struct tracepoint *create_tracepoint_from_upload (struct uploaded_tp *utp);
 372 extern void merge_uploaded_tracepoints (struct uploaded_tp **utpp);
 373 extern void merge_uploaded_trace_state_variables (struct uploaded_tsv **utsvp);
 374
 375 extern void disconnect_tracing (int from_tty);
 376
 377 extern void start_tracing (char *notes);
 378 extern void stop_tracing (char *notes);
 379
 380 extern void trace_status_mi (int on_stop);
 381
 382 extern void tvariables_info_1 (void);
 383 extern void save_trace_state_variables (struct ui_file *fp);
 384
 385 extern void tfind_1 (enum trace_find_type type, int num,
 386                      ULONGEST addr1, ULONGEST addr2,
 387                      int from_tty);
 388
 389 extern void trace_save_tfile (const char *filename,
 390                               int target_does_save);
 391 extern void trace_save_ctf (const char *dirname,
 392                             int target_does_save);
 393
 394 extern struct traceframe_info *parse_traceframe_info (const char *tframe_info);
 395
 396 extern int traceframe_available_memory (VEC(mem_range_s) **result,
 397                                         CORE_ADDR memaddr, ULONGEST len);
 398
 399 #endif  /* TRACEPOINT_H */