Eink Framebuffer Update Trigger

[geekmaster]

Kindles have a built-in eips command that can clear the screen, can print to the screen, can scroll the text screen, and can display PNG files to the screen. Text is limited to 50 lines of 40 characters. It is used by the diagnostic mode scripts, and its output can be viewed in diagnostic mode menus and tests. It can also be used from scripts and native mode apps while the normal GUI framework is running, and can even display contents on top of normal GUI screens.

In my apps, I reset the screen to its previous contents by saving a copy before I change it, then before my app exits I copy the saved contents back onto the framebuffer, and then I trigger a display update.

You can find the bits/pixel and bytes/line with:
eips -i

On the older kindles a framebuffer display update can be triggered with an ioctl call from within a native app. Scripts can trigger a display update with:
echo 1 > /proc/eink_fb/update_display

On the kindle touch, the only way I have found (so far) to trigger a framebuffer display update is:
eips -g . > /dev/null

On the kindle touch, the framebuffer is 8 bits/pixel, 608 pixels wide (right 8 pixels not visible). On the kindle 4 (non touch), the framebuffer is 8 bits/pixel, 600 pixels wide. On prior kindles, the framebuffer is 4 bits/pixel, width depending on model. Display orientation also affects width.

From a script, you can copy the framebuffer like this example for a kindle touch:
dd if=/dev/fb0 bs=608 count=800 > /mnt/us/fb0.raw
and restore it to previous contents like this:
cat /mnt/us/fb0.raw > /dev/fb0
eips -g . > /dev/null

A little tip: raw 8-bit images copied directly from the framebuffer with dd can be loaded into IrfanView as a raw image. IrfanView will ask for bit depth and line width (8 bits and 608 pixels for kindle touch, 8 bits and 600 pixels for the K4NT). For older kindles with a 4-bit framebuffer, you could tell IrfanView that you have 8-bit images that are half-width (300 instead of 600), and see the image good enough to get an idea of what it represents.

Request for assistance: I would like to find a better way to trigger a framebuffer update to the display, especially one that uses an ioctl call. If anybody has found a better way, please let us know. Thanks.

[Matan]

Did you run:

strace eips -g .

[geekmaster]

In my kindle touch, I get "strace not found". I was not aware of strace. I will look for one to install on my touch.

[Doramanjyu]

Since it's difficult for me to x-compile strace for arm-linux, I made strace-like utility(attached) to observe syscalls.
"eips -g ." updates e-ink by ioctl request of MXCFB_SEND_UPDATE with following commented values:
(Structures and definitions are written in kernel-source-root/include/linux/mxcfb.h)

struct mxcfb_update_data {
    struct mxcfb_rect {
        __u32 top;      // 0x0000
        __u32 left;     // 0x0000
        __u32 width;    // 0x0258 = 600
        __u32 height;   // 0x0320 = 800
    } update_region;
    __u32 waveform_mode;    // 0x0002 = WAVEFORM_MODE_GC16
    __u32 update_mode;      // 0x0000 = UPDATE_MODE_PARTIAL
    __u32 update_marker;    // 0x002a
    int temp;               // 0x1001 = TEMP_USE_PAPYRUS
    uint flags;             // 0x0000
    struct mxcfb_alt_buffer_data alt_buffer_data; // must not used when flags is 0
};

I confirmed that:
Partial update request and full update request works,
WAVEFORM_MODE_GC16 and WAVEFORM_MODE_GC4 works but WAVEFORM_MODE_A2 seems not to work,
and no problem with another update_marker value but update_marker = 0 makes kernel panic.

[geekmaster]

Thank you. I have seen the header file. This tells me which values to use.

[eureka]

For the record: I've successfully ran on Kindle Touch precompiled strace executable for Android from this page. (I used it for my own purposes, not for eips tracing).

[rastik]

Originally Posted by geekmaster

In my kindle touch, I get "strace not found". I was not aware of strace. I will look for one to install on my touch.

Install optware. It's called Extend on KT hacking wiki page. Then do

/opt/bin/ipkg install strace

and you have it:

/opt/bin/strace

[geekmaster]

I have strace now thanks. It is great. I could have saved many hours of my time if I had known about this tool years ago.

[geekmaster]

The eips call is still useful when used in scripts.

I found a better eips call that updates the framebuffer without causing an error message:

eips ''

(that is two single quotes, not one double quote).

