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