DCFG
Dynamic Control Flow Graph
 All Classes Functions
dcfg_api.H
1 /*BEGIN_LEGAL
2 BSD License
3 
4 Copyright (c) 2015 Intel Corporation. All rights reserved.
5 
6 Redistribution and use in source and binary forms, with or without
7 modification, are permitted provided that the following conditions are
8 met:
9 
10 Redistributions of source code must retain the above copyright notice,
11 this list of conditions and the following disclaimer. Redistributions
12 in binary form must reproduce the above copyright notice, this list of
13 conditions and the following disclaimer in the documentation and/or
14 other materials provided with the distribution. Neither the name of
15 the Intel Corporation nor the names of its contributors may be used to
16 endorse or promote products derived from this software without
17 specific prior written permission.
18 
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL OR
23 ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 END_LEGAL */
31 
32 #ifndef DCFG_API_H
33 #define DCFG_API_H
34 
35 #include <vector>
36 #include <set>
37 #include <iostream>
38 
39 // Fundamental types.
40 #if !defined(TYPES_FOUNDATION_H)
41 
42 #if defined(_MSC_VER)
43  typedef unsigned char UINT8 ;
44  typedef unsigned short UINT16;
45  typedef unsigned int UINT32;
46  typedef unsigned __int64 UINT64;
47  typedef signed char INT8;
48  typedef signed short INT16;
49  typedef signed int INT32;
50  typedef signed __int64 INT64;
51 #else
52 #include <stdint.h>
53  typedef uint8_t UINT8;
54  typedef uint16_t UINT16;
55  typedef uint32_t UINT32;
56  typedef uint64_t UINT64;
57  typedef int8_t INT8;
58  typedef int16_t INT16;
59  typedef int32_t INT32;
60  typedef int64_t INT64;
61 #endif
62 #endif
63 
64 namespace dcfg_api {
65 
82  typedef UINT32 DCFG_ID;
83 
84  // Interface declarations.
85  class DCFG_DATA;
86  class DCFG_PROCESS;
87  class DCFG_IMAGE;
88  class DCFG_ROUTINE;
89  class DCFG_LOOP;
90  class DCFG_BASIC_BLOCK;
91  class DCFG_EDGE;
92  class DCFG_ID_CONTAINER;
93 
95  typedef const DCFG_DATA* DCFG_DATA_CPTR;
96 
98  typedef const DCFG_PROCESS* DCFG_PROCESS_CPTR;
99 
101  typedef const DCFG_IMAGE* DCFG_IMAGE_CPTR;
102 
104  typedef const DCFG_ROUTINE* DCFG_ROUTINE_CPTR;
105 
107  typedef const DCFG_LOOP* DCFG_LOOP_CPTR;
108 
110  typedef const DCFG_BASIC_BLOCK* DCFG_BASIC_BLOCK_CPTR;
111 
113  typedef const DCFG_EDGE* DCFG_EDGE_CPTR;
114 
120  class DCFG_DATA {
121  public:
122 
123  // Default virtual destructor to ensure cleanup.
124  virtual ~DCFG_DATA() {}
125 
132  static DCFG_DATA* new_dcfg();
133 
138  virtual bool
139  read(std::istream& strm,
142  std::string& errMsg,
144  bool readToEof = true
149  ) =0;
150 
156  virtual bool
157  read(const std::string filename,
160  std::string& errMsg
162  ) =0;
163 
167  virtual void
168  write(std::ostream& strm
171  ) const =0;
172 
177  virtual bool
178  write(const std::string& filename,
181  std::string& errMsg
183  ) const =0;
184 
188  virtual void clearCounts() =0;
189 
194  virtual UINT32
203  ) const =0;
204 
210  virtual DCFG_PROCESS_CPTR
211  get_process_info(DCFG_ID process_id
213  ) const =0;
214  };
215 
225  public:
226 
227  // Default virtual destructor to ensure cleanup.
228  virtual ~DCFG_GRAPH_BASE() {}
229 
234  virtual UINT32
243  ) const =0;
244 
251  virtual UINT32
260  ) const =0;
261 
271  virtual UINT32
280  ) const =0;
281 
282 
292  virtual UINT32
301  ) const =0;
302 
308  virtual UINT64 get_instr_count() const =0;
309 
315  virtual UINT64
316  get_instr_count_for_thread(UINT32 thread_id
320  ) const =0;
321  };
322 
332  public virtual DCFG_GRAPH_BASE {
333  public:
334 
335  // Default virtual destructor to ensure cleanup.
336  virtual ~DCFG_LOOP_CONTAINER() {}
337 
345  virtual UINT32
354  ) const =0;
355 
361  virtual DCFG_LOOP_CPTR
362  get_loop_info(DCFG_ID loop_id
364  ) const =0;
365  };
366 
372  public virtual DCFG_LOOP_CONTAINER {
373  public:
374 
375  // Default virtual destructor to ensure cleanup.
376  virtual ~DCFG_ROUTINE_CONTAINER() {}
377 
385  virtual UINT32
394  ) const =0;
395 
401  virtual DCFG_ROUTINE_CPTR
402  get_routine_info(DCFG_ID routine_id
404  ) const =0;
405  };
406 
412  public virtual DCFG_ROUTINE_CONTAINER {
413  public:
414 
415  // Default virtual destructor to ensure cleanup.
416  virtual ~DCFG_IMAGE_CONTAINER() {}
417 
426  virtual UINT32
435  ) const =0;
436 
442  virtual DCFG_IMAGE_CPTR
443  get_image_info(DCFG_ID image_id
445  ) const =0;
446  };
447 
451  class DCFG_PROCESS :
452  public virtual DCFG_IMAGE_CONTAINER {
453  public:
454 
455  // Default virtual destructor to ensure cleanup.
456  virtual ~DCFG_PROCESS() {}
457 
462  virtual DCFG_ID get_process_id() const =0;
463 
471  virtual UINT32 get_highest_thread_id() const =0;
472 
485  virtual UINT32
486  get_basic_block_ids_by_addr(UINT64 addr,
489  DCFG_ID_CONTAINER &node_ids
497  ) const =0;
498 
506  virtual UINT32 get_start_node_id() const =0;
507 
515  virtual UINT32 get_end_node_id() const =0;
516 
526  virtual UINT32 get_unknown_node_id() const =0;
527 
533  virtual DCFG_ID
534  get_edge_id(DCFG_ID source_node_id,
536  DCFG_ID target_node_id
538  ) const =0;
539 
545  virtual UINT32
546  get_successor_node_ids(DCFG_ID source_node_id,
548  DCFG_ID_CONTAINER &node_ids
556  ) const =0;
557 
558 
564  virtual UINT32
565  get_predecessor_node_ids(DCFG_ID target_node_id,
567  DCFG_ID_CONTAINER &node_ids
575  ) const =0;
576 
582  virtual DCFG_EDGE_CPTR
583  get_edge_info(DCFG_ID edge_id
585  ) const =0;
586 
592  virtual DCFG_BASIC_BLOCK_CPTR
593  get_basic_block_info(DCFG_ID node_id
595  ) const =0;
596 
606  virtual bool
607  is_special_node(DCFG_ID node_id
609  ) const =0;
610 
616  virtual bool
617  is_start_node(DCFG_ID node_id
619  ) const =0;
620 
626  virtual bool
627  is_end_node(DCFG_ID node_id
629  ) const =0;
630 
638  virtual bool
639  is_unknown_node(DCFG_ID node_id
641  ) const =0;
642 
643 
644  };
645 
649  class DCFG_IMAGE :
650  public virtual DCFG_ROUTINE_CONTAINER {
651  public:
652 
653  // Default virtual destructor to ensure cleanup.
654  virtual ~DCFG_IMAGE() {}
655 
660  virtual DCFG_ID get_process_id() const =0;
661 
666  virtual DCFG_ID get_image_id() const =0;
667 
673  virtual const std::string* get_filename() const =0;
674 
679  virtual UINT64 get_base_address() const =0;
680 
685  virtual UINT64 get_size() const =0;
686 
701  virtual UINT32
702  get_basic_block_ids_by_addr(UINT64 addr,
705  DCFG_ID_CONTAINER &node_ids
713  ) const =0;
714 
715  };
716 
721  class DCFG_ROUTINE :
722  public virtual DCFG_LOOP_CONTAINER {
723  public:
724 
725  // Default virtual destructor to ensure cleanup.
726  virtual ~DCFG_ROUTINE() {}
727 
732  virtual DCFG_ID get_process_id() const =0;
733 
738  virtual DCFG_ID get_image_id() const =0;
739 
747  virtual DCFG_ID get_routine_id() const =0;
748 
759  virtual const std::string* get_symbol_name() const =0;
760 
775  virtual UINT32
784  ) const =0;
785 
798  virtual UINT32
807  ) const =0;
808 
821  virtual DCFG_ID
822  get_idom_node_id(DCFG_ID node_id
824  ) const =0;
825 
836  virtual UINT64 get_entry_count() const =0;
837 
845  virtual UINT64
846  get_entry_count_for_thread(UINT32 thread_id
850  ) const =0;
851 
852  };
853 
857  class DCFG_LOOP :
858  public virtual DCFG_GRAPH_BASE {
859  public:
860 
861  // Default virtual destructor to ensure cleanup.
862  virtual ~DCFG_LOOP() {}
863 
868  virtual DCFG_ID get_process_id() const =0;
869 
874  virtual DCFG_ID get_image_id() const =0;
875 
880  virtual DCFG_ID get_routine_id() const =0;
881 
888  virtual DCFG_ID get_loop_id() const =0;
889 
897  virtual UINT32
906  ) const =0;
907 
918  virtual UINT32
927  ) const =0;
928 
937  virtual UINT32
946  ) const =0;
947 
948 
956  virtual DCFG_ID get_parent_loop_id() const =0;
967  virtual UINT64 get_iteration_count() const =0;
968 
976  virtual UINT64
977  get_iteration_count_for_thread(UINT32 thread_id
981  ) const =0;
982 
983  };
984 
989  public virtual DCFG_GRAPH_BASE {
990  public:
991 
992  // Default virtual destructor to ensure cleanup.
993  virtual ~DCFG_BASIC_BLOCK() {}
994 
1000  virtual DCFG_ID get_basic_block_id() const =0;
1001 
1006  virtual DCFG_ID get_process_id() const =0;
1007 
1012  virtual DCFG_ID get_image_id() const =0;
1013 
1019  virtual DCFG_ID get_routine_id() const =0;
1020 
1029  virtual DCFG_ID get_inner_loop_id() const =0;
1030 
1035  virtual UINT64 get_first_instr_addr() const =0;
1036 
1046  virtual UINT64 get_last_instr_addr() const =0;
1047 
1052  virtual UINT32 get_size() const =0;
1053 
1061  virtual UINT32 get_num_instrs() const =0;
1062 
1068  virtual const std::string* get_symbol_name() const =0;
1069 
1077  virtual UINT32 get_symbol_offset() const =0;
1078 
1084  virtual const std::string* get_source_filename() const =0;
1085 
1091  virtual UINT32 get_source_line_number() const =0;
1092 
1098  virtual UINT64 get_exec_count() const =0;
1099 
1105  virtual UINT64
1106  get_exec_count_for_thread(UINT32 thread_id
1110  ) const =0;
1111 
1112  };
1113 
1118  class DCFG_EDGE {
1119  public:
1120 
1121  // Default virtual destructor to ensure cleanup.
1122  virtual ~DCFG_EDGE() {}
1123 
1128  virtual DCFG_ID get_edge_id() const =0;
1129 
1138  virtual DCFG_ID get_source_node_id() const =0;
1139 
1148  virtual DCFG_ID get_target_node_id() const =0;
1149 
1154  virtual UINT64 get_exec_count() const =0;
1155 
1160  virtual UINT64
1161  get_exec_count_for_thread(UINT32 thread_id
1165  ) const =0;
1166 
1173  virtual const std::string* get_edge_type() const =0;
1174 
1179  virtual bool is_any_branch_type() const =0;
1180 
1186  virtual bool is_any_call_type() const =0;
1187 
1193  virtual bool is_any_return_type() const =0;
1194 
1201  virtual bool is_any_inter_routine_type() const =0;
1202 
1210  virtual bool is_any_bypass_type() const =0;
1211 
1218  virtual bool is_branch_edge_type() const =0;
1219 
1226  virtual bool is_call_edge_type() const =0;
1227 
1234  virtual bool is_return_edge_type() const =0;
1235 
1242  virtual bool is_call_bypass_edge_type() const =0;
1243 
1250  virtual bool is_conditional_branch_edge_type() const =0;
1251 
1258  virtual bool is_context_bypass_edge_type() const =0;
1259 
1266  virtual bool is_context_edge_type() const =0;
1267 
1274  virtual bool is_context_return_edge_type() const =0;
1275 
1282  virtual bool is_direct_branch_edge_type() const =0;
1283 
1290  virtual bool is_direct_call_edge_type() const =0;
1291 
1298  virtual bool is_direct_conditional_branch_edge_type() const =0;
1299 
1306  virtual bool is_direct_unconditional_branch_edge_type() const =0;
1307 
1314  virtual bool is_entry_edge_type() const =0;
1315 
1322  virtual bool is_excluded_bypass_edge_type() const =0;
1323 
1330  virtual bool is_exit_edge_type() const =0;
1331 
1338  virtual bool is_fall_thru_edge_type() const =0;
1339 
1346  virtual bool is_indirect_branch_edge_type() const =0;
1347 
1354  virtual bool is_indirect_call_edge_type() const =0;
1355 
1362  virtual bool is_indirect_conditional_branch_edge_type() const =0;
1363 
1370  virtual bool is_indirect_unconditional_branch_edge_type() const =0;
1371 
1378  virtual bool is_rep_edge_type() const =0;
1379 
1386  virtual bool is_sys_call_bypass_edge_type() const =0;
1387 
1394  virtual bool is_sys_call_edge_type() const =0;
1395 
1402  virtual bool is_sys_return_edge_type() const =0;
1403 
1410  virtual bool is_unconditional_branch_edge_type() const =0;
1411 
1418  virtual bool is_unknown_edge_type() const =0;
1419  };
1420 
1421 
1429  public:
1430 
1431  // Default virtual destructor to ensure cleanup.
1432  virtual ~DCFG_ID_CONTAINER() {}
1433 
1438  virtual void add_id(DCFG_ID id
1440  )=0;
1441  };
1442 
1451  public std::vector<DCFG_ID>,
1452  public DCFG_ID_CONTAINER {
1453  public:
1454 
1455  // Default virtual destructor to ensure cleanup.
1456  virtual ~DCFG_ID_VECTOR() {}
1457 
1458  virtual void add_id(DCFG_ID id) {
1459  push_back(id);
1460  }
1461  };
1462 
1469  class DCFG_ID_SET :
1470  public std::set<DCFG_ID>,
1471  public DCFG_ID_CONTAINER {
1472  public:
1473 
1474  // Default virtual destructor to ensure cleanup.
1475  virtual ~DCFG_ID_SET() {}
1476 
1477  virtual void add_id(DCFG_ID id) {
1478  insert(id);
1479  }
1480  };
1481 
1482 }; // namespace
1483 #endif