From 41a7eccad30dd7609751bff3ebc061d3db4516c2 Mon Sep 17 00:00:00 2001
From: Patrick Lipka <patrick.lipka@codasip.com>
Date: Mon, 18 Aug 2025 18:03:01 +0200
Subject: [PATCH] Add README

---
 README.md | 280 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 279 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 30dbb3d..593f667 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,281 @@
 # rvprof
 
-riscv profling tool, inspired by vftrace
\ No newline at end of file
+A lightweight profiling library for RISC-V applications, inspired by [vftrace](https://github.com/SX-Aurora/Vftrace). rvprof provides function-level timing analysis with minimal overhead and automatic instrumentation support.
+
+## Features
+
+- **Automatic Function Profiling**: Uses cycgnus function hooks inserted via `-finstrument-functions` for zero-code-change profiling
+- **Manual Region Profiling**: Explicit profiling regions for fine-grained control
+- **Symbol Resolution**: ELF parsing for human-readable function names
+- **Timing Precision**: Nanosecond-resolution timing with optional cycle counter support
+- **Memory Tracking**: Built-in profiler overhead monitoring
+- **Stack Analysis**: Complete call stack tracking and analysis
+- **Multi-language Support**: Native C/C++ and Fortran APIs
+- **Configurable Output**: Environment variable control and customizable reports
+
+## Quick Start
+
+### 1. Build the Library
+
+```bash
+make
+```
+
+This creates `librvprof.a` static library.
+
+### 2. Automatic Profiling (Recommended)
+
+Compile your program with function instrumentation:
+
+```bash
+# C/C++
+gcc -finstrument-functions your_program.c -L. -lrvprof -o your_program
+
+# Fortran
+gfortran -finstrument-functions your_program.f90 -L. -lrvprof -o your_program
+```
+
+Run your program normally - profiling happens automatically:
+
+```bash
+./your_program
+# Creates: your_program_rvprof.log
+```
+
+### 3. Manual Profiling
+
+For (additional) manual control over profiling regions:
+
+**C/C++:**
+```c
+#include "rvprof.h"
+
+int main() {
+    rvprof_region_begin("initialization");
+    // your initialization code
+    rvprof_region_end("initialization");
+    
+    rvprof_region_begin("computation");
+    // your computation code
+    rvprof_region_end("computation");
+    
+    return 0;
+}
+```
+
+**Fortran:**
+```fortran
+program example
+    use rvprof
+    implicit none
+    
+    call rvprof_region_begin("initialization")
+    ! your initialization code
+    call rvprof_region_end("initialization")
+    
+    call rvprof_region_begin("computation")
+    ! your computation code
+    call rvprof_region_end("computation")
+    
+end program example
+```
+
+If the code is compiled using `-finstrument-functions`, the user-defined regions will show up in addition to the automatic ones.
+
+## Configuration
+
+Control rvprof behavior with environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RVPROF_OUTPUT` | `<program>_rvprof.log` | Output filename |
+| `RVPROF_DISABLE_HOOKS` | `0` | Set to `1` to disable automatic function hooks |
+| `RVPROF_DISABLE_MERGE` | `0` | Set to `1` to keep separate entries for same function from different callers |
+
+### Examples
+
+```bash
+# Custom output file
+RVPROF_OUTPUT=my_profile.txt ./your_program
+
+# Disable automatic profiling, use manual regions only
+RVPROF_DISABLE_HOOKS=1 ./your_program
+
+# Keep separate entries for functions called from different contexts
+RVPROF_DISABLE_MERGE=1 ./your_program
+```
+
+## Understanding the Output
+
+rvprof generates a detailed text report with multiple sections:
+
+### Function Profile Table
+
+```
++-------+-----------+-----------+-----------+-----------+---------------+---------------+---------------------------------------------+---------------------------------------------+------+
+| Calls | t_excl[s] | t_excl[%] | t_incl[s] | t_incl[%] | excl_cycles   | incl_cycles   |                  Function                   |                   Caller                    | STID |
++-------+-----------+-----------+-----------+-----------+---------------+---------------+---------------------------------------------+---------------------------------------------+------+
+|     1 |     2.450 |      89.2 |     2.750 |     100.0 | 2450000000    | 2750000000    | main                                        | ---                                         |    1 |
+|   100 |     0.250 |       9.1 |     0.300 |      10.9 | 250000000     | 300000000     | compute_heavy                               | main                                        |    2 |
++-------+-----------+-----------+-----------+-----------+---------------+---------------+---------------------------------------------+---------------------------------------------+------+
+```
+
+**Columns explained:**
+- **Calls**: Number of times function was called
+- **t_excl[s]**: Exclusive time (time spent in function itself, excluding children)
+- **t_excl[%]**: Exclusive time as percentage of total program runtime
+- **t_incl[s]**: Inclusive time (time spent in function including all children)
+- **t_incl[%]**: Inclusive time as percentage of total program runtime
+- **excl_cycles/incl_cycles**: Cycle counts (if RISC-V cycle counter available)
+- **Function**: Function name (resolved from symbols or address)
+- **Caller**: Calling function (or "various" if called from multiple places)
+- **STID**: Stack ID referencing the call stack table
+
+### Call Stack Analysis
+
+```
+Global call stacks:
+--------------------------------------------------------------------
+   STID   Call stack                                                
+--------------------------------------------------------------------
+  STID1    main
+  STID2    main<compute_heavy
+  STID3    main<compute_heavy<helper_function
+--------------------------------------------------------------------
+```
+
+Shows the complete call paths for each stack ID, with `<` separating stack levels.
+
+### Performance Summary
+
+```
+Summary:
+  Total execution time: 2.750 seconds
+  Total cycles:         2750000000 cycles (informational)
+  Timer resolution:     nanosecond timer
+  Number of functions:  15
+  Number of stacks:     8
+  Function hooks:       enabled
+  Symbol table:         142 symbols loaded (ELF parsing)
+  Region merging:       enabled
+  Memory footprint:     45.2 KB
+```
+
+## API Reference
+
+### C/C++ API
+
+```c
+// Manual region profiling
+void rvprof_region_begin(const char* name);
+void rvprof_region_end(const char* name);
+
+// Automatic hooks (called by -finstrument-functions)
+void __cyg_profile_func_enter(void *this_fn, void *call_site);
+void __cyg_profile_func_exit(void *this_fn, void *call_site);
+```
+
+### Fortran API
+
+```fortran
+! Manual region profiling
+subroutine rvprof_region_begin(name)
+subroutine rvprof_region_end(name)
+```
+
+
+### Performance Considerations
+
+- **Overhead**: rvprof is designed for minimal overhead (~1-5% typical) but this can still get significant for a huge number of calls. Consider adding `__attribute__((no_instrument_function))` to functions that should not be profiled.
+- **Memory**: Scales with number of unique functions and call stacks
+- **Accuracy**: Nanosecond timing resolution; cycle counter when available
+
+### Symbol Resolution
+
+rvprof automatically attempts to resolve function addresses to names by:
+1. Parsing the ELF symbol table from `/proc/self/exe`
+2. Handling Position-Independent Executables (PIE)
+3. Falling back to address display if symbols unavailable
+
+## Troubleshooting
+
+### Common Issues
+
+**"No symbols loaded"**
+- Compile with debug symbols: add `-g` flag
+- Ensure executable has symbol table: `objdump -t your_program`
+
+**"Cycle counter unavailable"**
+- Normal on some RISC-V implementations
+- Timing still works with nanosecond precision
+
+**Missing function names**
+- Some optimized builds strip symbols
+- Functions may be inlined by compiler
+
+### Debugging
+
+Enable verbose output:
+```bash
+# rvprof prints initialization messages to stderr
+./your_program 2>debug.log
+```
+
+## Building from Source
+
+### Requirements
+- RISC-V GCC toolchain (clang/gcc)
+- RISC-V Fortran compiler (flang/gfortran) for Fortran support
+- Make
+
+### Build Options
+```bash
+# Default build
+make
+
+# Clean build
+make clean
+
+# Debug build
+make CFLAGS="-g -O0 -DDEBUG"
+```
+
+## Integration Examples
+
+### CMake Integration
+
+```cmake
+# In your CMakeLists.txt
+add_library(rvprof STATIC IMPORTED)
+set_target_properties(rvprof PROPERTIES IMPORTED_LOCATION /path/to/librvprof.a)
+
+target_link_libraries(your_target rvprof)
+target_compile_options(your_target PRIVATE -finstrument-functions)
+```
+
+### Makefile Integration
+
+```makefile
+RVPROF_DIR = /path/to/rvprof
+CFLAGS += -finstrument-functions -I$(RVPROF_DIR)
+LDFLAGS += -L$(RVPROF_DIR) -lrvprof
+
+your_program: your_program.o
+	$(CC) $< $(LDFLAGS) -o $@
+```
+
+## License
+
+This software is provided under the MIT license. See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+rvprof is designed for RISC-V systems but the core profiling logic is portable. Contributions welcome for:
+- Additional architecture support
+- Output format improvements
+- Performance optimizations
+- Additional analysis features
+
+## Acknowledgments
+
+Inspired by [vftrace](https://github.com/SX-Aurora/Vftrace) from the SX-Aurora project.
\ No newline at end of file