diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..e83b243 --- /dev/null +++ b/README.txt @@ -0,0 +1,190 @@ +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. |