Mirror
/
ardupilot
mirror of https://github.com/ArduPilot/ardupilot
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

AP_HAL: Documentation for ConsoleDriver

This commit is contained in:
Pat Hickey 2012-09-16 13:32:50 -07:00 committed by Andrew Tridgell
parent 95bfe29298
commit e932abb7b5
1 changed files with 28 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
README_AP_HAL.md
View File

@ -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
----------------------
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.
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.
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 the future, I envision extending this driver to support a transport layer
over a Mavlink connection.
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.)
Implementations may either leave the console unimplemented or alias it to one
of the UARTDriver implementations.
* `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
--------------