Google Git
Sign in
fuchsia / third_party / github.com / intel / libva / c28c0d34c298f759230bdd4e5ecfee36beb9d359 / . / group__api__prot.html
blob: 05247728aae388770eea0f0574e0fe4cec0f2e97 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>VA-API: Protected content API</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">VA-API
&#160;<span id="projectnumber">2.13.0.pre1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="summary">
<a href="#nested-classes">Classes</a> &#124;
<a href="#typedef-members">Typedefs</a> &#124;
<a href="#enum-members">Enumerations</a> &#124;
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Protected content API</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structVAProtectedSessionBuffer.html">VAProtectedSessionBuffer</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Input/Output buffer of <a class="el" href="structVAProtectedSessionExecuteBuffer.html" title="Buffer for vaProtectedSessionExecute() ">VAProtectedSessionExecuteBuffer</a>. <a href="structVAProtectedSessionBuffer.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structVAProtectedSessionExecuteBuffer.html">VAProtectedSessionExecuteBuffer</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Buffer for <a class="el" href="group__api__prot.html#ga3aa87ed9c82cf09a4c90c6285af6357b" title="Execute provides a general mechanism for TEE client tasks execution. ">vaProtectedSessionExecute()</a> <a href="structVAProtectedSessionExecuteBuffer.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:ga092a2c03eb3f5be8262590aca3b049cf"><td class="memItemLeft" align="right" valign="top">typedef <a class="el" href="group__api__core.html#gab3ee763380573fdd05464ca16cf46d1d">VAGenericID</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a></td></tr>
<tr class="separator:ga092a2c03eb3f5be8262590aca3b049cf"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:ga12ebbce16beeeed9cfbf2f409be7ddc3"><td class="memItemLeft" align="right" valign="top"><a id="ga12ebbce16beeeed9cfbf2f409be7ddc3"></a>enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#ga12ebbce16beeeed9cfbf2f409be7ddc3">VA_TEE_EXECUTE_FUNCTION_ID</a> <tr class="memdesc:ga12ebbce16beeeed9cfbf2f409be7ddc3"><td class="mdescLeft">&#160;</td><td class="mdescRight">TEE Execucte Function ID. <br /></td></tr>
</td></tr>
<tr class="separator:ga12ebbce16beeeed9cfbf2f409be7ddc3"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gaeca36080858922da2bedd4298c6b07f8"><td class="memItemLeft" align="right" valign="top">VAStatus&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#gaeca36080858922da2bedd4298c6b07f8">vaCreateProtectedSession</a> (<a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a> dpy, VAConfigID config_id, <a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a> *protected_session)</td></tr>
<tr class="memdesc:gaeca36080858922da2bedd4298c6b07f8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Create a protected session. <a href="#gaeca36080858922da2bedd4298c6b07f8">More...</a><br /></td></tr>
<tr class="separator:gaeca36080858922da2bedd4298c6b07f8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga9c531a9f026f22d71b7900a9c375817b"><td class="memItemLeft" align="right" valign="top">VAStatus&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#ga9c531a9f026f22d71b7900a9c375817b">vaDestroyProtectedSession</a> (<a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a> dpy, <a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a> protected_session)</td></tr>
<tr class="memdesc:ga9c531a9f026f22d71b7900a9c375817b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destroy a protected session. <a href="#ga9c531a9f026f22d71b7900a9c375817b">More...</a><br /></td></tr>
<tr class="separator:ga9c531a9f026f22d71b7900a9c375817b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gad5a42586ce84a698ade0791a2a9ceb86"><td class="memItemLeft" align="right" valign="top">VAStatus&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#gad5a42586ce84a698ade0791a2a9ceb86">vaAttachProtectedSession</a> (<a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a> dpy, <a class="el" href="group__api__core.html#gab3ee763380573fdd05464ca16cf46d1d">VAGenericID</a> id, <a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a> protected_session)</td></tr>
<tr class="memdesc:gad5a42586ce84a698ade0791a2a9ceb86"><td class="mdescLeft">&#160;</td><td class="mdescRight">Attach a protected content session to VA context. <a href="#gad5a42586ce84a698ade0791a2a9ceb86">More...</a><br /></td></tr>
<tr class="separator:gad5a42586ce84a698ade0791a2a9ceb86"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gae7efc8bef99f742cdfdb4bddf519625e"><td class="memItemLeft" align="right" valign="top">VAStatus&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#gae7efc8bef99f742cdfdb4bddf519625e">vaDetachProtectedSession</a> (<a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a> dpy, <a class="el" href="group__api__core.html#gab3ee763380573fdd05464ca16cf46d1d">VAGenericID</a> id)</td></tr>
<tr class="memdesc:gae7efc8bef99f742cdfdb4bddf519625e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Detach the protected content session from the VA context. <a href="#gae7efc8bef99f742cdfdb4bddf519625e">More...</a><br /></td></tr>
<tr class="separator:gae7efc8bef99f742cdfdb4bddf519625e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga3aa87ed9c82cf09a4c90c6285af6357b"><td class="memItemLeft" align="right" valign="top">VAStatus&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__api__prot.html#ga3aa87ed9c82cf09a4c90c6285af6357b">vaProtectedSessionExecute</a> (<a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a> dpy, <a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a> protected_session, <a class="el" href="group__api__core.html#gad26441ddf2f4441ef65bbefa4662607f">VABufferID</a> buf_id)</td></tr>
<tr class="memdesc:ga3aa87ed9c82cf09a4c90c6285af6357b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Execute provides a general mechanism for TEE client tasks execution. <a href="#ga3aa87ed9c82cf09a4c90c6285af6357b">More...</a><br /></td></tr>
<tr class="separator:ga3aa87ed9c82cf09a4c90c6285af6357b"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h1><a class="anchor" id="prolouge"></a>
Prolouge</h1>
<p>Video streaming is ubiquitous and the support for video streaming is widely available across client open systems such as PCs, MACs, Chromebooks etc. and closed systems such as settop box, smart TVs, DVDs etc. By default, video streaming is not considered premium due to various constraints such as resolution, quality, production cost etc. but recently streaming of premium video(1080p+) has become norm. The streaming of premium video in open systems such as PCs, MACs, Chromebooks etc. makes video particularly susceptible to piracy (due to non-video playback usages of such systems) resulting in millions of dollars of loss to content creators.</p>
<p>Digital Rights Management(DRM) has been proposed to stop piracy of premium video streams across a wide spectrum. There are some known open/closed DRM standards such as <a href="https://www.widevine.com/">Widevine by Google</a>, <a href="https://www.microsoft.com/playready/">PlayReady by Microsoft</a>, <a href="https://developer.apple.com/streaming/fps/">FairPlay by Apple</a>, <a href="https://www.marlin-community.com/">Merlin by Sony</a>, etc... Each DRM standard has its properties but all DRM standards support a common mechanism. This common mechanism involves cryptographical method for authenticating the client system, delivering bitstream and required cryptographic assets to client system and then cryptographically processing bitstream in client system. The cryptographic methods used in these steps are asymmetric such as RSA, DH etc. and symmetric such as AES CTR, CBC etc. encryption mechanisms. The authentication of client system, delivery of bitstream and cryptographic assets to client system is performed using asymmetric cryptographic mechanism while bitstream is encrypted and processed using symmetric cryptographic. In DRM world, authentication of client system, delivery of bitstream and required cryptographic assets to client system is loosely called provisioning and license acquisition while the processing of cryptographically secure bitstream is divided as video decryption/decoding, audio decryption/playback, video display. Besides DRM standards, Video/Audio bitstream encryption standard such as <a href="https://www.iso.org/standard/76597.html">Common Encryption Standard(CENC)</a> provides a mechanism to normalize bitstream encryption methods across vendors while providing flexibility.</p>
<h1><a class="anchor" id="DRM"></a>
Pipeline</h1>
<p>Most DRM standards execute the following deep pipeline to playback contents on client systems from streaming servers - provisioning uses provisioning servers, licence aquisition uses license servers, video bitstream delivery uses content servers and decryption/decoding, audio bitstream delivery uses content servers and decyption/playback, display/playback. The system level HWDRM sequence diagram is following - </p><div class="image">
<img src="https://user-images.githubusercontent.com/75039699/102427278-df284e80-3fc5-11eb-9a3e-129b5f6b567a.png" alt="HWDRM sequence diagram"/>
</div>
<p> and HWDRM pipeline view is following - </p><div class="image">
<img src="https://user-images.githubusercontent.com/75039699/102427357-04b55800-3fc6-11eb-8b8c-f34fc44ec061.png" alt="HWDRM pipeline view"/>
</div>
<h1><a class="anchor" id="LibVA"></a>
Protected Content APIs</h1>
<p>The LibVA Protected APIs are designed to enable DRM capabilities or facilitate isolated communicaiton with TEE. The VAEntrypointProtectedTEEComm is to define interfaces for Application to TEE direct communication to perform various TEE centric operations such as standalone provisioning of platform at factory or provisioning TEE for other usages, providing TEE capabilities etc. The VAEntrypointProtectedContent is to define interfaces for protected video playback using HWDRM. This entry point co-ordinates assets across TEE/GPU/Display for HWDRM playback.</p>
<p>The difference between Protected Content and Protected TEE Communication is that Protected Content Entrypoint does not provide isolated entry point for TEE and invokes TEE only from HWDRM perspective.</p>
<p>Protected Content Entrypoint The most of DRM standards execute following deep pipeline to playback contents on client systems from streaming servers - provisioning uses provisioning servers, licence aquisition uses license servers, video bitstream delivery uses content servers and decryption/decoding, audio bitstream delivery uses content servers and decyption/playback, display/playback.</p>
<p>The Provisioning and License aquisition implementations are Independent Hardware Vendor (IHV) specific but most IHVs use some form of Trusted Execution Environment (TEE) to prepare client platform or system for DRM content playback. The provisioning operations use provisioning servers (as instructed in DRM standard) and client system TEE. The communication between provisioning servers and client system TEE uses asymmetic cryptographic mechanism. This step provides a way to establish root-of-trust between client system and streaming servers. Once root-of-trust is established then client system requests for license aquisition for a particular streaming title. The license aquisition involves communication between licensing servers and TEE using asymmetic cryptographic mechanism. At end of this step, client system TEE has required assets to decrypt/decode. Although these communication does not direcly involve video aspect of GPU but <b>facilitate GPU required assets to playback premium contents</b>.</p>
<p>To support DRM standard requirements in playback pipeline, OSes and HWs incorporate various methods to protect full playback pipeline. These methods of protection could be SW based or HW based. The SW based protection mechanism of DRMs is called SWDRM while HW based protection mechanism is called HWDRM. There is no previous support in LibVA to support either DRM mechanism.</p>
<p>For DRM capabilities, APIs inolve creation of protected session to communicate with TEE and then using these protected sessions to process video/audio data. The philophashy behind these API is to leverage existing LibVA infrastructure as much as possible.</p>
<p>Note: TEE could be any secure HW device such as ME-FW or FPGA Secure Enclave or NPU Secure Enclave. There are 2 concepts here – TEE Type such as ME-FW or FPGA or NPU; TEE Type Client such as for AMT or HDCP or something else etc.</p>
<h1><a class="anchor" id="description"></a>
Detailed Description</h1>
<p>The Protected content API provides a general mechanism for opening protected session with TEE and if required then <a class="el" href="group__api__prot.html#priming">Priming</a> GPU/Display. The behavior of protected session API depends on parameterization/ configuration of protected session. Just for TEE tasks, protected session is parameterized/configured as TEE Communication while for HWDRM, protected session is parameterized/confgured as Protected Content.</p>
<p>TEE Communication Entrypoint With TEE Communication parameterization/configuration, client executes TEE workloads in TEE with TEE Communication protected session.</p>
<p>Protected Content Entrypoint With Protected Content parameterization/configuration, client executes HWDRM playback workloads HW accelerating protected video content decryption/decoding with protected content session.</p>
<p>Before calling vaCreateProtectedSession, VAConfigID is obtained using existing libva mechanism to determine configuration parameters of protected session. The VAConfigID is determined in this way so that Protected Session implementation aligns with existing libva implementation. After obtaining VAConfigID, Protected Session needs to be created but note this is a session and not a context. Refer VAProtectedSessionID for more details.</p>
<p>Note:- Protected session represents session object that has all security information needed for Secure Enclave to operate certain operations.</p>
<h2><a class="anchor" id="priming"></a>
Priming</h2>
<p>Priming is used to refer various types of initializations. For example, if license acquisition is being performed then priming means that TEE is already provisioned aka TEE has some sort of "cryptographic" whitelist of servers that TEE will use to do license acquisition for video playback. If HWDRM video playback is being performed then priming means that HWDRM eco-system TEE/GPU/Display has proper keys to do proper video playback etc.</p>
<p>Protected content API uses the following paradigm for protected content session:</p><ul>
<li><a class="el" href="group__api__prot.html#api_pc_caps">Query for supported cipher mode, block size, mode</a></li>
<li><a class="el" href="group__api__prot.html#api_pc_setup">Set up a protected content session</a></li>
<li><a class="el" href="group__api__prot.html#api_pc_exec">TEE communication via vaProtectedSessionExecute()</a></li>
<li><a class="el" href="group__api__prot.html#api_pc_attach">Attach/Detach protected content session to the VA</a></li>
</ul>
<h2><a class="anchor" id="api_pc_caps"></a>
Query for supported cipher mode, block size, mode</h2>
<p>Checking whether protected content is supported can be performed with <a class="el" href="group__api__core.html#ga7c6ec979697dafc172123c5d3ad80d8e">vaQueryConfigEntrypoints()</a> and the profile argument set to <a class="el" href="group__api__core.html#ggaa4851f694a48c22af8877f5cfbb11bdea5edf00635e9f778c2e64ecc2e8b98b34" title="Profile ID used for protected video playback. ">VAProfileProtected</a>. If protected content is supported, then the list of returned entry-points will include <a class="el" href="group__api__core.html#gga5f3bcbb940e51be2e84097463557321eafbd8339b9116b5edad5274a141c8dfd3" title="VAEntrypointProtectedContent. ">VAEntrypointProtectedContent</a></p>
<div class="fragment"><div class="line"><a class="code" href="group__api__core.html#ga5f3bcbb940e51be2e84097463557321e">VAEntrypoint</a> *entrypoints;</div><div class="line"><span class="keywordtype">int</span> i, num_entrypoints, supportsProtectedContent = 0;</div><div class="line"></div><div class="line">num_entrypoints = <a class="code" href="group__api__core.html#ga4f595f04fb847dd8c241c7fd74f8396c">vaMaxNumEntrypoints</a>();</div><div class="line">entrypoints = malloc(num_entrypoints * <span class="keyword">sizeof</span>(entrypoints[0]);</div><div class="line"><a class="code" href="group__api__core.html#ga7c6ec979697dafc172123c5d3ad80d8e">vaQueryConfigEntrypoints</a>(va_dpy, <a class="code" href="group__api__core.html#ggaa4851f694a48c22af8877f5cfbb11bdea5edf00635e9f778c2e64ecc2e8b98b34">VAProfileProtected</a>, entrypoints,</div><div class="line"> &amp;num_entrypoints);</div><div class="line"></div><div class="line"><span class="keywordflow">for</span> (i = 0; !supportsProtectedContent &amp;&amp; i &lt; num_entrypoints; i++) {</div><div class="line"> <span class="keywordflow">if</span> (entrypoints[i] == <a class="code" href="group__api__core.html#gga5f3bcbb940e51be2e84097463557321eafbd8339b9116b5edad5274a141c8dfd3">VAEntrypointProtectedContent</a>)</div><div class="line"> supportsProtectedContent = 1;</div><div class="line">}</div></div><!-- fragment --><p>Then, the <a class="el" href="group__api__core.html#gae51cad2e388d6cc63ce3d4221798f9fd">vaGetConfigAttributes()</a> function is used to query the protected session capabilities.</p>
<div class="fragment"><div class="line"><a class="code" href="structVAConfigAttrib.html">VAConfigAttrib</a> attribs;</div><div class="line">attribs[0].type = <a class="code" href="group__api__core.html#gga2c3be94ce142fb92a4bf93e9b1b4fa01afb39c2e76fab3b7a3a84131497ec95f7">VAConfigAttribProtectedContentCipherAlgorithm</a>;</div><div class="line">attribs[1].type = <a class="code" href="group__api__core.html#gga2c3be94ce142fb92a4bf93e9b1b4fa01ad408edc12ad2edeabc02be43a3710145">VAConfigAttribProtectedContentCipherBlockSize</a>;</div><div class="line">attribs[2].type = <a class="code" href="group__api__core.html#gga2c3be94ce142fb92a4bf93e9b1b4fa01a0d94a6ba968b758d7b53c05e1070cc7a">VAConfigAttribProtectedContentCipherMode</a>;</div><div class="line">attribs[3].type = <a class="code" href="group__api__core.html#gga2c3be94ce142fb92a4bf93e9b1b4fa01a4d3947eb7d70bb6ade7001eca036f863">VAConfigAttribProtectedContentCipherSampleType</a>;</div><div class="line">attribs[4].type = <a class="code" href="group__api__core.html#gga2c3be94ce142fb92a4bf93e9b1b4fa01a3787994abd0e4b2e55761b43ab7729d9">VAConfigAttribProtectedContentUsage</a>;</div><div class="line"><a class="code" href="group__api__core.html#gae51cad2e388d6cc63ce3d4221798f9fd">vaGetConfigAttributes</a>(va_dpy, <a class="code" href="group__api__core.html#ggaa4851f694a48c22af8877f5cfbb11bdea5edf00635e9f778c2e64ecc2e8b98b34">VAProfileProtected</a>,</div><div class="line"> <a class="code" href="group__api__core.html#gga5f3bcbb940e51be2e84097463557321eafbd8339b9116b5edad5274a141c8dfd3">VAEntrypointProtectedContent</a>, attribs, 5);</div><div class="line"><span class="keywordflow">if</span> ((attribs[1].value &amp; <a class="code" href="group__api__core.html#gab57437d522d8e236ebbe3c2d4e35f2c3">VA_PC_CIPHER_AES</a>) == 0) {</div><div class="line"> <span class="comment">// not find desired cipher algorithm</span></div><div class="line"> assert(0);</div><div class="line">}</div><div class="line"><span class="keywordflow">if</span> ((attribs[2].value &amp; <a class="code" href="group__api__core.html#ga6b105bf49d4c7bfec05f7299e4e6cba0">VA_PC_BLOCK_SIZE_128</a>) == 0) {</div><div class="line"> <span class="comment">// not find desired block size</span></div><div class="line"> assert(0);</div><div class="line">}</div><div class="line"><span class="keywordflow">if</span> ((attribs[3].value &amp; <a class="code" href="group__api__core.html#ga38fe461d9f931d1b5dd407824bf0de6d">VA_PC_CIPHER_MODE_CBC</a>) == 0) {</div><div class="line"> <span class="comment">// not find desired counter mode</span></div><div class="line"> assert(0);</div><div class="line">}</div><div class="line"><span class="keywordflow">if</span> ((attribs[4].value &amp; <a class="code" href="group__api__core.html#ga5e868b40098071600d60ce58e33aa245">VA_PC_SAMPLE_TYPE_SUBSAMPLE</a>) == 0) {</div><div class="line"> <span class="comment">// not find desired sample type</span></div><div class="line"> assert(0);</div><div class="line">}</div><div class="line"><span class="keywordflow">if</span> ((attribs[5].value &amp; <a class="code" href="group__api__core.html#ga179b50cf144c068643dd558ef0de34cd">VA_PC_USAGE_WIDEVINE</a>) == 0) {</div><div class="line"> <span class="comment">// not find desired usage</span></div><div class="line"> assert(0);</div><div class="line">}</div></div><!-- fragment --><h2><a class="anchor" id="api_pc_setup"></a>
Set up a protected content session</h2>
<p>TEE Communication Entrypoint The protected content session provides a TEE session that is used to extract TEE information. This information could be used to peform TEE operations.</p>
<p>Protected Content Entrypoint The protected content session can be attached to VA decode/encode/vp context to do decryption/protection in the pipeline. Before creating a protected content session, it needs to create a config first via <a class="el" href="group__api__core.html#ga9ff7833d425406cb1834c783b0a47652">vaCreateConfig()</a>. Then using this config id to create a protected content session via <a class="el" href="group__api__prot.html#gaeca36080858922da2bedd4298c6b07f8" title="Create a protected session. ">vaCreateProtectedSession()</a>.</p>
<p>The general control flow is demonstrated by the following pseudo-code: </p><div class="fragment"><div class="line"><span class="comment">// Create config</span></div><div class="line">VAConfigID config_id;</div><div class="line"></div><div class="line">attribs[0].value = <a class="code" href="group__api__core.html#gab57437d522d8e236ebbe3c2d4e35f2c3">VA_PC_CIPHER_AES</a>;</div><div class="line">attribs[1].value = <a class="code" href="group__api__core.html#ga6b105bf49d4c7bfec05f7299e4e6cba0">VA_PC_BLOCK_SIZE_128</a>;</div><div class="line">attribs[2].value = <a class="code" href="group__api__core.html#ga38fe461d9f931d1b5dd407824bf0de6d">VA_PC_CIPHER_MODE_CBC</a>;</div><div class="line">attribs[3].value = <a class="code" href="group__api__core.html#ga5e868b40098071600d60ce58e33aa245">VA_PC_SAMPLE_TYPE_SUBSAMPLE</a>;</div><div class="line">attribs[4].value = <a class="code" href="group__api__core.html#ga179b50cf144c068643dd558ef0de34cd">VA_PC_USAGE_WIDEVINE</a>;</div><div class="line">va_status = <a class="code" href="group__api__core.html#ga9ff7833d425406cb1834c783b0a47652">vaCreateConfig</a>(va_dpy, <a class="code" href="group__api__core.html#ggaa4851f694a48c22af8877f5cfbb11bdea5edf00635e9f778c2e64ecc2e8b98b34">VAProfileProtected</a>,</div><div class="line"> <a class="code" href="group__api__core.html#gga5f3bcbb940e51be2e84097463557321eafbd8339b9116b5edad5274a141c8dfd3">VAEntrypointProtectedContent</a>, attribs, 5, &amp;config_id);</div><div class="line">CHECK_VASTATUS(va_status, <span class="stringliteral">&quot;vaCreateConfig&quot;</span>);</div></div><!-- fragment --><p>Once the config is set up, we can create protected content session via <a class="el" href="group__api__prot.html#gaeca36080858922da2bedd4298c6b07f8" title="Create a protected session. ">vaCreateProtectedSession()</a>. </p><div class="fragment"><div class="line"><span class="comment">// Create a protected session</span></div><div class="line"><a class="code" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a> crypto_session;</div><div class="line"></div><div class="line">va_status = <a class="code" href="group__api__prot.html#gaeca36080858922da2bedd4298c6b07f8">vaCreateProtectedSession</a>(va_dpy, config_id, &amp;crypto_session);</div><div class="line">CHECK_VASTATUS(va_status, <span class="stringliteral">&quot;vaCreateProtectedSession&quot;</span>);</div></div><!-- fragment --><h2><a class="anchor" id="api_pc_exec"></a>
TEE communication via vaProtectedSessionExecute()</h2>
<p>TEE Communication Entrypoint App needs to communicate with TEE to get TEE information or <a class="el" href="group__api__prot.html#priming">prime</a> TEE with information that will be utilized for future TEE operations/tasks.</p>
<p>Protected Content Entrypoint Before starting decryption/encryption operation in GPU, app may need to communicate with TEE to get encrypted assets for <a class="el" href="group__api__prot.html#priming">Priming</a> HWDRM pipeline for decryption. App need to call <a class="el" href="group__api__prot.html#ga3aa87ed9c82cf09a4c90c6285af6357b" title="Execute provides a general mechanism for TEE client tasks execution. ">vaProtectedSessionExecute()</a> to get this asset. The following pseudo-code demonstrates getting session assets via <a class="el" href="group__api__prot.html#ga3aa87ed9c82cf09a4c90c6285af6357b" title="Execute provides a general mechanism for TEE client tasks execution. ">vaProtectedSessionExecute()</a> as an example.</p>
<p>In this example, the vaCreateBuffer is called with exec_buffer mainly becasue TEE Communication Entrypoint buffers are CPU bound and buffer size is small enough to have extra copy operation without impacting performance.</p>
<div class="fragment"><div class="line">uint32_t app_id = 0xFF;</div><div class="line"><a class="code" href="group__api__core.html#gad26441ddf2f4441ef65bbefa4662607f">VABufferID</a> buffer;</div><div class="line"><a class="code" href="structVAProtectedSessionExecuteBuffer.html">VAProtectedSessionExecuteBuffer</a> exec_buff = {0};</div><div class="line"></div><div class="line">exec_buff.<a class="code" href="structVAProtectedSessionExecuteBuffer.html#aa35f4f812a3c5767ab29dfb73772e753">function_id</a> = GET_SESSION_ID;</div><div class="line">exec_buff.<a class="code" href="structVAProtectedSessionExecuteBuffer.html#a99d3b1cbd53734c1f253320792dea5e1">input</a>.data = <span class="keyword">nullptr</span>;</div><div class="line">exec_buff.<a class="code" href="structVAProtectedSessionExecuteBuffer.html#a99d3b1cbd53734c1f253320792dea5e1">input</a>.data_size = 0;</div><div class="line">exec_buff.<a class="code" href="structVAProtectedSessionExecuteBuffer.html#a5555cc622f2797b790479a0b45b79f46">output</a>.data = &amp;app_id;</div><div class="line">exec_buff.<a class="code" href="structVAProtectedSessionExecuteBuffer.html#a5555cc622f2797b790479a0b45b79f46">output</a>.max_data_size = <span class="keyword">sizeof</span>(app_id);</div><div class="line">va_status = <a class="code" href="group__api__core.html#gaba254978bf0d32781f4a9e67f1fa7a78">vaCreateBuffer</a>(</div><div class="line"> va_dpy,</div><div class="line"> crypto_session,</div><div class="line"> (<a class="code" href="group__api__core.html#ga24da9776c5d3a5ce29cb592cf22c00db">VABufferType</a>) <a class="code" href="group__api__core.html#gga24da9776c5d3a5ce29cb592cf22c00dba7a2ea7b1732bc899a151543e7bd79ddd">VAProtectedSessionExecuteBufferType</a>,</div><div class="line"> <span class="keyword">sizeof</span>(exec_buff),</div><div class="line"> 1,</div><div class="line"> &amp;exec_buff,</div><div class="line"> &amp;buffer);</div><div class="line"></div><div class="line">va_status = <a class="code" href="group__api__prot.html#ga3aa87ed9c82cf09a4c90c6285af6357b">vaProtectedSessionExecute</a>(va_dpy, crypto_session, buffer);</div><div class="line"></div><div class="line"><a class="code" href="group__api__core.html#gaa2d1d886aed7b104ed2e50883aa8ccde">vaDestroyBuffer</a>(va_dpy, buffer);</div></div><!-- fragment --><h2><a class="anchor" id="api_pc_attach"></a>
Attach/Detach protected content session to the VA</h2>
<p>context which want to enable/disable decryption/protection</p>
<p>Protected content session is attached to VA decode/encode/vp context to enable protected decoding/encoding/video processing per frame or entire stream. If protected session attached per frame then application has 2 options for decoding/encoding skip processing i.e. accomodating clear frames - 1. Application could do detach after each frame is processed to process clear frame 2. Application could remains attached to decode/ encode session but specify enryption byte length to 0. The video processing does not has option #2 mainly because API does not provide skip processing.</p>
<div class="fragment"><div class="line"><a class="code" href="group__api__prot.html#gad5a42586ce84a698ade0791a2a9ceb86">vaAttachProtectedSession</a>(va_dpy, decode_ctx, crypto_session);</div><div class="line"><span class="keywordflow">foreach</span> (iteration) {</div><div class="line"> <a class="code" href="group__api__core.html#gacf031b9aaf39365bf8d79d92372f2ec8">vaBeginPicture</a>(va_dpy, decode_ctx, surface);</div><div class="line"> ...</div><div class="line"> <a class="code" href="group__api__core.html#ga3facc622a14fc901d5d44dcda845cb6f">vaRenderPicture</a>(va_dpy, decode_ctx, &amp;buf_id1, 1);</div><div class="line"> <a class="code" href="group__api__core.html#ga3facc622a14fc901d5d44dcda845cb6f">vaRenderPicture</a>(va_dpy, decode_ctx, &amp;buf_id2, 1);</div><div class="line"> <span class="comment">// Buffer holding encryption parameters, i.e. VAEncryptionParameterBufferType buffer</span></div><div class="line"> <a class="code" href="group__api__core.html#ga3facc622a14fc901d5d44dcda845cb6f">vaRenderPicture</a>(va_dpy, decode_ctx, &amp;buf_id_enc_param, 1);</div><div class="line"> ...</div><div class="line"> <a class="code" href="group__api__core.html#gaffbd38af17b5f061707010287e7d4c97">vaEndPicture</a>(va_dpy, decode_ctx);</div><div class="line">}</div><div class="line"><a class="code" href="group__api__prot.html#gae7efc8bef99f742cdfdb4bddf519625e">vaDetachProtectedSession</a>(va_dpy, decode_ctx);</div></div><!-- fragment --><p>or it could be frame-by-frame attaching/detaching as following:</p>
<div class="fragment"><div class="line"><span class="keywordflow">foreach</span> (iteration) {</div><div class="line"> <span class="keywordflow">if</span> (encrypted)</div><div class="line"> <a class="code" href="group__api__prot.html#gad5a42586ce84a698ade0791a2a9ceb86">vaAttachProtectedSession</a>(va_dpy, decode_ctx, crypto_session);</div><div class="line"></div><div class="line"> <a class="code" href="group__api__core.html#gacf031b9aaf39365bf8d79d92372f2ec8">vaBeginPicture</a>(va_dpy, decode_ctx, surface);</div><div class="line"> ...</div><div class="line"> <a class="code" href="group__api__core.html#ga3facc622a14fc901d5d44dcda845cb6f">vaRenderPicture</a>(va_dpy, decode_ctx, &amp;buf_id1, 1);</div><div class="line"> <a class="code" href="group__api__core.html#ga3facc622a14fc901d5d44dcda845cb6f">vaRenderPicture</a>(va_dpy, decode_ctx, &amp;buf_id2, 1);</div><div class="line"> <span class="comment">// Buffer holding encryption parameters, i.e. VAEncryptionParameterBufferType buffer</span></div><div class="line"> <a class="code" href="group__api__core.html#ga3facc622a14fc901d5d44dcda845cb6f">vaRenderPicture</a>(va_dpy, decode_ctx, &amp;buf_id_enc_param, 1);</div><div class="line"> ...</div><div class="line"> <a class="code" href="group__api__core.html#gaffbd38af17b5f061707010287e7d4c97">vaEndPicture</a>(va_dpy, decode_ctx);</div><div class="line"></div><div class="line"> <span class="keywordflow">if</span> (encrypted)</div><div class="line"> <a class="code" href="group__api__prot.html#gae7efc8bef99f742cdfdb4bddf519625e">vaDetachProtectedSession</a>(va_dpy, decode_ctx);</div><div class="line"></div><div class="line"> <span class="comment">// check encrypted variable for next frame</span></div><div class="line">}</div></div><!-- fragment --> <h2 class="groupheader">Typedef Documentation</h2>
<a id="ga092a2c03eb3f5be8262590aca3b049cf"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga092a2c03eb3f5be8262590aca3b049cf">&#9670;&nbsp;</a></span>VAProtectedSessionID</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef <a class="el" href="group__api__core.html#gab3ee763380573fdd05464ca16cf46d1d">VAGenericID</a> <a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>ProtectedSessions and Contexts</p>
<p>According to <a class="el" href="group__api__core.html#ga4af336e410aefeb4ca4315e2c7cbd653">VAContextID</a>, Context represents a "virtual" video decode, encode or video processing pipeline. Surfaces are render targets for a given context. The data in the surfaces are not accessible to the client except if derived image is supported and the internal data format of the surface is implementation specific. Application can create a video decode, encode or processing context which represents a "virtualized" hardware device.</p>
<p>Since Protected Session does not virtualize any HW device or build any pipeline but rather accessorize existing virtualized HW device or pipeline to operate in protected mode so we decided to create separate function. Beside this, a virtualized HW device or pipeline could own several protected sessions and operate in those protected modes without ever re-creating virtualization of HW device or re-building HW pipeline (an unique protected environment multiplexing capability in Intel HW).</p>
<p>The returned protected_session represents a notion of Host and TEE clients while representing protection status in GPU and Display.</p>
<p>Both contexts and protected sessions are identified by unique IDs and its implementation specific internals are kept opaque to the clients </p>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="gad5a42586ce84a698ade0791a2a9ceb86"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gad5a42586ce84a698ade0791a2a9ceb86">&#9670;&nbsp;</a></span>vaAttachProtectedSession()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">VAStatus vaAttachProtectedSession </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a>&#160;</td>
<td class="paramname"><em>dpy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__core.html#gab3ee763380573fdd05464ca16cf46d1d">VAGenericID</a>&#160;</td>
<td class="paramname"><em>id</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a>&#160;</td>
<td class="paramname"><em>protected_session</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Attach a protected content session to VA context. </p>
<p>Attach a protected content session to the context to enable decryption/protection</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dpy</td><td>the VA display </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>the VA decode/encode/vp context </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">protected_session</td><td>the protected session to attach </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gaeca36080858922da2bedd4298c6b07f8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaeca36080858922da2bedd4298c6b07f8">&#9670;&nbsp;</a></span>vaCreateProtectedSession()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">VAStatus vaCreateProtectedSession </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a>&#160;</td>
<td class="paramname"><em>dpy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">VAConfigID&#160;</td>
<td class="paramname"><em>config_id</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a> *&#160;</td>
<td class="paramname"><em>protected_session</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Create a protected session. </p>
<p>Create a protected session</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dpy</td><td>the VA display </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">config_id</td><td>configuration for the protected session </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">protected_session</td><td>created protected session id upon return </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga9c531a9f026f22d71b7900a9c375817b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga9c531a9f026f22d71b7900a9c375817b">&#9670;&nbsp;</a></span>vaDestroyProtectedSession()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">VAStatus vaDestroyProtectedSession </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a>&#160;</td>
<td class="paramname"><em>dpy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a>&#160;</td>
<td class="paramname"><em>protected_session</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Destroy a protected session. </p>
<p>Destroy a protected session</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dpy</td><td>the VA display </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">protected_session</td><td>protected session to be destroyed </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gae7efc8bef99f742cdfdb4bddf519625e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gae7efc8bef99f742cdfdb4bddf519625e">&#9670;&nbsp;</a></span>vaDetachProtectedSession()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">VAStatus vaDetachProtectedSession </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a>&#160;</td>
<td class="paramname"><em>dpy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__core.html#gab3ee763380573fdd05464ca16cf46d1d">VAGenericID</a>&#160;</td>
<td class="paramname"><em>id</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Detach the protected content session from the VA context. </p>
<p>Detach protected content session of the context to disable decryption/protection</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dpy</td><td>the VA display </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TEE client id to be detached </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga3aa87ed9c82cf09a4c90c6285af6357b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga3aa87ed9c82cf09a4c90c6285af6357b">&#9670;&nbsp;</a></span>vaProtectedSessionExecute()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">VAStatus vaProtectedSessionExecute </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__api__core.html#gad534cae750fddc9ad30d0dc267deffa3">VADisplay</a>&#160;</td>
<td class="paramname"><em>dpy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__prot.html#ga092a2c03eb3f5be8262590aca3b049cf">VAProtectedSessionID</a>&#160;</td>
<td class="paramname"><em>protected_session</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__api__core.html#gad26441ddf2f4441ef65bbefa4662607f">VABufferID</a>&#160;</td>
<td class="paramname"><em>buf_id</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Execute provides a general mechanism for TEE client tasks execution. </p>
<p>vaProtectedSessionExecute provides a mechanism for TEE clients to execute specific tasks. The implementation may differ between IHVs. This is a synchronous API.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dpy</td><td>the VA display </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">protected_session</td><td>the protected session </td></tr>
<tr><td class="paramdir">[in,out]</td><td class="paramname">buf_id</td><td>the VA buffer </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
<hr class="footer"/><address class="footer"><small>
Generated for VA-API by&#160;<a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13</small></address>
</body>
</html>