Difference between revisions of "FX-CG-UI"

From WikiPrizm
Jump to navigationJump to search
(Created page with "<span style="margin-left:1em"><i>The real title of this page should be <b>FX-CG[UI]</b>. Technical limitations prevent this.</i></span> FX-CG[UI] is a piece of software design...")
 
(No longer communicates via TCP: now shared memory.)
Line 1: Line 1:
 
<span style="margin-left:1em"><i>The real title of this page should be <b>FX-CG[UI]</b>. Technical limitations prevent this.</i></span>
 
<span style="margin-left:1em"><i>The real title of this page should be <b>FX-CG[UI]</b>. Technical limitations prevent this.</i></span>
FX-CG[UI] is a piece of software designed to be a common interface for Prizm programs executing on non-Prizm platforms. It is implemented in Python and communicates with backend software (such as an emulator) via TCP.
+
 
 +
FX-CG[UI] is a piece of software designed to be a common interface for Prizm programs executing on non-Prizm platforms. It is implemented in Python and communicates with backend software (such as an emulator) via a shared memory mapping.
  
 
= Communication =
 
= Communication =
This section documents the protocol used to communicate with the UI. Connections are accepted on TCP port 19756. All data is encapsulated in packets.
+
The shared memory mapping is implemented as a named mapping on Windows (via [http://msdn.microsoft.com/en-us/library/windows/desktop/aa366551(v=vs.85).aspx CreateFileMapping]), and is file-backed via mmap() on UNIX systems. The name or path of the mapping is passed to the UI as the first command line argument. The name should not contain any backslashes on Windows.
 +
 
 +
When file-backed, the file must be the requisite size. Until the UI is capable of automatically creating a file of the correct size, it must be created manually. The exact size necessary depends on your platform, and may be obtained by checking the value stored to SHM_SIZE in the UI's createSharedMapping function (fx_cg_ui/core.py).
 +
 
 +
== Mapping format ==
 +
The actual shared mapping is rather simple. The canonical definition is provided by the ipc_interface struct in FX-CG[CL] (interface.h). It has the following memebers.
 +
 
 +
=== keyboard_regs ===
 +
Eight 16-bit values mimicking the Prizm's keyboard registers. Various bits in the register are set when keys are depressed, and cleared when released. A function such as [[PRGM_GetKey]] can be used to convert values from these registers to KEY_PRGM_* values.
  
== Packet format ==
+
=== vram ===
Packets are composed of a small header and zero or more bytes of data. The header is the string "FXCG" in ASCII, followed by a single type byte and a 32-bit big-endian integer specifying the number of data bytes in the packet. For example, the following string represents a packet of type 16 with 0 bytes of data (C-style escapes): "FXCG\x10\x00\x00\x00\x00".
+
A simple 384 by 216 row-major array of 16-bit values representing the current display contents. 565 RGB, same as VRAM on the device. The contents of this array are displayed at regular intervals.
  
== Packet types ==
+
=== vram_mutex ===
The packet type indicates the meaning of the contained data. Any packet type is valid going in either direction (to or from the UI), but some may only make sense in one direction, but are still valid. Behavior in response to such packets (sending input events to the UI, for example) is implementation-defined.
+
Mutex protecting the contents of [[#vram|vram]] during updates, used to prevent display tearing. If the UI updates the display from vram while a program is writing to VRAM (typically via a Bdisp_* syscall), it may display a partially-updated screen. Simply put, any function that reads or writes directly to the shared VRAM mapping should lock this mutex while accessing the mapping, in order to prevent partial updates.
  
=== 0: Screen image ===
+
Exact semantics of the mutex are platform-dependent (refer to the platform_mutex_acquire and platform_mutex_release functions in FX-CG[CL]), but current implementations use a value of 0 to indicate unlocked, and 1 to indicate locked.
Contains an image of the device screen, formatted as an image file. Most common formats are accepted, such as BMP, GIF, JPEG (not recommended due to its lossy nature) and PNG. FX-CG[CL] uses 24-bit PPM for simplicity. The UI backs this functionality with a QImage structure, so all supported formats may be found in the [http://doc.qt.digia.com/latest/qimage.html#reading-and-writing-image-files Qt Documentation].
 

Revision as of 20:40, 16 February 2013

The real title of this page should be FX-CG[UI]. Technical limitations prevent this.

FX-CG[UI] is a piece of software designed to be a common interface for Prizm programs executing on non-Prizm platforms. It is implemented in Python and communicates with backend software (such as an emulator) via a shared memory mapping.

Communication

The shared memory mapping is implemented as a named mapping on Windows (via CreateFileMapping), and is file-backed via mmap() on UNIX systems. The name or path of the mapping is passed to the UI as the first command line argument. The name should not contain any backslashes on Windows.

When file-backed, the file must be the requisite size. Until the UI is capable of automatically creating a file of the correct size, it must be created manually. The exact size necessary depends on your platform, and may be obtained by checking the value stored to SHM_SIZE in the UI's createSharedMapping function (fx_cg_ui/core.py).

Mapping format

The actual shared mapping is rather simple. The canonical definition is provided by the ipc_interface struct in FX-CG[CL] (interface.h). It has the following memebers.

keyboard_regs

Eight 16-bit values mimicking the Prizm's keyboard registers. Various bits in the register are set when keys are depressed, and cleared when released. A function such as PRGM_GetKey can be used to convert values from these registers to KEY_PRGM_* values.

vram

A simple 384 by 216 row-major array of 16-bit values representing the current display contents. 565 RGB, same as VRAM on the device. The contents of this array are displayed at regular intervals.

vram_mutex

Mutex protecting the contents of vram during updates, used to prevent display tearing. If the UI updates the display from vram while a program is writing to VRAM (typically via a Bdisp_* syscall), it may display a partially-updated screen. Simply put, any function that reads or writes directly to the shared VRAM mapping should lock this mutex while accessing the mapping, in order to prevent partial updates.

Exact semantics of the mutex are platform-dependent (refer to the platform_mutex_acquire and platform_mutex_release functions in FX-CG[CL]), but current implementations use a value of 0 to indicate unlocked, and 1 to indicate locked.