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