From dac5d20ee8115d2a2c4b8266dc86a3b3153f7aa2 Mon Sep 17 00:00:00 2001 From: Alberto Cabrera Date: Mon, 17 Sep 2018 09:04:43 +0100 Subject: [PATCH] Documentation updated, doxygen file headers added. Updated documentation to match the library version --- INSTALL | 23 ++++++++------ README.md | 26 +++++++-------- doc/configuration.md | 76 ++++++++++++++++++++++++++++++++++++++++++-- src/driver-dummy.c | 6 +++- src/driver-labee.c | 6 ++-- src/driver-odroid.c | 6 +++- 6 files changed, 115 insertions(+), 28 deletions(-) diff --git a/INSTALL b/INSTALL index 6208678..a83c488 100644 --- a/INSTALL +++ b/INSTALL @@ -23,19 +23,24 @@ You can now proceed as with a source package: Build configuration ------------------- -By default, the library will be built with support for all devices. If necessary +By default, the library will be built with support for all devices, +except for those accessed through a network connection. If necessary header files for a specific device type are not found on the build machine, support will be automatically disabled for that type. -It is also possible to manually disable support for a specific device through +It is also possible to manually enable/disable support for a specific device through `configure` flags: - --without-mic Disable Intel Many Integrated Core support (default: - enabled if present) + --with-dummy Enable Dummy testing support (default: disabled) + --without-mic Disable Intel Many Integrated Core support + (default: enabled if miclib.h is available) --without-rapl Disable Intel Running Average Power Limit support - (default: enabled) - --without-nvml Disable NVIDIA Management Library support (default: - enabled if present) - -Check the output of `configure --help` for a full list of configuration + (default: enabled) + --without-nvml Disable NVIDIA Management Library support + (default: enabled if nvml.h is available) + --with-sb-pdu Enable Schleifenbauer PDU support (default: disabled) + --without-odroid Disable Odroid support (default: enabled) + --with-labee Enable Labee support (default: disabled) + +Check the output of `./configure --help` for a full list of configuration parameters. diff --git a/README.md b/README.md index ec82c05..2dea189 100644 --- a/README.md +++ b/README.md @@ -7,25 +7,25 @@ kinds of hardware. The following devices are currently supported: - * Dummy devices for testing purposes + * Dummy devices for testing purposes - * Intel CPUs starting from Sandy Bridge - (through the Running Average Power Limit interface) + * Intel CPUs starting from Sandy Bridge + (through the Running Average Power Limit interface) - * Recent Nvidia Tesla and Quadro GPUs - (through NVIDIA Management Library) + * Recent Nvidia Tesla and Quadro GPUs + (through NVIDIA Management Library) - * Intel Xeon Phi MICs - (through the Intel Manycore Platform Software Stack (3.x+), from the host device) + * Intel Xeon Phi MICs + (through the Intel Manycore Platform Software Stack (3.x+), from the host device) - * Schleifenbauer PDUs - (through the Schleifenbauer socket API) + * Schleifenbauer PDUs + (through the Schleifenbauer socket API) - * Odroid-XU3 integrated sensors - (through linux sysfs) + * Odroid-XU3 integrated sensors + (through linux sysfs) - * Poznań Supercomputing and Networking Center Labee XML Interface - (through its REST API) + * Poznań Supercomputing and Networking Center Labee XML Interface + (through its REST API) EML automatically discovers necessary libraries and available devices at runtime. diff --git a/doc/configuration.md b/doc/configuration.md index ab2eda6..9bfc8cf 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -39,10 +39,82 @@ nvml { rapl { disabled = true } -~~~ -For available values, please check the driver code for now. +# Nested configurations are configured as follows +sb-pdu { + +} +~~~ Default values will be used for any missing entries, except for values made necessary for existing entries (such as the hostname field for a network device that is declared by the configuration). In particular, loading an empty config file has no effect. + +Available Configuration Values +------------------------------ +The driver configuration section is the .name value defined in its specified driver struct. + +- Common Values + - **disabled**. Determines wether to use the module or not.
+ Values: true, false.
+ Default: false, except for the dummy module. + - **sampling_interval**. Determines the sampling interval for the driver. Check each module for its default value. + Values: numerical value of nanoseconds. 100000000 = 100ms, 100000 = 100μs + +- dummy (Dummy testing driver) + - **disabled**. This module is disabled by default.
+ Default: true + - **sampling_interval**.
+ Default: 100000000, i.e. 100ms. + +- rapl (Intel RAPL) + - **sampling_interval**.
+ Default: 1000000, i.e. ~1ms. + +- nvml (Nvidia Management Library) + - **sampling_interval**.
+ Default: 16000000, i.e. ~16ms. Adjusted for Fermi power readings. + +- mic (Intel MIC) + - **sampling_interval**.
+ Default: 50000000, i.e. ~50ms. + +- sb-pdu (Schleifenbauer PDUs) + - **sampling_interval**.
+ Default: 1000000000, i.e. ~1s. + - **device**. SBPDU device specification. + - **host**. Host IPv4.
+ Default: 192.168.1.200 + - **port**.
+ Default: 7783 + - **rc4key**. RC4 encryption key.
+ Default: 000000000000 + +- odroid (Odroid-XU3) + - **sampling_interval**.
+ Default: 263808000, i.e. ~263808μs as defined by /sys/bus/i2c/drivers/INA231/*/update_period. + +- labee (Poznań Supercomputing and Networking Center Labee XML Interface). Currently only one device per node is supported. + - **sampling_interval**.
+ Default: 150000000, i.e. ~150ms. + - **hostname**. Name of the host to measure.
+ Default: "" + - **nodelist_file**. Path to the file with the hardware labels mapped to hostnames as comma separated values.
+ Example file:
+~~~ +hw-id1,hostname1 +hw-id2,hostname2 +hw-id3,hostname3 +hw-id4,hostname4 +~~~ + Default: ./nodelist + - **api_url**. Rest API full url.
+ Default: http://10.11.12.242/REST/node + - **user**. API username.
+ Default: user + - **password**. API password.
+ Default: password + - **power_attribute**. Key in the XML response that contains the measurement we want to query.
+ Default: actualPowerUsage + + diff --git a/src/driver-dummy.c b/src/driver-dummy.c index 4c24395..95797bb 100644 --- a/src/driver-dummy.c +++ b/src/driver-dummy.c @@ -1,10 +1,14 @@ -/* +/*! * Copyright (c) 2017 Universidad de La Laguna * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the Free * Software Foundation; either version 2 of the License, or (at your option) * any later version. + * + * \author Alberto Cabrera Perez + * \date jun-2018 + * \brief Driver implementation for the dummy module */ //feature test macro for pread() in unistd.h diff --git a/src/driver-labee.c b/src/driver-labee.c index 5c29ae5..20476ae 100644 --- a/src/driver-labee.c +++ b/src/driver-labee.c @@ -1,4 +1,4 @@ -/* +/*! * Copyright (c) 2018 Universidad de La Laguna * * This program is free software; you can redistribute it and/or modify it @@ -6,7 +6,9 @@ * Software Foundation; either version 2 of the License, or (at your option) * any later version. * - * @author: Alberto Cabrera Perez + * \author Alberto Cabrera Perez + * \date jun-2018 + * \brief Driver implementation for the Labee module using curl and xml */ #define _XOPEN_SOURCE 500 diff --git a/src/driver-odroid.c b/src/driver-odroid.c index 6501ddc..ceb041e 100644 --- a/src/driver-odroid.c +++ b/src/driver-odroid.c @@ -1,10 +1,14 @@ -/* +/*! * Copyright (c) 2017 Universidad de La Laguna * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the Free * Software Foundation; either version 2 of the License, or (at your option) * any later version. + * + * \author Alberto Cabrera + * \date jun-2017 + * \brief Driver implementation for the odroid module using sysfs */ //feature test macro for pread() in unistd.h