ARM Mali Application Developer BestPractices
Copyright 2017 ARM Limited or its affiliates. All rights reserved.ARM 100971_0100_02_en
ARM Mali Application Developer Best PracticesDeveloper GuideCopyright 2017 ARM Limited or its affiliates. All rights reserved.
Issue Date Confidentiality Change
0100-00 27 February 2017 Non-Confidential First release for version 1
0100-01 06 March 2017 Non-Confidential Second release for version 1
0100-02 17 March 2017 Non-Confidential Third release for version 1
Non-Confidential Proprietary Notice
This document is protected by copyright and other related rights and the practice or implementation of the information contained inthis document may be protected by one or more patents or pending patent applications. No part of this document may bereproduced in any form by any means without the express prior written permission of ARM. No license, express or implied, byestoppel or otherwise to any intellectual property rights is granted by this document unless specifically stated.
Your access to the information in this document is conditional upon your acceptance that you will not use or permit others to usethe information for the purposes of determining whether implementations infringe any third party patents.
THIS DOCUMENT IS PROVIDED AS IS. ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES,EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OFMERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSEWITH RESPECT TO THE DOCUMENT. For the avoidance of doubt, ARM makes no representation with respect to, and hasundertaken no analysis to identify or understand the scope and content of, third party patents, copyrights, trade secrets, or otherrights.
This document may include technical inaccuracies or typographical errors.
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES,INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, ORCONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISINGOUT OF ANY USE OF THIS DOCUMENT, EVEN IF ARM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCHDAMAGES.
This document consists solely of commercial items. You shall be responsible for ensuring that any use, duplication or disclosure ofthis document complies fully with any relevant export laws and regulations to assure that this document or any portion thereof isnot exported, directly or indirectly, in violation of such export laws. Use of the word partner in reference to ARMs customers isnot intended to create or refer to any partnership relationship with any other company. ARM may make changes to this document atany time and without notice.
If any of the provisions contained in these terms conflict with any of the provisions of any signed written agreement covering thisdocument with ARM, then the signed written agreement prevails over and supersedes the conflicting provisions of these terms.This document may be translated into other languages for convenience, and you agree that if there is any conflict between theEnglish version of this document and any translation, the terms of the English version of the Agreement shall prevail.
Words and logos marked with or are registered trademarks or trademarks of ARM Limited or its affiliates in the EU and/orelsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respectiveowners. Please follow ARMs trademark usage guidelines at http://www.arm.com/about/trademark-usage-guidelines.php
Copyright 2017, ARM Limited or its affiliates. All rights reserved.
ARM Limited. Company 02557590 registered in England.
110 Fulbourn Road, Cambridge, England CB1 9NJ.
ARM Mali Application Developer Best Practices
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 2Non-Confidential
This document is Non-Confidential. The right to use, copy and disclose this document may be subject to license restrictions inaccordance with the terms of the agreement entered into by ARM and the party that ARM delivered this document to.
Unrestricted Access is an ARM internal classification.
The information in this document is Final, that is for a developed product.
ARM Mali Application Developer Best Practices
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 3Non-Confidential
ContentsARM Mali Application Developer Best PracticesDeveloper Guide
PrefaceAbout this book ...................................................... ...................................................... 6Feedback ...................................................................................................................... 8
Chapter 1 Application development best practices for Mali GPUs1.1 Application developer best practices for Mali GPUs ....................... ....................... 1-10
Appendix A RevisionsA.1 Revisions ................................................... ................................................... Appx-A-12
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 4Non-Confidential
This preface introduces the ARM Mali Application Developer Best Practices Developer Guide.
It contains the following: About this book on page 6. Feedback on page 8.
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 5Non-Confidential
About this bookThis book is for the ARM Mali Application Developer Best Practices for Mali GPUs.
Product revision status
The rmpn identifier indicates the revision status of the product described in this book, for example, r1p2,where:
rm Identifies the major revision of the product, for example, r1.pn Identifies the minor revision or modification status of the product, for example, p2.
This book is for application developers who are developing for the Mali GPU.
Using this book
This book is organized into the following chapters:
Chapter 1 Application development best practices for Mali GPUsThis chapter introduces best practices for ARM Mali GPUs.
Appendix A RevisionsThis appendix describes the changes between released issues of this book.
The ARM Glossary is a list of terms used in ARM documentation, together with definitions for thoseterms. The ARM Glossary does not contain terms that are industry standard unless the ARM meaningdiffers from the generally accepted meaning.
See the ARM Glossary for more information.
italicIntroduces special terminology, denotes cross-references, and citations.
boldHighlights interface elements, such as menu names. Denotes signal names. Also used for termsin descriptive lists, where appropriate.
monospaceDenotes text that you can enter at the keyboard, such as commands, file and program names,and source code.
monospaceDenotes a permitted abbreviation for a command or option. You can enter the underlined textinstead of the full command or option name.
monospace italicDenotes arguments to monospace text where the argument is to be replaced by a specific value.
monospace boldDenotes language keywords when used outside example code.
Encloses replaceable terms for assembler syntax where they appear in code or code fragments.For example:
MRC p15, 0, , , ,
Used in body text for a few terms that have specific technical meanings, that are defined in theARM Glossary. For example, IMPLEMENTATION DEFINED, IMPLEMENTATION SPECIFIC, UNKNOWN, andUNPREDICTABLE.
Preface About this book
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 6Non-Confidential
Additional reading - appdev
Information published by ARM and by third parties.
See http://infocenter.arm.com for access to ARM documentation.
ARM publicationsThis book contains information that is specific to this product. See the following documents forother relevant information:Developer resources:
Preface About this book
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 7Non-Confidential
Feedback on this product
If you have any comments or suggestions about this product, contact your supplier and give: The product name. The product revision or version. An explanation with as much information as you can provide. Include symptoms and diagnostic
procedures if appropriate.
Feedback on content
If you have comments on content then send an e-mail to firstname.lastname@example.org. Give:
The title ARM Mali Application Developer Best Practices Developer Guide. The number ARM 100971_0100_02_en. If applicable, the page number(s) to which your comments refer. A concise explanation of your comments.
ARM also welcomes general suggestions for additions and improvements. Note
ARM tests the PDF only in Adobe Acrobat and Acrobat Reader, and cannot guarantee the quality of therepresented document when used with any other PDF reader.
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 8Non-Confidential
Chapter 1Application development best practices for MaliGPUs
This chapter introduces best practices for ARM Mali GPUs.
It contains the following section: 1.1 Application developer best practices for Mali GPUs on page 1-10.
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 1-9Non-Confidential
1.1 Application developer best practices for Mali GPUsThis information is for the expert developer audience, familiar with Vulkan and OpenGL ES APIprogramming. The technical details given here are for information only. Use with care.
A graphics system can be represented as a pipeline of stages, performance problems can arise in each ofthese stages.
At each stage we outline topics of interest. Each topic has a detailed explanation, with actionable "dos"and "don'ts" which should be considered in application development. In addition to the dos and don'ts,we state the impact of failing to follow that topic's best practice and include debugging advice which canbe used to troubleshoot each performance issue.
Each topic contains an anchor link to a justification which explains the recommendation.
1 Application development best practices for Mali GPUs1.1 Application developer best practices for Mali GPUs
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved. 1-10Non-Confidential
Application Developer Best Practices for Mali GPUs
System level overview
A graphics system can be represented as a pipeline of stages, performance problems can arisein each of these stages. At each stage we outline topics of interest. Each topic has a detailedexplanation, with actionable "dos" and "don'ts" which should be considered in applicationdevelopment. In addition to the dos and don'ts, we state the impact of failing to follow thattopic's best practice and include debugging advice which can be used to troubleshoot eachperformance issue. Each topic contains an anchor link to a justification which explains therecommendation.
CPU - Driver mapping and unmapping memory
Vulkan adds support for far more sophisticated buffer mapping implementations compared toOpenGL ES. Multiple memory types with different caching mechanisms are exposed, as well asbeing able to persistently map memory in to the CPU address space.
The Mali driver exposes 3 memory types on Midgard architecture GPUs:
DEVICE_LOCAL_BIT | HOST_VISIBLE_BIT | HOST_COHERENT_BITDEVICE_LOCAL_BIT | HOST_VISIBLE_BIT | HOST_CACHED_BITDEVICE_LOCAL_BIT | LAZILY_ALLOCATED_BIT
On Bifrost architecture GPUs, the following memory types are exposed:
DEVICE_LOCAL_BIT | HOST_VISIBLE_BIT | HOST_COHERENT_BITDEVICE_LOCAL_BIT | HOST_VISIBLE_BIT | HOST_COHERENT_BIT |HOST_CACHED_BITDEVICE_LOCAL_BIT | LAZILY_ALLOCATED_BIT
These four different types serve different purposes.
Coherent, not cached
This is the default memory type as HOST_VISIBLE | COHERENT is guaranteed to besupported. It is great for streaming out data to GPU buffers since write-combine in ARM CPUscan buffer up small bursts of write-outs which go straight to memory, so for passing data fromthe application to the GPU it is the most appropriate buffer type.
While write-out from CPU is great even without host caching, readbacks in to the CPUdesperately need cached memory. Throughput for cached readbacks with havememcpy()been observed to be 10x faster due to the ability prefetch in to the CPU cache. However, in thiscase since the memory is incoherent, manual cache management is required to ensure that theCPU and GPU always correctly access the current version of the data. To write to incoherentmemory from CPU vkFlushMappedRanges is required, and vkInvalidateMappedRanges isrequired back data from GPU.to safely read
Cached and coherent
This memory type is supported by Bifrost only, but requires the chip memory system toimplement full coherency so many not always be available. In this mode memory coherency as
expert developer audience, familiar with Vulkan andThis information is for the OpenGL ES API programming. The technical details given here are forinformation only. Use with care.
This section is Vulkan only.
ARM 100971_0100_02_en Copyright 2017 ARM Limited or its affiliates. All rights reserved.Non-Confidential
well as CPU caching are enabled, which means no manual cache management is necessary,and the use of cache means that CPU readback performance is also optimal.
Coherency has a small power cost, so we prefer uncached, incoherent for data which is neverread back onto the CPU.
This is a memory type designed to only be backed by virtual address space and never physicalmemory since the memory should never be normally accessed. This is intended for resourceswhich live entirely in the tile-buffer such as G-buffer attachments and depth/stencil buffers. If thememory is written to for some reason, the memory will be backed when it's accessed, but thiscould create stalls.
Use HOST_VISIBLE | COHERENT . to stream out data from CPU to GPU #JUST24Use HOST_VISIBLE | COHERENT to back static GPU resources. #JUST24 #JUST9Use HOST_VISIBLE | CACHED to back memory which will be read by the CPU,including the COHERENT flag if the host system supports it. #JUST24If writing to non-cached memory use or make sure your writes arememcpy()contiguous to get best efficiency from the CPU write-combine unit. #JUST24Persistently map CPU visible buffers which are accessed often (uniform buffer databuffers, vertex data streaming); mapping and unma...