Or, you can use two double quotes instead:

eips ""

[Novo]

Hey,
after friting some Status with:
eips 2 10 "Hello World"
how can I delete it / refresh the screen without my message?

[geekmaster]

Originally Posted by Novo

Hey,
after friting some Status with:
eips 2 10 "Hello World"
how can I delete it / refresh the screen without my message?

There are many ways to do this. When your code operates inside the framework, on newer kindles you can send a "power on" event with a "lipc-" command (details available by searching the forums). On older kindles you can send two Menu key press to refresh the display.

My code usually operates outside the framework, from diagnostics more, or during startup before the framework is loaded, so I use "eips" for most of my display management, just like the startup scripts do it. I usually save the framebuffer contents and restore it after I change it like this:

cat /dev/fb0 /mnt/us/fb0.raw  # save framebuffer
eips -c                       # clear display
eips 2 10 "Hello, world! "    # (row column message)
sleep 5                       # wait 5 seconds
cat /mnt/us /dev/fb0          # restore saved framebuffer
eips ''                       # refresh display (two single-quotes)

Notice that eips displays /dev/fb0 when called with two single-quotes. Clearing the display is optional. You can use the row and column values to position your text on top of an existing screen (column 0-49, row 0-39).

You can use eips for eInk display management from inside the framework too.

In the startup scripts there is a function library that you can "source" inside your scripts (just like the startup scripts do it), which gives you extra eips functions, like centering text on the display.

I hope that helps. Search the forums for more details. You can learn a lot about this by reading the startups scripts in your kindle (and more in the GPL source code you can download from amazon).

[thomass]

Originally Posted by geekmaster

There are many ways to do this.
...

Thanks for the info. Really helped.

[Novo]

Originally Posted by geekmaster

cat /dev/fb0 /mnt/us/fb0.raw  # save framebuffer
cat /mnt/us /dev/fb0             # restore saved framebuffer

Are you sure this is correct? Don't work for me.

Originally Posted by geekmaster

dd if=/dev/fb0 bs=608 count=800 > /mnt/us/fb0.raw
and restore it to previous contents like this:
cat /mnt/us/fb0.raw > /dev/fb0
eips -g . > /dev/null

This one works.

[geekmaster]

Originally Posted by Novo

Are you sure this is correct? Don't work for me.


This one works.

I first discovered the "eips -g ." but that reports that it cannot display image file ".".

Later I discovered that you can tell it to display emtpy text (just two single-quotes or two double-quotes) and that works too, but with no error messages.

I have done cat to and from framebuffer, but with dd you do not need to save the entire thing. The problem is sometimes the width is 608 instead of 600. You can tell with "eips -i".

Framebuffer images compress very nicely with gz (lots of white space), so I like to display them with "zcat image1.gz > /dev/fb0".

I did notice that "dd" seems to be more reliable for copying from the framebuffer than cat (I do not know why). You can view raw framebuffer contents (like fb0.raw) with IrfanView. Why you open a ".raw" file it asks you for width (600 or 608), height (800) and bits-per-pixel (8). If it displays skewed at 600 wide, try opening it at 608 wide (or vice versa).

The k4nt seems to always use 600, but the touch sometimes changes between 608 and 600. Main boot is 600, but diags is 608, and during a reboot (like in my RUNME.sh) it could be in either mode. You can check the mode with "eips -i" and grep the "virtual xres" line and use cut or awk to extract the number. Then use that to decide which image to display. I have most images in 600 and 608 widths. If I extract the eips virtual xres to var $i, then I display my image with "zcat imgabc$i.gz".

On the k3 and earlier, you need to deal with 4 pit-per-pixel displays. You can (mostly) see what the raw framebuffer image looks like with IrfanView, if you set width to 300. You can then crop and save images to .png files with IrfanView, which is how I create screenshot images from a the raw framebuffer.

[Novo]

Hm save and restore buffer is not a good idea.
I use eips now to show some status messages at the fist and last line.
But imagine you show 10 Second some Text and then you will delete that text.
While 10 Seconds the Time and maybe your read ebook text has changed.
And now you copy your framebuffer back ---

I also tried:
eips 15 0 "Test Text Message"
eips 15 0 " "
this will delete the text with white areas.

EDIT: GOT IT!
every line is count=20, so to only delete first line is:
dd if=/dev/fb0 bs=608 count=20 > /mnt/us/fb0.raw # save framebuffer