From c30a6f2e6b9fd44e14345d0a44fe8ea9bd65d653 Mon Sep 17 00:00:00 2001
From: Kevin O'Connor <kevin@koconnor.net>
Date: Mon, 1 Apr 2019 21:32:33 -0400
Subject: [PATCH] docs: Update Protocol documentation with enumerations
Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
---
docs/MCU_Commands.md | 14 +++++-------
docs/Protocol.md | 52 ++++++++++++++++++++++++++++----------------
2 files changed, 38 insertions(+), 28 deletions(-)
diff --git a/docs/MCU_Commands.md b/docs/MCU_Commands.md
index f5019814d..c576ad888 100644
--- a/docs/MCU_Commands.md
+++ b/docs/MCU_Commands.md
@@ -12,7 +12,11 @@ format of commands and their transmission. The commands here are
described using their "printf" style syntax - for those unfamiliar
with that format, just note that where a '%...' sequence is seen it
should be replaced with an actual integer. For example, a description
-with "count=%c" could be replaced with the text "count=10".
+with "count=%c" could be replaced with the text "count=10". Note that
+parameters that are considered "enumerations" (see the above protocol
+document) actually take a string value which is automatically
+converted to an integer value for the micro-controller. This is common
+with parameters named "pin" (or that have a suffix of "_pin").
Startup Commands
================
@@ -23,14 +27,6 @@ commands available for that purpose. Unlike most micro-controller
commands, these commands run as soon as they are received and they do
not require any particular setup.
-Several of these commands will take a "pin=%u" parameter. The
-low-level micro-controller software uses integer encodings of the
-hardware pin numbers, but to make things more readable the host will
-translate human readable pin names (eg, "PA3") to their equivalent
-integer encodings. By convention, any parameter named "pin" or that
-has a "_pin" suffix will use pin name translation by the
-host.
-
Common startup commands:
* `set_digital_out pin=%u value=%c` : This command immediately
diff --git a/docs/Protocol.md b/docs/Protocol.md
index f73a195a6..d10a11860 100644
--- a/docs/Protocol.md
+++ b/docs/Protocol.md
@@ -109,6 +109,30 @@ output("The value of %u is %s with size %u.", x, buf, buf_len);
The output() function is similar in usage to printf() - it is intended
to generate and format arbitrary messages for human consumption.
+Declaring enumerations
+----------------------
+
+Enumerations allow the host code to use string identifiers for
+parameters that the micro-controller handles as integers. They are
+declared in the micro-controller code - for example:
+
+```
+DECL_ENUMERATION("spi_bus", "spi", 0);
+
+DECL_ENUMERATION_RANGE("pin", "PC0", 16, 8);
+```
+
+If the first example, the DECL_ENUMERATION() macro defines an
+enumeration for any command/response message with a parameter name of
+"spi_bus" or parameter name with a suffix of "_spi_bus". For those
+parameters the string "spi" is a valid value and it will be
+transmitted with an integer value of zero.
+
+It's also possible to declare an enumeration range. In the second
+example, a "pin" parameter (or any parameter with a suffix of "_pin")
+would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will
+be transmitted with integers 16, 17, 18, ..., 23.
+
Declaring constants
-------------------
@@ -119,7 +143,12 @@ DECL_CONSTANT("SERIAL_BAUD", 250000);
```
would export a constant named "SERIAL_BAUD" with a value of 250000
-from the micro-controller to the host.
+from the micro-controller to the host. It is also possible to declare
+a constant that is a string - for example:
+
+```
+DECL_CONSTANT_STR("MCU", "pru");
+```
Low-level message encoding
==========================
@@ -277,24 +306,9 @@ dictionary. Once all chunks are obtained the host will assemble the
chunks, uncompress the data, and parse the contents.
In addition to information on the communication protocol, the data
-dictionary also contains the software version, constants (as defined
-by DECL_CONSTANT), and static strings.
-
-Static Strings
---------------
-
-To reduce bandwidth the data dictionary also contains a set of static
-strings known to the micro-controller. This is useful when sending
-messages from micro-controller to host. For example, if the
-micro-controller were to run:
-
-```
-shutdown("Unable to handle command");
-```
-
-The error message would be encoded and sent using a single VLQ. The
-host uses the data dictionary to resolve VLQ encoded static string ids
-to their associated human-readable strings.
+dictionary also contains the software version, enumerations (as
+defined by DECL_ENUMERATION), and constants (as defined by
+DECL_CONSTANT).
Message flow
============