diff options
| -rwxr-xr-x | Android.mk | 30 | ||||
| -rw-r--r-- | GNUmakefile | 31 | ||||
| -rwxr-xr-x | Makefile | 32 | ||||
| -rw-r--r-- | component/component.xml | 12 | ||||
| -rw-r--r-- | debian/b2r2lib-dev.dirs | 1 | ||||
| -rw-r--r-- | debian/b2r2lib-dev.install | 2 | ||||
| -rw-r--r-- | debian/b2r2lib.dirs | 1 | ||||
| -rw-r--r-- | debian/b2r2lib.install | 1 | ||||
| -rw-r--r-- | debian/changelog | 49 | ||||
| -rw-r--r-- | debian/compat | 1 | ||||
| -rw-r--r-- | debian/control | 21 | ||||
| -rw-r--r-- | debian/copyright | 9 | ||||
| -rwxr-xr-x | debian/rules | 14 | ||||
| -rw-r--r-- | debian/source/format | 1 | ||||
| -rwxr-xr-x | include/blt_api.h | 738 | ||||
| -rw-r--r-- | src/blt_b2r2.c | 309 | ||||
| -rwxr-xr-x | ste-info/toc-locations.xml | 8 | ||||
| -rwxr-xr-x | ste-info/userspace_std_api_b2r2lib.xml | 354 |
18 files changed, 1614 insertions, 0 deletions
diff --git a/Android.mk b/Android.mk new file mode 100755 index 0000000..1284956 --- /dev/null +++ b/Android.mk @@ -0,0 +1,30 @@ +# Copyright (C) 2008 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +LOCAL_PATH:= $(call my-dir) +include $(CLEAR_VARS) + +LOCAL_PRELINK_MODULE := false + +LOCAL_SRC_FILES := src/blt_b2r2.c + +LOCAL_C_INCLUDES += $(LOCAL_PATH)/include + +LOCAL_SHARED_LIBRARIES := liblog + +LOCAL_MODULE := libblt_hw + +LOCAL_MODULE_TAGS := optional + +include $(BUILD_SHARED_LIBRARY) diff --git a/GNUmakefile b/GNUmakefile new file mode 100644 index 0000000..778e185 --- /dev/null +++ b/GNUmakefile @@ -0,0 +1,31 @@ +.PHONY: clean build libblt_hw.so +IDIR =./include +CC=gcc +CFLAGS=-I$(IDIR) -I$(KDIR) + +SDIR=./src + +LIBS=-lpthread + +default: build + +blt_b2r2.o: $(SDIR)/blt_b2r2.c + gcc -fPIC -g -c -o $@ $^ $(CFLAGS) + +libblt_hw.so: blt_b2r2.o + gcc -shared -Wl,-soname,libblt_hw.so.1 -o libblt_hw.so.1.0 $^ $(LIBS) + +build: libblt_hw.so + +install: + mkdir -p $(DESTDIR)/usr/lib + find . -name "*.so*" + cp *.so* $(DESTDIR)/usr/lib/ + ln -s /usr/lib/libblt_hw.so.1.0 $(DESTDIR)/usr/lib/libblt_hw.so.1 + ln -s /usr/lib/libblt_hw.so.1 $(DESTDIR)/usr/lib/libblt_hw.so + + mkdir -p $(DESTDIR)/usr/include + cp $(IDIR)/*.h $(DESTDIR)/usr/include +clean: + rm -f *.o *.so.* + diff --git a/Makefile b/Makefile new file mode 100755 index 0000000..301ef4c --- /dev/null +++ b/Makefile @@ -0,0 +1,32 @@ +# +# Copyright (C) ST-Ericsson SA 2010. All rights reserved. +# This code is ST-Ericsson proprietary and confidential. +# Any use of the code for whatever purpose is subject to +# specific written permission of ST-Ericsson SA. +# + +include $(MM_MAKEFILES_DIR)/SharedConfig.mk + +ifeq ($(DEBUG),1) +CPPFLAGS += -DDEBUG +endif + +# shared library +SOLIBNAMES += blt_hw +LIBOBJ_blt_hw = blt_b2r2 +INSTALL_SOLIB = blt_hw + +# static library +LIBNAME = blt_hw +LIBOBJ = blt_b2r2 +INSTALL_LIB = libblt_hw.a + +INSTALL_HEADER = blt_api.h + +ifneq ($(MMSYSTEM),android) + FLAGS_blt_hw += -pthread +endif + +todo: solib lib + +include $(MM_MAKEFILES_DIR)/SharedRules.mk diff --git a/component/component.xml b/component/component.xml new file mode 100644 index 0000000..f10bbcb --- /dev/null +++ b/component/component.xml @@ -0,0 +1,12 @@ +<?xml version="1.0"?> +<component name="linux_b2r2lib"> + <abstract> Implementation of blt_api for STE B2R2 IP </abstract> + + <property name="tag" value="href_v1-linux" /> + <property name="tag" value="svp5500_v1-linux"/> + <property name="tag" value="u8500_v2-linux"/> + + <dependency name="makefiles" /> + <dependency name="linux_kernel" /> + +</component> diff --git a/debian/b2r2lib-dev.dirs b/debian/b2r2lib-dev.dirs new file mode 100644 index 0000000..e43b95c --- /dev/null +++ b/debian/b2r2lib-dev.dirs @@ -0,0 +1 @@ +usr/include diff --git a/debian/b2r2lib-dev.install b/debian/b2r2lib-dev.install new file mode 100644 index 0000000..b341905 --- /dev/null +++ b/debian/b2r2lib-dev.install @@ -0,0 +1,2 @@ +usr/include/* +usr/lib/lib*.so diff --git a/debian/b2r2lib.dirs b/debian/b2r2lib.dirs new file mode 100644 index 0000000..6845771 --- /dev/null +++ b/debian/b2r2lib.dirs @@ -0,0 +1 @@ +usr/lib diff --git a/debian/b2r2lib.install b/debian/b2r2lib.install new file mode 100644 index 0000000..d0dbfd1 --- /dev/null +++ b/debian/b2r2lib.install @@ -0,0 +1 @@ +usr/lib/lib*.so.* diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 0000000..8b572f4 --- /dev/null +++ b/debian/changelog @@ -0,0 +1,49 @@ +b2r2lib (1.0.1-3linaro1) precise; urgency=low + + * Kernel API update + + -- Ricardo Salveti de Araujo <ricardo.salveti@linaro.org> Thu, 05 Apr 2012 04:47:01 -0300 + +b2r2lib (1.0.1-2linaro1) oneiric; urgency=low + + * debian/control: + - Making it build-depend on linux-headers-linaro-lt-ux500 + - Enabling build for armhf + + -- Ricardo Salveti de Araujo <ricardo.salveti@linaro.org> Wed, 28 Mar 2012 18:35:41 -0300 + +b2r2lib (1.0.1-2) oneiric; urgency=low + + * Revert API change, we don't have that yet in the kernel side + + -- Kalle Vahlman <kalle.vahlman@movial.com> Thu, 12 Jan 2012 15:58:38 +0000 + +b2r2lib (1.0.1-1) oneiric; urgency=low + + * Fix symlinking in GNUMakefile + + -- Kalle Vahlman <kalle.vahlman@movial.com> Fri, 16 Dec 2011 13:10:16 +0000 + +b2r2lib (1.0-4) oneiric; urgency=low + + * Add missing build-deps + + -- Kalle Vahlman <kalle.vahlman@movial.com> Fri, 16 Dec 2011 11:01:27 +0000 + +b2r2lib (1.0-3) oneiric; urgency=low + + * Fix building natively on non-snowball device + + -- Kalle Vahlman <kalle.vahlman@movial.com> Fri, 16 Dec 2011 10:43:48 +0000 + +b2r2lib (1.0-2) oneiric; urgency=low + + * Packaging changes for Launchpad + + -- Kalle Vahlman <kalle.vahlman@movial.com> Fri, 16 Dec 2011 10:04:01 +0000 + +b2r2lib (1.0-1) unstable; urgency=low + + * Initial release. + + -- root <root@unknown> Fri, 27 May 2011 08:38:24 +0000 diff --git a/debian/compat b/debian/compat new file mode 100644 index 0000000..7f8f011 --- /dev/null +++ b/debian/compat @@ -0,0 +1 @@ +7 diff --git a/debian/control b/debian/control new file mode 100644 index 0000000..f23098a --- /dev/null +++ b/debian/control @@ -0,0 +1,21 @@ +Source: b2r2lib +Priority: extra +Maintainer: packages@igloocommunity.org +Build-Depends: debhelper (>= 7.0.50~), linux-headers-linaro-lt-ux500 +Standards-Version: 3.9.3 +Section: libs +Homepage: http://www.igloocommunity.org + +Package: b2r2lib-dev +Section: libdevel +Architecture: armel armhf +Depends: b2r2lib (= ${binary:Version}) +Description: Development package to b2r2lib. + +Package: b2r2lib +Section: libs +Architecture: armel armhf +Depends: ${shlibs:Depends}, ${misc:Depends} +Description: Hardware blit library for 2D graphics acceleration. + B2R2 is a hardware block which blits, blends, rotates and resizes graphics buffers with various pixel formats. + Simple library with a 1:1 mapping to the kernel b2r2 api. diff --git a/debian/copyright b/debian/copyright new file mode 100644 index 0000000..71f8e6a --- /dev/null +++ b/debian/copyright @@ -0,0 +1,9 @@ +Format: http://dep.debian.net/deps/dep5 +Upstream-Name: b2r2lib +Source: <http://www.igloocommunity.org> + +Files: * +Copyright: <years> <put author's name and email here> + <years> <likewise for another author> +License: BSD + . diff --git a/debian/rules b/debian/rules new file mode 100755 index 0000000..c944ea9 --- /dev/null +++ b/debian/rules @@ -0,0 +1,14 @@ +#!/usr/bin/make -f +# -*- makefile -*- +# Sample debian/rules that uses debhelper. +# This file was originally written by Joey Hess and Craig Small. +# As a special exception, when this file is copied by dh-make into a +# dh-make output file, you may use that output file without restriction. +# This special exception was added by Craig Small in version 0.37 of dh-make. + +# Uncomment this to turn on verbose mode. +#export DH_VERBOSE=1 +export KDIR=$(shell ls -d -1 /usr/src/linux-headers-*-ux500 | tail -1)/include + +%: + dh $@ diff --git a/debian/source/format b/debian/source/format new file mode 100644 index 0000000..89ae9db --- /dev/null +++ b/debian/source/format @@ -0,0 +1 @@ +3.0 (native) diff --git a/include/blt_api.h b/include/blt_api.h new file mode 100755 index 0000000..5d99839 --- /dev/null +++ b/include/blt_api.h @@ -0,0 +1,738 @@ +/* + * Copyright (C) ST-Ericsson AB 2009 - All rights reserved + * Reproduction and Communication of this document is strictly prohibited + * unless specifically authorized in writing by ST-Ericsson + * + * \file blt_api.h + * \brief Blitting library userspace API + * \author ST-Ericsson + * + */ + + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef _BLT_API_H +#define _BLT_API_H + +#include <stdint.h> + +/** + * @brief Specifies a blit rectangle + * + * This type specifies a blit rectangle. + */ +struct blt_rect { + /** + * @brief X-coordinate of top left corner + */ + int32_t x; + /** + * @brief Y-coordinate of top left corner + */ + int32_t y; + /** + * @brief Rectangle width. Must be >= 0. + */ + int32_t width; + /** + * @brief Rectangle height. Must be >= 0. + */ + int32_t height; +}; + +/** + * @brief Defines the available buffer formats. + * Inspired by Khronos OpenMAX, please see + * OpenMAX IL specification for detailed descriptions of the formats. + * All OpenMAX formats are enumerated for possible future use but only + * a subset is supported by the actual hardware. + */ +enum blt_fmt { + /** + * @brief Placeholder value when format is unknown, + * or specified using vendor specific means. + */ + BLT_FMT_UNUSED = 0, + /*BLT_FMT_MONOCHROME = 1,*/ + /*BLT_FMT_8_BIT_RGB332 = 2,*/ + /*BLT_FMT_12_BIT_RGB444 = 3,*/ + /** + * @brief 16 bits per pixel ARGB format with colors stored as Alpha 15:12, + * Red 11:8, Green 7:4, and Blue 3:0. + */ + BLT_FMT_16_BIT_ARGB4444 = 4, + /** + * @brief 16 bits per pixel ARGB format with colors stored as Alpha 15, + * Red 14:10, Green 9:5, and Blue 4:0. + */ + BLT_FMT_16_BIT_ARGB1555 = 5, + /** + * @brief 16 bits per pixel RGB format with colors stored as Red 15:11, + * Green 10:5, and Blue 4:0. + */ + BLT_FMT_16_BIT_RGB565 = 6, + /*BLT_FMT_16_BIT_BGR565 = 7,*/ + /*BLT_FMT_18_BIT_RGB666 = 8,*/ + /*BLT_FMT_18_BIT_ARGB1665 = 9,*/ + /*BLT_FMT_19_BIT_ARGB1666 = 10, */ + /** + * @brief 24 bits per pixel RGB format with colors stored as Red 23:16, + * Green 15:8, and Blue 7:0. + */ + BLT_FMT_24_BIT_RGB888 = 11, + /*BLT_FMT_24_BIT_BGR888 = 12,*/ + /*BLT_FMT_24_BIT_ARGB1887 = 13,*/ + /*BLT_FMT_25_BIT_ARGB1888 = 14,*/ + /*BLT_FMT_32_BIT_BGRA8888 = 15,*/ + /** + * @brief 32 bits per pixel ARGB format with colors stored as Alpha 31:24, + * Red 23:16, Green 15:8, and Blue 7:0. + */ + BLT_FMT_32_BIT_ARGB8888 = 16, + /*BLT_FMT_YUV_411_PLANAR = 17,*/ + /*BLT_FMT_YUV_411_PACKED_PLANAR = 18,*/ + /*BLT_FMT_YUV_420_PLANAR = 19,*/ + /** + * @brief YUV planar format, organized with three separate planes, + * one for each color component, namely Y, U, and V. + * U and V pixels are subsampled by a factor of two + * both horizontally and vertically. + * The buffer shall contain a plane of Y, U, and V data in this + * order. + */ + BLT_FMT_YUV420_PACKED_PLANAR = 20, + /*BLT_FMT_YUV420_SEMI_PLANAR = 21,*/ + /*BLT_FMT_YUV422_PLANAR = 22,*/ + /** + * @brief YUV planar format, organized with three separate planes, + * one for each color component, namely Y, U, and V. + * U and V pixels are subsampled by a factor of two horizontally. + * The buffer shall contain a plane of Y, U, and V data in this + * order. + */ + BLT_FMT_YUV422_PACKED_PLANAR = 23, + /*BLT_FMT_YUV422_SEMI_PLANAR = 24,*/ + /** + * @brief 16 bits per pixel YUV interleaved format organized as YUYV + * (i.e., YCbYCr). + * (Corresponds to YUV422 interleaved) + */ + BLT_FMT_Y_CB_Y_CR = 25, + /*BLT_FMT_Y_CR_Y_CB = 26,*/ + /** + * @brief 16 bits per pixel YUV interleaved format organized as UYVY + * (i.e., CbYCrY). + * (Corresponds to YUV422R) + */ + BLT_FMT_CB_Y_CR_Y = 27, + /*BLT_FMT_CR_Y_CB_Y=28,*/ + /*BLT_FMT_YUV_444_INTERLEAVED=29,*/ + /*BLT_FMT_RAW_BAYER_8_BIT=30,*/ + /*BLT_FMT_RAW_BAYER_10_BIT=31,*/ + /*BLT_FMT_RAW_BAYER_8_BIT_COMPRESSED=32,*/ + /*BLT_FMT_L2=33, */ + /*BLT_FMT_L4=34, */ + /*BLT_FMT_L8=35, */ + /*BLT_FMT_L16=36, */ + /*BLT_FMT_L24=37, */ + /*BLT_FMT_L32=38,*/ + /** + * @brief YUV planar format, organized with a first plane containing Y + * pixels, and a second plane containing U and V pixels interleaved + * with the first U value first. U and V pixels are subsampled by + * a factor of two both horizontally and vertically. The buffer + * shall contain a plane of Y, U and V data. + * (Same as B2R2 420 Raster 2 buffer - 420 R2B) + */ + BLT_FMT_YUV420_PACKED_SEMI_PLANAR=39, + /** + * @brief YUV planar format, organized with a first plane containing Y + * pixels, and a second plane containing U and V pixels interleaved + * with the first U value first. U and V pixels are subsampled by + * a factor of two horizontally. The buffer shall contain a plane + * of Y, U and V data. + * (Same as B2R2 422 Raster 2 buffer - 422 R2B) + */ + BLT_FMT_YUV422_PACKED_SEMI_PLANAR=40, + /*BLT_FMT_18_BIT_BGR_666=41,*/ + /*BLT_FMT_24_BIT_ARGB_6666=42,*/ + /*BLT_FMT_24_BIT_ABGR_6666=43,*/ + + /* Extensions, non OpenMAX formats */ + + /** + * @brief 32 bits per pixel ABGR format with colors stored as Alpha 31:24, + * Blue 23:16, Green 15:8, and Red 7:0. + */ + BLT_FMT_32_BIT_ABGR8888 = 0x7F000000, /* OpenMax vendor start */ + /** + * @brief 24 bits per pixel ARGB format with colors stored as Alpha 23:16, + * Red 15:11, Green 10:5, and Blue 4:0. + */ + BLT_FMT_24_BIT_ARGB8565 = 0x7F000001, + /** + * @brief 24 bits per pixel YUV format with colors stored as + * Y 23:16, U 15:8, and V 7:0. + */ + BLT_FMT_24_BIT_YUV888 = 0x7F000002, + /** + * @brief 32 bits per pixel AYUV format with colors stored as + * Alpha 31:24, Y 23:16, U 15:8, and V 7:0. + */ + BLT_FMT_32_BIT_AYUV8888 = 0x7F000003, + /** + * @brief Nomadik YUV 420 macro block format, see B2R2 specification for details + */ + BLT_FMT_YUV420_PACKED_SEMIPLANAR_MB_STE = 0x7F000004, + /** + * @brief Nomadik YUV 422 macro block format, see B2R2 specification for details + */ + BLT_FMT_YUV422_PACKED_SEMIPLANAR_MB_STE = 0x7F000005, + /** + * @brief 1 bit per pixel alpha format + */ + BLT_FMT_1_BIT_A1 = 0x7F000006, + /** + * @brief 8 bit per pixel alpha format + */ + BLT_FMT_8_BIT_A8 = 0x7F000007, + /** + * @brief YUV planar format, organized with + * three separate planes, one for each color component, namely Y, U, and V. + * All planes use full resolution, there is no subsampling. + * The buffer shall contain a plane of Y, U, and V data in this order. + */ + BLT_FMT_YUV444_PACKED_PLANAR = 0x7F000008, + /** + * @brief YVU planar format, organized with a first plane containing Y + * pixels, and a second plane containing V and U pixels interleaved + * with the first V value first. V and U pixels are subsampled by + * a factor of two both horizontally and vertically. The buffer + * shall contain two planes, one with Y, and one with V and U data. + * (Same as B2R2 420 Raster 2 buffer - 420 R2B except that chroma + * order is swapped.) + */ + BLT_FMT_YVU420_PACKED_SEMI_PLANAR = 0x7F000009, + /** + * @brief YVU planar format, organized with a first plane containing Y + * pixels, and a second plane containing V and U pixels interleaved + * with the first V value first. V and U pixels are subsampled by + * a factor of two both horizontally. The buffer shall contain + * two planes, one with Y, and one with V and U data. + * (Same as B2R2 422 Raster 2 buffer - 422 R2B except that chroma + * order is swapped.) + */ + BLT_FMT_YVU422_PACKED_SEMI_PLANAR = 0x7F00000A, + /** + * @brief YVU planar format, organized with three separate planes, + * one for each color component, namely Y, V, and U. + * V and U pixels are subsampled by a factor of two + * both horizontally and vertically. + * The buffer shall contain a plane of Y, V, and U data in this + * order. (Same as BLT_FMT_YUV420_PACKED_PLANAR, except that chroma + * order is swapped.) + */ + BLT_FMT_YVU420_PACKED_PLANAR = 0x7F00000B, + /** + * @brief YVU planar format, organized with three separate planes, + * one for each color component, namely Y, V, and U. + * V and U pixels are subsampled by a factor of two horizontally. + * The buffer shall contain a plane of Y, V, and U data in this + * order. (Same as BLT_FMT_YUV422_PACKED_PLANAR except that chroma + * order is swapped.) + */ + BLT_FMT_YVU422_PACKED_PLANAR = 0x7F00000C, + /** + * @brief 24 bits per pixel VUY format with colors stored as + * V 23:16, U 15:8, and Y 7:0. + */ + BLT_FMT_24_BIT_VUY888 = 0x7F00000D, + /** + * @brief 32 bits per pixel VUYA format with colors stored as + * V 31:24, U 23:16, Y 15:8, and Alpha 7:0. + */ + BLT_FMT_32_BIT_VUYA8888 = 0x7F00000E, +}; + + +/** + * @brief Specifies a buffer pointer + */ +enum blt_ptr_type { + /** + * @brief No pointer (NULL). E.g. src fill. + */ + BLT_PTR_NONE, + /** + * @brief Use offset as a userspace virtual address + */ + BLT_PTR_VIRTUAL, + /** + * @brief Use offset as a physical address + */ + BLT_PTR_PHYSICAL, + /** + * @brief Use fd and offset to determine buffer location. + */ + BLT_PTR_FD_OFFSET, + /** + * @brief Use hwmem_buf_name and offset to determine buffer location. + */ + BLT_PTR_HWMEM_BUF_NAME_OFFSET, +}; + +/** + * @brief Specifies a buffer + */ +struct blt_buf { + /** + * @brief Pointer type + */ + enum blt_ptr_type type; + /** + * @brief Hwmem buffer name. + */ + int32_t hwmem_buf_name; + /** + * @brief File descriptor (e.g. file handle to a pmem device) + */ + int32_t fd; + /** + * @brief Offset where buffer can be found. When used in + * conjunction with a hwmem buffer the offset must be a multiple + * of the image size. If 'type' is set to BLT_PTR_VIRTUAL or + * BLT_PTR_PHYSICAL, then the offset is interpreted as an address. + */ + uint32_t offset; + /** + * @brief Size of buffer in bytes + */ + uint32_t len; + /** + * @brief Pointer to the bitmap data. This field can be used to specify + * an alternative way to access the buffer. Whenever the 'bits' pointer + * is set to non-NULL, the underlying implementation is free to decide + * whether or not to use it in favor of other ways to locate the buffer. + */ + void *bits; +}; + + +/** + * @brief Specifies a image + */ +struct blt_img { + /** + * @brief Pixel format of image + */ + enum blt_fmt fmt; + /** + * @brief Buffer pointer + */ + struct blt_buf buf; + /** + * @brief Width in pixels + */ + int32_t width; + /** + * @brief Height in pixels + */ + int32_t height; + /** + * @brief Pitch in bytes (set to zero for default based on width) + */ + uint32_t pitch; +}; + + +/** + * @brief Specifies rotation and flipping, mutually exclusive + */ +enum blt_transform { + /** + * @brief No rotation or flip + */ + BLT_TRANSFORM_NONE = 0, + /** + * @brief Flip horizontally + */ + BLT_TRANSFORM_FLIP_H = 1, + /** + * @brief Flip vertically + */ + BLT_TRANSFORM_FLIP_V = 2, + /** + * @brief Rotate 90 degrees counter clockwise + */ + BLT_TRANSFORM_CCW_ROT_90 = 4, + /** + * @brief Rotate 180 degrees (same as flip horizontally together with flip + * vertically) + */ + BLT_TRANSFORM_CCW_ROT_180 = 3, + /** + * @brief Rotate 270 degrees counter clockwise + */ + BLT_TRANSFORM_CCW_ROT_270 = 7, + /** + * @brief Flip horizontally and then rotate 90 degrees counter clockwise + */ + BLT_TRANSFORM_FLIP_H_CCW_ROT_90 = 5, + /** + * @brief Flip vertically and then rotate 90 degrees counter clockwise + */ + BLT_TRANSFORM_FLIP_V_CCW_ROT_90 = 6, +}; + + +/** + * @brief Flags that specifies the request to the blt_api + * + * Can be combined + */ +enum blt_flag { + /** + * @brief Asynchronous request. blt_request will return when the request + * has been queued. + */ + BLT_FLAG_ASYNCH = 0x1, + /** + * @brief Dry run, just to check if request can be performed. + */ + BLT_FLAG_DRY_RUN = 0x2, + /** + * @brief Enable per pixel alpha blend + * (assumes alpha is embedded in source pixel format). + */ + BLT_FLAG_PER_PIXEL_ALPHA_BLEND = 0x4, + /** + * @brief Enable global alpha blend (alpha value in global_alpha). + */ + BLT_FLAG_GLOBAL_ALPHA_BLEND = 0x8, + /** + * @brief Enable source color key (color in src_color). Color should + * be in raw format. + * + * BLT_FLAG_SOURCE_COLOR_KEY, BLT_FLAG_SOURCE_FILL and BLT_FLAG_SOURCE_FILL_RAW + * cannot be specified at the same time. BLT_FLAG_SOURCE_COLOR_KEY and + * BLT_FLAG_DEST_COLOR_KEY cannot be specified at the same time. + */ + BLT_FLAG_SOURCE_COLOR_KEY = 0x10, + /** + * @brief Enable ARGB/AYUV source fill (color in src_color). Which of + * ARGB and AYUV is determined by destination format. + * + * BLT_FLAG_SOURCE_COLOR_KEY, BLT_FLAG_SOURCE_FILL and BLT_FLAG_SOURCE_FILL_RAW + * cannot be specified at the same time. + */ + BLT_FLAG_SOURCE_FILL = 0x20, + /** + * @brief Enable raw source fill (color in src_color) + * + * BLT_FLAG_SOURCE_COLOR_KEY, BLT_FLAG_SOURCE_FILL and BLT_FLAG_SOURCE_FILL_RAW + * cannot be specified at the same time. + */ + BLT_FLAG_SOURCE_FILL_RAW = 0x40, + /** + * @brief Enable dest color key (color in dst_color). Color should be in raw format. + * BLT_FLAG_SOURCE_COLOR_KEY and BLT_FLAG_DEST_COLOR_KEY cannot be specified at the same time. + */ + BLT_FLAG_DEST_COLOR_KEY = 0x80, + /** + * @brief Source color not premultiplied (Valid only for formats with embedded alpha). + */ + BLT_FLAG_SRC_IS_NOT_PREMULT = 0x100, + /** + * @brief Enable dithering. + */ + BLT_FLAG_DITHER = 0x200, + /** + * @brief Enable blur. + */ + BLT_FLAG_BLUR = 0x400, + /** + * @brief Enable source mask. + */ + BLT_FLAG_SOURCE_MASK = 0x800, + /** + * @brief Enable destination clip rectangle. + */ + BLT_FLAG_DESTINATION_CLIP = 0x1000, + /** + * @brief Inherit process priority. + */ + BLT_FLAG_INHERIT_PRIO = 0x2000, + /** + * @brief Indicate that a background buffer for blend operation is supplied. + * + * B2R2_BLT_FLAG_PER_PIXEL_ALPHA_BLEND, B2R2_BLT_FLAG_SRC_IS_NOT_PREMULT, and + * B2R2_BLT_FLAG_GLOBAL_ALPHA_BLEND will control the blend operation. + */ + BLT_FLAG_BG_BLEND = 0x20000, + /** + * @brief Use color look-up table for color correction. + * Pointer to the table must be specified in *clut field of + * the b2r2_blt_req structure. + * The table must map all input color values + * for each channel to the desired output values. + * It is an array with the following format: + * R0 G0 B0 A0 R1 G1 B1 A1...R255 G255 B255 A255 + * where R0 is the 8 bit output value for red channel whenever its input + * equals 0. + * Similarly, R1 through R255 are the red channel outputs whenever + * the channel's inputs equal 1 through 255 respectively. + * Gn, Bn, An denote green, blue and alpha channel. + * Whenever the input bitmap format lacks the alpha channel, + * all alpha values in the color correction table should be set to 255. + * Size of the array that specifies the color correction table + * must be 1024 bytes. + * A table that does not change anything has the form: + * 0 0 0 0 1 1 1 1 2 2 2 2 ... 254 254 254 254 255 255 255 255. + * CLUT color correction can be applied to YUV raster buffers as well, + * in which case the RGB color channels are mapped onto YUV-space + * as follows: + * R = red chrominance + * G = luminance + * B = blue chrominance + * A = alpha + * If any of the planar or semi-planar formats is used, luminance cannot + * be changed by the color correction table. + */ + BLT_FLAG_CLUT_COLOR_CORRECTION = 0x80000000 +}; + +/** + * @brief Specifies a request to blt_api. + */ +struct blt_req { + /** + * @brief Size of this structure (used for versioning). Must be set to the size of this structure. + */ + uint32_t size; + /** + * @brief Flags that control the BLT request. + */ + enum blt_flag flags; + /** + * @brief Flip & rotate. + */ + enum blt_transform transform; + /** + * @brief Priority (-20 to 19). Inherits process prio + * if BLT_FLAG_INHERIT_PRIO is set. Given priority is mapped onto BLT. + * TBD: How? + */ + int32_t prio; + /** + * @brief Pointer to the look-up table for color correction. + */ + void *clut; + /** + * @brief Source image. Ignored when source fill is specified. + */ + struct blt_img src_img; + /** + * @brief Source mask image. Ignored when source fill is specified. + */ + struct blt_img src_mask; + /** + * @brief Source area to be blitted. + */ + struct blt_rect src_rect; + /** + * @brief Source fill color or color key. + */ + uint32_t src_color; + /** + * @brief Background image. + */ + struct blt_img bg_img; + /** + * @brief Background area to be blitted. + */ + struct blt_rect bg_rect; + /** + * @brief Destination image. + */ + struct blt_img dst_img; + /** + * @brief Destination area for the blit. + */ + struct blt_rect dst_rect; + /** + * @brief Destination clip rectangle. + */ + struct blt_rect dst_clip_rect; + /** + * @brief Destination color key. + */ + uint32_t dst_color; + /** + * @brief Global alpha value (0 - 255). + */ + uint8_t global_alpha; + /** + * @brief Callback function, will be called when request is finished. + * It will be called from another thread. May be NULL. + */ + void (*callback)(int request_id, uint32_t callback_data); + /** + * @brief Data to callback function. + */ + uint32_t callback_data; +}; + +/** + * @brief Capabilities that can be queried for. Capabilities can be queried + * for a specific format or for formats in general. To query for + * capabilities in general, specify BLT_FMT_UNUSED as format. + */ +enum blt_cap { + /** + * @brief Unused/unspecified capability. + */ + BLT_CAP_UNUSED = 0, + /** + * @brief Is format supported as source? + */ + BLT_CAP_FMT_SOURCE, + /** + * @brief Is format supported as source mask? + */ + BLT_CAP_FMT_SOURCE_MASK, + /** + * @brief Is format supported as destination? + */ + BLT_CAP_FMT_DEST, + /** + * @brief Is per pixel alpha blending supported with format as source? + */ + BLT_CAP_PER_PIXEL_ALPHA_BLEND, + /** + * @brief Is global alpha blending supported with format as source? + */ + BLT_CAP_GLOBAL_ALPHA_BLEND, + /** + * @brief Is source color key supported with format as source? + */ + BLT_CAP_SOURCE_COLOR_KEY, + /** + * @brief Is source fill supported with format as source? + */ + BLT_CAP_SOURCE_FILL, + /** + * @brief Is source fill raw supported with format as dest? + */ + BLT_CAP_SOURCE_FILL_RAW, + /** + * @brief Is dest color key supported with format as dest? + */ + BLT_CAP_DEST_COLOR_KEY, + /** + * @brief Is dithering supported with format as source? + */ + BLT_CAP_DITHER, + /** + * @brief Is blur supported with format as source? + */ + BLT_CAP_BLUR, + /** + * @brief Minification limit (copybit support). + */ + BLT_CAP_MINIFICATION_LIMIT, + /** + * @brief Magnification limit (copybit support). + */ + BLT_CAP_MAGNIFICATION_LIMIT, + /** + * @brief Number of scaling fractional bits (copybit support). + */ + BLT_CAP_SCALING_FRAC_BITS, + /** + * @brief Supported rotation step in degrees (copybit support). + */ + BLT_CAP_ROTATION_STEP_DEG, +}; + +/** + * The blt_open() function opens the blit library and returns + * a handle to it. + * + * @return Returns a handle to the blit library if >= 0, + * else a negative error code + * @retval -ESOMERROR Description of an error + * + * @see blt_close() + */ +int blt_open(void); + +/** + * The blt_close() function closes the blit library. + * + * @param [in] blt_handle Handle to the blit library. + * + * @return Returns nothing + * + * @see blt_open() + */ +void blt_close(int blt_handle); + +/** + * The blt_request() adds a blit request. + * + * blt_request() returns when the blit has been performed unless + * asynchronous execution has been specified. In that case, + * control is returned as soon as the request has been queued. + * + * @param [in] blt_handle Handle to the blit library. + * @param [in] req Blit request structure + * + * @return Returns a unique request id if >= 0, else a negative error code. + * This request id can be waited for using blt_synch(). + * @retval -ESOMERROR Description of an error + * + * @see blt_synch() + */ +int blt_request(int blt_handle, struct blt_req *req); + +/** + * blt_synch() waits for all or for a specific request to be finished. + * + * @param [in] blt_handle Handle to the blit library. + * @param [in] request_id Request id returned by blt_request or 0 to specify all + * requests. + * + * @return Returns 0 upon success, a negative error code otherwise. + * @retval -ESOMERROR Description of an error + * + * @see blt_request() + */ +int blt_synch(int blt_handle, int request_id); + +/** + * blt_query_cap() returns capability information for all or + * for a certain format + * + * @param [in] blt_handle Handle to the blit library. + * @param [in] fmt Format to query capabilities for or BLT_FMT_UNUSED to consider + * all formats. + * @param [in] capability Capability to query for. + * @param [out] cap Returned capability. Interpretaion of this variable varies + * with the capability queried. + * + * @return Returns 0 upon success, a negative error code otherwise. + * @retval -ESOMERROR Description of an error + */ +int blt_query_cap(int blt_handle, + enum blt_fmt fmt, + enum blt_cap capability, + uint32_t *cap); + +#endif /* #ifdef _BLT_API_H */ + +#ifdef __cplusplus +} +#endif diff --git a/src/blt_b2r2.c b/src/blt_b2r2.c new file mode 100644 index 0000000..1d3e55f --- /dev/null +++ b/src/blt_b2r2.c @@ -0,0 +1,309 @@ +/* + * Copyright (C) ST-Ericsson AB 2009 - All rights reserved + * Reproduction and Communication of this document is strictly prohibited + * unless specifically authorized in writing by ST-Ericsson + * + * \file blt_b2r2.c + * \brief Android driver for B2R2 hardware + * \author ST-Ericsson + * + */ + +#include <blt_api.h> + +#include <sys/ioctl.h> +#include <fcntl.h> +#include <errno.h> +#include <pthread.h> +#include <poll.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <unistd.h> + +#include <video/b2r2_blt.h> + +#define LOG_TAG "libblt_hw" + +#ifdef ANDROID +# include <cutils/log.h> +# define LOGE2(...) LOGE(__VA_ARGS__) +# define LOGI2(...) LOGI(__VA_ARGS__) +#else +# define LOGE(format) fprintf(stderr, LOG_TAG format "\n") +# define LOGE2(format, ...) fprintf(stderr, LOG_TAG format "\n", __VA_ARGS__) +# define LOGI(format) printf(LOG_TAG format "\n") +# define LOGI2(format, ...) printf(LOG_TAG format "\n", __VA_ARGS__) +#endif + +#define B2R2_BLT_DEV "/dev/b2r2_blt" + +enum thread_event { + EVENT_NONE = 0, + EVENT_HANDLE_TERMINATED = 1, + EVENT_REQUEST_CALLBACK = 2 +}; + +struct blt_b2r2_data { + int fd; + pthread_t callback_thread; + pthread_cond_t event_cond; + pthread_mutex_t event_mutex; + volatile enum thread_event event; + volatile int number_reports; +}; + +#define DATAS_START_SIZE 10 +#define DATAS_GROW_SIZE 5 +static struct blt_b2r2_data **datas = NULL; +static int data_count = 0; + +static int grow_datas(void) +{ + struct blt_b2r2_data **new_datas = NULL; + int new_data_count = data_count + DATAS_GROW_SIZE; + + new_datas = malloc(new_data_count*sizeof(*new_datas)); + if (new_datas == NULL) { + LOGE("Out of memory!"); + errno = -ENOMEM; + goto error; + } + + memset(new_datas, 0, new_data_count*sizeof(*new_datas)); + memcpy(new_datas, datas, data_count*sizeof(*datas)); + + free(datas); + + data_count = new_data_count; + datas = new_datas; + + return 0; + +error: + return -1; +} + +static int get_handle(struct blt_b2r2_data *data) { + int handle; + + if (datas == NULL) { + + datas = malloc(DATAS_START_SIZE*sizeof(*datas)); + if (datas == NULL) { + LOGE("Out of memory!\n"); + errno = -ENOMEM; + goto error; + } + + data_count = DATAS_START_SIZE; + memset(datas, 0, data_count*sizeof(*datas)); + } + + for (handle = 0; handle < data_count; handle++) { + if (datas[handle] == NULL) { + datas[handle] = data; + break; + } + + if (handle == data_count - 1) { + if (grow_datas() < 0) + goto error; + } + } + + return handle; + +error: + return -1; +} + +static struct blt_b2r2_data *get_data(int handle) { + if (handle >= data_count || handle < 0) + return NULL; + else + return datas[handle]; +} + +static void free_handle(int handle) { + if (handle < data_count && handle >= 0) { + datas[handle] = NULL; + } +} + +static void *callback_thread_run(void *arg) +{ + struct blt_b2r2_data *data = (struct blt_b2r2_data *) arg; + int number_reports = 0; + + while (1) { + enum thread_event event; + struct b2r2_blt_report report; + + /* Read parent command */ + pthread_mutex_lock(&data->event_mutex); + if (data->event == EVENT_NONE) + pthread_cond_wait(&data->event_cond, &data->event_mutex); + event = data->event; + number_reports += data->number_reports; + data->event = EVENT_NONE; + data->number_reports = 0; + pthread_mutex_unlock(&data->event_mutex); + + while (number_reports > 0) { + ssize_t count; + memset(&report, 0, sizeof(report)); + count = read(data->fd, &report, sizeof(report)); + if (count < 0) { + LOGE2("Pt%d: Could not read report from b2r2 (%s)", + data->fd, strerror(errno)); + goto thread_exit; + } else if (report.report1 != 0) { + void (*callback)(int, uint32_t) = (void*)report.report1; + callback(report.request_id, (uint32_t)report.report2); + number_reports--; + } + } + + if (event == EVENT_HANDLE_TERMINATED) { + goto thread_exit; + } + } + +thread_exit: + if (number_reports) { + LOGE2("Pt%d: Exit with outstanding reports: %d", + data->fd, number_reports); + } + + return NULL; +} + +int blt_open(void) +{ + struct blt_b2r2_data *data = NULL; + int fd; + int handle; + + fd = open(B2R2_BLT_DEV, O_RDWR); + if (fd < 0) { + LOGE2("Could not open device %s", B2R2_BLT_DEV); + goto error; + } + + data = malloc(sizeof(struct blt_b2r2_data)); + if (data == NULL) { + LOGE("Out of memory"); + goto error; + } + + memset(data, 0, sizeof(*data)); + + data->fd = fd; + data->callback_thread = -1; + data->event = EVENT_NONE; + data->number_reports = 0; + pthread_cond_init(&data->event_cond, NULL); + pthread_mutex_init(&data->event_mutex, NULL); + + handle = get_handle(data); + if (handle < 0) + goto error_free; + + pthread_create(&data->callback_thread, NULL, callback_thread_run, + (void *)data); + + LOGI2("Library opened (handle = %d, fd = %d)", handle, fd); + + return handle; + +error_free: + free(data); +error: + return -1; +} + +void blt_close(int blt_handle) +{ + struct blt_b2r2_data *data = get_data(blt_handle); + + if (data == NULL) + goto out; + + if (data->callback_thread > 0) { + pthread_mutex_lock(&data->event_mutex); + data->event = EVENT_HANDLE_TERMINATED; + pthread_cond_signal(&data->event_cond); + pthread_mutex_unlock(&data->event_mutex); + pthread_join(data->callback_thread, NULL); + } + + pthread_mutex_destroy(&data->event_mutex); + pthread_cond_destroy(&data->event_cond); + close(data->fd); + + LOGI2("Library closed (handle = %d, fd = %d)", + blt_handle, data->fd); + free_handle(blt_handle); + free(data); +out: + return; +} + +int blt_request(int blt_handle, struct blt_req *req) +{ + struct blt_b2r2_data *data = get_data(blt_handle); + int ret; + + if (data == NULL) { + errno = EINVAL; + ret = -1; + goto out; + } + + if (req->callback != NULL) { + req->flags |= B2R2_BLT_FLAG_REPORT_WHEN_DONE; +#ifdef BLT_B2R2_DEBUG_PERFORMANCE + req->flags |= B2R2_BLT_FLAG_REPORT_PERFORMANCE; +#endif + } + + ret = ioctl(data->fd, B2R2_BLT_IOC, (struct b2r2_blt_req *) req); + if (ret < 0) + goto out; + + if (req->callback != NULL) { + /* Tell callback worker that there will be a report + * to read */ + pthread_mutex_lock(&data->event_mutex); + data->event = EVENT_REQUEST_CALLBACK; + data->number_reports++; + pthread_cond_signal(&data->event_cond); + pthread_mutex_unlock(&data->event_mutex); + } + +out: + return ret; +} + +int blt_synch(int blt_handle, int request_id) +{ + struct blt_b2r2_data *data = get_data(blt_handle); + + if (data == NULL) { + errno = EINVAL; + return -1; + } + + return ioctl(data->fd, B2R2_BLT_SYNCH_IOC, request_id); +} + +int blt_query_cap(int blt_handle, + enum blt_fmt fmt, + enum blt_cap capability, + uint32_t *cap) +{ + LOGE("blt_query_cap not implemented yet"); + errno = ENOSYS; + return -1; +} diff --git a/ste-info/toc-locations.xml b/ste-info/toc-locations.xml new file mode 100755 index 0000000..aa7d4d6 --- /dev/null +++ b/ste-info/toc-locations.xml @@ -0,0 +1,8 @@ +<?xml version="1.0" encoding="utf-8"?>
+<toc xmlns="http://www.stericsson.com/refman/API_Toc.xsd" label="API">
+ <topic label="Multimedia">
+ <topic label="User space">
+ <topic label="bltlib" href="../include"/>
+ </topic>
+ </topic>
+</toc>
diff --git a/ste-info/userspace_std_api_b2r2lib.xml b/ste-info/userspace_std_api_b2r2lib.xml new file mode 100755 index 0000000..1aa31cd --- /dev/null +++ b/ste-info/userspace_std_api_b2r2lib.xml @@ -0,0 +1,354 @@ +<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<book id="userspace_std_api_bltlib">
+ <bookinfo>
+ <title>bltlib
+ </title>
+
+ <copyright>
+ <year>2010</year>
+ <holder>ST-Ericsson AB</holder>
+ </copyright>
+
+ </bookinfo>
+
+ <toc></toc>
+
+ <chapter id="intro">
+ <title>Introduction</title>
+ <!-- Do NOT change the chapter id or title! -->
+ <para>
+ bltlib is a library and API towards the device driver for the B2R2 graphics hardware. + <!-- Do NOT change the chapter id or title!
+
+ For numbered lists, outside of the para tag,
+ use the tags
+ (orderedlist)
+ (listitem)(para) ... (/para)(/listitem)
+ ...
+ (listitem)(para) ... (/para)(/listitem)
+ (orderedlist)
+
+ For a bulleted list, outside of the para tag,
+ use the tags
+ (itemizedlist)
+ (listitem)(para) ... (/para)(/listitem)
+ ...
+ (listitem)(para) ... (/para)(/listitem)
+ (itemizedlist)
+
+ For a table, outside of the para tag,
+ use the tags
+ (table)
+ (title) ... (title)
+ (tgroup cols="number_of_columns")(tbody)
+ (row)(entry) ... (/entry) (entry) ... (/entry) (/row)
+ (row)(entry) ... (/entry) (entry) ... (/entry) (/row)
+ (/tbody)(/tgroup)
+ (/table)
+
+ To omit the title for the table, use (informaltable)
+ instead of (table).
+
+ For hyper-links, use (ulink) tag.
+
+ Avoid duplicating information into this chapter
+ that is better located in the UML model. -->
+ </para>
+ </chapter>
+
+ <chapter id="conformance-description">
+ <title>Conformance Description</title>
+ <!-- Do NOT change the chapter id or title! -->
+ <section id="conformance-description-intro">
+ <title>Introduction</title>
+
+ <para>This chapter describes conformance and implementation-defined
+ behaviour of the module.</para>
+ </section>
+
+ <section id="conformance-description-references">
+ <title>References</title>
+ <!-- Do NOT change the section id or title! -->
+
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Title</entry>
+ <entry>Web Link</entry>
+ </row>
+ </thead>
+ <tbody>
+ <!-- EXAMPLE:
+ <row>
+ <entry>OpenGL ES 1.1 - April 4, 2007 </entry>
+
+ <entry><ulink
+ url="http://www.khronos.org/registry/gles/specs/1.1/es_full_spec.1.1.10.pdf">http://www.khronos.org/registry/gles/specs/1.1/es_full_spec.1.1.10.pdf
+ </ulink></entry>
+ </row>
+ -->
+
+ <row>
+ <entry>OpenMAX AL 1.0.1</entry>
+
+ <entry><ulink
+ url="http://www.khronos.org/registry/omxal/">Khronos registry (OpenMAX AL)
+ </ulink></entry>
+ </row> -->
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section>
+ <section id="conformance-description-function-conformance">
+ <title>Function Conformance</title>
+ <!-- Do NOT change the section id or title! -->
+ <para>
+ TODO: For each function or set of functions,
+ supply one row indicating functions,
+ the header file defining the function
+ and the level of implementation support
+ provided by the platform.
+
+ A conformance description describes which features,
+ interfaces of the standard that are supported or not
+ supported.
+
+ While the UML model may reference features,
+ or featuresets or functionality, in the broad sence,
+ this table must explicitly list all functions or other
+ means of controlling the API, so that a developer
+ knows for each and every function if the function is
+ implemented or not.
+
+ All header files that defines functions
+ must be listed and linked using (ulink), and also
+ referenced in the toc-locations.xml file.
+
+ What is stated about functions, is also valid if the module
+ implements an API in another way, such as using methods,
+ operations or signals.
+
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Functions</entry>
+ <entry>Header File</entry>
+ <entry>Description/Conformance</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>All functions</entry>
+ <entry><ulink url="includes/blt_api.h">blt_api.h</ulink></entry>
+ <entry>Functions/Functionality are fully implemented</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ See Implementation Description for implementation-defined behaviour.
+ </para>
+ </section>
+ </chapter>
+
+ <chapter id="implementation-description">
+ <title>Implementation Description</title>
+ <!-- Do NOT change the chapter id or title! -->
+
+ <section id="implementation-description-details">
+ <title>Implementation details</title>
+ <!-- Do NOT change the section id or title! -->
+
+ <para> + The client fills in a blt_req struct with all of the information required for the + blitting job. + + The request method then submits the job to the blitting driver and hardware. + The driver analyzes the job and splits it into the required nodes. + If the job is run in synchronous mode, the request method returns only when the + job has been completed (or has failed). If the job is run in asynchronous mode, + the request method returns immediately. The client can use the synch method to + wait for completion. + + When a client sends a request to bltlib, the job is sorted into a prioritized queue. + When the job can acquire the resources it needs, it is dispatched to the blitting hardware. + +<!-- TODO: Description of which features, interfaces of the standard
+ that are supported or vice versa.
+ Describe the behavior of the implementation for
+ implementation-specific features.
+
+ An implementation description describes the behavior of the
+ implementation of implementation-specific features.
+ An implementation-specific feature is a feature that the
+ standard does not fully specify or is specifically left up to
+ the implementer. All implementation-specific behavior must be
+ documented to make the interface usable.
+ The implementation description also needs to include sizes
+ or values that are specific to the implementation.
+
+ Other implementation-specific information that may need to be
+ included is limitations that are brought on by platform
+ hardware or software constraints. These constraints change the
+ standard behavior of the specified functionality and may impact
+ the software accessing the functionality.
+
+ Not every standard interface is exposed to the customer's
+ domains. Some interfaces are interfaces between platform
+ components and only documented in platform internal reference
+ manuals.
+
+ What to disclose in the documentation about an implementation
+ is generally quite limited. Only information that the user needs
+ to know about the implementation is to be described.
+ Restrict the documentation to phenomena that are externally
+ visible. Once information is exposed, other elements may rely
+ on it, and changes to the internal implementation will have a
+ more widespread effect. Avoid documenting more than is necessary.
+
+ While the UML model may reference features,
+ or featuresets or functionality, in the broad sence,
+ this table must explicitly list all functions or other
+ means of controlling the API that has been modified, extended or added,
+ so that a developer knows for each and every function
+ that the function does not execute in the same way as it
+ would do if implemented by another vendor than ST-Ericsson.
+
+ For functions added to the standard, ensure they are
+ documented in the relevant header file, using the documentation
+ format used by the standard, or doxygen, if the standard's
+ header files does not include any documentation.
+
+ Ensure that any header files added by ST-Ericsson is linked
+ to using (ulink), and that they are referenced in the
+ toc-locations.xml file.
+
+ What is stated about functions, is also valid if the module
+ implements an API in another way, such as using methods,
+ operations or signals.
+
+ Use an (informaltable) to specify details on function-by
+ function-level. -->
+ </para>
+
+<!-- <para>EXAMPLE: ST-Ericsson provides the ARM reference implementation.</para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Functions</entry>
+ <entry>Header File</entry>
+ <entry>Description/Conformance</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry><emphasis>TODO Modify example below</emphasis></entry>
+ </row>
+ <row>
+ <entry>g_function()</entry>
+ <entry><ulink url="includes/another_include_file.h">another_include_file.h</ulink></entry>
+ <entry>The function returns ... .
+ Restriction: The function can only be used ... .
+ </entry>
+ </row>
+ <row>
+ <entry>h_ste_function()</entry>
+ <entry><ulink url="includes/another_include_file.h">another_include_file.h</ulink></entry>
+ <entry>This function is an STE-extension to the standard.
+ </entry>
+ </row>
+ <row>
+ <entry>All functions</entry>
+ <entry><ulink url="includes/ste_extensions.h">ste_extensions.h</ulink></entry>
+ <entry>All functions in this file are STE-extensions to the standard.
+ </entry>
+ </row>
+ <row>
+ <entry>TODO: List functions</entry>
+ <entry><ulink
+ url="includes/an_include_file.h">
+ Provide a link using the ulink tag to the header file,
+ Ensure the url matches what is specified in
+ the toc_location.xml file using the
+ (includefile) or (includedirectory) elementsd in that
+ file.
+ </ulink></entry>
+ <entry>TODO: Describe extensions, restrictions, additions and
+ implementation-specific details.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable> -->
+ </section>
+
+ <section id="implementation-description-supported-versions">
+ <title>Supported versions</title>
+ <!-- Do NOT change the section id or title! -->
+
+ <para>This section specifies the supported versions of the module. </para>
+
+ <para>
+ bltlib supports only a subset of the bitmap formats defined by OpenMAX, + due to limitations in the blitting hardware. +
+<!-- TODO: Specify the supported versions
+
+ The conformance description can also
+ describe the conformance degree (or level)
+ according to a definition given by the reference manual
+ or by the standard.
+
+ Standard interfaces can be implemented in more than one
+ place in the architecture. In those cases, the behavior
+ of the implementations can differ. Several coexisting
+ implementations affect the documentation.
+
+ If suitable, different implementations are documented by
+ the same category. The documentation shall clearly describe
+ that there are different implementations and the differences
+ between them. The differences between implementations are
+ expected to be small. -->
+ </para>
+ <para></para>
+ </section>
+ </chapter>
+
+ <chapter id="specifications">
+ <title>Specifications</title>
+ <!-- Do NOT change the chapter id or title! -->
+ <para> + bltlib does not implement a standard specification but defines its own API. + Still, it borrows from some of the data types used in OpenMAX.
+ </para>
+ + <row>
+ <entry>OpenMAX AL 1.0.1</entry>
+
+ <entry></entry>
+ </row> -->
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink
+ url="http://www.khronos.org/registry/omxal/">Khronos registry (OpenMAX AL)
+ </ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </chapter>
+
+</book>
|