Verified Commit 8e26bdaf authored by Rahix's avatar Rahix
Browse files

doc(epicardium): Document API error convention


Signed-off-by: Rahix's avatarRahix <rahix@rahix.de>
parent acb9e8d4
...@@ -5,6 +5,35 @@ Epicardium is the main firmware. It runs on core0 and is based on FreeRTOS. ...@@ -5,6 +5,35 @@ Epicardium is the main firmware. It runs on core0 and is based on FreeRTOS.
Epicardium provides an API to a payload running on the other core which exposes Epicardium provides an API to a payload running on the other core which exposes
most functionality. This section of the docs details this "Epicardium API". most functionality. This section of the docs details this "Epicardium API".
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. To quote:
**16) Function return values and names**
Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or
failed. Such a value can be represented as an error-code integer
(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
non-zero = success).
Mixing up these two sorts of representations is a fertile source of
difficult-to-find bugs. If the C language included a strong distinction
between integers and booleans then the compiler would find these mistakes
for us... but it doesn't. To help prevent such bugs, always follow this
convention:
.. code-block:: text
If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
is a predicate, the function should return a "succeeded" boolean.
For example, ``add work`` is a command, and the add_work() function returns 0
for success or -EBUSY for failure. In the same way, ``PCI device present`` is
a predicate, and the pci_dev_present() function returns 1 if it succeeds in
finding a matching device or 0 if it doesn't.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
......
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