├── .gitignore
├── LICENSE
├── Makefile
├── README.md
├── dctrace.py
├── main.c
└── profiler.c


/.gitignore:
--------------------------------------------------------------------------------
1 | *.o
2 | *.elf
3 | *.jpg
4 | *.txt
5 | *.dot
6 | *.bin
7 | .DS_Store
8 | .vscode/
9 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | BSD 2-Clause License
 2 | 
 3 | Copyright (c) 2023, Dreamcast
 4 | 
 5 | Redistribution and use in source and binary forms, with or without
 6 | modification, are permitted provided that the following conditions are met:
 7 | 
 8 | 1. Redistributions of source code must retain the above copyright notice, this
 9 |    list of conditions and the following disclaimer.
10 | 
11 | 2. Redistributions in binary form must reproduce the above copyright notice,
12 |    this list of conditions and the following disclaimer in the documentation
13 |    and/or other materials provided with the distribution.
14 | 
15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
19 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
 1 | # What we are building
 2 | TARGET = profile.elf
 3 | 
 4 | # List of all source files
 5 | SRCS = main.c profiler.c
 6 | 
 7 | # List of files to exclude from instrumentation
 8 | EXCLUDE_FILES = profiler.c
 9 | 
10 | # Set compiler flags
11 | CFLAGS = -g -finstrument-functions
12 | 
13 | DATETIME := $(shell date '+%Y-%m-%d_%I-%M-%S_%p')
14 | 
15 | all: clean $(TARGET)
16 | 
17 | include $(KOS_BASE)/Makefile.rules
18 | 
19 | clean:
20 | 	-rm -f $(TARGET) $(OBJS)
21 | 	-rm -f PROF.CDI
22 | 	-rm -rf ISO
23 | 
24 | $(TARGET): $(SRCS) 
25 | 	kos-cc $(CFLAGS) -finstrument-functions-exclude-file-list=$(EXCLUDE_FILES) $^ -o $@ $(DATAOBJS) $(OBJEXTRA)
26 | 
27 | profileip: $(TARGET)
28 | 	sudo /opt/toolchains/dc-utils/dc-tool-ip -c "." -t 172.16.0.10 -x $(TARGET)
29 | 
30 | profileser: $(TARGET)
31 | 	sudo /opt/toolchains/dc-utils/dc-tool-ser -c "." -t /dev/cu.usbserial-ABSCDWND -b 115200 -x $(TARGET)
32 | 
33 | dot: trace.bin $(TARGET)
34 | 	python3 dctrace.py $(TARGET)
35 | 
36 | image: dot
37 | 	dot -Tjpg graph.dot -o graph_$(DATETIME).jpg
38 | 
39 | run: $(TARGET)
40 | 	$(KOS_IP_LOADER) $(TARGET)
41 | 
42 | rei: dist
43 | 	$(REICAST) PROF.CDI
44 | 
45 | lxd: dist
46 | 	$(LXDREAM) PROF.CDI
47 | 
48 | fly: dist
49 | 	$(FLYCAST) PROF.CDI
50 | 
51 | dist: $(target)
52 | 	$(KOS_STRIP) $(TARGET)
53 | 	$(KOS_OBJCOPY) -O binary $(TARGET) prog.bin
54 | 	$(KOS_SCRAMBLE) prog.bin 1ST_READ.BIN
55 | 	mkdir -p ISO
56 | 	cp 1ST_READ.BIN ISO
57 | 	mkisofs -C 0,11702 -V DCTEST -G ${KOS_BASE}/IP.BIN -J -R -l -o PROF.ISO ISO
58 | 	$(CREATE_CDI) PROF.ISO PROF.CDI
59 | 	rm -f PROF.ISO
60 | 	rm -f prog.BIN
61 | 	rm -f 1ST_READ.BIN
62 | 	rm -rf ISO
63 | 	rm $(TARGET)
64 | 
65 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # dcprofiler
  2 | 
  3 | `dcprofiler` is a profiling toolkit for Dreamcast applications that uses GCC's `-finstrument-functions` feature to track function calls. It records detailed timing and performance counter data, generating a call graph visualization that highlights hotspots in your code. `dcprofiler` generates a lot of tracing data — use **dcload-ip for best performance**.
  4 | 
  5 | There are two main parts to this project:
  6 | 1. `profiler.c` – included in your Dreamcast project
  7 | 2. `dctrace.py` – a Python script that parses `trace.bin` and generates a Graphviz `.dot` file
  8 | 
  9 | ---
 10 | 
 11 | ## Setup Instructions
 12 | 
 13 | 1. **Add** `profiler.c` to your project’s source directory.
 14 | 2. **Modify your Makefile**:
 15 |    - Add `-g -finstrument-functions` to `KOS_CFLAGS`
 16 |    - Add `profiler.o` to `OBJS`
 17 | 3. **Upload your ELF** to the Dreamcast via dc-tool-ip:
 18 |    ```sh
 19 |    sudo /path/to/dc-tool-ip -c "." -t 192.168.1.137 -x program.elf
 20 |    ```
 21 | 4. **Run your Dreamcast app** - profiling begins immediately and stops on exit. The results are saved to trace.bin on your PC.
 22 | 5. **Generate the call graph by running**:
 23 |    ```sh
 24 |    python3 dctrace.py [OPTIONS] program.elf
 25 |    ```
 26 | > **Note**: Make sure the following are true before running `dctrace.py`:
 27 | > - `KOS_ADDR2LINE` is set **or** `sh-elf-addr2line` is located at `/opt/toolchains/dc/sh-elf/bin/`
 28 | > - Your `trace.bin` and the corresponding `.elf` file are in the same directory
 29 | 
 30 | 6.  **Render the graph with Graphviz**:
 31 |   ```sh
 32 |   dot -Tpng graph.dot -o graph.png
 33 |   ```
 34 | 
 35 | ### Installing Graphviz
 36 | 
 37 | To generate images from `.dot` files, you'll need to install the **Graphviz** tool.
 38 | 
 39 | - Download it from the official site: [https://graphviz.org/download](https://graphviz.org/download)
 40 | 
 41 | - On macOS (with Homebrew), run:
 42 |   ```sh
 43 |   brew install graphviz
 44 |   ```
 45 | 
 46 | ## dctrace.py Optional Flags
 47 | 
 48 | The `dctrace.py` script accepts several options to customize the profiling output:
 49 | 
 50 | | Option              | Description                                                                                         |
 51 | |---------------------|-----------------------------------------------------------------------------------------------------|
 52 | | `-t <filename>`     | Specify the input trace file (default: `trace.bin`).                                                |
 53 | | `-a <path>`         | Path to the `sh-elf-addr2line` tool (default: `/opt/toolchains/dc/sh-elf/bin/sh-elf-addr2line`).    |
 54 | | `-p <percent>`      | Percentage threshold for graph visibility. Functions below this inclusive time % are omitted.       |
 55 | | `-ev0="<label>"`    | Custom label to display for event counter 0 (default: `ev0`).                                       |
 56 | | `-ev1="<label>"`    | Custom label to display for event counter 1 (default: `ev1`).                                       |
 57 | | `--xt <float>`      | Exclude-time threshold. Suggest excluding functions below this % of runtime (alias: `--ex-time`).   |
 58 | | `--xe <float>`      | Exclude-event threshold. Suggest excluding functions below this % of ev0/ev1 (alias: `--ex-ev`).    |
 59 | | `-v`                | Enable verbose output for debugging unmatched functions, parsing info, etc.                         |
 60 | 
 61 | ### Example Usage
 62 | 
 63 | ```sh
 64 | python3 dctrace.py -t my_trace.bin -p 1.5 -ev0="dcache miss" -ev1="icache miss" program.elf
 65 | ```
 66 | 
 67 | ## Example Makefile Snippet:
 68 | 
 69 | ```make
 70 | TARGET = main.elf
 71 | DATETIME := $(shell date '+%Y-%m-%d_%I-%M-%S_%p')
 72 | 
 73 | profileip: $(TARGET)
 74 | 	sudo /PATH/TO/dc-tool-ip -c "." -t 192.168.1.137 -x $(TARGET)
 75 | 
 76 | dot: trace.bin $(TARGET)
 77 | 	python3 /PATH/TO/dctrace.py $(TARGET)
 78 | 
 79 | image: dot
 80 | 	dot -Tpng graph.dot -o graph_$(DATETIME).png
 81 | ```
 82 | **After profiling your app with make profileip, simply run**:
 83 | ```sh
 84 | make image
 85 | ```
 86 | This generates graph.dot and the visual graph.png.
 87 | 
 88 | ## TIPS:
 89 | 
 90 | ### Excluding Functions from Profiling
 91 | 
 92 | To prevent specific functions from being instrumented:
 93 | 
 94 | - Add the following attribute to their **declaration or definition**:
 95 |   ```c
 96 |   __attribute__ ((no_instrument_function))
 97 |   ```
 98 | - Or use this in your Makefile to exclude by name:
 99 |   ```make
100 |   -finstrument-functions-exclude-function-list=func1,func2,...
101 |   ```
102 | 
103 | ---
104 | 
105 | ### Excluding Entire Files
106 | 
107 | To exclude whole files from instrumentation, use:
108 |   ```make
109 |   -finstrument-functions-exclude-file-list=file1.c,file2.c
110 |   ```
111 | ---
112 | 
113 | ### Inlining & Optimization
114 | 
115 | Functions that are **inlined** by the compiler are not instrumented and won’t appear in traces.
116 | 
117 | Additionally, high optimization levels (like -O2 or -O3) may:
118 | - Remove/merge function prologues and epilogues
119 | - Cause missing or inaccurate __cyg_profile_func_* callbacks
120 | 
121 | > **Solution:**  
122 | > Disable inlining using `-fno-inline`
123 | 
124 | ---
125 | 
126 | ### Tail Call Optimizations (TCO)
127 | 
128 | TCO can replace a `call + return` sequence with a direct `jump`, which **bypasses** `__cyg_profile_func_exit`.
129 | 
130 | > **Solution:**  
131 | > Disable tail-call optimizations using `-fno-optimize-sibling-calls`
132 | 


--------------------------------------------------------------------------------
/dctrace.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python3
  2 | """
  3 | dctrace.py – Python utility for decoding compressed Dreamcast profiler output,
  4 | and generating a visual call graph with detailed performance stats.
  5 | 
  6 | This script works in conjunction with a Dreamcast profiler that:
  7 |   - Uses -finstrument-functions to log function entry/exit
  8 |   - Delta-encodes performance counter and timestamp values
  9 |   - Writes records in a compact binary format (trace.bin)
 10 | 
 11 | Each record is variable-length (typically 9–19 bytes), consisting of:
 12 |   - uint32_t address:
 13 |       - Bits 31     = 1 for entry, 0 for exit
 14 |       - Bits 30–22  = thread ID
 15 |       - Bits 21–0   = compressed function address (>>2 from 0x8C000000)
 16 |   - LEB128 encoded:
 17 |       - uint32_t scaled_time (delta time / 80ns)
 18 |       - uint32_t delta_evt0 (e.g. operand cache misses)
 19 |       - uint32_t delta_evt1 (e.g. instruction cache misses)
 20 | 
 21 | This script performs:
 22 |   ✓ LEB128 decoding of all deltas
 23 |   ✓ Symbol resolution using addr2line
 24 |   ✓ Accurate wall-clock runtime reconstruction
 25 |   ✓ Call graph reconstruction and self/inclusive time breakdown
 26 |   ✓ Parent → child contribution tracking
 27 |   ✓ Low-impact function detection and Makefile CFLAGS suggestions
 28 |   ✓ DOT file generation for Graphviz
 29 | 
 30 | Output:
 31 |   - graph.dot: a visual call graph (render using `dot -Tpng graph.dot -o graph.png`)
 32 |   - Console: list of functions you may wish to exclude from profiling for smaller traces
 33 | 
 34 | Example usage:
 35 |     python3 dctrace.py -t trace.bin -p 2 myprogram.elf
 36 |     dot -Tsvg graph.dot -o graph.svg
 37 | """
 38 | import argparse
 39 | import struct
 40 | import subprocess
 41 | import sys
 42 | import time
 43 | import os
 44 | import traceback
 45 | from bisect import insort
 46 | from collections import defaultdict
 47 | 
 48 | # Constants matching the C version
 49 | ENTRY_FLAG      = 0x80000000
 50 | TID_MASK        = 0x1FF
 51 | ADDR_MASK       = 0x003FFFFF
 52 | BASE_ADDRESS    = 0x8C000000
 53 | 
 54 | DEFAULT_TRACE   = 'trace.bin'
 55 | DEFAULT_ADDR2LINE = os.environ.get('KOS_ADDR2LINE', '/opt/toolchains/dc/sh-elf/bin/sh-elf-addr2line')
 56 | PQ_MAX_SIZE     = 5
 57 | 
 58 | # --- Data structures ---
 59 | class StackFrame:
 60 |     __slots__ = ('addr','start_time','start_e0','start_e1')
 61 |     def __init__(self, addr, start_time, start_e0, start_e1):
 62 |         self.addr = addr
 63 |         self.start_time = start_time
 64 |         self.start_e0 = start_e0
 65 |         self.start_e1 = start_e1
 66 | 
 67 | class FunctionRecord:
 68 |     __slots__ = ('name','total_time','times_called','ev0','ev1')
 69 |     def __init__(self, name):
 70 |         self.name = name
 71 |         self.total_time = 0
 72 |         self.times_called = 0
 73 |         self.ev0 = 0
 74 |         self.ev1 = 0
 75 | 
 76 | class ChildCall:
 77 |     __slots__ = ('total_cycles','times_called','ev0','ev1')
 78 |     def __init__(self):
 79 |         self.total_cycles = 0
 80 |         self.times_called = 0
 81 |         self.ev0 = 0
 82 |         self.ev1 = 0
 83 | 
 84 | class PriorityQueue:
 85 |     def __init__(self, max_size=PQ_MAX_SIZE):
 86 |         self.max_size = max_size
 87 |         self.elements = []  # list of tuples (-percentage, from_idx, cycles)
 88 | 
 89 |     def insert(self, from_idx, percentage, cycles):
 90 |         # If full and new is no better than worst, skip
 91 |         if len(self.elements) == self.max_size and percentage <= -self.elements[-1][0]:
 92 |             return
 93 |         # Insert and keep sorted descending by percentage
 94 |         insort(self.elements, (-percentage, from_idx, cycles))
 95 |         # Trim to max_size
 96 |         if len(self.elements) > self.max_size:
 97 |             self.elements.pop()
 98 | 
 99 |     @property
100 |     def size(self):
101 |         return len(self.elements)
102 | 
103 | # --- Global mappings ---
104 | functions = {}  # addr -> FunctionRecord
105 | child_calls = defaultdict(lambda: defaultdict(ChildCall))  # parent_addr -> (child_addr -> ChildCall)
106 | call_stack = []  # list of StackFrame
107 | 
108 | class DotManager:
109 |     def __init__(self, program, addr2line_path, verbose, threshold, total, ev0, ev1):
110 |         self.program     = program
111 |         self.addr2line     = addr2line_path
112 |         self.verbose       = verbose
113 |         self.threshold     = threshold
114 |         self.pq            = PriorityQueue()
115 |         self.total         = total
116 |         self.ev0           = ev0
117 |         self.ev1           = ev1
118 | 
119 |     def color_from_percent(self, pct):
120 |         wl = 440 + pct*(220/100)
121 |         if wl < 490:
122 |             r, g, b = 0, (wl-440)/(490-440), 1
123 |         elif wl < 510:
124 |             r, g, b = 0,1,-(wl-510)/(510-490)
125 |         elif wl < 580:
126 |             r, g, b = (wl-510)/(580-510),1,0
127 |         elif wl < 645:
128 |             r, g, b = 1, -(wl-645)/(645-580),0
129 |         else:
130 |             r, g, b = 1,0,0
131 |         r,g,b = [int(x*255*0.7) for x in (r,g,b)]
132 |         return f"#{r:02x}{g:02x}{b:02x}"
133 | 
134 |     def format_float_smart(self, val):
135 |         return f"{val:.0f}" if val == int(val) else f"{val:.2f}"
136 | 
137 |     def write_node_shapes(self, fp):
138 |         for addr, fn in functions.items():
139 |             if fn.times_called == 0:
140 |                 continue
141 |             cum = fn.total_time
142 |             # sum cycles spent in children (excluding self-calls)
143 |             child_cycles = sum(cc.total_cycles
144 |                                for callee, cc in child_calls.get(addr, {}).items()
145 |                                if callee != addr)
146 |             inclusive = cum - child_cycles
147 |             pct_cum = (cum / self.total) * 100
148 |             pct_inclusive = (inclusive / self.total) * 100
149 |             if pct_inclusive < self.threshold:
150 |                 continue
151 | 
152 |             # insert into priority queue
153 |             self.pq.insert(addr, pct_inclusive, cum)
154 | 
155 |             # if recursive, record full cumulative into that child edge
156 |             if addr in child_calls.get(addr, {}):
157 |                 child_calls[addr][addr].total_cycles = cum
158 | 
159 |             col   = self.color_from_percent(pct_cum)
160 |             shape = "rectangle" if child_cycles else "ellipse"
161 |             label = f"{fn.name}\\n{pct_cum:.2f}%\\n"
162 |             children = child_calls.get(addr, {})
163 | 
164 |             # Only include inclusive % line if it's NOT a leaf
165 |             if child_cycles:
166 |                 label += f"({pct_inclusive:.2f}%)\\n"
167 | 
168 |             # Avoid division by zero just in case
169 |             ev0_avg = fn.ev0 / fn.times_called if fn.times_called else 0
170 |             ev1_avg = fn.ev1 / fn.times_called if fn.times_called else 0
171 | 
172 |             label += f"{self.ev0}: {self.format_float_smart(ev0_avg)} / call\\n"
173 | 
174 |             if child_cycles:
175 |                 child_ev0_total = sum(cc.ev0 for callee, cc in children.items() if callee != addr)
176 |                 inclusive_ev0 = fn.ev0 - child_ev0_total
177 |                 inclusive_ev0_avg = inclusive_ev0 / fn.times_called if fn.times_called else 0
178 |                 label += f"({self.ev0}: {self.format_float_smart(inclusive_ev0_avg)} / call)\\n"
179 | 
180 |             label += f"{self.ev1}: {self.format_float_smart(ev1_avg)} / call\\n"
181 | 
182 |             if child_cycles:
183 |                 child_ev1_total = sum(cc.ev1 for callee, cc in children.items() if callee != addr)
184 |                 inclusive_ev1 = fn.ev1 - child_ev1_total
185 |                 inclusive_ev1_avg = inclusive_ev1 / fn.times_called if fn.times_called else 0
186 |                 label += f"({self.ev1}: {self.format_float_smart(inclusive_ev1_avg)} / call)\\n"
187 | 
188 |             label += f"{fn.times_called} x"
189 | 
190 |             fp.write(
191 |                 f"\t\t\"{fn.name}\" [label=\"{label}\" "
192 |                 f"fontcolor=\"white\" color=\"{col}\" shape={shape}]\n"
193 |             )
194 |         fp.write("\n")
195 | 
196 |     def write_call_graph(self, fp):
197 |         for caller, callee_dict in child_calls.items():
198 |             for callee, cc in callee_dict.items():
199 |                 if cc.times_called == 0:
200 |                     continue
201 |                 pct = (cc.total_cycles / self.total) * 100
202 |                 if pct < self.threshold:
203 |                     continue
204 |                 col   = self.color_from_percent(pct)
205 |                 style = "bold" if pct > 0.35 else "solid"
206 |                 name_f = functions[caller].name
207 |                 name_t = functions[callee].name
208 |                 label = f"{pct:.2f}%\\n{cc.times_called} x"
209 |                 fp.write(
210 |                     f"\t\t\"{name_f}\" -> \"{name_t}\" "
211 |                     f"[label=\"{label}\" color=\"{col}\" style=\"{style}\" fontsize=10]\n"
212 |                 )
213 | 
214 |     def write_table(self, fp):
215 |         elements = self.pq.elements
216 |         last_index = len(elements)
217 | 
218 |         fp.write("\t\ta0 [shape=none label=<\n\t\t\t<TABLE border=\"0\" cellspacing=\"3\" cellpadding=\"10\" bgcolor=\"black\">\n\t\t\t\t")
219 | 
220 |         for rank, (neg_pct, idx, cycles) in enumerate(elements, 1):
221 |             pct = -neg_pct
222 |             name = functions[idx].name
223 |             fp.write("<TR>\n\t\t\t\t\t")
224 |             fp.write(f"<TD bgcolor=\"white\">{rank}</TD>\n\t\t\t\t\t")
225 |             fp.write(f"<TD bgcolor=\"white\">{name}</TD>\n\t\t\t\t\t")
226 |             fp.write(f"<TD bgcolor=\"white\">{pct:.2f}%</TD>\n\t\t\t\t\t")
227 |             fp.write("</TR>")
228 | 
229 |             if rank != last_index:
230 |                 fp.write("\n\n\t\t\t\t")  # Extra spacing *only* between rows
231 | 
232 |         fp.write("\n\t\t\t</TABLE>\n\t\t>];\n")
233 | 
234 |     def write_graph_caption(self, fp):
235 |         now = time.localtime()
236 |         ampm = 'PM' if now.tm_hour >= 12 else 'AM'
237 |         hour = now.tm_hour % 12 or 12
238 |         secs = (self.total) / 1e9
239 |         label = (f"{self.program}\n\t\tRuntime: {secs:.3f} secs\n\t\t"
240 |                  f"{now.tm_mon+1}/{now.tm_mday}/{now.tm_year} @ "
241 |                  f"{hour}:{now.tm_min:02d} {ampm}")
242 | 
243 |         fp.write("\n\tgraph [\n"
244 |                  "\t\tfontname = \"Helvetica-Oblique\",\n"
245 |                  "\t\tfontsize = 32,\n")
246 |         fp.write(f"\t\tlabel=\"{label}\"\n\t];")
247 | 
248 |     def create_dot_file(self):
249 |         with open('graph.dot', 'w') as fp:
250 |             fp.write("digraph program {\n\n\t")
251 | 
252 |             # Write the graph cluster
253 |             fp.write("subgraph cluster0 {\n\t\t"
254 |                      "ratio=fill;\n\t\t"
255 |                      "node [style=filled];\n\t\t"
256 |                      "peripheries=0;\n\n")
257 | 
258 |             self.write_node_shapes(fp)
259 |             self.write_call_graph(fp)
260 |             fp.write("\t}\n\n\t")
261 | 
262 |             # Write the table cluster
263 |             fp.write("subgraph cluster1 {\n\t\t"
264 |                      "peripheries=0;\n\t\t"
265 |                      "node [fontname=\"Helvetica,Arial,sans-serif\" fontsize=22]\n\t\t"
266 |                      "edge [fontname=\"Helvetica,Arial,sans-serif\" fontsize=22]\n\n")
267 |             self.write_table(fp)
268 |             fp.write("\t}\n")
269 | 
270 |             self.write_graph_caption(fp)
271 |             fp.write("\n}\n")
272 | 
273 | # ----------------------------------------------------------------------------
274 | # main: parse trace.bin and drive analysis
275 | # ----------------------------------------------------------------------------
276 | def addr2name(addr, addr2line, program):
277 |     try:
278 |         p = subprocess.Popen([addr2line, '-e', program, '-f', '-s', hex(addr)],
279 |                              stdout=subprocess.PIPE,
280 |                              stderr=subprocess.DEVNULL)
281 |         name = p.stdout.readline().strip().decode()
282 |         return name or hex(addr)
283 |     except Exception:
284 |         return hex(addr)
285 | 
286 | def print_progress_bar(progress, bar_length=50):
287 |     """
288 |     Prints a progress bar to the console.
289 | 
290 |     :param progress: Progress percentage (0–100)
291 |     :param bar_length: Length of the bar in characters
292 |     """
293 |     filled_length = int(bar_length * progress // 100)
294 |     bar = '#' * filled_length + '-' * (bar_length - filled_length)
295 |     sys.stdout.write(f'\r[{bar}] {progress}%')
296 |     sys.stdout.flush()
297 | 
298 |     if progress == 100:
299 |         print()
300 | 
301 | def usage():
302 |     print("Usage: python3 dctrace.py [OPTIONS] <program.elf>")
303 |     print("Requires: A trace.bin, sh-elf-addr2line\n")
304 |     print("OPTIONS:")
305 |     print("  -t <filename>     Set trace file to <filename> (default: trace.bin)")
306 |     print("  -a <filepath>     Set sh-elf-addr2line filepath to <filepath>")
307 |     print("                    (default: /opt/toolchains/dc/sh-elf/bin/sh-elf-addr2line)")
308 |     print("  -p <percentage>   Set percentage threshold. Every function under this threshold")
309 |     print("                    will not show up in the dot file (default: 0; 0–100 range)")
310 |     print("  -ev0=\"<label>\"  Custom label for ev0 (default: ev0)")
311 |     print("  -ev1=\"<label>\"  Custom label for ev1 (default: ev1)")
312 |     print("  --xt <float>      Suggest exclude for functions below this % of runtime")
313 |     print("                         (alias: --ex-time, default: 3.0)")
314 |     print("  --xe <float>      Suggest exclude for functions using less than this % of")
315 |     print("                         ev0 and ev1 (alias: --ex-ev, default: 1.0)")
316 |     print("  -v                Verbose output")
317 |     sys.exit(1)
318 | 
319 | def parse_args():
320 |     p = argparse.ArgumentParser(description="dctrace")
321 |     p.add_argument('-t', '--trace', default=DEFAULT_TRACE)
322 |     p.add_argument('-a', '--addr2line', default=DEFAULT_ADDR2LINE)
323 |     p.add_argument('-p', '--percentage', type=float, default=0)
324 |     p.add_argument('-v', '--verbose', action='store_true')
325 |     p.add_argument('-ev0', '--ev0-label', default='ev0', help='Custom label for ev0 (default: ev0)')
326 |     p.add_argument('-ev1', '--ev1-label', default='ev1', help='Custom label for ev1 (default: ev1)')
327 |     p.add_argument('--xt', '--ex-time', dest='exclude_time_threshold', type=float, default=3.0,
328 |                help='Suggest exclude for functions below this % of runtime (default: 3.0)')
329 |     p.add_argument('--xe', '--ex-ev', dest='exclude_ev_threshold', type=float, default=1.0,
330 |                help='Suggest exclude for functions below this % of ev0/ev1 usage (default: 1.0)')
331 |     p.add_argument('program', help='path to ELF executable')
332 |     return p.parse_args()
333 | 
334 | def suggest_exclude_functions(total_time, total_ev0, total_ev1, percent_threshold, ev_percent_threshold):
335 |     """
336 |     Suggests low-impact functions to exclude from instrumentation.
337 | 
338 |     Criteria for exclusion:
339 |     - Inclusive time < `percent_threshold` (% of total runtime).
340 |     - Inclusive ev0 and ev1 < `ev_percent_threshold` (% of total ev0/ev1 counts).
341 |     - Called at least once (times_called > 0).
342 | 
343 |     This version includes functions with children, as long as the total impact remains small.
344 |     That way, even small utility functions that call other tiny helpers can be excluded.
345 | 
346 |     This helps reduce trace size and overhead on the Dreamcast.
347 |     """
348 |     candidates = []
349 | 
350 |     for addr, fn in functions.items():
351 |         if fn.times_called == 0:
352 |             continue
353 | 
354 |         name = fn.name
355 |         inclusive_time_pct = (fn.total_time / total_time) * 100 if total_time else 0
356 |         ev0_pct = (fn.ev0 / total_ev0) * 100 if total_ev0 else 0
357 |         ev1_pct = (fn.ev1 / total_ev1) * 100 if total_ev1 else 0
358 | 
359 |         if (
360 |             inclusive_time_pct < percent_threshold and
361 |             ev0_pct < ev_percent_threshold and
362 |             ev1_pct < ev_percent_threshold
363 |         ):
364 |             candidates.append((inclusive_time_pct, name))
365 | 
366 |     if not candidates:
367 |         return
368 | 
369 |     candidates.sort()
370 |     exclude_names = [name for _, name in candidates]
371 |     total_pct = sum(p for p, _ in candidates)
372 | 
373 |     print("\n Suggested low-impact functions to exclude from instrumentation:")
374 |     print(f"    (Collectively account for {total_pct:.2f}% of total runtime)\n")
375 |     
376 |     # Multiline Makefile-friendly format
377 |     print("EXCLUDE_FUNCS = \\")
378 |     for name in exclude_names:
379 |         print(f"    {name} \\")
380 | 
381 |     print("CFLAGS += -finstrument-functions-exclude-function-list=$(EXCLUDE_FUNCS)\n")
382 |     print("  NOTE: Be sure your CFLAGS appear *before* kos-cc or kos-c++ in your Makefile command:")
383 |     print("    Example:")
384 |     print("    $(TARGET): $(OBJS)")
385 |     print("        kos-cc $(CFLAGS) -o $(TARGET)\n")
386 | 
387 | def read_uleb128(f):
388 |     result = 0
389 |     shift = 0
390 |     count = 0
391 |     while True:
392 |         byte = f.read(1)
393 |         if not byte:
394 |             raise EOFError("Unexpected EOF while reading ULEB128")
395 |         b = byte[0]
396 |         result |= (b & 0x7F) << shift
397 |         count += 1
398 |         if not (b & 0x80):
399 |             break
400 |         shift += 7
401 |     return result, count
402 | 
403 | def main():
404 |     args = parse_args()
405 | 
406 |     try:
407 |         with open(args.trace, 'rb') as f:
408 |             current_time = 0
409 |             current_e0 = 0
410 |             current_e1 = 0
411 | 
412 |             total_size = os.path.getsize(args.trace)
413 |             read_size = 0
414 | 
415 |             total_size = os.path.getsize(args.trace)
416 |             read_size = 0
417 | 
418 |             while True:
419 |                 header = f.read(4)
420 |                 if not header or len(header) < 4:
421 |                     break
422 | 
423 |                 entry_tid_addr = struct.unpack('<I', header)[0]
424 |                 read_size += 4
425 | 
426 |                 try:
427 |                     delta_time, t_bytes = read_uleb128(f)
428 |                     delta_evt0, e0_bytes = read_uleb128(f)
429 |                     delta_evt1, e1_bytes = read_uleb128(f)
430 |                     read_size += t_bytes + e0_bytes + e1_bytes
431 |                 except EOFError:
432 |                     if args.verbose:
433 |                         print("Incomplete record at end of file; skipping.")
434 |                     break
435 | 
436 |                 progress = int((read_size / total_size) * 100)
437 |                 print_progress_bar(progress)
438 | 
439 |                 is_entry = bool((entry_tid_addr >> 31) & 1)
440 |                 thread_id = (entry_tid_addr >> 22) & TID_MASK
441 |                 compressed_addr = entry_tid_addr & ADDR_MASK
442 |                 address = (compressed_addr << 2) + BASE_ADDRESS
443 | 
444 |                 current_time += delta_time * 80
445 |                 current_e0 += delta_evt0
446 |                 current_e1 += delta_evt1
447 | 
448 |                 if is_entry:
449 |                     # -- ENTRY logic --
450 |                     if address not in functions:
451 |                         func_name = addr2name(address, args.addr2line, args.program)
452 |                         functions[address] = FunctionRecord(func_name)
453 |                     func = functions[address]
454 |                     func.times_called += 1
455 | 
456 |                     # record child call count
457 |                     if call_stack:
458 |                         parent = call_stack[-1].addr
459 |                         cc = child_calls[parent][address]
460 |                         cc.times_called += 1
461 | 
462 |                     # push new frame
463 |                     frame = StackFrame(address, current_time, current_e0, current_e1)
464 |                     call_stack.append(frame)
465 | 
466 |                 else:
467 |                     # -- EXIT logic --
468 |                     if not call_stack:
469 |                         # unmatched exit, skip
470 |                         continue
471 | 
472 |                     frame = call_stack.pop()
473 |                     delta_time = current_time - frame.start_time
474 |                     delta_e0 = current_e0 - frame.start_e0
475 |                     delta_e1 = current_e1 - frame.start_e1
476 | 
477 |                     # update function totals
478 |                     func = functions[frame.addr]
479 |                     func.total_time += delta_time
480 |                     func.ev0 += delta_e0
481 |                     func.ev1 += delta_e1
482 | 
483 |                     # update child call accumulation
484 |                     if call_stack:
485 |                         parent = call_stack[-1]
486 |                         cc = child_calls[parent.addr][frame.addr]
487 |                         cc.total_cycles += delta_time
488 |                         cc.ev0 += delta_e0
489 |                         cc.ev1 += delta_e1
490 | 
491 |             # Final cleanup for any unmatched function entries
492 |             if call_stack:
493 |                 if args.verbose:
494 |                     print(f"Warning: {len(call_stack)} unmatched function entries detected. Processing them as incomplete frames.")
495 | 
496 |                 for i, frame in enumerate(call_stack):
497 |                     delta_time = current_time - frame.start_time
498 |                     delta_e0 = current_e0 - frame.start_e0
499 |                     delta_e1 = current_e1 - frame.start_e1
500 | 
501 |                     func = functions[frame.addr]
502 |                     if args.verbose:
503 |                         print(f"  Function: {func.name} at depth {i}")
504 |                     func.total_time += delta_time
505 |                     func.ev0 += delta_e0
506 |                     func.ev1 += delta_e1
507 | 
508 |                     if i > 0:
509 |                         parent = call_stack[i - 1].addr
510 |                         cc = child_calls[parent][frame.addr]
511 |                         cc.total_cycles += delta_time
512 |                         cc.ev0 += delta_e0
513 |                         cc.ev1 += delta_e1
514 | 
515 |             # Suggest some functions the user can remove from intrumenstation after the first run
516 |             suggest_exclude_functions(current_time, current_e0, current_e1, args.exclude_time_threshold, args.exclude_ev_threshold)
517 | 
518 |             dm = DotManager(args.program, args.addr2line, args.verbose, args.percentage, current_time, args.ev0_label, args.ev1_label)
519 |             dm.create_dot_file()
520 |     except FileNotFoundError:
521 |         print(f"Error: file '{args.infile}' not found.\n\n")
522 |         usage()
523 |     except Exception as e:
524 |         print("An error occurred:")
525 |         traceback.print_exc()   # prints file, line, and stack trace
526 |         print("\n\n")
527 |         usage()
528 | 
529 | if __name__ == '__main__':
530 |     main()
531 | 


--------------------------------------------------------------------------------
/main.c:
--------------------------------------------------------------------------------
 1 | #include <kos.h>
 2 | 
 3 | #include <stdio.h>
 4 | #include <stdlib.h>
 5 | 
 6 | /* I use this program to test small utility functions. I test
 7 | *  different variations of the same function to find which is 
 8 | *  best/fastest.
 9 | */
10 | 
11 | int test0() {
12 |     return 0;
13 | }
14 | 
15 | int test1() {
16 | 	return 1;
17 | }
18 | 
19 | int test2() {
20 | 	return 2;
21 | }
22 | 
23 | int main(int argc, char **argv) {
24 | 
25 |     vid_set_mode(DM_640x480, PM_RGB555);
26 |     vid_clear(255, 0, 255);
27 |     int i;
28 | 
29 |     for(i=0;i<1000;i++) {
30 |         test0();
31 |         test1();
32 |         test2();
33 |     }
34 | 
35 |     return 0;
36 | }


--------------------------------------------------------------------------------
/profiler.c:
--------------------------------------------------------------------------------
  1 | #include <stdio.h>
  2 | #include <stdlib.h>
  3 | 
  4 | #include <kos/thread.h>
  5 | #include <kos/mutex.h>
  6 | #include <arch/timer.h>
  7 | 
  8 | #include <dc/perf_monitor.h>
  9 | 
 10 | /*
 11 |  * Dreamcast Function Profiler – Low-overhead instrumentation for function entry/exit
 12 |  * Works in tandem with GCC’s -finstrument-functions.
 13 |  *
 14 |  * This profiler:
 15 |  *   ✓ Captures timestamps and performance counters (PRFC0 / PRFC1)
 16 |  *   ✓ Computes deltas since the last call per-thread
 17 |  *   ✓ Compresses data using unsigned LEB128 encoding
 18 |  *   ✓ Divides time deltas by 80 (to match 80ns tick resolution)
 19 |  *   ✓ Writes compact variable-length records to /pc/trace.bin via dcload
 20 |  *
 21 |  * Binary Record Format (per function entry or exit):
 22 |  *   uint32_t address
 23 |  *     - Bit 31: 1 for entry, 0 for exit
 24 |  *     - Bits 30–22: thread ID
 25 |  *     - Bits 21–0: compressed function address (>>2 from 0x8C000000)
 26 |  *
 27 |  *   LEB128 encoded values (1–5 bytes each):
 28 |  *     - scaled_time:   delta time / 80ns
 29 |  *     - delta_evt0:    delta of PRFC0 (e.g., operand cache misses)
 30 |  *     - delta_evt1:    delta of PRFC1 (e.g., instruction cache misses)
 31 |  *
 32 |  * Memory & Performance:
 33 |  *   - Each thread maintains its own 8KB TLS buffer, flushed when full
 34 |  *   - All instrumentation functions are marked __no_instrument_function to avoid recursion
 35 |  *   - No dynamic allocations; aligned buffers for safe unaligned writes
 36 |  *
 37 |  * Initialization:
 38 |  *   - File opened at startup via constructor (main_constructor)
 39 |  *   - Counters started and cleared
 40 |  *   - Cleanup handler registered with atexit()
 41 |  *
 42 |  * Cleanup:
 43 |  *   - Flushes remaining buffer contents
 44 |  *   - Stops and clears hardware counters
 45 |  *   - Closes trace file
 46 |  *
 47 |  * Paired with `dctrace.py` to decode, resolve symbols, and generate call graphs.
 48 |  */
 49 | 
 50 | /* Use TLS to keep things separate */ 
 51 | #define thread_local _Thread_local
 52 | 
 53 | #define BUFFER_SIZE    (1024 * 8)
 54 | 
 55 | #define ENTRY_FLAG     0x80000000
 56 | #define EXIT_FLAG      0x00000000
 57 | 
 58 | #define BASE_ADDRESS   0x8C000000
 59 | #define TID_MASK       0x1FF       /* 9 bits */
 60 | #define ADDR_MASK      0x003FFFFF  /* 22 bits (compressed address) */
 61 | 
 62 | #define MAX_ENTRY_SIZE 19
 63 | 
 64 | #define MAKE_ADDRESS(entry, tid, full_addr) \
 65 |      (((entry) ? ENTRY_FLAG : 0) | \
 66 |      (((tid) & TID_MASK) << 22) | \
 67 |      (((((uint32_t)(full_addr)) - BASE_ADDRESS) >> 2) & ADDR_MASK))
 68 | 
 69 | static int fd;
 70 | static FILE *fp;
 71 | static mutex_t io_lock = MUTEX_INITIALIZER;
 72 | 
 73 | /* TLS buffer management */
 74 | static thread_local uint8_t *tls_ptr;
 75 | static thread_local size_t   tls_buffer_idx;
 76 | static thread_local uint8_t  tls_buffer[BUFFER_SIZE] __attribute__((aligned(32)));
 77 | 
 78 | /* TLS stats management */
 79 | static thread_local bool     tls_inited;
 80 | static thread_local uint32_t tls_thread_id;
 81 | static thread_local uint64_t tls_last_time;
 82 | static thread_local uint64_t tls_last_event0;
 83 | static thread_local uint64_t tls_last_event1;
 84 | 
 85 | static inline void  __attribute__ ((no_instrument_function)) write_u32_unaligned(uint8_t *dst, uint32_t value) {
 86 |     dst[0] = (uint8_t)(value & 0xFF);
 87 |     dst[1] = (uint8_t)((value >> 8) & 0xFF);
 88 |     dst[2] = (uint8_t)((value >> 16) & 0xFF);
 89 |     dst[3] = (uint8_t)((value >> 24) & 0xFF);
 90 | }
 91 | 
 92 | static size_t __attribute__ ((no_instrument_function)) encode_uleb128(uint32_t value, uint8_t *out) {
 93 |     /* Fast path: single-byte encoding (value < 128).
 94 |      * Very common for scaled_time and event deltas. */
 95 |     if (value < 0x80) {
 96 |         out[0] = (uint8_t)value;
 97 |         return 1;
 98 |     }
 99 | 
100 |     size_t count = 0;
101 |     do {
102 |         uint8_t byte = value & 0x7F;
103 |         value >>= 7;
104 |         if(value != 0)
105 |             byte |= 0x80;
106 |         out[count++] = byte;
107 |     } while (value != 0);
108 | 
109 |     return count;
110 | }
111 | 
112 | static void __attribute__ ((no_instrument_function)) init_tls(void) {
113 |     kthread_t *th = thd_get_current();
114 |     tls_thread_id = th->tid & TID_MASK; /* Reserve bit 31 for entry/exit */
115 |     tls_buffer_idx = 0;
116 |     tls_ptr = tls_buffer;
117 |     tls_last_time = timer_ns_gettime64();
118 |     tls_last_event0 = perf_cntr_count(PRFC0);
119 |     tls_last_event1 = perf_cntr_count(PRFC1);
120 | 
121 |     tls_inited = true;
122 | }
123 | 
124 | static void __attribute__ ((no_instrument_function, hot)) create_entry(void *this, uint32_t flag) {
125 |     if(__unlikely(!tls_inited))
126 |         init_tls();
127 |     
128 |     uint64_t now = timer_ns_gettime64();
129 |     uint64_t e0  = perf_cntr_count(PRFC0);
130 |     uint64_t e1  = perf_cntr_count(PRFC1);
131 | 
132 |     uint32_t diff_evt0 = (uint32_t)(e0 - tls_last_event0);
133 |     uint32_t diff_evt1 = (uint32_t)(e1 - tls_last_event1);
134 |     uint32_t delta_time = (uint32_t)(now - tls_last_time);
135 | 
136 |     /* Scale delta_time down to 80ns units (the resolution of timer_ns_gettime64()) */
137 |     uint32_t scaled_time = delta_time / 80;
138 | 
139 |     /* Write record byte by byte */
140 |     uint32_t addr = MAKE_ADDRESS(flag, tls_thread_id, this);
141 |     write_u32_unaligned(tls_ptr, addr);
142 |     tls_ptr += 4;
143 |     tls_ptr += encode_uleb128(scaled_time, tls_ptr);
144 |     tls_ptr += encode_uleb128(diff_evt0, tls_ptr);
145 |     tls_ptr += encode_uleb128(diff_evt1, tls_ptr);
146 | 
147 |     /* Advance this thread’s buffer */
148 |     tls_buffer_idx = tls_ptr - tls_buffer;
149 | 
150 |     /* Update for next delta */
151 |     tls_last_time = now;
152 |     tls_last_event0 = e0;
153 |     tls_last_event1 = e1;
154 | 
155 |     /* When this thread’s buffer is full, flush under lock */
156 |     if(__unlikely(tls_buffer_idx >= BUFFER_SIZE - MAX_ENTRY_SIZE)) {
157 |         mutex_lock(&io_lock);
158 |         write(fd, tls_buffer, tls_buffer_idx);
159 |         mutex_unlock(&io_lock);
160 |         tls_ptr = tls_buffer;
161 |         tls_buffer_idx = 0;
162 |     }
163 | }
164 | 
165 | static void __attribute__ ((no_instrument_function)) cleanup(void) {
166 |     if(tls_buffer_idx > 0) {
167 |         mutex_lock(&io_lock);
168 |         write(fd, tls_buffer, tls_buffer_idx);
169 |         mutex_unlock(&io_lock);
170 |     }
171 |     
172 |     perf_cntr_stop(PRFC0);
173 |     perf_cntr_stop(PRFC1);
174 | 
175 |     perf_cntr_clear(PRFC0);
176 |     perf_cntr_clear(PRFC1);
177 | 
178 |     if(fp != NULL) {
179 |         fclose(fp);
180 |         fp = NULL;
181 |     }
182 | }
183 | 
184 | void __attribute__ ((no_instrument_function, hot)) __cyg_profile_func_enter(void *this, void *callsite) {
185 |     (void)callsite;
186 | 
187 |     if(__unlikely(fp == NULL))
188 |         return;
189 | 
190 |     create_entry(this, ENTRY_FLAG);
191 | }
192 | 
193 | void __attribute__ ((no_instrument_function, hot)) __cyg_profile_func_exit(void *this, void *callsite) {
194 |     (void)callsite;
195 | 
196 |     if(__unlikely(fp == NULL))
197 |         return;
198 | 
199 |     create_entry(this, EXIT_FLAG);
200 | }
201 | 
202 | void __attribute__ ((no_instrument_function, constructor)) main_constructor(void) {
203 |     fp = fopen("/pc/trace.bin", "wb");
204 |     if(fp == NULL) {
205 |         fprintf(stderr, "trace.bin file not opened\n");
206 |         return;
207 |     }
208 | 
209 |     fd = fileno(fp);
210 | 
211 |     /* Cleanup at exit */
212 |     atexit(cleanup);
213 | 
214 |     /* Start performance counters */
215 |     perf_cntr_timer_disable();
216 |     perf_cntr_clear(PRFC0);
217 |     perf_cntr_clear(PRFC1);
218 |     perf_cntr_start(PRFC0, PMCR_OPERAND_CACHE_MISS_MODE, PMCR_COUNT_CPU_CYCLES);
219 |     perf_cntr_start(PRFC1, PMCR_INSTRUCTION_CACHE_MISS_MODE, PMCR_COUNT_CPU_CYCLES);
220 | }
221 | 


--------------------------------------------------------------------------------