Commit 5630a992 authored by schneider's avatar schneider
Browse files

Update epicardium_api_development.md

parent a3ff5ca3
Pipeline #1265 passed with stages
in 50 seconds
......@@ -2,92 +2,5 @@
title: Epicardium API Development
---
## Overview
The Epicardium API allows user code running on core 1 (running the pycardium)
to access functionality running on the epicardium (core 0). In other words: It
allows you to call C code running on the Epicardium from a Python module. You
can also call the API call from inside Epicardium as well and doing so is
encouraged. Calling an API call is as easy as just calling the function like
it is defined in [`epicardium.h`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/epicardium.h).
Our build-script take care of abstracting the core-boundary away.
## API definition
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 doc-comments. API calls should have names prefixed
with `epic_`. (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, int epic_do_example(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`](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).
An exemplary implementation to the declaration above could look like the following:
```c
#include <stdio.h>
#include "epicardium.h"
int epic_example_call(int example_param_a, uint8_t example_param_b)
{
printf("I'm just an example: %d %d\n", example_param_a, example_param_b);
return 0;
}
```
## Best Practices
- In [`epicardium/epicardium.h`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/epicardium.h)
only types from stdlib should be included. Any other types you need
(especially structs) should be defined (and documented!) in `epicardium.h`
directly. We do not want other `#includes` in 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. (Ref:
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 but calls from epicardium might be called from any task.
Don't make assumptions aboutwhich task you're in. Especially if using a task
semaphore.
- Please format your code using the `tools/code-style.sh`.
## Internals
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. When the call returnes, the result
is written into the place where the arguments have been previously and core 1
is woken up. 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`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/epicardium.h)
using
[`genapi.py`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/epicardium/api/genapi.py).
## Obsolete:
Please tend to https://firmware.card10.badge.events.ccc.de/epicardium/overview.html
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment