From 8e26bdaf22423321b03af1940aa90666078bdc63 Mon Sep 17 00:00:00 2001
From: Rahix <rahix@rahix.de>
Date: Mon, 8 Jul 2019 23:43:19 +0200
Subject: [PATCH] doc(epicardium): Document API error convention
Signed-off-by: Rahix <rahix@rahix.de>
---
Documentation/epicardium.rst | 29 +++++++++++++++++++++++++++++
1 file changed, 29 insertions(+)
diff --git a/Documentation/epicardium.rst b/Documentation/epicardium.rst
index 295d69d13..c852c4154 100644
--- a/Documentation/epicardium.rst
+++ b/Documentation/epicardium.rst
@@ -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
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::
:maxdepth: 1
--
GitLab