Add links and code examples

en/firmware/epicardium_api_development.md

@@ -13,20 +13,47 @@ The API call signatures are the same on both cores.
 
 ## API definition
 
-The API calls are declared in `epicardium/epicardium.h` and documented with sphinx doccomments.
+The API calls are declared in [`epicardium/epicardium.h`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/epicardium.h) and documented with sphinx doccomments.
 (For building the API documentation, python-sphinx and optionally python-sphinx-hawkmoth are required.)
 
+Adding an example call to the API would look like this:
+```c
+/**
+ * Example API call.
+ *
+ * :param example_param_a:  An exemplary parameter.
+ * :param example_param_b:  Another exemplary parameter.
+ */
+API(API_EXAMPLE_CALL, void epic_example_call(int example_param_a, uint8_t example_param_b));
+```
+
+Choose the `API_EXAMPLE_CALL` as you see fit, it just needs to be unique.
+
 
 ## API implementation
 
-The API calls are implemented in `epicardium/modules/*.c`.
+The API calls are implemented in [`epicardium/modules/*.c`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/modules).
+
+The `*.c`-files need to be added to [`epicardium/modules/meson.build`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/modules/meson.build) and assigned unique API IDs.
+
+An exemplary implementation to the declaration above could look like the following:
+```c
+#include "example.h"
+
+void epic_example_call(int example_param_a, uint8_t example_param_b)
+{
+	while (1) {
+		printf ("I'm just an example!\n");
+	}
+}
+```
 
-The `*.c`-files need to be added to `epicardium/modules/meson.build` and assigned unique API IDs.
+The `example.h` would go into [`lib/card10`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/lib/card10).
 
 
 ## Best Practices
 
- - Only types from stdlib and `epicardium/epicardium.h` are used. We do not want other `#includes`.
+ - In [`epicardium/epicardium.h`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/epicardium.h) only types from stdlib and [`epicardium/epicardium.h`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/epicardium.h) are used. We do not want other `#includes` there.
  - Passing pointers into the address space of (py)cardium is fine. Do not pass pointers into the address space of epicardium to (py)cardium.
  - The API functions follow the kernel convention of either returning a boolean if the function is a predicate or returning a success integer (with negative values denoting errors) if it is an action or imperative command. (See also https://www.kernel.org/doc/html/v4.10/process/coding-style.html#function-return-values-and-names.)
  - Pay attention while implementing an API call that it might be called from within different FreeRTOS tasks. (Calls made from (py)cardium are executed by the dispatcher task on the epicardium.) Don't make assumptions which task you're in. Especially if using a task semaphore.
@@ -35,7 +62,7 @@ The `*.c`-files need to be added to `epicardium/modules/meson.build` and assigne
 
 ## Internals
 
-Note: This describes the current state of the API. There exist plans for improvement (issue #9) but they have no high priority.
+Note: This describes the current state of the API. There exist plans for improvement ([issue #9](https://git.card10.badge.events.ccc.de/card10/firmware/issues/9)) but they have no high priority.
 
 When an API call is called, its arguments and the unique ID of the call are written into a shared memory region. Then the epicardium is woken up so the dispatcher can read and execute the call.
 
@@ -43,4 +70,4 @@ When the call returned, the result is written into the place the arguments have
 
 This data structure is subject to change as it only allows synchronous calls. To allow asynchronous calls, some sort of queue/list/... is required.
 
-The code for serialisation and de-serialisation is generated from `epicardium/epicardium.h`.
+The code for serialisation and de-serialisation is generated from [`epicardium/epicardium.h`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/modules/meson.build).