update: initial library loader

Signed-off-by: Lorenzo Fontana <lo@linux.com>

userspace/libhawk/README.md

@@ -0,0 +1,80 @@
+# Libhawk
+
+Libhawk is a plugin system that can be used to enrich Falco
+functionalities via external, user-defined libraries.
+
+## Glossary:
+
+- library: a bundle (e.g: an ELF shared library) containing one or more plugins
+- plugin: an hawk plugin. Libraries can register one or more plugins using the `HAWK_REGISTER_PLUGIN` macro
+- plugin function: a specific function inside the plugin definition of each plugin. `hawk_init`, `hawk_destroy`
+
+## Plugin definitions and lifecycle
+
+Plugins are all loaded when Falco starts.
+Falco provides a default plugin for the main functionalities.
+
+### hawk_init
+On start, the `hawk_init` function of every plugin is called.
+You can use that function to create any resource you might need
+for your plugin's lifecycle.
+
+### hawk_destroy
+
+When Falco is stopped, the `hawk_destroy` p
+
+### hawk_watch_rules
+
+TODO: explain that only one at time can be done and how to configure. This can be
+explained once we have the plugin configuration code done.
+
+<a name="plugin-loading"></a>
+## Plugin loading
+
+TODO, describe how to dynamically load a plugin.
+This can be explained once this feature is developed.
+
+## Plugin configuration
+
+TODO
+This can be explained once this feature is developed.
+
+## Plugin example
+
+A plugin can define one or more definitions.
+
+Here's an example of plugin that is registered and defines
+`hawk_init`, `hawk_destroy` and `hawk_watch_rules`
+
+```c
+#include "hawk.h"
+
+void hawk_init() { printf("hawk_example init!\n"); }
+
+void hawk_destroy() {printf("hawk example destroy\n");}
+
+void hawk_watch_rules(hawk_watch_rules_cb cb, hawk_engine *engine) {
+  printf("loading rules\n");
+  cb("", engine); // todo: pass the rules here, this is empty
+}
+
+hawk_plugin_definition plugin_definition = {
+    .hawk_init = &hawk_init,
+    .hawk_destroy = &hawk_destroy,
+    .hawk_watch_rules = &hawk_watch_rules,
+};
+
+HAWK_REGISTER_PLUGIN(hawk_example_c, plugin_definition)
+```
+
+To compile the plugin, save it in a file `plugin.c` and then:
+
+```bash
+FALCO=/source/falco
+gcc -o libhawk.so -fPIC -shared -I$FALCO/userspace/libhawk plugin.c
+```
+
+Remember to change the `FALCO` variable to point to where you have the Falco sources.
+
+This should produce shared object called `libhawk.so`, you can use that to load the plugin in Falco.
+See the [Plugin loading](#plugin-loading) section.

userspace/libhawk/exception.h

@@ -14,10 +14,24 @@ public:
 		std::runtime_error(message) {}
 };
 
-class hawk_plugin_exception: public hawk_exception
+class hawk_plugin_exception : public hawk_exception
 {
 public:
 	hawk_plugin_exception(const std::string& plugin_name, const std::string& message):
 		hawk_exception("plugin: " + plugin_name + ", error: " + message) {}
 };
+
+class hawk_library_exception : public hawk_exception
+{
+public:
+	hawk_library_exception(const std::string& message):
+		hawk_exception(message) {}
+};
+
+class hawk_library_load_exception : public hawk_library_exception
+{
+	public:
+		hawk_library_load_exception(const std::string&library_name, const std::string&message):
+			hawk_library_exception("library loading error, library: " + library_name + " error: " + message) {}
+};
 } // namespace libhawk

userspace/libhawk/hawk.h

@@ -1,6 +1,7 @@
 #ifndef HAWK_H
 #define HAWK_H
 
+// TODO(fntlnz): decide what to do with versioning here
 #define HAWK_VERSION_CODE 0x000001
 #define HAWK_VERSION_BITS(x, y, z) ((x) << 16 | (y) << 8 | (z))
 #define HAWK_AT_LEAST_VERSION(x, y, z) \

userspace/libhawk/library.cpp

@@ -0,0 +1,34 @@
+/*
+Copyright (C) 2020 The Falco Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+#include "library.h"
+#include "exception.h"
+
+#include <dlfcn.h>
+
+libhawk::library::library(const std::string &filename) : m_library_filename(filename) {};
+
+bool libhawk::library::load()
+{
+	void *handler = nullptr;
+	handler = dlopen(m_library_filename.c_str(), RTLD_NOW);
+	if (!handler) {
+		std::string errmsg(dlerror());
+		throw hawk_library_load_exception(m_library_filename, errmsg);
+	}
+	//todo(fntlnz): need to store the handler or anything to use the library?
+	return (handler != nullptr);
+}

userspace/libhawk/library.h

@@ -0,0 +1,31 @@
+/*
+Copyright (C) 2020 The Falco Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+#pragma once
+
+#include <string>
+namespace libhawk
+{
+class library
+{
+public:
+	library(const std::string &filename);
+	bool load();
+	~library();
+private:
+	std::string m_library_filename;
+};
+}; // namespace libhawk