ADR note: to have a simple solution for printing logs when running from Brickrun (#494), use of System.out is discouraged. System.err or SLF4J should be used instead.

Allrighty

I will follow the following structure:
https://github.com/joelparkerhenderson/architecture_decision_record

• /docs/adr/adr_name.md

ADR note 2: sensor modes itself do not switch sensor modes. It is necessary to use only the sensor mode returned from last call to get*Mode() and also not mix it with in-sensor measurement functions & resets.
Reason: checking for kernel sensor mode during fetchSample was too slow and caching through integer mode index added complexity to the solution.

Intro into the display code:
The code has roughly these interfaces:

• leJOS LCD emulation in LCD - This reimplements some parts of leJOS GraphicsLCD API. The BufferedImage is obtained from and the refresh is forwarded to JavaFramebuffer. The JavaFramebuffer itself is obtained from SystemDisplay.
• Glue in SystemDisplay - This provides a factory for system display manager - either a native one or a remote one, and a JavaFramebuffer above the display manager.
• JavaFramebuffer interface - This interface abstracts away a framebuffer. The interface provides:
  • basic information about the display geometry,
  • methods for creating offscreen BufferedImage for drawing,
  • writing full-size offscreen buffers to the display,
  • clearing the display,
  • saving and restoring a single snapshot,
  • getter for the underlying DisplayInterface
• DisplayInterface interface - This class manages the underlying display output. It provides:
  • switching between text mode (Linux console is displayed) and graphics mode (user graphics is displayed),
  • framebuffer creation - this class creates the appropriate JavaFramebuffer implementation for the system display.
  • framebuffer lifetime management - this class stores the opened framebuffer.
• FramebufferProvider interface with AllImplFailedException - These classes provide Java SPI for framebuffer formats. The DisplayInterface uses this SPI to instantiate the correct JavaFramebuffer implementation for the system framebuffer.

Then, we have the following implementations:

• ImageUtils class - This class implements BufferedImage creation for 32bpp XRGB and 1bpp BW framebuffers.
• LinuxFramebuffer class - This class implements JavaFramebuffer for native Linux framebuffer device.
• BitFramebuffer, RGBFramebuffer - These classes specialize LinuxFramebuffer for 1bpp BW and 32bpp XRGB formats, respectively.
• BitFramebufferProvider, RGBFramebufferProvider - These classes wrap BitFramebuffer and RGBFramebuffer for usage in FramebufferProvider.
• OwnedDisplay class - This class implements DisplayInterface for standard Linux console. The Java process must have access to the system console.
• StolenDisplay class - This class implements DisplayInterface when the standard Linux console is unavailable. It ignores text/graphics mode switches. However it disables brickman process when instantiated.

Under all of this is an extension of leJOS Native* APIs:

• NativeFile class - this class wraps ILibc file system calls.
• NativeDevice class - this class wraps ILibc system calls for Linux devices.
• NativeFramebuffer class - this class wraps ILibc system calls for Linux framebuffer devices.
• NativeTTY class - this class wraps ILibc system calls for Linux console devices.
• NativeConstants class - contains basic C macros, like errno values and ioctl arguments.
• ILibc interface - abstraction of basic system calls. This is useful for testing the interface code.
• NativeLibc interface - class which is used for JNA binding to system libc.

ILibc interface had been mocked for purposes of unit testing:

• EmulatedLibc - class which provides a virtual file system to which fake files and devices can be mounted.
• IFile - interface for fake files,
• ICounter - interface for event counters,
• CountingFile - this class wraps another IFile and provides counting of system call invocations,
• EmulatedFramebuffer - this class provides a mocked version of system framebuffer device.
• EmulatedFramebufferBuilder - this class helps with EmulatedFramebuffer construction.

I added the Sensor ADR and the Display API ADR. I also tweaked a bit the other ADRs.

Added