Introduction
This library provides damage tracking information version 2 of the reMarkable tablet. Unlike the reMarkable 1, the reMarkable 2 does not use the integrated e-paper display controller on the SoC used for the system, but instead drives the display directly from software. This makes it impossible to extract damage information from the (nonexistent) hardware driver, which was the approach taken on the rM1.
It is therefore necessary to inject code into the process that is
controlling the framebuffer in order to provide notification of damage
update. In all known production software, the display is controlled by
executables using the proprietary static library libqsgepaper.a. The
purpose of this project, therefore, is to inject code into a
libqsgepaper.a-based binary that exports the software framebuffer to
which content is drawn, as well as damage notifications whenever an
update is sent to the display.
In order to work on as wide a range of driving binaries as possible,
this library avoids using hardcoded addresses or similar techniques.
Instead, it uses data taken from Qt metaobjects that are part of the
interface of libqsgepaper.a in order to locate relevant functions
and data.
It is relatively easy to find the Qt metaobject in the data section of
the binary@riving the display. Unfortunately, this does not give
direct access to the virtual framebuffer, or to the function used to
notify the display that an update is present. In order to find these
things, the Unicorn Engine emulator
is used to emulate the Qt static meta-call function (when given
appropriate parameters). This uses the fact that libqsgepaper.a
passes the framebuffer address to QImage::fill in the (inlined)
clearScreen function, the fact that sendUpdate is not inlined into
QObject::metacall, and little else.
Once the appropriate addresses have been found, a writable and
executable page is mmapd via ptrace()ing the target process, and a
payload built from payload-c.c and
payload-a.s is injected. The preamble of the
sendUpdate function in the original process is overwritten to
redirect to a portion of the payload which saves the information
damaged, runs the original sendUpdate,and then exports the damage
information over a Unix domain socket. The payload also includes
initialization code that replaces the private anonymous mapping of the
framebuffer with a shared mapping backed by an in-memory file from
memfd_create and connects to a Unix domain socket opened by the
process requesting the information.
The necessary addresses appear to in practice remain stable over
multiple executions of the same binary, as the EPFramebuffer class
which is being hooked into is a singleton and address-space layout
randomization is not used on the reMarkable. Therefore, in order to
improve startup time and minimize resource usage, the Unicorn-based
emulation analysis is not run every time, but rather stored in a
cache.
Building
The supported way to build this is via the
Nix package manager, through the
nix-remarkable
expressions. To build just this project via nix build from this
repo, download it into the pkgs/ directory of nix-remarkable.
For other systems, the Makefile provides the necessary commands. A suitable build of the Unicorn engine (static for the standalone static library) is required.
Prebuilt binaries are available in the Releases tab.
Usage
See libqsgepaper-snoop.h.