1. Introduction --------------- The purpose of this document is to give a very brief overview of the X.Org components closely connected to the Mali DDK, and how the Mali DDK can be integrated into an existing an X.Org environment. 2. Architecture overview ------------------------ The X Windowing system is also commonly known as XFree86, X, X11 and X.Org. X.Org is the current name of the project. The X Windowing system is based on a client-server model, and provides management of native resources, such as windows, pixmaps, and handling of input device control. X is primarily a protocol and graphics primitive definition, and contains as such no specifications on how to create a user interface design. Such details are handled by "Window Managers", "GUI toolkits", "Desktop Environments" and other application specific graphical user interfaces. X is a modular stack, and the Mali DDK integration will be done at the X Display Driver level, as well as the kernel device driver level. Mali DDK ---------------- |EGL,Base,GLES,VG| ---------------- | DDX | ------------------ ----- | EXA, DRI2, FBDEV | <---------> | UMP | ------------------ ----- ^ | | ----------------- ----- | X.Org Server | <----------> | DRM | ----------------- ----- Figure 1: Architecture overview The above figure tries to depict an overview of the components interesting with respect to Mali DDK integration. 2.1 UMP UMP (Unified Memory Provider) provides a way to share both existing and new memory areas across processes and hardware units. UMP is a kernel device driver accompanied with a userspace library. 2.2 DRM DRM (Direct Rendering Manager) is a component of the Direct Rendering Infrastructure, a generic DRM driver, and another which has specific support for the video hardware. This pair of drivers allow a userspace client direct access to the video hardware. As the device specific driver, "Mali DRM" is provided. 2.3 EXA EXA was designed to replace XAA in the X.Org server, with initial aims to "extend the life of venerable XFree86 video drivers". EXA provides hooks for accelerating parts of the 2D operationis in the X Display Driver. These hooks include: - pixmap allocation and management - solid fills - blitting operations * within screen memory * to and from system memory - porter-Duff compositing and transform operations It is assumed that the vendor either have a 2D HW unit for which to integrate into EXA - or alternatively, use software optimized fallbacks for these operations. The "pixman" library already provides reasonably optimized operations. 2.4 DRI2 DRI2 (Direct Rendering Infrastructure 2) is a vital part for using native resources as renderable surfaces with the Mali GPU. DRI2 allows Mali DDK to set up rendering directly into offscreen and onscreen windows and pixmaps. 3. X.Org Display driver ---------------------- "xf86-video-mali" is provided as a basis for creating your own X Display Driver. It requires a recent version of the xorg-server, as well as a successfull integration of UMP with your display device driver. A reference configuration file, xorg.conf is provided. Please place this file in your configuration folder, typically /etc/X11/. In order to utilize page flipping for fullscreen OpenGL ES and OpenVG applications, make sure that you configure your kernel display driver to support at least twice the amount of virtual y-resolution as the physical resolution. For a device with a 800x480 display, this means that you will have to reserve at least 800x960 for your framebuffer memory. 4. Integrating and building --------------------------- 4.1 Integrating UMP with your display driver It is required that you support the "GET_UMP_SECURE_ID" ioctl for your display driver. This ioctl has to return a UMP secure ID for your framebuffer memory. Such an integration typically consists of two major parts - Mapping and UnMapping of physical blocks of memory - Returning UMP Secure ID from within ioctl handler A typical example of mapping the framebuffer memory would look like this: ump_dd_handle ump_wrapped_buffer; ump_dd_physical_block ump_memory_description; ump_memory_description.addr = fix->smem_start; ump_memory_description.size = buffer_size; ump_wrapped_buffer = ump_dd_handle_create_from_phys_blocks( &ump_memory_description, 1); A typical example of retrieving the secure ID from this memory look like this: u32 __user *psecureid = (u32 __user *) arg; ump_secure_id secure_id; secure_id = ump_dd_secure_id_get( ump_wrapped_buffer ); return put_user( (unsigned int)secure_id, psecureid ); 4.2 Integrating EXA with your 2D hardware The EXA module provides hooks for accelerating various 2D operations. Please refer to the EXA documentation for further information regarding this. The provided "xf86-video-mali" driver contains an EXA module which has been integrated with the UMP system. Your 2D driver may therefore require an integration with UMP as well. The suggestion is to pass the secure ID down to the kernel device driver for your hardware, but it is also possible to get the CPU-mapped address for the memory by calling ump_mapped_pointer_get. Please refer to UMP documentation for more information regarding this. 4.3 Building the Mali DDK for X.Org The client API libraries can be built to support X.Org by including "linux-x11-ump" in the variant string. An example of such a variant string can be VARIANT="mali400-gles20-gles11-linux-x11-ump" You will also have to edit driver/Makefile_x11.mak to reflect your system. A complete development setup for X Window System is required, including development header files and precompiled libraries. The process of building the Mali DDK, including client API libraries and device drivers are otherwise the same as building for regular Linux. Copy your libraries into the system library folder, typically /usr/lib or /usr/local/lib. Make sure that file permissions allows read and execute. 4.4 Building the X Display Driver As for the Mali DDK, the X Display Driver "xf86-video-mali" requires an existing development setup for the X Windowing System for your architecture. Modify the GET_UMP_SECURE_ID ioctl define in mali_exa.h to reflect your integration with the display driver. Also modify the build.sh script inside the X Display Driver package to reflect your current include paths and library folders for X Window System. The build.sh shell script performs the following steps: 1. make distclean 2. runs configure script to generate makefile(s) 3. runs make The display driver can be found in xf86-video-mali-0.0.1/src/.lib/mali_drv.so. Copy this driver into your X Server display driver path, typically /usr/lib/xorg/modules/drivers Make sure that the file has the correct permissions. A reference xorg.conf file can be found under xf86-video-mali-0.0.1/xorg.conf. Make sure that you are using "mali" as the Driver under the "Device" section. Supported options under "Device" section for Mali are: > fbdev Select which framebuffer device to use. Defalt: /dev/fb0 > DRI2 Enable DRI2 or not. Default: false > DRI2_PAGE_FLIP Enable flipping for fullscreen gles apps. Default: false > DRI2_WAIT_VSYNC Enable vsync for fullscreen gles apps. Default: false 4.5 Building the Mali DRM The Mali DRM can be plugged into the drivers/gpu/drm folder of your kernel. It is compatible with the latest 2.6.36 kernel where PCI and AGP bus requirements were removed in favor of supporting a generic platform device. Please refer to the to Mali DRM README.txt for more information on including the Mali DRM as a platform device.