From e932abb7b5e3c46adf02bdf78e54b93c3c3b00c1 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Sun, 16 Sep 2012 13:32:50 -0700 Subject: [PATCH] AP_HAL: Documentation for ConsoleDriver --- README_AP_HAL.md | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/README_AP_HAL.md b/README_AP_HAL.md index e32435ade3..cd9dbaa932 100644 --- a/README_AP_HAL.md +++ b/README_AP_HAL.md @@ -334,19 +334,39 @@ interface may have to be revised to support bulk transfers for efficient use in a threaded environment. -AP\_HAL Console driver +AP\_HAL::ConsoleDriver ---------------------- -In the existing ArduPilot code, there is no unified way to send debugging -messages, warnings, and errors to the user. A dedicated Console driver, exposed -as an `AP_HAL::BetterStream`, is envisioned as a better way to communicate that -sort of information. - -In the future, I envision extending this driver to support a transport layer -over a Mavlink connection. +The `AP_HAL::ConsoleDriver` class is pure virtual and can be found in `/libraries/AP_HAL/Console.h` . It is derived from the `AP_HAL::BetterStream` class. -Implementations may either leave the console unimplemented or alias it to one -of the UARTDriver implementations. +In the existing ArduPilot code, there is no unified way to send debugging +messages, warnings, and errors to the user. A dedicated Console driver, is +envisioned as a better way to communicate that sort of information to the user. + +In addition to the `AP_HAL::BetterStream` interface, `AP_HAL::ConsoleDriver` +exposes the following methods for implementing a user defined backend. (I +envision this backend will be piped over a mavlink connection by application, +but right now I'm leaving it open ended.) + +* `void init(void*implspecific)` : Standard init code. Should be called after +the UARTDrivers, but before all other drivers, in `AP_HAL::HAL::init`. +* `void backend_open()` : Start buffering reads and writes to user backend +* `void backend_close()` : Stop buffering reads and writes to user backend +* `int backend_read(uint8_t *data, int len)` : Read from user backend buffer. Data sent by `write` through the `BetterStream` interface will be available to `backend_read`, modulo oveflowing the internal buffers (undefined behavior). +* `int backend_write(const uint8_t *data, int len)` : Write to user backend buffer. Written data will be available by `read` through the `BetterStream` interface, modulo overflowing the internal buffers (undefined behavior). + +A few implementation guidelines: +* This is a low assurance data interface: it is more important to maintain the +timing properties of the system than deliver data properly. Assume the user +backend to the BetterStream interface will be operated synchronously, and take +care not to create deadlocks. +* Behavior while the user backend _is not_ open is undefined. It may be +appropriate to either implement a trivial interface (drop all writes, return -1 +on all reads) or proxy to a UARTDriver, depending on the platform & developer's +needs. +* Behavior while the user backend _is_ open: activity on the `BetterStream` +interface should never block. Internal buffer sizes are undefined. Data that +doesn't fit into the internal buffers should be dropped. AP\_HAL::RCInput --------------