From 817d20624313a5bd81d50e58881b9f07b37db122 Mon Sep 17 00:00:00 2001
From: Daniel Krebs <github@daniel-krebs.net>
Date: Tue, 13 Feb 2018 17:40:40 +0100
Subject: [PATCH] lib/ip: formatting cleanup and more comments

---
 fpga/include/villas/fpga/ip.hpp | 55 +++++++++++++++++++++------------
 fpga/lib/ip.cpp                 |  2 +-
 2 files changed, 37 insertions(+), 20 deletions(-)

diff --git a/fpga/include/villas/fpga/ip.hpp b/fpga/include/villas/fpga/ip.hpp
index 8c23b38e6..b708ed1e4 100644
--- a/fpga/include/villas/fpga/ip.hpp
+++ b/fpga/include/villas/fpga/ip.hpp
@@ -105,15 +105,40 @@ class IpCore {
 
 public:
 	IpCore() : card(nullptr) {}
-	virtual ~IpCore() {}
+	virtual ~IpCore() = default;
 
-	// IPs can implement this interface
+public:
+	/* Generic management interface for IPs */
+
+	/// Runtime setup of IP, should access and initialize hardware
+	virtual bool init()
+	{ return true; }
+
+	/// Runtime check of IP, should verify basic functionality
 	virtual bool check() { return true; }
-	virtual bool init() { return true; }
+
+	/// Generic disabling of IP, meaning may depend on IP
 	virtual bool stop()  { return true; }
+
+	/// Reset the IP, it should behave like freshly initialized afterwards
 	virtual bool reset() { return true; }
+
+	/// Print some debug information about the IP
 	virtual void dump();
 
+protected:
+	/// Each IP can declare via this function which memory blocks it requires
+	virtual std::list<std::string>
+	getMemoryBlocks() const
+	{ return {}; }
+
+public:
+	const std::string&
+	getInstanceName() const
+	{ return id.getName(); }
+
+	/* Operators */
+
 	bool
 	operator==(const Vlnv& otherVlnv) const
 	{ return id.getVlnv() == otherVlnv; }
@@ -150,10 +175,6 @@ public:
 	operator<< (std::ostream& stream, const IpCore& ip)
 	{ return stream << ip.id; }
 
-	const std::string&
-	getInstanceName() const
-	{ return id.getName(); }
-
 protected:
 	uintptr_t
 	getBaseAddr(const std::string& block) const;
@@ -162,23 +183,19 @@ protected:
 	getLocalAddr(const std::string& block, uintptr_t address) const;
 
 	SpdLogger
-	getLogger() { return loggerGetOrCreate(id.getName()); }
+	getLogger() const
+	{ return loggerGetOrCreate(getInstanceName()); }
 
+	InterruptController*
+	getInterruptController(const std::string& interruptName) const;
+
+protected:
 	struct IrqPort {
 		int num;
 		InterruptController* irqController;
 		std::string description;
 	};
 
-	InterruptController*
-	getInterruptController(const std::string& interruptName);
-
-	/// Each IP can declare via this function which memory blocks it requires
-	virtual std::list<std::string>
-	getMemoryBlocks() const
-	{ return {}; }
-
-protected:
 	/// FPGA card this IP is instantiated on (populated by FpgaIpFactory)
 	PCIeCard* card;
 
@@ -194,7 +211,6 @@ protected:
 
 
 
-
 class IpCoreFactory : public Plugin {
 public:
 	IpCoreFactory(std::string concreteName) :
@@ -207,7 +223,8 @@ public:
 
 protected:
 	SpdLogger
-	getLogger() { return loggerGetOrCreate(getName()); }
+	getLogger() const
+	{ return loggerGetOrCreate(getName()); }
 
 private:
 	/// Create a concrete IP instance
diff --git a/fpga/lib/ip.cpp b/fpga/lib/ip.cpp
index 39e3c4805..7b93320a8 100644
--- a/fpga/lib/ip.cpp
+++ b/fpga/lib/ip.cpp
@@ -346,7 +346,7 @@ IpCore::getLocalAddr(const std::string& block, uintptr_t address) const
 
 
 InterruptController*
-IpCore::getInterruptController(const std::string& interruptName)
+IpCore::getInterruptController(const std::string& interruptName) const
 {
 	try {
 		const IrqPort irq = irqs.at(interruptName);