Fix pointers of the docs in the README

Author: harendra-kumar

README.md

@@ -51,7 +51,7 @@ With these tools you can find:
 
 For more details on each of the performance analysis methods see the following
 documents:
-* GHC RTS Stats
-* threadCPUTime# RTS primitive
-* GHC Event logging
-* GHC patches details
+* [GHC RTS Stats](docs/ghc-rts-performance-analysis.md)
+* [threadCPUTime# RTS primitive](docs/thread-cputime-primop.md)
+* [GHC Event logging](docs/eventlog-performance-analysis.md)
+* [GHC patches details](dev/ghc-work.md)

docs/eventlog-performance-analysis.md

@@ -1,6 +1,22 @@
-# haskell-perf
+# GHC Event logging
 
+Available in GHC 9.2.8 RTS patch. Can be ported to later GHCs.
+
+<!--
 GHC Patch: https://github.com/composewell/ghc/tree/ghc-8.10.7-eventlog-enhancements
+-->
+
+Eventlog based Haskell thread aware time and allocation analysis is
+possible with stock GHC but there are some limitations and drawbacks
+which are fixed in the RTS patch described below. The patch adds
+accurate timing and allocation information and hardware performance
+counters, and we then use a custom event log analysis program to provide
+an accurate and comprehensive analysis of all the threads in the entire
+program not just the current thread.
+
+<!--
+TBD: document the exact limitations and differences.
+-->
 
 ## Enable Linux perf counters
 

docs/ghc-rts-performance-analysis.md

@@ -1,3 +1,27 @@
+<!--
+# GHC RTS Stats
+
+RTS Stats give entire OS process level (not OS thread level) cpu time
+and not Haskell thread cpu time. When multiple OS threads are used, the
+cpu time recorded is the cpu time of all the threads combined. Also, the
+way kernel accounts this time it could be off by a little (microseconds)
+because each thread's cpu time is recorded at the last accounting
+event. Allocations are recorded by the GHC RTS only at the GC boundary,
+so the allocations reported are from the point when the last GC
+happened. So we need to be careful when using or interpreting these
+stats.
+
+If we built the program without -threaded and we are using a single
+Haskell thread then we can get cpu time between any two points in the
+program accurately. Accurate accounting of allocations will require a GC
+to be forced which is not usually practical.
+
+In a multithreaded program using RTS stats we can only tell time how
+much total CPU time (and allocations) the entire Haskell process (all
+threads) spent between two points, but we cannot tell which Haskell
+thread spent how much time.
+-->
+
 # Components of a Haskell Process
 
 * An OS level process

docs/performance-analysis-methods.md docs/thread-cputime-primop.mddocs/performance-analysis-methods.md renamed to docs/thread-cputime-primop.md

@@ -1,39 +1,4 @@
-# Haskell Performance Analysis
-
-## GHC RTS Stats
-
-RTS Stats give entire OS process level (not OS thread level) cpu time
-and not Haskell thread cpu time. When multiple OS threads are used, the
-cpu time recorded is the cpu time of all the threads combined. Also, the
-way kernel accounts this time it could be off by a little (microseconds)
-because each thread's cpu time is recorded at the last accounting
-event. Allocations are recorded by the GHC RTS only at the GC boundary,
-so the allocations reported are from the point when the last GC
-happened. So we need to be careful when using or interpreting these
-stats.
-
-If we built the program without -threaded and we are using a single
-Haskell thread then we can get cpu time between any two points in the
-program accurately. Accurate accounting of allocations will require a GC
-to be forced which is not usually practical.
-
-In a multithreaded program using RTS stats we can only tell time how
-much total CPU time (and allocations) the entire Haskell process (all
-threads) spent between two points, but we cannot tell which Haskell
-thread spent how much time.
-
-## GHC Event logging
-
-Eventlog based Haskell thread aware time and allocation analysis is
-possible with stock GHC but there are some limitations and drawbacks
-which are fixed in the RTS patch described below. The patch basically
-adds accurate information and more information, and we then use a custom
-event log analysis program to provide an accurate and comprehensive
-picture of the entire program.
-
-TBD: document the exact limitations and differences.
-
-## threadCPUTime# prim op
+# threadCPUTime# prim op
 
 Available in the
 [GHC 9.2.8 RTS patch](https://github.com/composewell/ghc/releases/tag/ghc-9.2.8-perf-counters-1-rc1).
@@ -56,7 +21,7 @@ and B in a program, diff will tell us the time spent and allocations
 between the two points.
 
 We have to ensure that we are diffing the data for the same thread id at
-both the points. See [this example program](./threadCPUTime.hs).
+both the points. See [this example program](../examples/threadCPUTime.hs).
 
 The API has some measurement overhead but it is not very high.  If we
 are nesting measurements be aware that outer measurement will measure
@@ -82,13 +47,3 @@ though. For accurate synchronization (if needed) of all threads at the
 given points we can stop-the-world, can be useful in testing but not a
 good idea in production though. Also, managing windows with possible
 nesting can complicate the RTS code.
-
-## Eventlog based perf counters
-
-Available in GHC 8.10.7 RTS patch. Can be ported to later GHCs.
-
-This gives you a more comprehensive picture of the entire program
-between any two specified points, it gives a detailed report about all
-the threads in the system not just the current thread.
-
-See the [README](../README.md) for more details on this.