API in readme, simplify required includes

README.md

@@ -17,11 +17,119 @@ CPU/GPU performance control library for benchmarking
 - [x] Disable GPU turbo (nvidia)
 - [x] Flush addresses from cache (amd64, POWER)
 
-## API
+## Installing
+
+### CMake 
+
+Ensure you have CMake 3.13+.
+
+Add the source tree to your project and then use add_subdirectory
+
+```
+git submodule add git@github.com:cwpearson/perfect.git thirdparty/perfect
+```
+
+`CMakeLists.txt`
+```
+...
+add_subdirectory(thirdparty/perfect)
+...
+target_link_libraries(your-target perfect)
+```
+
+### Without CMake 
+Download the source and add the include directory to your includes and `nvidia-ml` to your link flags
+
+```
+g++ code_using_perfect.cpp -I perfect/include -l nvidia-ml
+nvcc code_using_perfect.cu -I perfect/include
+```
+
+## Usage
+
+The `perfect` functions all return a `perfect::Result`, which is defined in [include/perfect/result.hpp].
+When things are working, it will be `perfect::Result::SUCCESS`.
+A `PERFECT` macro is also defined, which will terminate with an error message unless the `perfect::Result` is `perfect::Result::SUCCESS`.
+
+```c++
+perfect::CpuTurboState state;
+PERFECT(perfect::get_cpu_turbo_state(&state));
+```
+
+### CPU Turbo
+
+`perfect` can enable and disable CPU boost through the Intel p-state mechanism or the ACPI cpufreq mechanism.
+
+See [examples/cpu_turbo.cpp].
 
 
+```c++
+#include "perfect/cpu_turbo.hpp"
+```
+
+* `Result get_cpu_turbo_state(CpuTurboState *state)`
+* `Result set_cpu_turbo_state(CpuTurboState *state)`
+* `Result disable_cpu_turbo()`
+* `Result enable_cpu_turbo()`
+* `bool is_turbo_enabled(CpuTurboState state)`
+
+### OS Performance
+
+`perfect` can control the OS governor on linux.
+
+See [examples/os_perf.cpp].
+
+```c++
+#include "perfect/os_perf.hpp"
+```
+
+* `Result get_os_perf_state(OsPerfState *state, const int cpu)`: Save the current OS governor mode for CPU `cpu`.
+* `Result os_perf_state_maximum(const int cpu)`: Set the OS governor to it's maximum performance mode.
+* `Result set_os_perf_state(const int cpu, OsPerfState state)`: Restore a previously-saved OS governor mode.
+
+### GPU Turbo
+
+`perfect` can enable/disable GPU turbo boost.
+
+See [examples/gpu_turbo.cu]
+
+```c++
+#include "perfect/gpu_turbo.hpp"
+```
+
+* `Result get_gpu_turbo_state(GpuTurboState *state, unsigned int idx)`: Get the current turbo state for GPU `idx`, useful to restore later.
+* `bool is_turbo_enabled(GpuTurboState state)`: Check if turbo is enabled.
+* `Result set_gpu_turbo_state(GpuTurboState state, unsigned int idx)`: Set a previously saved turbo state.
+* `Result disable_gpu_turbo(unsigned int idx)`: Disable GPU `idx` turbo.
+* `Result enable_gpu_turbo(unsigned int idx)`: Enable GPU `idx` turbo.
+
+### GPU Clocks
+
+`perfect` can lock GPU clocks to their maximum values.
+
+See [examples/gpu_clocks.cu]
+
+```c++
+#include "perfect/gpu_clocks.hpp`
+```
+
+* `Result set_max_gpu_clocks(unsigned int idx)`: Set GPU `idx` clocks to their maximum reported values.
+* `Result reset_gpu_clocks(unsigned int idx)`: Unset GPU `idx` clocks.
+
+### CPU Cache
+
+`perfect` can flush data from CPU caches. Unlike the other APIs, these do not return a `Result` because they do not fail.
+
+See [examples/cpu_cache.cpp].
+
+```c++
+#include "perfect/cpu_cache.hpp`
+```
+
+* `void flush_all(void *p, const size_t n)`: Flush all cache lines starting at `p` for `n` bytes.
 
 ## Wish List
 
+- [ ] Make CUDA Optional
 - [ ] Nvidia GPU power monitoring
 - [ ] Nivida GPU utilization monitoring