| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 1.5.8"> |
| <meta name="author" content="Khronos® OpenCL Working Group"> |
| <title>The OpenCL™ Specification</title> |
| <style> |
| /*! normalize.css v2.1.2 | MIT License | git.io/normalize */ |
| /* ========================================================================== HTML5 display definitions ========================================================================== */ |
| /** Correct `block` display not defined in IE 8/9. */ |
| article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; } |
| |
| /** Correct `inline-block` display not defined in IE 8/9. */ |
| audio, canvas, video { display: inline-block; } |
| |
| /** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */ |
| audio:not([controls]) { display: none; height: 0; } |
| |
| /** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */ |
| [hidden], template { display: none; } |
| |
| script { display: none !important; } |
| |
| /* ========================================================================== Base ========================================================================== */ |
| /** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */ |
| html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ } |
| |
| /** Remove default margin. */ |
| body { margin: 0; } |
| |
| /* ========================================================================== Links ========================================================================== */ |
| /** Remove the gray background color from active links in IE 10. */ |
| a { background: transparent; } |
| |
| /** Address `outline` inconsistency between Chrome and other browsers. */ |
| a:focus { outline: thin dotted; } |
| |
| /** Improve readability when focused and also mouse hovered in all browsers. */ |
| a:active, a:hover { outline: 0; } |
| |
| /* ========================================================================== Typography ========================================================================== */ |
| /** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */ |
| h1 { font-size: 2em; margin: 0.67em 0; } |
| |
| /** Address styling not present in IE 8/9, Safari 5, and Chrome. */ |
| abbr[title] { border-bottom: 1px dotted; } |
| |
| /** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */ |
| b, strong { font-weight: bold; } |
| |
| /** Address styling not present in Safari 5 and Chrome. */ |
| dfn { font-style: italic; } |
| |
| /** Address differences between Firefox and other browsers. */ |
| hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; } |
| |
| /** Address styling not present in IE 8/9. */ |
| mark { background: #ff0; color: #000; } |
| |
| /** Correct font family set oddly in Safari 5 and Chrome. */ |
| code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; } |
| |
| /** Improve readability of pre-formatted text in all browsers. */ |
| pre { white-space: pre-wrap; } |
| |
| /** Set consistent quote types. */ |
| q { quotes: "\201C" "\201D" "\2018" "\2019"; } |
| |
| /** Address inconsistent and variable font size in all browsers. */ |
| small { font-size: 80%; } |
| |
| /** Prevent `sub` and `sup` affecting `line-height` in all browsers. */ |
| sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; } |
| |
| sup { top: -0.5em; } |
| |
| sub { bottom: -0.25em; } |
| |
| /* ========================================================================== Embedded content ========================================================================== */ |
| /** Remove border when inside `a` element in IE 8/9. */ |
| img { border: 0; } |
| |
| /** Correct overflow displayed oddly in IE 9. */ |
| svg:not(:root) { overflow: hidden; } |
| |
| /* ========================================================================== Figures ========================================================================== */ |
| /** Address margin not present in IE 8/9 and Safari 5. */ |
| figure { margin: 0; } |
| |
| /* ========================================================================== Forms ========================================================================== */ |
| /** Define consistent border, margin, and padding. */ |
| fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; } |
| |
| /** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */ |
| legend { border: 0; /* 1 */ padding: 0; /* 2 */ } |
| |
| /** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */ |
| button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ } |
| |
| /** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */ |
| button, input { line-height: normal; } |
| |
| /** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */ |
| button, select { text-transform: none; } |
| |
| /** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */ |
| button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ } |
| |
| /** Re-set default cursor for disabled elements. */ |
| button[disabled], html input[disabled] { cursor: default; } |
| |
| /** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */ |
| input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ } |
| |
| /** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */ |
| input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; } |
| |
| /** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */ |
| input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; } |
| |
| /** Remove inner padding and border in Firefox 4+. */ |
| button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; } |
| |
| /** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */ |
| textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ } |
| |
| /* ========================================================================== Tables ========================================================================== */ |
| /** Remove most spacing between table cells. */ |
| table { border-collapse: collapse; border-spacing: 0; } |
| |
| meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; } |
| |
| meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; } |
| |
| meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; } |
| |
| *, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; } |
| |
| html, body { font-size: 100%; } |
| |
| body { background: white; color: #222222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; } |
| |
| a:hover { cursor: pointer; } |
| |
| img, object, embed { max-width: 100%; height: auto; } |
| |
| object, embed { height: 100%; } |
| |
| img { -ms-interpolation-mode: bicubic; } |
| |
| #map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; } |
| |
| .left { float: left !important; } |
| |
| .right { float: right !important; } |
| |
| .text-left { text-align: left !important; } |
| |
| .text-right { text-align: right !important; } |
| |
| .text-center { text-align: center !important; } |
| |
| .text-justify { text-align: justify !important; } |
| |
| .hide { display: none; } |
| |
| .antialiased { -webkit-font-smoothing: antialiased; } |
| |
| img { display: inline-block; vertical-align: middle; } |
| |
| textarea { height: auto; min-height: 50px; } |
| |
| select { width: 100%; } |
| |
| object, svg { display: inline-block; vertical-align: middle; } |
| |
| .center { margin-left: auto; margin-right: auto; } |
| |
| .spread { width: 100%; } |
| |
| p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; } |
| |
| .subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: black; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; } |
| |
| /* Typography resets */ |
| div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; } |
| |
| /* Default Link Styles */ |
| a { color: #0068b0; text-decoration: none; line-height: inherit; } |
| a:hover, a:focus { color: #333333; } |
| a img { border: none; } |
| |
| /* Default paragraph styles */ |
| p { font-family: Noto, sans-serif; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; text-rendering: optimizeLegibility; } |
| p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; } |
| |
| /* Default header styles */ |
| h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Noto, sans-serif; font-weight: normal; font-style: normal; color: black; text-rendering: optimizeLegibility; margin-top: 0.5em; margin-bottom: 0.5em; line-height: 1.2125em; } |
| h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #4d4d4d; line-height: 0; } |
| |
| h1 { font-size: 2.125em; } |
| |
| h2 { font-size: 1.6875em; } |
| |
| h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; } |
| |
| h4 { font-size: 1.125em; } |
| |
| h5 { font-size: 1.125em; } |
| |
| h6 { font-size: 1em; } |
| |
| hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; } |
| |
| /* Helpful Typography Defaults */ |
| em, i { font-style: italic; line-height: inherit; } |
| |
| strong, b { font-weight: bold; line-height: inherit; } |
| |
| small { font-size: 60%; line-height: inherit; } |
| |
| code { font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; color: #264357; } |
| |
| /* Lists */ |
| ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; list-style-position: outside; font-family: Noto, sans-serif; } |
| |
| ul, ol { margin-left: 1.5em; } |
| ul.no-bullet, ol.no-bullet { margin-left: 1.5em; } |
| |
| /* Unordered Lists */ |
| ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ } |
| ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; } |
| ul.square { list-style-type: square; } |
| ul.circle { list-style-type: circle; } |
| ul.disc { list-style-type: disc; } |
| ul.no-bullet { list-style: none; } |
| |
| /* Ordered Lists */ |
| ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; } |
| |
| /* Definition Lists */ |
| dl dt { margin-bottom: 0.3em; font-weight: bold; } |
| dl dd { margin-bottom: 0.75em; } |
| |
| /* Abbreviations */ |
| abbr, acronym { text-transform: uppercase; font-size: 90%; color: black; border-bottom: 1px dotted #dddddd; cursor: help; } |
| |
| abbr { text-transform: none; } |
| |
| /* Blockquotes */ |
| blockquote { margin: 0 0 0.75em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; } |
| blockquote cite { display: block; font-size: 0.8125em; color: #5e93b8; } |
| blockquote cite:before { content: "\2014 \0020"; } |
| blockquote cite a, blockquote cite a:visited { color: #5e93b8; } |
| |
| blockquote, blockquote p { line-height: 1.6; color: #333333; } |
| |
| /* Microformats */ |
| .vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; } |
| .vcard li { margin: 0; display: block; } |
| .vcard .fn { font-weight: bold; font-size: 0.9375em; } |
| |
| .vevent .summary { font-weight: bold; } |
| .vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; } |
| |
| @media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } |
| h1 { font-size: 2.75em; } |
| h2 { font-size: 2.3125em; } |
| h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } |
| h4 { font-size: 1.4375em; } } |
| /* Tables */ |
| table { background: white; margin-bottom: 1.25em; border: solid 1px #d8d8ce; } |
| table thead, table tfoot { background: -webkit-linear-gradient(top, #add386, #90b66a); font-weight: bold; } |
| table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: white; text-align: left; } |
| table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #6d6e71; } |
| table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #edf2f2; } |
| table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.4; } |
| |
| body { -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; tab-size: 4; } |
| |
| h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } |
| |
| a:hover, a:focus { text-decoration: underline; } |
| |
| .clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; } |
| .clearfix:after, .float-group:after { clear: both; } |
| |
| *:not(pre) > code { font-size: inherit; font-style: normal !important; letter-spacing: 0; padding: 0; background-color: white; -webkit-border-radius: 0; border-radius: 0; line-height: inherit; word-wrap: break-word; } |
| *:not(pre) > code.nobreak { word-wrap: normal; } |
| *:not(pre) > code.nowrap { white-space: nowrap; } |
| |
| pre, pre > code { line-height: 1.6; color: #264357; font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; } |
| |
| em em { font-style: normal; } |
| |
| strong strong { font-weight: normal; } |
| |
| .keyseq { color: #333333; } |
| |
| kbd { font-family: Consolas, "Liberation Mono", Courier, monospace; display: inline-block; color: black; font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; } |
| |
| .keyseq kbd:first-child { margin-left: 0; } |
| |
| .keyseq kbd:last-child { margin-right: 0; } |
| |
| .menuseq, .menuref { color: #000; } |
| |
| .menuseq b:not(.caret), .menuref { font-weight: inherit; } |
| |
| .menuseq { word-spacing: -0.02em; } |
| .menuseq b.caret { font-size: 1.25em; line-height: 0.8; } |
| .menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; } |
| |
| b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; } |
| |
| b.button:before { content: "["; padding: 0 3px 0 2px; } |
| |
| b.button:after { content: "]"; padding: 0 2px 0 3px; } |
| |
| #header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 1.5em; padding-right: 1.5em; } |
| #header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; } |
| #header:after, #content:after, #footnotes:after, #footer:after { clear: both; } |
| |
| #content { margin-top: 1.25em; } |
| |
| #content:before { content: none; } |
| |
| #header > h1:first-child { color: black; margin-top: 2.25rem; margin-bottom: 0; } |
| #header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #dddddd; } |
| #header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #dddddd; padding-bottom: 8px; } |
| #header .details { border-bottom: 1px solid #dddddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #5e93b8; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; } |
| #header .details span:first-child { margin-left: -0.125em; } |
| #header .details span.email a { color: #333333; } |
| #header .details br { display: none; } |
| #header .details br + span:before { content: "\00a0\2013\00a0"; } |
| #header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #333333; } |
| #header .details br + span#revremark:before { content: "\00a0|\00a0"; } |
| #header #revnumber { text-transform: capitalize; } |
| #header #revnumber:after { content: "\00a0"; } |
| |
| #content > h1:first-child:not([class]) { color: black; border-bottom: 1px solid #dddddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; } |
| |
| #toc { border-bottom: 0 solid #dddddd; padding-bottom: 0.5em; } |
| #toc > ul { margin-left: 0.125em; } |
| #toc ul.sectlevel0 > li > a { font-style: italic; } |
| #toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; } |
| #toc ul { font-family: Noto, sans-serif; list-style-type: none; } |
| #toc li { line-height: 1.3334; margin-top: 0.3334em; } |
| #toc a { text-decoration: none; } |
| #toc a:active { text-decoration: underline; } |
| |
| #toctitle { color: black; font-size: 1.2em; } |
| |
| @media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; } |
| body.toc2 { padding-left: 15em; padding-right: 0; } |
| #toc.toc2 { margin-top: 0 !important; background-color: white; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; } |
| #toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; } |
| #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; } |
| #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } |
| body.toc2.toc-right { padding-left: 0; padding-right: 15em; } |
| body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } } |
| @media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } |
| #toc.toc2 { width: 20em; } |
| #toc.toc2 #toctitle { font-size: 1.375em; } |
| #toc.toc2 > ul { font-size: 0.95em; } |
| #toc.toc2 ul ul { padding-left: 1.25em; } |
| body.toc2.toc-right { padding-left: 0; padding-right: 20em; } } |
| #content #toc { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; } |
| #content #toc > :first-child { margin-top: 0; } |
| #content #toc > :last-child { margin-bottom: 0; } |
| |
| #footer { max-width: 100%; background-color: none; padding: 1.25em; } |
| |
| #footer-text { color: black; line-height: 1.44; } |
| |
| #content { margin-bottom: 0.625em; } |
| |
| .sect1 { padding-bottom: 0.625em; } |
| |
| @media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; } |
| .sect1 { padding-bottom: 1.25em; } } |
| .sect1:last-child { padding-bottom: 0; } |
| |
| .sect1 + .sect1 { border-top: 0 solid #dddddd; } |
| |
| #content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; } |
| #content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; } |
| #content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; } |
| #content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: black; text-decoration: none; } |
| #content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: black; } |
| |
| .audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; } |
| |
| .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; } |
| |
| table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; } |
| |
| .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { color: black; } |
| |
| table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; } |
| |
| .admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; } |
| .admonitionblock > table td.icon { text-align: center; width: 80px; } |
| .admonitionblock > table td.icon img { max-width: initial; } |
| .admonitionblock > table td.icon .title { font-weight: bold; font-family: Noto, sans-serif; text-transform: uppercase; } |
| .admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #5e93b8; } |
| .admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; } |
| |
| .exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; } |
| .exampleblock > .content > :first-child { margin-top: 0; } |
| .exampleblock > .content > :last-child { margin-bottom: 0; } |
| |
| .sidebarblock { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; } |
| .sidebarblock > :first-child { margin-top: 0; } |
| .sidebarblock > :last-child { margin-bottom: 0; } |
| .sidebarblock > .content > .title { color: black; margin-top: 0; } |
| |
| .exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; } |
| |
| .literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { background: #eeeeee; } |
| .sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { background: #f2f1f1; } |
| |
| .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 1px hidden #666666; -webkit-border-radius: 0; border-radius: 0; word-wrap: break-word; padding: 1.25em 1.5625em 1.125em 1.5625em; font-size: 0.8125em; } |
| .literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; } |
| @media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.90625em; } } |
| @media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 1em; } } |
| |
| .literalblock.output pre { color: #eeeeee; background-color: #264357; } |
| |
| .listingblock pre.highlightjs { padding: 0; } |
| .listingblock pre.highlightjs > code { padding: 1.25em 1.5625em 1.125em 1.5625em; -webkit-border-radius: 0; border-radius: 0; } |
| |
| .listingblock > .content { position: relative; } |
| |
| .listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: #999; } |
| |
| .listingblock:hover code[data-lang]:before { display: block; } |
| |
| .listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; } |
| |
| .listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; } |
| |
| table.pyhltable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; } |
| |
| table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; line-height: 1.6; } |
| |
| table.pyhltable td.code { padding-left: .75em; padding-right: 0; } |
| |
| pre.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #dddddd; } |
| |
| pre.pygments .lineno { display: inline-block; margin-right: .25em; } |
| |
| table.pyhltable .linenodiv { background: none !important; padding-right: 0 !important; } |
| |
| .quoteblock { margin: 0 1em 0.75em 1.5em; display: table; } |
| .quoteblock > .title { margin-left: -1.5em; margin-bottom: 0.75em; } |
| .quoteblock blockquote, .quoteblock blockquote p { color: #333333; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; } |
| .quoteblock blockquote { margin: 0; padding: 0; border: 0; } |
| .quoteblock blockquote:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: black; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); } |
| .quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; } |
| .quoteblock .attribution { margin-top: 0.5em; margin-right: 0.5ex; text-align: right; } |
| .quoteblock .quoteblock { margin-left: 0; margin-right: 0; padding: 0.5em 0; border-left: 3px solid #5e93b8; } |
| .quoteblock .quoteblock blockquote { padding: 0 0 0 0.75em; } |
| .quoteblock .quoteblock blockquote:before { display: none; } |
| |
| .verseblock { margin: 0 1em 0.75em 1em; } |
| .verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #333333; font-weight: 300; text-rendering: optimizeLegibility; } |
| .verseblock pre strong { font-weight: 400; } |
| .verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; } |
| |
| .quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; } |
| .quoteblock .attribution br, .verseblock .attribution br { display: none; } |
| .quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #5e93b8; } |
| |
| .quoteblock.abstract { margin: 0 0 0.75em 0; display: block; } |
| .quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { text-align: left; word-spacing: 0; } |
| .quoteblock.abstract blockquote:before, .quoteblock.abstract blockquote p:first-of-type:before { display: none; } |
| |
| table.tableblock { max-width: 100%; border-collapse: separate; } |
| table.tableblock td > .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; } |
| |
| table.tableblock, th.tableblock, td.tableblock { border: 0 solid #d8d8ce; } |
| |
| table.grid-all > thead > tr > .tableblock, table.grid-all > tbody > tr > .tableblock { border-width: 0 1px 1px 0; } |
| |
| table.grid-all > tfoot > tr > .tableblock { border-width: 1px 1px 0 0; } |
| |
| table.grid-cols > * > tr > .tableblock { border-width: 0 1px 0 0; } |
| |
| table.grid-rows > thead > tr > .tableblock, table.grid-rows > tbody > tr > .tableblock { border-width: 0 0 1px 0; } |
| |
| table.grid-rows > tfoot > tr > .tableblock { border-width: 1px 0 0 0; } |
| |
| table.grid-all > * > tr > .tableblock:last-child, table.grid-cols > * > tr > .tableblock:last-child { border-right-width: 0; } |
| |
| table.grid-all > tbody > tr:last-child > .tableblock, table.grid-all > thead:last-child > tr > .tableblock, table.grid-rows > tbody > tr:last-child > .tableblock, table.grid-rows > thead:last-child > tr > .tableblock { border-bottom-width: 0; } |
| |
| table.frame-all { border-width: 1px; } |
| |
| table.frame-sides { border-width: 0 1px; } |
| |
| table.frame-topbot { border-width: 1px 0; } |
| |
| th.halign-left, td.halign-left { text-align: left; } |
| |
| th.halign-right, td.halign-right { text-align: right; } |
| |
| th.halign-center, td.halign-center { text-align: center; } |
| |
| th.valign-top, td.valign-top { vertical-align: top; } |
| |
| th.valign-bottom, td.valign-bottom { vertical-align: bottom; } |
| |
| th.valign-middle, td.valign-middle { vertical-align: middle; } |
| |
| table thead th, table tfoot th { font-weight: bold; } |
| |
| tbody tr th { display: table-cell; line-height: 1.4; background: -webkit-linear-gradient(top, #add386, #90b66a); } |
| |
| tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: white; font-weight: bold; } |
| |
| p.tableblock > code:only-child { background: none; padding: 0; } |
| |
| p.tableblock { font-size: 1em; } |
| |
| td > div.verse { white-space: pre; } |
| |
| ol { margin-left: 1.75em; } |
| |
| ul li ol { margin-left: 1.5em; } |
| |
| dl dd { margin-left: 1.125em; } |
| |
| dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; } |
| |
| ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.375em; } |
| |
| ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; } |
| |
| ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; } |
| |
| ul.unstyled, ol.unstyled { margin-left: 0; } |
| |
| ul.checklist { margin-left: 0.625em; } |
| |
| ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; } |
| |
| ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; } |
| |
| ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.375em -0.75em; } |
| |
| ul.inline > li { margin-left: 0.75em; } |
| |
| .unstyled dl dt { font-weight: normal; font-style: normal; } |
| |
| ol.arabic { list-style-type: decimal; } |
| |
| ol.decimal { list-style-type: decimal-leading-zero; } |
| |
| ol.loweralpha { list-style-type: lower-alpha; } |
| |
| ol.upperalpha { list-style-type: upper-alpha; } |
| |
| ol.lowerroman { list-style-type: lower-roman; } |
| |
| ol.upperroman { list-style-type: upper-roman; } |
| |
| ol.lowergreek { list-style-type: lower-greek; } |
| |
| .hdlist > table, .colist > table { border: 0; background: none; } |
| .hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; } |
| |
| td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; } |
| |
| td.hdlist1 { font-weight: bold; padding-bottom: 0.75em; } |
| |
| .literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; } |
| |
| .colist > table tr > td:first-of-type { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; } |
| .colist > table tr > td:first-of-type img { max-width: initial; } |
| .colist > table tr > td:last-of-type { padding: 0.25em 0; } |
| |
| .thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; } |
| |
| .imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; } |
| .imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; } |
| .imageblock > .title { margin-bottom: 0; } |
| .imageblock.thumb, .imageblock.th { border-width: 6px; } |
| .imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; } |
| |
| .image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; } |
| .image.left { margin-right: 0.625em; } |
| .image.right { margin-left: 0.625em; } |
| |
| a.image { text-decoration: none; display: inline-block; } |
| a.image object { pointer-events: none; } |
| |
| sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; } |
| sup.footnote a, sup.footnoteref a { text-decoration: none; } |
| sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; } |
| |
| #footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; } |
| #footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; } |
| #footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; } |
| #footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; } |
| #footnotes .footnote:last-of-type { margin-bottom: 0; } |
| #content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; } |
| |
| .gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; } |
| .gist .file-data > table td.line-data { width: 99%; } |
| |
| div.unbreakable { page-break-inside: avoid; } |
| |
| .big { font-size: larger; } |
| |
| .small { font-size: smaller; } |
| |
| .underline { text-decoration: underline; } |
| |
| .overline { text-decoration: overline; } |
| |
| .line-through { text-decoration: line-through; } |
| |
| .aqua { color: #00bfbf; } |
| |
| .aqua-background { background-color: #00fafa; } |
| |
| .black { color: black; } |
| |
| .black-background { background-color: black; } |
| |
| .blue { color: #0000bf; } |
| |
| .blue-background { background-color: #0000fa; } |
| |
| .fuchsia { color: #bf00bf; } |
| |
| .fuchsia-background { background-color: #fa00fa; } |
| |
| .gray { color: #606060; } |
| |
| .gray-background { background-color: #7d7d7d; } |
| |
| .green { color: #006000; } |
| |
| .green-background { background-color: #007d00; } |
| |
| .lime { color: #00bf00; } |
| |
| .lime-background { background-color: #00fa00; } |
| |
| .maroon { color: #600000; } |
| |
| .maroon-background { background-color: #7d0000; } |
| |
| .navy { color: #000060; } |
| |
| .navy-background { background-color: #00007d; } |
| |
| .olive { color: #606000; } |
| |
| .olive-background { background-color: #7d7d00; } |
| |
| .purple { color: #600060; } |
| |
| .purple-background { background-color: #7d007d; } |
| |
| .red { color: #bf0000; } |
| |
| .red-background { background-color: #fa0000; } |
| |
| .silver { color: #909090; } |
| |
| .silver-background { background-color: #bcbcbc; } |
| |
| .teal { color: #006060; } |
| |
| .teal-background { background-color: #007d7d; } |
| |
| .white { color: #bfbfbf; } |
| |
| .white-background { background-color: #fafafa; } |
| |
| .yellow { color: #bfbf00; } |
| |
| .yellow-background { background-color: #fafa00; } |
| |
| span.icon > .fa { cursor: default; } |
| a span.icon > .fa { cursor: inherit; } |
| |
| .admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; } |
| .admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #29475c; } |
| .admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; } |
| .admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; } |
| .admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; } |
| .admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; } |
| |
| .conum[data-value] { display: inline-block; color: #fff !important; background-color: black; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; } |
| .conum[data-value] * { color: #fff !important; } |
| .conum[data-value] + b { display: none; } |
| .conum[data-value]:after { content: attr(data-value); } |
| pre .conum[data-value] { position: relative; top: -0.125em; } |
| |
| b.conum * { color: inherit !important; } |
| |
| .conum:not([data-value]):empty { display: none; } |
| |
| h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { border-bottom: 1px solid #dddddd; } |
| |
| .sect1 { padding-bottom: 0; } |
| |
| #toctitle { color: #00406F; font-weight: normal; margin-top: 1.5em; } |
| |
| .sidebarblock { border-color: #aaa; } |
| |
| code { -webkit-border-radius: 4px; border-radius: 4px; } |
| |
| p.tableblock.header { color: #6d6e71; } |
| |
| .literalblock pre, .listingblock pre { background: #eeeeee; } |
| |
| </style> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> |
| <style> |
| /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */ |
| /*pre.CodeRay {background-color:#f7f7f8;}*/ |
| .CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em} |
| .CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)} |
| .CodeRay .line-numbers strong{color:rgba(0,0,0,.4)} |
| table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none} |
| table.CodeRay td{vertical-align: top;line-height:1.45} |
| table.CodeRay td.line-numbers{text-align:right} |
| table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)} |
| table.CodeRay td.code{padding:0 0 0 .5em} |
| table.CodeRay td.code>pre{padding:0} |
| .CodeRay .debug{color:#fff !important;background:#000080 !important} |
| .CodeRay .annotation{color:#007} |
| .CodeRay .attribute-name{color:#000080} |
| .CodeRay .attribute-value{color:#700} |
| .CodeRay .binary{color:#509} |
| .CodeRay .comment{color:#998;font-style:italic} |
| .CodeRay .char{color:#04d} |
| .CodeRay .char .content{color:#04d} |
| .CodeRay .char .delimiter{color:#039} |
| .CodeRay .class{color:#458;font-weight:bold} |
| .CodeRay .complex{color:#a08} |
| .CodeRay .constant,.CodeRay .predefined-constant{color:#008080} |
| .CodeRay .color{color:#099} |
| .CodeRay .class-variable{color:#369} |
| .CodeRay .decorator{color:#b0b} |
| .CodeRay .definition{color:#099} |
| .CodeRay .delimiter{color:#000} |
| .CodeRay .doc{color:#970} |
| .CodeRay .doctype{color:#34b} |
| .CodeRay .doc-string{color:#d42} |
| .CodeRay .escape{color:#666} |
| .CodeRay .entity{color:#800} |
| .CodeRay .error{color:#808} |
| .CodeRay .exception{color:inherit} |
| .CodeRay .filename{color:#099} |
| .CodeRay .function{color:#900;font-weight:bold} |
| .CodeRay .global-variable{color:#008080} |
| .CodeRay .hex{color:#058} |
| .CodeRay .integer,.CodeRay .float{color:#099} |
| .CodeRay .include{color:#555} |
| .CodeRay .inline{color:#000} |
| .CodeRay .inline .inline{background:#ccc} |
| .CodeRay .inline .inline .inline{background:#bbb} |
| .CodeRay .inline .inline-delimiter{color:#d14} |
| .CodeRay .inline-delimiter{color:#d14} |
| .CodeRay .important{color:#555;font-weight:bold} |
| .CodeRay .interpreted{color:#b2b} |
| .CodeRay .instance-variable{color:#008080} |
| .CodeRay .label{color:#970} |
| .CodeRay .local-variable{color:#963} |
| .CodeRay .octal{color:#40e} |
| .CodeRay .predefined{color:#369} |
| .CodeRay .preprocessor{color:#579} |
| .CodeRay .pseudo-class{color:#555} |
| .CodeRay .directive{font-weight:bold} |
| .CodeRay .type{font-weight:bold} |
| .CodeRay .predefined-type{color:inherit} |
| .CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold} |
| .CodeRay .key{color:#808} |
| .CodeRay .key .delimiter{color:#606} |
| .CodeRay .key .char{color:#80f} |
| .CodeRay .value{color:#088} |
| .CodeRay .regexp .delimiter{color:#808} |
| .CodeRay .regexp .content{color:#808} |
| .CodeRay .regexp .modifier{color:#808} |
| .CodeRay .regexp .char{color:#d14} |
| .CodeRay .regexp .function{color:#404;font-weight:bold} |
| .CodeRay .string{color:#d20} |
| .CodeRay .string .string .string{background:#ffd0d0} |
| .CodeRay .string .content{color:#d14} |
| .CodeRay .string .char{color:#d14} |
| .CodeRay .string .delimiter{color:#d14} |
| .CodeRay .shell{color:#d14} |
| .CodeRay .shell .delimiter{color:#d14} |
| .CodeRay .symbol{color:#990073} |
| .CodeRay .symbol .content{color:#a60} |
| .CodeRay .symbol .delimiter{color:#630} |
| .CodeRay .tag{color:#008080} |
| .CodeRay .tag-special{color:#d70} |
| .CodeRay .variable{color:#036} |
| .CodeRay .insert{background:#afa} |
| .CodeRay .delete{background:#faa} |
| .CodeRay .change{color:#aaf;background:#007} |
| .CodeRay .head{color:#f8f;background:#505} |
| .CodeRay .insert .insert{color:#080} |
| .CodeRay .delete .delete{color:#800} |
| .CodeRay .change .change{color:#66f} |
| .CodeRay .head .head{color:#f4f} |
| </style> |
| <link rel="stylesheet" href="../katex/katex.min.css"> |
| <script src="../katex/katex.min.js"></script> |
| <script src="../katex/contrib/auto-render.min.js"></script> |
| <!-- Use KaTeX to render math once document is loaded, see |
| https://github.com/Khan/KaTeX/tree/master/contrib/auto-render --> |
| <script> |
| document.addEventListener("DOMContentLoaded", function () { |
| renderMathInElement( |
| document.body, |
| { |
| delimiters: [ |
| { left: "$$", right: "$$", display: true}, |
| { left: "\\[", right: "\\]", display: true}, |
| { left: "$", right: "$", display: false}, |
| { left: "\\(", right: "\\)", display: false} |
| ] |
| } |
| ); |
| }); |
| </script></head> |
| <body class="book toc2 toc-left" style="max-width: 100;"> |
| <div id="header"> |
| <h1>The OpenCL<sup>™</sup> Specification</h1> |
| <div class="details"> |
| <span id="author" class="author">Khronos<sup>®</sup> OpenCL Working Group</span><br> |
| <span id="revnumber">version v3.0.8,</span> |
| <span id="revdate">Wed, 30 Jun 2021 20:00:00 +0000</span> |
| <br><span id="revremark">from git branch: master commit: 09130de814688ec7b463cb089986b807c628ead3</span> |
| </div> |
| <div id="toc" class="toc2"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#_introduction">1. Introduction</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_normative_references">1.1. Normative References</a></li> |
| <li><a href="#_version_numbers">1.2. Version Numbers</a></li> |
| <li><a href="#unified-spec">1.3. Unified Specification</a></li> |
| </ul> |
| </li> |
| <li><a href="#_glossary">2. Glossary</a></li> |
| <li><a href="#_the_opencl_architecture">3. The OpenCL Architecture</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_platform_model">3.1. Platform Model</a></li> |
| <li><a href="#_execution_model">3.2. Execution Model</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_mapping_work_items_onto_an_ndrange">3.2.1. Mapping work-items onto an NDRange</a></li> |
| <li><a href="#_execution_of_kernel_instances">3.2.2. Execution of kernel-instances</a></li> |
| <li><a href="#device-side-enqueue">3.2.3. Device-side enqueue</a></li> |
| <li><a href="#execution-model-sync">3.2.4. Synchronization</a></li> |
| <li><a href="#_categories_of_kernels">3.2.5. Categories of Kernels</a></li> |
| </ul> |
| </li> |
| <li><a href="#_memory_model">3.3. Memory Model</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_fundamental_memory_regions">3.3.1. Fundamental Memory Regions</a></li> |
| <li><a href="#_memory_objects">3.3.2. Memory Objects</a></li> |
| <li><a href="#shared-virtual-memory">3.3.3. Shared Virtual Memory</a></li> |
| <li><a href="#_memory_consistency_model_for_opencl_1_x">3.3.4. Memory Consistency Model for OpenCL 1.x</a></li> |
| <li><a href="#memory-consistency-model">3.3.5. Memory Consistency Model for OpenCL 2.x</a></li> |
| <li><a href="#_overview_of_atomic_and_fence_operations">3.3.6. Overview of atomic and fence operations</a></li> |
| <li><a href="#memory-ordering-rules">3.3.7. Memory Ordering Rules</a></li> |
| </ul> |
| </li> |
| <li><a href="#opencl-framework">3.4. The OpenCL Framework</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_mixed_version_support">3.4.1. Mixed Version Support</a></li> |
| <li><a href="#_backwards_compatibility">3.4.2. Backwards Compatibility</a></li> |
| <li><a href="#_versioning">3.4.3. Versioning</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#opencl-platform-layer">4. The OpenCL Platform Layer</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_querying_platform_info">4.1. Querying Platform Info</a></li> |
| <li><a href="#platform-querying-devices">4.2. Querying Devices</a></li> |
| <li><a href="#_partitioning_a_device">4.3. Partitioning a Device</a></li> |
| <li><a href="#_contexts">4.4. Contexts</a></li> |
| </ul> |
| </li> |
| <li><a href="#opencl-runtime">5. The OpenCL Runtime</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_command_queues">5.1. Command Queues</a></li> |
| <li><a href="#_buffer_objects">5.2. Buffer Objects</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_creating_buffer_objects">5.2.1. Creating Buffer Objects</a></li> |
| <li><a href="#_reading_writing_and_copying_buffer_objects">5.2.2. Reading, Writing and Copying Buffer Objects</a></li> |
| <li><a href="#_filling_buffer_objects">5.2.3. Filling Buffer Objects</a></li> |
| <li><a href="#_mapping_buffer_objects">5.2.4. Mapping Buffer Objects</a></li> |
| </ul> |
| </li> |
| <li><a href="#_image_objects">5.3. Image Objects</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_creating_image_objects">5.3.1. Creating Image Objects</a></li> |
| <li><a href="#_querying_list_of_supported_image_formats">5.3.2. Querying List of Supported Image Formats</a></li> |
| <li><a href="#_reading_writing_and_copying_image_objects">5.3.3. Reading, Writing and Copying Image Objects</a></li> |
| <li><a href="#_filling_image_objects">5.3.4. Filling Image Objects</a></li> |
| <li><a href="#_copying_between_image_and_buffer_objects">5.3.5. Copying between Image and Buffer Objects</a></li> |
| <li><a href="#_mapping_image_objects">5.3.6. Mapping Image Objects</a></li> |
| <li><a href="#image-object-queries">5.3.7. Image Object Queries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_pipes">5.4. Pipes</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_creating_pipe_objects">5.4.1. Creating Pipe Objects</a></li> |
| <li><a href="#_pipe_object_queries">5.4.2. Pipe Object Queries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_querying_unmapping_migrating_retaining_and_releasing_memory_objects">5.5. Querying, Unmapping, Migrating, Retaining and Releasing Memory Objects</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_retaining_and_releasing_memory_objects">5.5.1. Retaining and Releasing Memory Objects</a></li> |
| <li><a href="#unmapping-mapped-memory">5.5.2. Unmapping Mapped Memory Objects</a></li> |
| <li><a href="#accessing-mapped-regions">5.5.3. Accessing mapped regions of a memory object</a></li> |
| <li><a href="#_migrating_memory_objects">5.5.4. Migrating Memory Objects</a></li> |
| <li><a href="#memory-object-queries">5.5.5. Memory Object Queries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_shared_virtual_memory">5.6. Shared Virtual Memory</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_svm_sharing_granularity_coarse_and_fine_grained_sharing">5.6.1. SVM sharing granularity: coarse- and fine- grained sharing</a></li> |
| <li><a href="#_memory_consistency_for_svm_allocations">5.6.2. Memory consistency for SVM allocations</a></li> |
| </ul> |
| </li> |
| <li><a href="#_sampler_objects">5.7. Sampler Objects</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_creating_sampler_objects">5.7.1. Creating Sampler Objects</a></li> |
| <li><a href="#_sampler_object_queries">5.7.2. Sampler Object Queries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_program_objects">5.8. Program Objects</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_creating_program_objects">5.8.1. Creating Program Objects</a></li> |
| <li><a href="#_retaining_and_releasing_program_objects">5.8.2. Retaining and Releasing Program Objects</a></li> |
| <li><a href="#_setting_spir_v_specialization_constants">5.8.3. Setting SPIR-V specialization constants</a></li> |
| <li><a href="#_building_program_executables">5.8.4. Building Program Executables</a></li> |
| <li><a href="#_separate_compilation_and_linking_of_programs">5.8.5. Separate Compilation and Linking of Programs</a></li> |
| <li><a href="#compiler-options">5.8.6. Compiler Options</a></li> |
| <li><a href="#linker-options">5.8.7. Linker Options</a></li> |
| <li><a href="#_unloading_the_opencl_compiler">5.8.8. Unloading the OpenCL Compiler</a></li> |
| <li><a href="#_program_object_queries">5.8.9. Program Object Queries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_kernel_objects">5.9. Kernel Objects</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_creating_kernel_objects">5.9.1. Creating Kernel Objects</a></li> |
| <li><a href="#_setting_kernel_arguments">5.9.2. Setting Kernel Arguments</a></li> |
| <li><a href="#_copying_kernel_objects">5.9.3. Copying Kernel Objects</a></li> |
| <li><a href="#_kernel_object_queries">5.9.4. Kernel Object Queries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_executing_kernels">5.10. Executing Kernels</a></li> |
| <li><a href="#event-objects">5.11. Event Objects</a></li> |
| <li><a href="#markers-barriers-waiting-for-events">5.12. Markers, Barriers and Waiting for Events</a></li> |
| <li><a href="#_out_of_order_execution_of_kernels_and_memory_object_commands">5.13. Out-of-order Execution of Kernels and Memory Object Commands</a></li> |
| <li><a href="#profiling-operations">5.14. Profiling Operations on Memory Objects and Kernels</a></li> |
| <li><a href="#_flush_and_finish">5.15. Flush and Finish</a></li> |
| </ul> |
| </li> |
| <li><a href="#_associated_opencl_specification">6. Associated OpenCL specification</a> |
| <ul class="sectlevel2"> |
| <li><a href="#spirv-il">6.1. SPIR-V Intermediate Language</a></li> |
| <li><a href="#opencl-extensions">6.2. Extensions to OpenCL</a></li> |
| <li><a href="#opencl-c-kernel-language">6.3. The OpenCL C Kernel Language</a></li> |
| </ul> |
| </li> |
| <li><a href="#opencl-embedded-profile">7. OpenCL Embedded Profile</a></li> |
| <li><a href="#_host_environment_and_thread_safety">Appendix A: Host environment and thread safety</a> |
| <ul class="sectlevel2"> |
| <li><a href="#shared-opencl-objects">Shared OpenCL Objects</a></li> |
| <li><a href="#_multiple_host_threads">Multiple Host Threads</a></li> |
| <li><a href="#_global_constructors_and_destructors">Global constructors and destructors</a></li> |
| </ul> |
| </li> |
| <li><a href="#_portability">Appendix B: Portability</a></li> |
| <li><a href="#data-types">Appendix C: Application Data Types</a> |
| <ul class="sectlevel2"> |
| <li><a href="#scalar-data-types">Supported Application Scalar Data Types</a></li> |
| <li><a href="#vector-data-types">Supported Application Vector Data Types</a></li> |
| <li><a href="#alignment-app-data-types">Alignment of Application Data Types</a></li> |
| <li><a href="#_vector_literals">Vector Literals</a></li> |
| <li><a href="#vector-components">Vector Components</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_named_vector_components_notation">Named vector components notation</a></li> |
| <li><a href="#_highlow_vector_component_notation">High/Low vector component notation</a></li> |
| <li><a href="#_native_vector_type_notation">Native vector type notation</a></li> |
| </ul> |
| </li> |
| <li><a href="#_implicit_conversions">Implicit Conversions</a></li> |
| <li><a href="#_explicit_casts">Explicit Casts</a></li> |
| <li><a href="#_other_operators_and_functions">Other operators and functions</a></li> |
| <li><a href="#_application_constant_definitions">Application constant definitions</a></li> |
| </ul> |
| </li> |
| <li><a href="#check-copy-overlap">Appendix D: Checking for Memory Copy Overlap</a></li> |
| <li><a href="#changes_to_opencl">Appendix E: Changes to OpenCL</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_summary_of_changes_from_opencl_1_0_to_opencl_1_1">Summary of changes from OpenCL 1.0 to OpenCL 1.1</a></li> |
| <li><a href="#_summary_of_changes_from_opencl_1_1_to_opencl_1_2">Summary of changes from OpenCL 1.1 to OpenCL 1.2</a></li> |
| <li><a href="#_summary_of_changes_from_opencl_1_2_to_opencl_2_0">Summary of changes from OpenCL 1.2 to OpenCL 2.0</a></li> |
| <li><a href="#_summary_of_changes_from_opencl_2_0_to_opencl_2_1">Summary of changes from OpenCL 2.0 to OpenCL 2.1</a></li> |
| <li><a href="#_summary_of_changes_from_opencl_2_1_to_opencl_2_2">Summary of changes from OpenCL 2.1 to OpenCL 2.2</a></li> |
| <li><a href="#_summary_of_changes_from_opencl_2_2_to_opencl_3_0">Summary of changes from OpenCL 2.2 to OpenCL 3.0</a></li> |
| </ul> |
| </li> |
| <li><a href="#error_codes">Appendix F: Error Codes</a></li> |
| <li><a href="#error_other_misc_enums">Appendix G: Other Miscellaneous Enums</a></li> |
| <li><a href="#opencl-3.0-backwards-compatibility">Appendix H: OpenCL 3.0 Backwards Compatibility</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_shared_virtual_memory_2">Shared Virtual Memory</a></li> |
| <li><a href="#_memory_consistency_model">Memory Consistency Model</a></li> |
| <li><a href="#_device_side_enqueue">Device-Side Enqueue</a></li> |
| <li><a href="#_pipes_2">Pipes</a></li> |
| <li><a href="#_program_scope_global_variables">Program Scope Global Variables</a></li> |
| <li><a href="#_non_uniform_work_groups">Non-Uniform Work Groups</a></li> |
| <li><a href="#_read_write_images">Read-Write Images</a></li> |
| <li><a href="#_creating_2d_images_from_buffers">Creating 2D Images from Buffers</a></li> |
| <li><a href="#_srgb_images">sRGB Images</a></li> |
| <li><a href="#_depth_images">Depth Images</a></li> |
| <li><a href="#_device_and_host_timer_synchronization">Device and Host Timer Synchronization</a></li> |
| <li><a href="#_intermediate_language_programs">Intermediate Language Programs</a></li> |
| <li><a href="#_subgroups">Subgroups</a></li> |
| <li><a href="#_program_initialization_and_clean_up_kernels">Program Initialization and Clean-Up Kernels</a></li> |
| <li><a href="#_3d_image_writes">3D Image Writes</a></li> |
| <li><a href="#_work_group_collective_functions">Work Group Collective Functions</a></li> |
| <li><a href="#_generic_address_space">Generic Address Space</a></li> |
| <li><a href="#_language_features_that_were_already_optional">Language Features that Were Already Optional</a></li> |
| </ul> |
| </li> |
| <li><a href="#_acknowledgements">Acknowledgements</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div style="page-break-after: always;"></div> |
| <div class="paragraph"> |
| <p>Copyright 2008-2021 The Khronos Group.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This specification is protected by copyright laws and contains material proprietary |
| to the Khronos Group, Inc. Except as described by these terms, it or any components |
| may not be reproduced, republished, distributed, transmitted, displayed, broadcast |
| or otherwise exploited in any manner without the express prior written permission |
| of Khronos Group.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Khronos Group grants a conditional copyright license to use and reproduce the |
| unmodified specification for any purpose, without fee or royalty, EXCEPT no licenses |
| to any patent, trademark or other intellectual property rights are granted under |
| these terms. Parties desiring to implement the specification and make use of |
| Khronos trademarks in relation to that implementation, and receive reciprocal patent |
| license protection under the Khronos IP Policy must become Adopters and confirm the |
| implementation as conformant under the process defined by Khronos for this |
| specification; see <a href="https://www.khronos.org/adopters" class="bare">https://www.khronos.org/adopters</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Khronos Group makes no, and expressly disclaims any, representations or warranties, |
| express or implied, regarding this specification, including, without limitation: |
| merchantability, fitness for a particular purpose, non-infringement of any |
| intellectual property, correctness, accuracy, completeness, timeliness, and |
| reliability. Under no circumstances will the Khronos Group, or any of its Promoters, |
| Contributors or Members, or their respective partners, officers, directors, |
| employees, agents or representatives be liable for any damages, whether direct, |
| indirect, special or consequential damages for lost revenues, lost profits, or |
| otherwise, arising from or in connection with these materials.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Vulkan and Khronos are registered trademarks, and OpenXR, SPIR, SPIR-V, SYCL, WebGL, |
| WebCL, OpenVX, OpenVG, EGL, COLLADA, glTF, NNEF, OpenKODE, OpenKCAM, StreamInput, |
| OpenWF, OpenSL ES, OpenMAX, OpenMAX AL, OpenMAX IL, OpenMAX DL, OpenML and DevU are |
| trademarks of the Khronos Group Inc. ASTC is a trademark of ARM Holdings PLC, |
| OpenCL is a trademark of Apple Inc. and OpenGL and OpenML are registered trademarks |
| and the OpenGL ES and OpenGL SC logos are trademarks of Hewlett Packard Enterprise |
| used under license by Khronos. All other product names, trademarks, |
| and/or company names are used solely for identification and belong to their |
| respective owners.</p> |
| </div> |
| <div style="page-break-after: always;"></div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_introduction"><a class="anchor" href="#_introduction"></a>1. Introduction</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Modern processor architectures have embraced parallelism as an important |
| pathway to increased performance. |
| Facing technical challenges with higher clock speeds in a fixed power |
| envelope, Central Processing Units (CPUs) now improve performance by adding |
| multiple cores. |
| Graphics Processing Units (GPUs) have also evolved from fixed function |
| rendering devices into programmable parallel processors. |
| As todays computer systems often include highly parallel CPUs, GPUs and |
| other types of processors, it is important to enable software developers to |
| take full advantage of these heterogeneous processing platforms.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Creating applications for heterogeneous parallel processing platforms is |
| challenging as traditional programming approaches for multi-core CPUs and |
| GPUs are very different. |
| CPU-based parallel programming models are typically based on standards but |
| usually assume a shared address space and do not encompass vector |
| operations. |
| General purpose GPU programming models address complex memory hierarchies |
| and vector operations but are traditionally platform-, vendor- or |
| hardware-specific. |
| These limitations make it difficult for a developer to access the compute |
| power of heterogeneous CPUs, GPUs and other types of processors from a |
| single, multi-platform source code base. |
| More than ever, there is a need to enable software developers to effectively |
| take full advantage of heterogeneous processing platforms from high |
| performance compute servers, through desktop computer systems to handheld |
| devices - that include a diverse mix of parallel CPUs, GPUs and other |
| processors such as DSPs and the Cell/B.E. |
| processor.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>OpenCL</strong> (Open Computing Language) is an open royalty-free standard for |
| general purpose parallel programming across CPUs, GPUs and other processors, |
| giving software developers portable and efficient access to the power of |
| these heterogeneous processing platforms.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL supports a wide range of applications, ranging from embedded and |
| consumer software to HPC solutions, through a low-level, high-performance, |
| portable abstraction. |
| By creating an efficient, close-to-the-metal programming interface, OpenCL |
| will form the foundation layer of a parallel computing ecosystem of |
| platform-independent tools, middleware and applications. |
| OpenCL is particularly suited to play an increasingly significant role in |
| emerging interactive graphics applications that combine general parallel |
| compute algorithms with graphics rendering pipelines.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL consists of an API for coordinating parallel computation across |
| heterogeneous processors, a cross-platform programming language, and a |
| cross-platform intermediate language with a well-specified computation |
| environment. |
| The OpenCL standard:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Supports both data- and task-based parallel programming models</p> |
| </li> |
| <li> |
| <p>Supports kernels written using a subset of ISO C99 with extensions |
| for parallel execution</p> |
| </li> |
| <li> |
| <p>Supports kernels represented by a portable and self-contained |
| intermediate language (e.g. SPIR-V) with support for parallel execution</p> |
| </li> |
| <li> |
| <p>Defines consistent numerical requirements based on IEEE 754</p> |
| </li> |
| <li> |
| <p>Defines a configuration profile for handheld and embedded devices</p> |
| </li> |
| <li> |
| <p>Supports efficient interop with OpenGL, OpenGL ES and other APIs</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This document begins with an overview of basic concepts and the architecture |
| of OpenCL, followed by a detailed description of its execution model, memory |
| model and synchronization support. |
| It then discusses the OpenCL platform and runtime API. |
| Some examples are given that describe sample compute use-cases and how they |
| would be written in OpenCL. |
| The specification is divided into a core specification that any OpenCL |
| compliant implementation must support; a handheld/embedded profile which |
| relaxes the OpenCL compliance requirements for handheld and embedded |
| devices; and a set of optional extensions that are likely to move into the |
| core specification in later revisions of the OpenCL specification.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_normative_references"><a class="anchor" href="#_normative_references"></a>1.1. Normative References</h3> |
| <div class="paragraph"> |
| <p>Normative references are references to external documents or resources to |
| which implementers of OpenCL must comply with all, or specified portions of, |
| as described in this specification.</p> |
| </div> |
| <div id="iso-c11" class="paragraph"> |
| <p><em>ISO/IEC 9899:2011 - Information technology - Programming languages - C</em>, |
| <a href="https://www.iso.org/standard/57853.html" class="bare">https://www.iso.org/standard/57853.html</a> (final specification), |
| <a href="http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1570.pdf" class="bare">http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1570.pdf</a> (last public |
| draft).</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_version_numbers"><a class="anchor" href="#_version_numbers"></a>1.2. Version Numbers</h3> |
| <div class="paragraph"> |
| <p>The OpenCL version number follows a <em>major.minor-revision</em> scheme. When this |
| version number is used within the API it generally only includes the |
| <em>major.minor</em> components of the version number.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A difference in the <em>major</em> or <em>minor</em> version number indicates that some |
| amount of new functionality has been added to the specification, and may also |
| include behavior changes and bug fixes. |
| Functionality may also be deprecated or removed when the <em>major</em> or <em>minor</em> |
| version changes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A difference in the <em>revision</em> number indicates small changes to the |
| specification, typically to fix a bug or to clarify language. |
| When the <em>revision</em> number changes there may be an impact on the behavior of |
| existing functionality, but this should not affect backwards compatibility. |
| Functionality should not be added or removed when the <em>revision</em> number |
| changes.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="unified-spec"><a class="anchor" href="#unified-spec"></a>1.3. Unified Specification</h3> |
| <div class="paragraph"> |
| <p>This document specifies all versions of the OpenCL API.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are three ways that an OpenCL feature may be described in terms of what |
| versions of OpenCL support that feature.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Missing before <em>major.minor</em>: Features that were introduced in |
| version <em>major.minor</em>. Implementations of an earlier version of OpenCL |
| will not provide these features.</p> |
| </li> |
| <li> |
| <p>Deprecated by <em>major.minor</em>: Features that were deprecated |
| in version <em>major.minor</em>, see the definition of deprecation in the |
| glossary.</p> |
| </li> |
| <li> |
| <p>Universal: Features that have no mention of what version they are missing |
| before or deprecated by are available in all versions of OpenCL.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_glossary"><a class="anchor" href="#_glossary"></a>2. Glossary</h2> |
| <div class="sectionbody"> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Application </dt> |
| <dd> |
| <p>The combination of the program running on the host and OpenCL devices.</p> |
| </dd> |
| <dt class="hdlist1">Acquire semantics </dt> |
| <dd> |
| <p>One of the memory order semantics defined for synchronization |
| operations. |
| Acquire semantics apply to atomic operations that load from memory. |
| Given two units of execution, <strong>A</strong> and <strong>B</strong>, acting on a shared atomic |
| object <strong>M</strong>, if <strong>A</strong> uses an atomic load of <strong>M</strong> with acquire semantics to |
| synchronize-with an atomic store to <strong>M</strong> by <strong>B</strong> that used release |
| semantics, then <strong>A</strong>'s atomic load will occur before any subsequent |
| operations by <strong>A</strong>. |
| Note that the memory orders <em>release</em>, <em>sequentially consistent</em>, and |
| <em>acquire_release</em> all include <em>release semantics</em> and effectively pair |
| with a load using acquire semantics.</p> |
| </dd> |
| <dt class="hdlist1">Acquire release semantics </dt> |
| <dd> |
| <p>A memory order semantics for synchronization operations (such as atomic |
| operations) that has the properties of both acquire and release memory |
| orders. |
| It is used with read-modify-write operations.</p> |
| </dd> |
| <dt class="hdlist1">Atomic operations </dt> |
| <dd> |
| <p>Operations that at any point, and from any perspective, have either |
| occurred completely, or not at all. |
| Memory orders associated with atomic operations may constrain the |
| visibility of loads and stores with respect to the atomic operations |
| (see <em>relaxed semantics</em>, <em>acquire semantics</em>, <em>release semantics</em> or |
| <em>acquire release semantics</em>).</p> |
| </dd> |
| <dt class="hdlist1">Blocking and Non-Blocking Enqueue API calls </dt> |
| <dd> |
| <p>A <em>non-blocking enqueue API call</em> places a <em>command</em> on a |
| <em>command-queue</em> and returns immediately to the host. |
| The <em>blocking-mode enqueue API calls</em> do not return to the host until |
| the command has completed.</p> |
| </dd> |
| <dt class="hdlist1">Barrier </dt> |
| <dd> |
| <p>There are three types of <em>barriers</em> a command-queue barrier, a |
| work-group barrier and a sub-group barrier.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The OpenCL API provides a function to enqueue a <em>command-queue</em> |
| <em>barrier</em> command. |
| This <em>barrier</em> command ensures that all previously enqueued commands to |
| a command-queue have finished execution before any following <em>commands</em> |
| enqueued in the <em>command-queue</em> can begin execution.</p> |
| </li> |
| <li> |
| <p>The OpenCL kernel execution model provides built-in <em>work-group barrier</em> |
| functionality. |
| This <em>barrier</em> built-in function can be used by a <em>kernel</em> executing on |
| a <em>device</em> to perform synchronization between <em>work-items</em> in a |
| <em>work-group</em> executing the <em>kernel</em>. |
| All the <em>work-items</em> of a <em>work-group</em> must execute the <em>barrier</em> |
| construct before any are allowed to continue execution beyond the |
| <em>barrier</em>.</p> |
| </li> |
| <li> |
| <p>The OpenCL kernel execution model provides built-in <em>sub-group barrier</em> |
| functionality. |
| This <em>barrier</em> built-in function can be used by a <em>kernel</em> executing on |
| a <em>device</em> to perform synchronization between <em>work-items</em> in a |
| <em>sub-group</em> executing the <em>kernel</em>. |
| All the <em>work-items</em> of a <em>sub-group</em> must execute the <em>barrier</em> |
| construct before any are allowed to continue execution beyond the |
| <em>barrier</em>.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1">Buffer Object </dt> |
| <dd> |
| <p>A memory object that stores a linear collection of bytes. |
| Buffer objects are accessible using a pointer in a <em>kernel</em> executing on |
| a <em>device</em>. |
| Buffer objects can be manipulated by the host using OpenCL API calls. |
| A <em>buffer object</em> encapsulates the following information:</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Size in bytes.</p> |
| </li> |
| <li> |
| <p>Properties that describe usage information and which region to allocate |
| from.</p> |
| </li> |
| <li> |
| <p>Buffer data.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1">Built-in Kernel </dt> |
| <dd> |
| <p>A <em>built-in kernel</em> is a <em>kernel</em> that is executed on an OpenCL <em>device</em> |
| or <em>custom device</em> by fixed-function hardware or in firmware. |
| <em>Applications</em> can query the <em>built-in kernels</em> supported by a <em>device</em> |
| or <em>custom device</em>. |
| A <em>program object</em> can only contain <em>kernels</em> written in OpenCL C or |
| <em>built-in kernels</em> but not both. |
| See also <em>Kernel</em> and <em>Program</em>.</p> |
| </dd> |
| <dt class="hdlist1">Child kernel </dt> |
| <dd> |
| <p>See <em>Device-side enqueue</em>.</p> |
| </dd> |
| <dt class="hdlist1">Command </dt> |
| <dd> |
| <p>The OpenCL operations that are submitted to a <em>command-queue</em> for |
| execution. |
| For example, OpenCL commands issue kernels for execution on a compute |
| device, manipulate memory objects, etc.</p> |
| </dd> |
| <dt class="hdlist1">Command-queue </dt> |
| <dd> |
| <p>An object that holds <em>commands</em> that will be executed on a specific |
| <em>device</em>. |
| The <em>command-queue</em> is created on a specific <em>device</em> in a <em>context</em>. |
| <em>Commands</em> to a <em>command-queue</em> are queued in-order but may be executed |
| in-order or out-of-order. |
| <em>Refer to In-order Execution_and_Out-of-order Execution</em>.</p> |
| </dd> |
| <dt class="hdlist1">Command-queue Barrier </dt> |
| <dd> |
| <p>See <em>Barrier</em>.</p> |
| </dd> |
| <dt class="hdlist1">Command synchronization </dt> |
| <dd> |
| <p>Constraints on the order that commands are launched for execution on a |
| device defined in terms of the synchronization points that occur between |
| commands in host command-queues and between commands in device-side |
| command-queues. |
| See <em>synchronization points</em>.</p> |
| </dd> |
| <dt class="hdlist1">Complete </dt> |
| <dd> |
| <p>The final state in the six state model for the execution of a command. |
| The transition into this state occurs is signaled through event objects |
| or callback functions associated with a command.</p> |
| </dd> |
| <dt class="hdlist1">Compute Device Memory </dt> |
| <dd> |
| <p>This refers to one or more memories attached to the compute device.</p> |
| </dd> |
| <dt class="hdlist1">Compute Unit </dt> |
| <dd> |
| <p>An OpenCL <em>device</em> has one or more <em>compute units</em>. |
| A <em>work-group</em> executes on a single <em>compute unit</em>. |
| A <em>compute unit</em> is composed of one or more <em>processing elements</em> and |
| <em>local memory</em>. |
| A <em>compute unit</em> may also include dedicated texture filter units that |
| can be accessed by its processing elements.</p> |
| </dd> |
| <dt class="hdlist1">Concurrency </dt> |
| <dd> |
| <p>A property of a system in which a set of tasks in a system can remain |
| active and make progress at the same time. |
| To utilize concurrent execution when running a program, a programmer |
| must identify the concurrency in their problem, expose it within the |
| source code, and then exploit it using a notation that supports |
| concurrency.</p> |
| </dd> |
| <dt class="hdlist1">Constant Memory </dt> |
| <dd> |
| <p>A region of <em>global memory</em> that remains constant during the execution |
| of a <em>kernel</em>. |
| The <em>host</em> allocates and initializes memory objects placed into |
| <em>constant memory</em>.</p> |
| </dd> |
| <dt class="hdlist1">Context </dt> |
| <dd> |
| <p>The environment within which the kernels execute and the domain in which |
| synchronization and memory management is defined. |
| The <em>context</em> includes a set of <em>devices</em>, the memory accessible to |
| those <em>devices</em>, the corresponding memory properties and one or more |
| <em>command-queues</em> used to schedule execution of a <em>kernel(s)</em> or |
| operations on <em>memory objects</em>.</p> |
| </dd> |
| <dt class="hdlist1">Control flow </dt> |
| <dd> |
| <p>The flow of instructions executed by a work-item. |
| Multiple logically related work-items may or may not execute the same |
| control flow. |
| The control flow is said to be <em>converged</em> if all the work-items in the |
| set execution the same stream of instructions. |
| In a <em>diverged</em> control flow, the work-items in the set execute |
| different instructions. |
| At a later point, if a diverged control flow becomes converged, it is |
| said to be a re-converged control flow.</p> |
| </dd> |
| <dt class="hdlist1">Converged control flow </dt> |
| <dd> |
| <p>See <em>Control flow</em>.</p> |
| </dd> |
| <dt class="hdlist1">Custom Device </dt> |
| <dd> |
| <p>An OpenCL <em>device</em> that fully implements the OpenCL Runtime but does not |
| support <em>programs</em> written in OpenCL C. |
| A custom device may be specialized non-programmable hardware that is |
| very power efficient and performant for directed tasks or hardware with |
| limited programmable capabilities such as specialized DSPs. |
| Custom devices are not OpenCL conformant. |
| Custom devices may support an online compiler. |
| Programs for custom devices can be created using the OpenCL runtime APIs |
| that allow OpenCL programs to be created from source (if an online |
| compiler is supported) and/or binary, or from <em>built-in kernels</em> |
| supported by the <em>device</em>. |
| See also <em>Device</em>.</p> |
| </dd> |
| <dt class="hdlist1">Data Parallel Programming Model </dt> |
| <dd> |
| <p>Traditionally, this term refers to a programming model where concurrency |
| is expressed as instructions from a single program applied to multiple |
| elements within a set of data structures. |
| The term has been generalized in OpenCL to refer to a model wherein a |
| set of instructions from a single program are applied concurrently to |
| each point within an abstract domain of indices.</p> |
| </dd> |
| <dt class="hdlist1">Data race </dt> |
| <dd> |
| <p>The execution of a program contains a data race if it contains two |
| actions in different work-items or host threads where (1) one action |
| modifies a memory location and the other action reads or modifies the |
| same memory location, and (2) at least one of these actions is not |
| atomic, or the corresponding memory scopes are not inclusive, and (3) |
| the actions are global actions unordered by the global-happens-before |
| relation or are local actions unordered by the local-happens before |
| relation.</p> |
| </dd> |
| <dt class="hdlist1">Deprecation </dt> |
| <dd> |
| <p>Existing features are marked as deprecated if their usage is not |
| recommended as that feature is being de-emphasized, superseded and may |
| be removed from a future version of the specification.</p> |
| </dd> |
| <dt class="hdlist1">Device </dt> |
| <dd> |
| <p>A <em>device</em> is a collection of <em>compute units</em>. |
| A <em>command-queue</em> is used to queue <em>commands</em> to a <em>device</em>. |
| Examples of <em>commands</em> include executing <em>kernels</em>, or reading and |
| writing <em>memory objects</em>. |
| OpenCL devices typically correspond to a GPU, a multi-core CPU, and |
| other processors such as DSPs and the Cell/B.E. |
| processor.</p> |
| </dd> |
| <dt class="hdlist1">Device-side enqueue </dt> |
| <dd> |
| <p>A mechanism whereby a kernel-instance is enqueued by a kernel-instance |
| running on a device without direct involvement by the host program. |
| This produces <em>nested parallelism</em>; i.e. additional levels of |
| concurrency are nested inside a running kernel-instance. |
| The kernel-instance executing on a device (the <em>parent kernel</em>) enqueues |
| a kernel-instance (the <em>child kernel</em>) to a device-side command queue. |
| Child and parent kernels execute asynchronously though a parent kernel |
| does not complete until all of its child-kernels have completed.</p> |
| </dd> |
| <dt class="hdlist1">Diverged control flow </dt> |
| <dd> |
| <p>See <em>Control flow</em>.</p> |
| </dd> |
| <dt class="hdlist1">Ended </dt> |
| <dd> |
| <p>The fifth state in the six state model for the execution of a command. |
| The transition into this state occurs when execution of a command has |
| ended. |
| When a Kernel-enqueue command ends, all of the work-groups associated |
| with that command have finished their execution.</p> |
| </dd> |
| <dt class="hdlist1">Event Object </dt> |
| <dd> |
| <p>An <em>event object</em> encapsulates the status of an operation such as a |
| <em>command</em>. |
| It can be used to synchronize operations in a context.</p> |
| </dd> |
| <dt class="hdlist1">Event Wait List </dt> |
| <dd> |
| <p>An <em>event wait list</em> is a list of <em>event objects</em> that can be used to |
| control when a particular <em>command</em> begins execution.</p> |
| </dd> |
| <dt class="hdlist1">Fence </dt> |
| <dd> |
| <p>A memory ordering operation without an associated atomic object. |
| A fence can use the <em>acquire semantics, release semantics</em>, or <em>acquire |
| release semantics</em>.</p> |
| </dd> |
| <dt class="hdlist1">Framework </dt> |
| <dd> |
| <p>A software system that contains the set of components to support |
| software development and execution. |
| A <em>framework</em> typically includes libraries, APIs, runtime systems, |
| compilers, etc.</p> |
| </dd> |
| <dt class="hdlist1">Generic address space </dt> |
| <dd> |
| <p>An address space that include the <em>private</em>, <em>local</em>, and <em>global</em> |
| address spaces available to a device. |
| The generic address space supports conversion of pointers to and from |
| private, local and global address spaces, and hence lets a programmer |
| write a single function that at compile time can take arguments from any |
| of the three named address spaces.</p> |
| </dd> |
| <dt class="hdlist1">Global Happens before </dt> |
| <dd> |
| <p>See <em>Happens before</em>.</p> |
| </dd> |
| <dt class="hdlist1">Global ID </dt> |
| <dd> |
| <p>A <em>global ID</em> is used to uniquely identify a <em>work-item</em> and is derived |
| from the number of <em>global work-items</em> specified when executing a |
| <em>kernel</em>. |
| The <em>global ID</em> is a N-dimensional value that starts at (0, 0, …​ 0). |
| See also <em>Local ID</em>.</p> |
| </dd> |
| <dt class="hdlist1">Global Memory </dt> |
| <dd> |
| <p>A memory region accessible to all <em>work-items</em> executing in a <em>context</em>. |
| It is accessible to the <em>host</em> using <em>commands</em> such as read, write and |
| map. |
| <em>Global memory</em> is included within the <em>generic address space</em> that |
| includes the private and local address spaces.</p> |
| </dd> |
| <dt class="hdlist1">GL share group </dt> |
| <dd> |
| <p>A <em>GL share group</em> object manages shared OpenGL or OpenGL ES resources |
| such as textures, buffers, framebuffers, and renderbuffers and is |
| associated with one or more GL context objects. |
| The <em>GL share group</em> is typically an opaque object and not directly |
| accessible.</p> |
| </dd> |
| <dt class="hdlist1">Handle </dt> |
| <dd> |
| <p>An opaque type that references an <em>object</em> allocated by OpenCL. |
| Any operation on an <em>object</em> occurs by reference to that objects handle.</p> |
| </dd> |
| <dt class="hdlist1">Happens before </dt> |
| <dd> |
| <p>An ordering relationship between operations that execute on multiple |
| units of execution. |
| If an operation A happens-before operation B then A must occur before B; |
| in particular, any value written by A will be visible to B. |
| We define two separate happens before relations: <em>global-happens-before</em> |
| and <em>local-happens-before</em>. |
| These are defined in <a href="#memory-ordering-rules">Memory Ordering Rules</a>.</p> |
| </dd> |
| <dt class="hdlist1">Host </dt> |
| <dd> |
| <p>The <em>host</em> interacts with the <em>context</em> using the OpenCL API.</p> |
| </dd> |
| <dt class="hdlist1">Host-thread </dt> |
| <dd> |
| <p>The unit of execution that executes the statements in the host program.</p> |
| </dd> |
| <dt class="hdlist1">Host pointer </dt> |
| <dd> |
| <p>A pointer to memory that is in the virtual address space on the <em>host</em>.</p> |
| </dd> |
| <dt class="hdlist1">Illegal </dt> |
| <dd> |
| <p>Behavior of a system that is explicitly not allowed and will be reported |
| as an error when encountered by OpenCL.</p> |
| </dd> |
| <dt class="hdlist1">Image Object </dt> |
| <dd> |
| <p>A <em>memory object</em> that stores a two- or three-dimensional structured |
| array. |
| Image data can only be accessed with read and write functions. |
| The read functions use a <em>sampler</em>.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The <em>image object</em> encapsulates the following information:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Dimensions of the image.</p> |
| </li> |
| <li> |
| <p>Description of each element in the image.</p> |
| </li> |
| <li> |
| <p>Properties that describe usage information and which region to allocate |
| from.</p> |
| </li> |
| <li> |
| <p>Image data.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The elements of an image are selected from a list of predefined image |
| formats.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1">Implementation Defined </dt> |
| <dd> |
| <p>Behavior that is explicitly allowed to vary between conforming |
| implementations of OpenCL. |
| An OpenCL implementor is required to document the implementation-defined |
| behavior.</p> |
| </dd> |
| <dt class="hdlist1">Independent Forward Progress </dt> |
| <dd> |
| <p>If an entity supports independent forward progress, then if it is |
| otherwise not dependent on any actions due to be performed by any other |
| entity (for example it does not wait on a lock held by, and thus that |
| must be released by, any other entity), then its execution cannot be |
| blocked by the execution of any other entity in the system (it will not |
| be starved). |
| Work-items in a subgroup, for example, typically do not support |
| independent forward progress, so one work-item in a subgroup may be |
| completely blocked (starved) if a different work-item in the same |
| subgroup enters a spin loop.</p> |
| </dd> |
| <dt class="hdlist1">In-order Execution </dt> |
| <dd> |
| <p>A model of execution in OpenCL where the <em>commands</em> in a <em>command-queue</em> |
| are executed in order of submission with each <em>command</em> running to |
| completion before the next one begins. |
| See Out-of-order Execution.</p> |
| </dd> |
| <dt class="hdlist1">Intermediate Language </dt> |
| <dd> |
| <p>A lower-level language that may be used to create programs. |
| SPIR-V is a required intermediate language (IL) for OpenCL 2.1 and 2.2 devices. |
| Other OpenCL devices may optionally support SPIR-V or other ILs.</p> |
| </dd> |
| <dt class="hdlist1">Kernel </dt> |
| <dd> |
| <p>A <em>kernel</em> is a function declared in a <em>program</em> and executed on an |
| OpenCL <em>device</em>. |
| A <em>kernel</em> is identified by the <code>__kernel</code> or <code>kernel</code> qualifier applied to |
| any function defined in a <em>program</em>.</p> |
| </dd> |
| <dt class="hdlist1">Kernel-instance </dt> |
| <dd> |
| <p>The work carried out by an OpenCL program occurs through the execution |
| of kernel-instances on devices. |
| The kernel instance is the <em>kernel object</em>, the values associated with |
| the arguments to the kernel, and the parameters that define the |
| <em>NDRange</em> index space.</p> |
| </dd> |
| <dt class="hdlist1">Kernel Object </dt> |
| <dd> |
| <p>A <em>kernel object</em> encapsulates a specific <em>kernel</em> function declared |
| in a <em>program</em> and the argument values to be used when executing this |
| <em>kernel</em> function.</p> |
| </dd> |
| <dt class="hdlist1">Kernel Language </dt> |
| <dd> |
| <p>A language that is used to represent source code for kernel. |
| Kernels may be directly created from OpenCL C kernel language |
| source strings. |
| Other kernel languages may be supported by compiling to SPIR-V, |
| another supported Intermediate Language, or to a device-specific |
| program binary format.</p> |
| </dd> |
| <dt class="hdlist1">Launch </dt> |
| <dd> |
| <p>The transition of a command from the <em>submitted</em> state to the <em>ready</em> |
| state. |
| See <em>Ready</em>.</p> |
| </dd> |
| <dt class="hdlist1">Local ID </dt> |
| <dd> |
| <p>A <em>local ID</em> specifies a unique <em>work-item ID</em> within a given |
| <em>work-group</em> that is executing a <em>kernel</em>. |
| The <em>local ID</em> is a N-dimensional value that starts at (0, 0, …​ 0). |
| See also <em>Global ID</em>.</p> |
| </dd> |
| <dt class="hdlist1">Local Memory </dt> |
| <dd> |
| <p>A memory region associated with a <em>work-group</em> and accessible only by |
| <em>work-items</em> in that <em>work-group</em>. |
| <em>Local memory</em> is included within the <em>generic address space</em> that |
| includes the private and global address spaces.</p> |
| </dd> |
| <dt class="hdlist1">Marker </dt> |
| <dd> |
| <p>A <em>command</em> queued in a <em>command-queue</em> that can be used to tag all |
| <em>commands</em> queued before the <em>marker</em> in the <em>command-queue</em>. |
| The <em>marker</em> command returns an <em>event</em> which can be used by the |
| <em>application</em> to queue a wait on the marker event i.e. wait for all |
| commands queued before the <em>marker</em> command to complete.</p> |
| </dd> |
| <dt class="hdlist1">Memory Consistency Model </dt> |
| <dd> |
| <p>Rules that define which values are observed when multiple units of |
| execution load data from any shared memory plus the synchronization |
| operations that constrain the order of memory operations and define |
| synchronization relationships. |
| The memory consistency model in OpenCL is based on the memory model from |
| the ISO C11 programming language.</p> |
| </dd> |
| <dt class="hdlist1">Memory Objects </dt> |
| <dd> |
| <p>A <em>memory object</em> is a handle to a reference counted region of <em>Global |
| Memory</em>. |
| Also see <em>Buffer Object</em> and <em>Image Object</em>.</p> |
| </dd> |
| <dt class="hdlist1">Memory Regions (or Pools) </dt> |
| <dd> |
| <p>A distinct address space in OpenCL. |
| <em>Memory regions</em> may overlap in physical memory though OpenCL will treat |
| them as logically distinct. |
| The <em>memory regions</em> are denoted as <em>private</em>, <em>local</em>, <em>constant,</em> and |
| <em>global</em>.</p> |
| </dd> |
| <dt class="hdlist1">Memory Scopes </dt> |
| <dd> |
| <p>These memory scopes define a hierarchy of visibilities when analyzing |
| the ordering constraints of memory operations. |
| They are defined by the values of the <strong>memory_scope</strong> enumeration |
| constant. |
| Current values are <strong>memory_scope_work_item</strong> (memory constraints only |
| apply to a single work-item and in practice apply only to image |
| operations), <strong>memory_scope_sub_group</strong> (memory-ordering constraints only |
| apply to work-items executing in a sub-group), <strong>memory_scope_work_group</strong> |
| (memory-ordering constraints only apply to work-items executing in a |
| work-group), <strong>memory_scope_device</strong> (memory-ordering constraints only |
| apply to work-items executing on a single device) and |
| <strong>memory_scope_all_svm_devices</strong> (memory-ordering constraints only apply |
| to work-items executing across multiple devices and when using shared |
| virtual memory).</p> |
| </dd> |
| <dt class="hdlist1">Modification Order </dt> |
| <dd> |
| <p>All modifications to a particular atomic object M occur in some |
| particular <em>total order</em>, called the <em>modification order</em> of M. |
| If A and B are modifications of an atomic object M, and A happens-before |
| B, then A shall precede B in the modification order of M. |
| Note that the modification order of an atomic object M is independent of |
| whether M is in local or global memory.</p> |
| </dd> |
| <dt class="hdlist1">Nested Parallelism </dt> |
| <dd> |
| <p>See <em>device-side enqueue</em>.</p> |
| </dd> |
| <dt class="hdlist1">Object </dt> |
| <dd> |
| <p>Objects are abstract representation of the resources that can be |
| manipulated by the OpenCL API. |
| Examples include <em>program objects</em>, <em>kernel objects</em>, and <em>memory |
| objects</em>.</p> |
| </dd> |
| <dt class="hdlist1">Out-of-Order Execution </dt> |
| <dd> |
| <p>A model of execution in which <em>commands</em> placed in the <em>work queue</em> may |
| begin and complete execution in any order consistent with constraints |
| imposed by <em>event wait lists_and_command-queue barrier</em>. |
| See <em>In-order Execution</em>.</p> |
| </dd> |
| <dt class="hdlist1">Parent device </dt> |
| <dd> |
| <p>The OpenCL <em>device</em> which is partitioned to create <em>sub-devices</em>. |
| Not all <em>parent devices</em> are <em>root devices</em>. |
| A <em>root device</em> might be partitioned and the <em>sub-devices</em> partitioned |
| again. |
| In this case, the first set of <em>sub-devices</em> would be <em>parent devices</em> |
| of the second set, but not the <em>root devices</em>. |
| Also see <em>Device</em>, <em>parent device</em> and <em>root device</em>.</p> |
| </dd> |
| <dt class="hdlist1">Parent kernel </dt> |
| <dd> |
| <p>see <em>Device-side enqueue</em>.</p> |
| </dd> |
| <dt class="hdlist1">Pipe </dt> |
| <dd> |
| <p>The <em>pipe</em> memory object conceptually is an ordered sequence of data |
| items. |
| A pipe has two endpoints: a write endpoint into which data items are |
| inserted, and a read endpoint from which data items are removed. |
| At any one time, only one kernel instance may write into a pipe, and |
| only one kernel instance may read from a pipe. |
| To support the producer consumer design pattern, one kernel instance |
| connects to the write endpoint (the producer) while another kernel |
| instance connects to the reading endpoint (the consumer).</p> |
| </dd> |
| <dt class="hdlist1">Platform </dt> |
| <dd> |
| <p>The <em>host</em> plus a collection of <em>devices</em> managed by the OpenCL |
| <em>framework</em> that allow an application to share <em>resources</em> and execute |
| <em>kernels</em> on <em>devices</em> in the <em>platform</em>.</p> |
| </dd> |
| <dt class="hdlist1">Private Memory </dt> |
| <dd> |
| <p>A region of memory private to a <em>work-item</em>. |
| Variables defined in one <em>work-items</em> <em>private memory</em> are not visible |
| to another <em>work-item</em>.</p> |
| </dd> |
| <dt class="hdlist1">Processing Element </dt> |
| <dd> |
| <p>A virtual scalar processor. |
| A work-item may execute on one or more processing elements.</p> |
| </dd> |
| <dt class="hdlist1">Program </dt> |
| <dd> |
| <p>An OpenCL <em>program</em> consists of a set of <em>kernels</em>. |
| <em>Programs</em> may also contain auxiliary functions called by the |
| <em>kernel</em> functions and constant data.</p> |
| </dd> |
| <dt class="hdlist1">Program Object </dt> |
| <dd> |
| <p>A <em>program object</em> encapsulates the following information:</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A reference to an associated <em>context</em>.</p> |
| </li> |
| <li> |
| <p>A <em>program</em> source or binary.</p> |
| </li> |
| <li> |
| <p>The latest successfully built program executable, the list of <em>devices</em> |
| for which the program executable is built, the build options used and a |
| build log.</p> |
| </li> |
| <li> |
| <p>The number of <em>kernel objects</em> currently attached.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1">Queued </dt> |
| <dd> |
| <p>The first state in the six state model for the execution of a command. |
| The transition into this state occurs when the command is enqueued into |
| a command-queue.</p> |
| </dd> |
| <dt class="hdlist1">Ready </dt> |
| <dd> |
| <p>The third state in the six state model for the execution of a command. |
| The transition into this state occurs when pre-requisites constraining |
| execution of a command have been met; i.e. the command has been |
| launched. |
| When a kernel-enqueue command is launched, work-groups associated with |
| the command are placed in a devices work-pool from which they are |
| scheduled for execution.</p> |
| </dd> |
| <dt class="hdlist1">Re-converged Control Flow </dt> |
| <dd> |
| <p>see <em>Control flow</em>.</p> |
| </dd> |
| <dt class="hdlist1">Reference Count </dt> |
| <dd> |
| <p>The life span of an OpenCL object is determined by its <em>reference |
| count</em>, an internal count of the number of references to the object. |
| When you create an object in OpenCL, its <em>reference count</em> is set to |
| one. |
| Subsequent calls to the appropriate <em>retain</em> API (such as |
| <a href="#clRetainContext"><strong>clRetainContext</strong></a>, <a href="#clRetainCommandQueue"><strong>clRetainCommandQueue</strong></a>) increment the <em>reference |
| count</em>. |
| Calls to the appropriate <em>release</em> API (such as <a href="#clReleaseContext"><strong>clReleaseContext</strong></a>, |
| <a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a>) decrement the <em>reference count</em>. |
| Implementations may also modify the <em>reference count</em>, e.g. to track |
| attached objects or to ensure correct operation of in-progress or |
| scheduled activities. |
| The object becomes inaccessible to host code when the number of |
| <em>release</em> operations performed matches the number of <em>retain</em> operations |
| plus the allocation of the object. |
| At this point the reference count may be zero but this is not |
| guaranteed.</p> |
| </dd> |
| <dt class="hdlist1">Relaxed Consistency </dt> |
| <dd> |
| <p>A memory consistency model in which the contents of memory visible to |
| different <em>work-items</em> or <em>commands</em> may be different except at a |
| <em>barrier</em> or other explicit synchronization points.</p> |
| </dd> |
| <dt class="hdlist1">Relaxed Semantics </dt> |
| <dd> |
| <p>A memory order semantics for atomic operations that implies no order |
| constraints. |
| The operation is <em>atomic</em> but it has no impact on the order of memory |
| operations.</p> |
| </dd> |
| <dt class="hdlist1">Release Semantics </dt> |
| <dd> |
| <p>One of the memory order semantics defined for synchronization |
| operations. |
| Release semantics apply to atomic operations that store to memory. |
| Given two units of execution, <strong>A</strong> and <strong>B</strong>, acting on a shared atomic |
| object <strong>M</strong>, if <strong>A</strong> uses an atomic store of <strong>M</strong> with release semantics to |
| synchronize-with an atomic load to <strong>M</strong> by <strong>B</strong> that used acquire |
| semantics, then <strong>A</strong>'s atomic store will occur <em>after</em> any prior |
| operations by <strong>A</strong>. |
| Note that the memory orders <em>acquire</em>, <em>sequentially consistent</em>, and |
| <em>acquire_release</em> all include <em>acquire semantics</em> and effectively pair |
| with a store using release semantics.</p> |
| </dd> |
| <dt class="hdlist1">Remainder work-groups </dt> |
| <dd> |
| <p>When the work-groups associated with a kernel-instance are defined, the |
| sizes of a work-group in each dimension may not evenly divide the size |
| of the NDRange in the corresponding dimensions. |
| The result is a collection of work-groups on the boundaries of the |
| NDRange that are smaller than the base work-group size. |
| These are known as <em>remainder work-groups</em>.</p> |
| </dd> |
| <dt class="hdlist1">Running </dt> |
| <dd> |
| <p>The fourth state in the six state model for the execution of a command. |
| The transition into this state occurs when the execution of the command |
| starts. |
| When a Kernel-enqueue command starts, one or more work-groups associated |
| with the command start to execute.</p> |
| </dd> |
| <dt class="hdlist1">Root device </dt> |
| <dd> |
| <p>A <em>root device</em> is an OpenCL <em>device</em> that has not been partitioned. |
| Also see <em>Device</em>, <em>Parent device</em> and <em>Root device</em>.</p> |
| </dd> |
| <dt class="hdlist1">Resource </dt> |
| <dd> |
| <p>A class of <em>objects</em> defined by OpenCL. |
| An instance of a <em>resource</em> is an <em>object</em>. |
| The most common <em>resources</em> are the <em>context</em>, <em>command-queue</em>, <em>program |
| objects</em>, <em>kernel objects</em>, and <em>memory objects</em>. |
| Computational resources are hardware elements that participate in the |
| action of advancing a program counter. |
| Examples include the <em>host</em>, <em>devices</em>, <em>compute units</em> and <em>processing |
| elements</em>.</p> |
| </dd> |
| <dt class="hdlist1">Retain, Release </dt> |
| <dd> |
| <p>The action of incrementing (retain) and decrementing (release) the |
| reference count using an OpenCL <em>object</em>. |
| This is a book keeping functionality to make sure the system doesn’t |
| remove an <em>object</em> before all instances that use this <em>object</em> have |
| finished. |
| Refer to <em>Reference Count</em>.</p> |
| </dd> |
| <dt class="hdlist1">Sampler </dt> |
| <dd> |
| <p>An <em>object</em> that describes how to sample an image when the image is read |
| in the <em>kernel</em>. |
| The image read functions take a <em>sampler</em> as an argument. |
| The <em>sampler</em> specifies the image addressing-mode i.e. how out-of-range |
| image coordinates are handled, the filter mode, and whether the input |
| image coordinate is a normalized or unnormalized value.</p> |
| </dd> |
| <dt class="hdlist1">Scope inclusion </dt> |
| <dd> |
| <p>Two actions <strong>A</strong> and <strong>B</strong> are defined to have an inclusive scope if they |
| have the same scope <strong>P</strong> such that: (1) if <strong>P</strong> is |
| <strong>memory_scope_sub_group</strong>, and <strong>A</strong> and <strong>B</strong> are executed by work-items |
| within the same sub-group, or (2) if <strong>P</strong> is <strong>memory_scope_work_group</strong>, |
| and <strong>A</strong> and <strong>B</strong> are executed by work-items within the same work-group, |
| or (3) if <strong>P</strong> is <strong>memory_scope_device</strong>, and <strong>A</strong> and <strong>B</strong> are executed by |
| work-items on the same device, or (4) if <strong>P</strong> is |
| <strong>memory_scope_all_svm_devices</strong>, if <strong>A</strong> and <strong>B</strong> are executed by host |
| threads or by work-items on one or more devices that can share SVM |
| memory with each other and the host process.</p> |
| </dd> |
| <dt class="hdlist1">Sequenced before </dt> |
| <dd> |
| <p>A relation between evaluations executed by a single unit of execution. |
| Sequenced-before is an asymmetric, transitive, pair-wise relation that |
| induces a partial order between evaluations. |
| Given any two evaluations A and B, if A is sequenced-before B, then the |
| execution of A shall precede the execution of B.</p> |
| </dd> |
| <dt class="hdlist1">Sequential consistency </dt> |
| <dd> |
| <p>Sequential consistency interleaves the steps executed by each unit of |
| execution. |
| Each access to a memory location sees the last assignment to that |
| location in that interleaving.</p> |
| </dd> |
| <dt class="hdlist1">Sequentially consistent semantics </dt> |
| <dd> |
| <p>One of the memory order semantics defined for synchronization |
| operations. |
| When using sequentially-consistent synchronization operations, the loads |
| and stores within one unit of execution appear to execute in program |
| order (i.e., the sequenced-before order), and loads and stores from |
| different units of execution appear to be simply interleaved.</p> |
| </dd> |
| <dt class="hdlist1">Shared Virtual Memory (SVM) </dt> |
| <dd> |
| <p>An address space exposed to both the host and the devices within a |
| context. |
| SVM causes addresses to be meaningful between the host and all of the |
| devices within a context and therefore supports the use of pointer based |
| data structures in OpenCL kernels. |
| It logically extends a portion of the global memory into the host |
| address space therefore giving work-items access to the host address |
| space. |
| There are three types of SVM in OpenCL:</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><em>Coarse-Grained buffer SVM</em> </dt> |
| <dd> |
| <p>Sharing occurs at the granularity of regions of OpenCL buffer memory |
| objects.</p> |
| </dd> |
| <dt class="hdlist1"><em>Fine-Grained buffer SVM</em> </dt> |
| <dd> |
| <p>Sharing occurs at the granularity of individual loads/stores into bytes |
| within OpenCL buffer memory objects.</p> |
| </dd> |
| <dt class="hdlist1"><em>Fine-Grained system SVM</em> </dt> |
| <dd> |
| <p>Sharing occurs at the granularity of individual loads/stores into bytes |
| occurring anywhere within the host memory.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1">SIMD </dt> |
| <dd> |
| <p>Single Instruction Multiple Data. |
| A programming model where a <em>kernel</em> is executed concurrently on |
| multiple <em>processing elements</em> each with its own data and a shared |
| program counter. |
| All <em>processing elements</em> execute a strictly identical set of |
| instructions.</p> |
| </dd> |
| <dt class="hdlist1">Specialization constants </dt> |
| <dd> |
| <p>Specialization constants are special constant objects that do not |
| have known constant values in an intermediate language (e.g. SPIR-V). |
| Applications may provide updated values for the specialization constants |
| before a program is built. |
| Specialization constants that do not receive a value from an application |
| shall use the default specialization constant value.</p> |
| </dd> |
| <dt class="hdlist1">SPMD </dt> |
| <dd> |
| <p>Single Program Multiple Data. |
| A programming model where a <em>kernel</em> is executed concurrently on |
| multiple <em>processing elements</em> each with its own data and its own |
| program counter. |
| Hence, while all computational resources run the same <em>kernel</em> they |
| maintain their own instruction counter and due to branches in a |
| <em>kernel</em>, the actual sequence of instructions can be quite different |
| across the set of <em>processing elements</em>.</p> |
| </dd> |
| <dt class="hdlist1">Sub-device </dt> |
| <dd> |
| <p>An OpenCL <em>device</em> can be partitioned into multiple <em>sub-devices</em>. |
| The new <em>sub-devices</em> alias specific collections of compute units within |
| the parent <em>device</em>, according to a partition scheme. |
| The <em>sub-devices</em> may be used in any situation that their parent |
| <em>device</em> may be used. |
| Partitioning a <em>device</em> does not destroy the parent <em>device</em>, which may |
| continue to be used along side and intermingled with its child |
| <em>sub-devices</em>. |
| Also see <em>Device</em>, <em>Parent device</em> and <em>Root device</em>.</p> |
| </dd> |
| <dt class="hdlist1">Sub-group </dt> |
| <dd> |
| <p>Sub-groups are an implementation-dependent grouping of work-items within |
| a work-group. |
| The size and number of sub-groups is implementation-defined.</p> |
| </dd> |
| <dt class="hdlist1">Sub-group Barrier </dt> |
| <dd> |
| <p>See <em>Barrier</em>.</p> |
| </dd> |
| <dt class="hdlist1">Submitted </dt> |
| <dd> |
| <p>The second state in the six state model for the execution of a command. |
| The transition into this state occurs when the command is flushed from |
| the command-queue and submitted for execution on the device. |
| Once submitted, a programmer can assume a command will execute once its |
| prerequisites have been met.</p> |
| </dd> |
| <dt class="hdlist1">SVM Buffer </dt> |
| <dd> |
| <p>A memory allocation enabled to work with <em>Shared Virtual Memory (SVM)</em>. |
| Depending on how the SVM buffer is created, it can be a coarse-grained |
| or fine-grained SVM buffer. |
| Optionally it may be wrapped by a <em>Buffer Object</em>. |
| See <em>Shared Virtual Memory (SVM)</em>.</p> |
| </dd> |
| <dt class="hdlist1">Synchronization </dt> |
| <dd> |
| <p>Synchronization refers to mechanisms that constrain the order of |
| execution and the visibility of memory operations between two or more |
| units of execution.</p> |
| </dd> |
| <dt class="hdlist1">Synchronization operations </dt> |
| <dd> |
| <p>Operations that define memory order constraints in a program. |
| They play a special role in controlling how memory operations in one |
| unit of execution (such as work-items or, when using SVM a host thread) |
| are made visible to another. |
| Synchronization operations in OpenCL include <em>atomic operations</em> and |
| <em>fences</em>.</p> |
| </dd> |
| <dt class="hdlist1">Synchronization point </dt> |
| <dd> |
| <p>A synchronization point between a pair of commands (A and B) assures |
| that results of command A happens-before command B is launched (i.e. |
| enters the ready state) .</p> |
| </dd> |
| <dt class="hdlist1">Synchronizes with </dt> |
| <dd> |
| <p>A relation between operations in two different units of execution that |
| defines a memory order constraint in global memory |
| (<em>global-synchronizes-with</em>) or local memory |
| (<em>local-synchronizes-with</em>).</p> |
| </dd> |
| <dt class="hdlist1">Task Parallel Programming Model </dt> |
| <dd> |
| <p>A programming model in which computations are expressed in terms of |
| multiple concurrent tasks executing in one or more <em>command-queues</em>. |
| The concurrent tasks can be running different <em>kernels</em>.</p> |
| </dd> |
| <dt class="hdlist1">Thread-safe </dt> |
| <dd> |
| <p>An OpenCL API call is considered to be <em>thread-safe</em> if the internal |
| state as managed by OpenCL remains consistent when called simultaneously |
| by multiple <em>host</em> threads. |
| OpenCL API calls that are <em>thread-safe</em> allow an application to call |
| these functions in multiple <em>host</em> threads without having to implement |
| mutual exclusion across these <em>host</em> threads i.e. they are also |
| re-entrant-safe.</p> |
| </dd> |
| <dt class="hdlist1">Undefined </dt> |
| <dd> |
| <p>The behavior of an OpenCL API call, built-in function used inside a |
| <em>kernel</em> or execution of a <em>kernel</em> that is explicitly not defined by |
| OpenCL. |
| A conforming implementation is not required to specify what occurs when |
| an undefined construct is encountered in OpenCL.</p> |
| </dd> |
| <dt class="hdlist1">Unit of execution </dt> |
| <dd> |
| <p>A generic term for a process, OS managed thread running on the host (a |
| host-thread), kernel-instance, host program, work-item or any other |
| executable agent that advances the work associated with a program.</p> |
| </dd> |
| <dt class="hdlist1">Work-group </dt> |
| <dd> |
| <p>A collection of related <em>work-items</em> that execute on a single <em>compute |
| unit</em>. |
| The <em>work-items</em> in the group execute the same <em>kernel-instance</em> and |
| share <em>local</em> <em>memory</em> and <em>work-group functions</em>.</p> |
| </dd> |
| <dt class="hdlist1">Work-group Barrier </dt> |
| <dd> |
| <p>See <em>Barrier</em>.</p> |
| </dd> |
| <dt class="hdlist1">Work-group Function </dt> |
| <dd> |
| <p>A function that carries out collective operations across all the |
| work-items in a work-group. |
| Available collective operations are a barrier, reduction, broadcast, |
| prefix sum, and evaluation of a predicate. |
| A work-group function must occur within a <em>converged control flow</em>; i.e. |
| all work-items in the work-group must encounter precisely the same |
| work-group function.</p> |
| </dd> |
| <dt class="hdlist1">Work-group Synchronization </dt> |
| <dd> |
| <p>Constraints on the order of execution for work-items in a single |
| work-group.</p> |
| </dd> |
| <dt class="hdlist1">Work-pool </dt> |
| <dd> |
| <p>A logical pool associated with a device that holds commands and |
| work-groups from kernel-instances that are ready to execute. |
| OpenCL does not constrain the order that commands and work-groups are |
| scheduled for execution from the work-pool; i.e. a programmer must |
| assume that they could be interleaved. |
| There is one work-pool per device used by all command-queues associated |
| with that device. |
| The work-pool may be implemented in any manner as long as it assures |
| that work-groups placed in the pool will eventually execute.</p> |
| </dd> |
| <dt class="hdlist1">Work-item </dt> |
| <dd> |
| <p>One of a collection of parallel executions of a <em>kernel</em> invoked on a |
| <em>device</em> by a <em>command</em>. |
| A <em>work-item</em> is executed by one or more <em>processing elements</em> as part |
| of a <em>work-group</em> executing on a <em>compute unit</em>. |
| A <em>work-item</em> is distinguished from other work-items by its <em>global ID</em> |
| or the combination of its <em>work-group</em> ID and its <em>local ID</em> within a |
| <em>work-group</em>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_the_opencl_architecture"><a class="anchor" href="#_the_opencl_architecture"></a>3. The OpenCL Architecture</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><strong>OpenCL</strong> is an open industry standard for programming a heterogeneous |
| collection of CPUs, GPUs and other discrete computing devices organized into |
| a single platform. |
| It is more than a language. |
| OpenCL is a framework for parallel programming and includes a language, API, |
| libraries and a runtime system to support software development. |
| Using OpenCL, for example, a programmer can write general purpose programs |
| that execute on GPUs without the need to map their algorithms onto a 3D |
| graphics API such as OpenGL or DirectX.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The target of OpenCL is expert programmers wanting to write portable yet |
| efficient code. |
| This includes library writers, middleware vendors, and performance oriented |
| application programmers. |
| Therefore OpenCL provides a low-level hardware abstraction plus a framework |
| to support programming and many details of the underlying hardware are |
| exposed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To describe the core ideas behind OpenCL, we will use a hierarchy of models:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Platform Model</p> |
| </li> |
| <li> |
| <p>Memory Model</p> |
| </li> |
| <li> |
| <p>Execution Model</p> |
| </li> |
| <li> |
| <p>Programming Model</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="_platform_model"><a class="anchor" href="#_platform_model"></a>3.1. Platform Model</h3> |
| <div class="paragraph"> |
| <p>The <a href="#platform-model-image">Platform model</a> for OpenCL is defined below. |
| The model consists of a <strong>host</strong> connected to one or more <strong>OpenCL devices</strong>. |
| An OpenCL device is divided into one or more <strong>compute units</strong> (CUs) which are |
| further divided into one or more <strong>processing elements</strong> (PEs). |
| Computations on a device occur within the processing elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An OpenCL application is implemented as both host code and device kernel |
| code. |
| The host code portion of an OpenCL application runs on a host processor |
| according to the models native to the host platform. |
| The OpenCL application host code submits the kernel code as commands from |
| the host to OpenCL devices. |
| An OpenCL device executes the commands computation on the processing |
| elements within the device.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An OpenCL device has considerable latitude on how computations are mapped |
| onto the devices processing elements. |
| When processing elements within a compute unit execute the same sequence of |
| statements across the processing elements, the control flow is said to be |
| <em>converged</em>. |
| Hardware optimized for executing a single stream of instructions over |
| multiple processing elements is well suited to converged control flows. |
| When the control flow varies from one processing element to another, it is |
| said to be <em>diverged</em>. |
| While a kernel always begins execution with a converged control flow, due to |
| branching statements within a kernel, converged and diverged control flows |
| may occur within a single kernel. |
| This provides a great deal of flexibility in the algorithms that can be |
| implemented with OpenCL.</p> |
| </div> |
| <div id="platform-model-image" class="imageblock text-center"> |
| <div class="content"> |
| <img src="data:image/png;base64,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k6NHjzY37LRhmh+M59Xvg3nHDmBHuLp+rtoAz/j7778n11tvveTIkSOr7TAzZsywcuT+5ptvTrZo0SKpnUDy7LPPTirxJffZZ5+kknNSiTS5xx57JD/88MPkpptummzVqlXykUcesbDbb7998rDDDrNw22yzTVI7EDNbb711cty4cVbOhx56aLJXr17JNm3aJJX8kzfccEPyoYceSq699toW7tRTT7V3ox2EvUswatSo5Lrrrpv866+/7DcYPny4xaEdT1I7KAu71lprJS+99FIL37lz5+SwYcMszZ9++im55557Jq+88kp7HvDkk09amjzniy++aGEmTpxo/oiX+Hr37m1+tZOozkuIVYu65Mk1Q9xbArQcTOpBwsHUFZCqkBgZ+iMtckQe+60jiXkelaxMCuNeG7rZc8Xery454AezJoBnpsx4f0ir3LPHDxIsO1GyzPG5556T//znP3Yq1VtvvSXamcptt91m6h7Ki1EAH54h/eOXkcCjjz5qZcgOl+j7+/TpYyOFs846y8qaE60od96JEr60bdvWJspRFfHuOP3qhRdesLiJgzN6kbj9vfDOCR8E0jrmnnvukaefftrUOOSVOBjl8d3EnXfeaWneddddoh2PjTKoO3zEdcUVV9hzosJ67733bHRCXSJNztnt3r27hecoRkYpPDsmRMNFSPQB0HB8KFsXoLGxRzoN98QTT7RGSOMkT5AKCHZE2EEUhOPeGyykx29/Hg/b0EFZYNBZo07hHgJEd/3HH38YsTHReeSRR5oenDJm8zJIFXLnIyfCoCrbZZddbIsD3gFlzqlUkDZ+rrvuOtOtu9rG6wx+GzdubCqW9u3b2wdT+IGML7vsMksfwub9OLkH35eDPIDp06eb/S233CI33XSThYe4DzjgANGRgHUsXLt27WqqGdLX0Yuly9LbSy65xDoJOj5UQnQE3bp1M3Xg0KFD7dnpdDy9EA0XaxzR03BouBCoS1U0VMiBxsI97hhvfNy7tEzDBIR1gvX4/DdXDHb8duPuQePw33xCD8kgkQIaoadN3pigIz0H9r5sEEOakIvH57pg0gbBfDYk8EysRoLIOVoQQMJ8sYqEjXRPOUGEDv+SlXJF8gdB6Zp3gDtliI4ecgesfiItl8zXXXdds0fXzzsgHHFyT9jTTjvNiP6qq66Sgw8+2OIkL1wB74dVNg46Bjob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" alt="platform model"> |
| </div> |
| <div class="title">Figure 1. Platform Model …​ one host plus one or more compute devices each with one or more compute units composed of one or more processing elements.</div> |
| </div> |
| <div class="paragraph"> |
| <p>Programmers may provide programs in the form of OpenCL C source strings, |
| the SPIR-V intermediate language, or as implementation-defined binary objects. |
| An OpenCL platform provides a compiler to translate programs of these |
| forms into executable program objects. |
| The device code compiler may be <em>online</em> or <em>offline</em>. |
| An <em>online</em> <em>compiler</em> is available during host program execution using |
| standard APIs. |
| An <em>offline compiler</em> is invoked outside of host program control, using |
| platform-specific methods. |
| The OpenCL runtime allows developers to get a previously compiled device |
| program executable and be able to load and execute a previously compiled |
| device program executable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL defines two kinds of platform profiles: a <em>full profile</em> and a |
| reduced-functionality <em>embedded profile</em>. |
| A full profile platform must provide an online compiler for all its devices. |
| An embedded platform may provide an online compiler, but is not required to |
| do so.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A device may expose special purpose functionality as a <em>built-in kernel</em>. |
| The platform provides APIs for enumerating and invoking the built-in |
| kernels offered by a device, but otherwise does not define their |
| construction or semantics. |
| A <em>custom device</em> supports only built-in kernels, and cannot be programmed |
| via a kernel language.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Built-in kernels and custom devices are <a href="#unified-spec">missing before</a> |
| version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>All device types support the OpenCL execution model, the OpenCL memory |
| model, and the APIs used in OpenCL to manage devices.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The platform model is an abstraction describing how OpenCL views the |
| hardware. |
| The relationship between the elements of the platform model and the hardware |
| in a system may be a fixed property of a device or it may be a dynamic |
| feature of a program dependent on how a compiler optimizes code to best |
| utilize physical hardware.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_execution_model"><a class="anchor" href="#_execution_model"></a>3.2. Execution Model</h3> |
| <div class="paragraph"> |
| <p>The OpenCL execution model is defined in terms of two distinct units of |
| execution: <strong>kernels</strong> that execute on one or more OpenCL devices and a <strong>host |
| program</strong> that executes on the host. |
| With regard to OpenCL, the kernels are where the "work" associated with a |
| computation occurs. |
| This work occurs through <strong>work-items</strong> that execute in groups |
| (<strong>work-groups</strong>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>A kernel executes within a well-defined context managed by the host. |
| The context defines the environment within which kernels execute. |
| It includes the following resources:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Devices</strong>: One or more devices exposed by the OpenCL platform.</p> |
| </li> |
| <li> |
| <p><strong>Kernel Objects</strong>: The OpenCL functions with their associated argument |
| values that run on OpenCL devices.</p> |
| </li> |
| <li> |
| <p><strong>Program Objects</strong>: The program source and executable that implement the |
| kernels.</p> |
| </li> |
| <li> |
| <p><strong>Memory Objects</strong>: Variables visible to the host and the OpenCL devices. |
| Instances of kernels operate on these objects as they execute.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The host program uses the OpenCL API to create and manage the context. |
| Functions from the OpenCL API enable the host to interact with a device |
| through a <em>command-queue</em>. |
| Each command-queue is associated with a single device. |
| The commands placed into the command-queue fall into one of three types:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Kernel-enqueue commands</strong>: Enqueue a kernel for execution on a device.</p> |
| </li> |
| <li> |
| <p><strong>Memory commands</strong>: Transfer data between the host and device memory, |
| between memory objects, or map and unmap memory objects from the host |
| address space.</p> |
| </li> |
| <li> |
| <p><strong>Synchronization commands</strong>: Explicit synchronization points that define |
| order constraints between commands.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In addition to commands submitted from the host command-queue, a kernel |
| running on a device can enqueue commands to a device-side command queue. |
| This results in <em>child kernels</em> enqueued by a kernel executing on a device |
| (the <em>parent kernel</em>). |
| Regardless of whether the command-queue resides on the host or a device, |
| each command passes through six states.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><strong>Queued</strong>: The command is enqueued to a command-queue. |
| A command may reside in the queue until it is flushed either explicitly |
| (a call to <a href="#clFlush"><strong>clFlush</strong></a>) or implicitly by some other command.</p> |
| </li> |
| <li> |
| <p><strong>Submitted</strong>: The command is flushed from the command-queue and submitted |
| for execution on the device. |
| Once flushed from the command-queue, a command will execute after any |
| prerequisites for execution are met.</p> |
| </li> |
| <li> |
| <p><strong>Ready</strong>: All prerequisites constraining execution of a command have been |
| met. |
| The command, or for a kernel-enqueue command the collection of work |
| groups associated with a command, is placed in a device work-pool from |
| which it is scheduled for execution.</p> |
| </li> |
| <li> |
| <p><strong>Running</strong>: Execution of the command starts. |
| For the case of a kernel-enqueue command, one or more work-groups |
| associated with the command start to execute.</p> |
| </li> |
| <li> |
| <p><strong>Ended</strong>: Execution of a command ends. |
| When a Kernel-enqueue command ends, all of the work-groups associated |
| with that command have finished their execution. |
| <em>Immediate side effects</em>, i.e. those associated with the kernel but not |
| necessarily with its child kernels, are visible to other units of |
| execution. |
| These side effects include updates to values in global memory.</p> |
| </li> |
| <li> |
| <p><strong>Complete</strong>: The command and its child commands have finished execution |
| and the status of the event object, if any, associated with the command |
| is set to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="#profiled-states-image">execution states and the transitions between |
| them</a> are summarized below. |
| These states and the concept of a device work-pool are conceptual elements |
| of the execution model. |
| An implementation of OpenCL has considerable freedom in how these are |
| exposed to a program. |
| Five of the transitions, however, are directly observable through a |
| profiling interface. |
| These <a href="#profiled-states-image">profiled states</a> are shown below.</p> |
| </div> |
| <div id="profiled-states-image" class="imageblock text-center"> |
| <div class="content"> |
| <img src="data:image/png;base64,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" alt="profiled states"> |
| </div> |
| <div class="title">Figure 2. The states and transitions between states defined in the OpenCL execution model. A subset of these transitions is exposed through the <a href="#profiling-operations">profiling interface</a>.</div> |
| </div> |
| <div class="paragraph"> |
| <p>Commands communicate their status through <em>Event objects</em>. |
| Successful completion is indicated by setting the event status associated |
| with a command to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>. |
| Unsuccessful completion results in abnormal termination of the command which |
| is indicated by setting the event status to a negative value. |
| In this case, the command-queue associated with the abnormally terminated |
| command and all other command-queues in the same context may no longer be |
| available and their behavior is implementation defined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A command submitted to a device will not launch until prerequisites that |
| constrain the order of commands have been resolved. |
| These prerequisites have three sources:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>They may arise from commands submitted to a command-queue that constrain |
| the order in which commands are launched. |
| For example, commands that follow a command queue barrier will not |
| launch until all commands prior to the barrier are complete.</p> |
| </li> |
| <li> |
| <p>The second source of prerequisites is dependencies between commands |
| expressed through events. |
| A command may include an optional list of events. |
| The command will wait and not launch until all the events in the list |
| are in the state CL COMPLETE. |
| By this mechanism, event objects define order constraints between |
| commands and coordinate execution between the host and one or more |
| devices.</p> |
| </li> |
| <li> |
| <p>The third source of prerequisites can be the presence of non-trivial C |
| initializers or C++ constructors for program scope global variables. |
| In this case, OpenCL C/C++ compiler shall generate program |
| initialization kernels that perform C initialization or C++ |
| construction. |
| These kernels must be executed by OpenCL runtime on a device before any |
| kernel from the same program can be executed on the same device. |
| The ND-range for any program initialization kernel is (1,1,1). |
| When multiple programs are linked together, the order of execution of |
| program initialization kernels that belong to different programs is |
| undefined.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Program clean up may result in the execution of one or more program clean up |
| kernels by the OpenCL runtime. |
| This is due to the presence of non-trivial C++ destructors for |
| program scope variables. |
| The ND-range for executing any program clean up kernel is (1,1,1). |
| The order of execution of clean up kernels from different programs (that are |
| linked together) is undefined.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Program initialization and clean-up kernels are <a href="#unified-spec">missing before</a> version 2.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Note that C initializers, C++ constructors, or C++ destructors for program |
| scope variables cannot use pointers to coarse grain and fine grain SVM |
| allocations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A command may be submitted to a device and yet have no visible side effects |
| outside of waiting on and satisfying event dependences. |
| Examples include markers, kernels executed over ranges of no work-items or |
| copy operations with zero sizes. |
| Such commands may pass directly from the <em>ready</em> state to the <em>ended</em> state.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Command execution can be blocking or non-blocking. |
| Consider a sequence of OpenCL commands. |
| For blocking commands, the OpenCL API functions that enqueue commands don’t |
| return until the command has completed. |
| Alternatively, OpenCL functions that enqueue non-blocking commands return |
| immediately and require that a programmer defines dependencies between |
| enqueued commands to ensure that enqueued commands are not launched before |
| needed resources are available. |
| In both cases, the actual execution of the command may occur asynchronously |
| with execution of the host program.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Commands within a single command-queue execute relative to each other in one |
| of two modes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>In-order Execution</strong>: Commands and any side effects associated with |
| commands appear to the OpenCL application as if they execute in the same |
| order they are enqueued to a command-queue.</p> |
| </li> |
| <li> |
| <p><strong>Out-of-order Execution</strong>: Commands execute in any order constrained only |
| by explicit synchronization points (e.g. through command queue barriers) |
| or explicit dependencies on events.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Multiple command-queues can be present within a single context. |
| Multiple command-queues execute commands independently. |
| Event objects visible to the host program can be used to define |
| synchronization points between commands in multiple command queues. |
| If such synchronization points are established between commands in multiple |
| command-queues, an implementation must assure that the command-queues |
| progress concurrently and correctly account for the dependencies established |
| by the synchronization points. |
| For a detailed explanation of synchronization points, see the execution model |
| <a href="#execution-model-sync">Synchronization</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The core of the OpenCL execution model is defined by how the kernels |
| execute. |
| When a kernel-enqueue command submits a kernel for execution, an index space |
| is defined. |
| The kernel, the argument values associated with the arguments to the kernel, |
| and the parameters that define the index space define a <em>kernel-instance</em>. |
| When a kernel-instance executes on a device, the kernel function executes |
| for each point in the defined index space. |
| Each of these executing kernel functions is called a <em>work-item</em>. |
| The work-items associated with a given kernel-instance are managed by the |
| device in groups called <em>work-groups</em>. |
| These work-groups define a coarse grained decomposition of the Index space. |
| Work-groups are further divided into <em>sub-groups</em>, which provide an |
| additional level of control over execution.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Sub-groups are <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Work-items have a global ID based on their coordinates within the Index |
| space. |
| They can also be defined in terms of their work-group and the local ID |
| within a work-group. |
| The details of this mapping are described in the following section.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_mapping_work_items_onto_an_ndrange"><a class="anchor" href="#_mapping_work_items_onto_an_ndrange"></a>3.2.1. Mapping work-items onto an NDRange</h4> |
| <div class="paragraph"> |
| <p>The index space supported by OpenCL is called an NDRange. |
| An NDRange is an N-dimensional index space, where N is one, two or three. |
| The NDRange is decomposed into work-groups forming blocks that cover the |
| Index space. |
| An NDRange is defined by three integer arrays of length N:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The extent of the index space (or global size) in each dimension.</p> |
| </li> |
| <li> |
| <p>An offset index F indicating the initial value of the indices in each |
| dimension (zero by default).</p> |
| </li> |
| <li> |
| <p>The size of a work-group (local size) in each dimension.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Each work-items global ID is an N-dimensional tuple. |
| The global ID components are values in the range from F, to F plus the |
| number of elements in that dimension minus one.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Unless a kernel comes from a source that disallows it, e.g. OpenCL C 1.x or |
| using <code>-cl-uniform-work-group-size</code>, the size of work-groups in |
| an NDRange (the local size) need not be the same for all work-groups. |
| In this case, any single dimension for which the global size is not |
| divisible by the local size will be partitioned into two regions. |
| One region will have work-groups that have the same number of work-items as |
| was specified for that dimension by the programmer (the local size). |
| The other region will have work-groups with less than the number of work |
| items specified by the local size parameter in that dimension (the |
| <em>remainder work-groups</em>). |
| Work-group sizes could be non-uniform in multiple dimensions, potentially |
| producing work-groups of up to 4 different sizes in a 2D range and 8 |
| different sizes in a 3D range.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Non-uniform work-group sizes are <a href="#unified-spec">missing before</a> version |
| 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Each work-item is assigned to a work-group and given a local ID to represent |
| its position within the work-group. |
| A work-item’s local ID is an N-dimensional tuple with components in the |
| range from zero to the size of the work-group in that dimension minus one.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Work-groups are assigned IDs similarly. |
| The number of work-groups in each dimension is not directly defined but is |
| inferred from the local and global NDRanges provided when a kernel-instance |
| is enqueued. |
| A work-group’s ID is an N-dimensional tuple with components in the range 0 |
| to the ceiling of the global size in that dimension divided by the local |
| size in the same dimension. |
| As a result, the combination of a work-group ID and the local-ID within a |
| work-group uniquely defines a work-item. |
| Each work-item is identifiable in two ways; in terms of a global index, and |
| in terms of a work-group index plus a local index within a work-group.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, consider the <a href="#index-space-image">2-dimensional index space</a> |
| shown below. |
| We input the index space for the work-items (G<sub>x</sub>, G<sub>y</sub>), the size of each |
| work-group (S<sub>x</sub>, S<sub>y</sub>) and the global ID offset (F<sub>x</sub>, F<sub>y</sub>). |
| The global indices define an G<sub>x</sub>by G<sub>y</sub> index space where the total number |
| of work-items is the product of G<sub>x</sub> and G<sub>y</sub>. |
| The local indices define an S<sub>x</sub> by S<sub>y</sub> index space where the number of |
| work-items in a single work-group is the product of S<sub>x</sub> and S<sub>y</sub>. |
| Given the size of each work-group and the total number of work-items we can |
| compute the number of work-groups. |
| A 2-dimensional index space is used to uniquely identify a work-group. |
| Each work-item is identified by its global ID (<em>g</em><sub>x</sub>, <em>g</em><sub>y</sub>) or by the |
| combination of the work-group ID (<em>w</em><sub>x</sub>, <em>w</em><sub>y</sub>), the size of each |
| work-group (S<sub>x</sub>,S<sub>y</sub>) and the local ID (s<sub>x</sub>, s<sub>y</sub>) inside the work-group |
| such that</p> |
| </div> |
| <div class="ulist none"> |
| <ul class="none"> |
| <li> |
| <p>(g<sub>x</sub>, g<sub>y</sub>) = (w<sub>x</sub> × S<sub>x</sub> + s<sub>x</sub> + F<sub>x</sub>, w<sub>y</sub> × S<sub>y</sub> + s<sub>y</sub> + F<sub>y</sub>)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The number of work-groups can be computed as:</p> |
| </div> |
| <div class="ulist none"> |
| <ul class="none"> |
| <li> |
| <p>(W<sub>x</sub>, W<sub>y</sub>) = (ceil(G<sub>x</sub> / S<sub>x</sub>), ceil(G<sub>y</sub> / S<sub>y</sub>))</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Given a global ID and the work-group size, the work-group ID for a work-item |
| is computed as:</p> |
| </div> |
| <div class="ulist none"> |
| <ul class="none"> |
| <li> |
| <p>(w<sub>x</sub>, w<sub>y</sub>) = ( (g<sub>x</sub> - s<sub>x</sub> - F<sub>x</sub>) / S<sub>x</sub>, (g<sub>y</sub> - s<sub>y</sub> - F<sub>y</sub>) / S<sub>y</sub> )</p> |
| </li> |
| </ul> |
| </div> |
| <div id="index-space-image" class="imageblock text-center"> |
| <div class="content"> |
| <img src="data:image/jpg;base64,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/wDwlWiHSbfVFv42sriN5IpVBIZVBLHpngA0AV/7N8T/APQw2v8A4Lx/8XR/Zvif/oYbX/wXj/4ukTx14ck0ufUU1EG3gkWOX904dGbhQUxu5zxxzWlo+t6dr1o11ptyJ4lcxt8pUqw7EEAg8jrQBnf2b4n/AOhhtf8AwXj/AOLo/s3xP/0MNr/4Lx/8XXQ0UAc9/Zvif/oYbX/wXj/4uj+zfE//AEMNr/4Lx/8AF10NRW9zFdRs8TEqrshypHKnB6+4oAw/7N8T/wDQw2v/AILx/wDF0f2b4n/6GG1/8F4/+LroaxNN8W6Jq+pPp9leiW4UMQNjKsgU4YoxGGweDgmgCH+zfE//AEMNr/4Lx/8AF1V1HR/FNxp1xCuvW7s6FQq2nlk/Rg+V+tdXRQB5poeleJdJ8X+H4fEeuRao5hvPJ2xYaMYTgvwX/IV6XUbQQvPHM8SNLGCEcqCyg9cHtnAqSgAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKAIrkFrSYKCWKMAB9K8ifw/rml21jBBp08umS6c1yY44yZLe58kK8e3/aPIHrmvYqKAPLr/T9S8Sa62tW1hqOn25extkeSHZO2ybe8pRgcBQcAsPWs7XdI1WCPUrEWmoXzvqMsovXs2laXdAnl4ClVyDuUP0Xb0ya9iooA8gk0S+XSrrV0tL+G+nuLjzJJWaN/IMQ4+Y4UEg496zL2xkv5b0aLp+o22mpcui2pt2leOZoI9h2bwY++CeFJyQM17dPBFdW8kE8aSwyKVdHGQwPUEVBp2l2OkWxt9PtIraEsXKxLgFj1J9TQBxXjqyv5U0Nktrq5mhUgqkLSo0nycMVIMbcHEnQc561i3VlfXPiNIW0fU4rqD7VLbXyQOVeZ3kESmQcKig7ueMlfSvWqKAPN/h1pOpQaZqcN0t1C0tvHE3n27Q/vwrB2GWJY5Iy44btTdIv9UtLnRom0nVo4dKs5Ir6E2ieUGSPAMTkZYsRng4I6816VUF7BJdWM8ENw1vJIhVZlGSme496GBT0PXbLxFYG+08yPalyiSsu0SY6lfUZ4+oNadZPh3QIPDWljTbSaWS0RyYUlOTGp5257jOT+Na1ABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFAH//2Q==" alt="index space"> |
| </div> |
| <div class="title">Figure 3. An example of an NDRange index space showing work-items, their global IDs and their mapping onto the pair of work-group and local IDs. In this case, we assume that in each dimension, the size of the work-group evenly divides the global NDRange size (i.e. all work-groups have the same size) and that the offset is equal to zero.</div> |
| </div> |
| <div class="paragraph"> |
| <p>Within a work-group work-items may be divided into sub-groups. |
| The mapping of work-items to sub-groups is implementation-defined and may be |
| queried at runtime. |
| While sub-groups may be used in multi-dimensional work-groups, each |
| sub-group is 1-dimensional and any given work-item may query which sub-group |
| it is a member of.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Sub-groups are <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Work-items are mapped into sub-groups through a combination of compile-time |
| decisions and the parameters of the dispatch. |
| The mapping to sub-groups is invariant for the duration of a kernels |
| execution, across dispatches of a given kernel with the same work-group |
| dimensions, between dispatches and query operations consistent with the |
| dispatch parameterization, and from one work-group to another within the |
| dispatch (excluding the trailing edge work-groups in the presence of |
| non-uniform work-group sizes). |
| In addition, all sub-groups within a work-group will be the same size, apart |
| from the sub-group with the maximum index which may be smaller if the size |
| of the work-group is not evenly divisible by the size of the sub-groups.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the degenerate case, a single sub-group must be supported for each |
| work-group. |
| In this situation all sub-group scope functions are equivalent to their |
| work-group level equivalents.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_execution_of_kernel_instances"><a class="anchor" href="#_execution_of_kernel_instances"></a>3.2.2. Execution of kernel-instances</h4> |
| <div class="paragraph"> |
| <p>The work carried out by an OpenCL program occurs through the execution of |
| kernel-instances on compute devices. |
| To understand the details of OpenCL’s execution model, we need to consider |
| how a kernel object moves from the kernel-enqueue command, into a |
| command-queue, executes on a device, and completes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A kernel object is defined as a function within the program object and a |
| collection of arguments connecting the kernel to a set of argument values. |
| The host program enqueues a kernel object to the command queue along with |
| the NDRange and the work-group decomposition. |
| These define a <em>kernel-instance</em>. |
| In addition, an optional set of events may be defined when the kernel is |
| enqueued. |
| The events associated with a particular kernel-instance are used to |
| constrain when the kernel-instance is launched with respect to other |
| commands in the queue or to commands in other queues within the same |
| context.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A kernel-instance is submitted to a device. |
| For an in-order command queue, the kernel instances appear to launch and |
| then execute in that same order; where we use the term appear to emphasize |
| that when there are no dependencies between commands and hence differences |
| in the order that commands execute cannot be observed in a program, an |
| implementation can reorder commands even in an in-order command queue. |
| For an out of order command-queue, kernel-instances wait to be launched |
| until:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Synchronization commands enqueued prior to the kernel-instance are |
| satisfied.</p> |
| </li> |
| <li> |
| <p>Each of the events in an optional event list defined when the |
| kernel-instance was enqueued are set to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Once these conditions are met, the kernel-instance is launched and the |
| work-groups associated with the kernel-instance are placed into a pool of |
| ready to execute work-groups. |
| This pool is called a <em>work-pool</em>. |
| The work-pool may be implemented in any manner as long as it assures that |
| work-groups placed in the pool will eventually execute. |
| The device schedules work-groups from the work-pool for execution on the |
| compute units of the device. |
| The kernel-enqueue command is complete when all work-groups associated with |
| the kernel-instance end their execution, updates to global memory associated |
| with a command are visible globally, and the device signals successful |
| completion by setting the event associated with the kernel-enqueue command |
| to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>While a command-queue is associated with only one device, a single device |
| may be associated with multiple command-queues all feeding into the single |
| work-pool. |
| A device may also be associated with command queues associated with |
| different contexts within the same platform, again all feeding into the |
| single work-pool. |
| The device will pull work-groups from the work-pool and execute them on one |
| or several compute units in any order; possibly interleaving execution of |
| work-groups from multiple commands. |
| A conforming implementation may choose to serialize the work-groups so a |
| correct algorithm cannot assume that work-groups will execute in parallel. |
| There is no safe and portable way to synchronize across the independent |
| execution of work-groups since once in the work-pool, they can execute in |
| any order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The work-items within a single sub-group execute concurrently but not |
| necessarily in parallel (i.e. they are not guaranteed to make independent |
| forward progress). |
| Therefore, only high-level synchronization constructs (e.g. sub-group |
| functions such as barriers) that apply to all the work-items in a sub-group |
| are well defined and included in OpenCL.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Sub-groups are <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Sub-groups execute concurrently within a given work-group and with |
| appropriate device support (see <a href="#platform-querying-devices">Querying |
| Devices</a>), may make independent forward progress with respect to each |
| other, with respect to host threads and with respect to any entities |
| external to the OpenCL system but running on an OpenCL device, even in the |
| absence of work-group barrier operations. |
| In this situation, sub-groups are able to internally synchronize using |
| barrier operations without synchronizing with each other and may perform |
| operations that rely on runtime dependencies on operations other sub-groups |
| perform.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The work-items within a single work-group execute concurrently but are only |
| guaranteed to make independent progress in the presence of sub-groups and |
| device support. |
| In the absence of this capability, only high-level synchronization |
| constructs (e.g. work-group functions such as barriers) that apply to all |
| the work-items in a work-group are well defined and included in OpenCL for |
| synchronization within the work-group.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the absence of synchronization functions (e.g. a barrier), work-items |
| within a sub-group may be serialized. |
| In the presence of sub -group functions, work-items within a sub -group may |
| be serialized before any given sub -group function, between dynamically |
| encountered pairs of sub-group functions and between a work-group function |
| and the end of the kernel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the absence of independent forward progress of constituent sub-groups, |
| work-items within a work-group may be serialized before, after or between |
| work-group synchronization functions.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="device-side-enqueue"><a class="anchor" href="#device-side-enqueue"></a>3.2.3. Device-side enqueue</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Device-side enqueue is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Algorithms may need to generate additional work as they execute. |
| In many cases, this additional work cannot be determined statically; so the |
| work associated with a kernel only emerges at runtime as the kernel-instance |
| executes. |
| This capability could be implemented in logic running within the host |
| program, but involvement of the host may add significant overhead and/or |
| complexity to the application control flow. |
| A more efficient approach would be to nest kernel-enqueue commands from |
| inside other kernels. |
| This <strong>nested parallelism</strong> can be realized by supporting the enqueuing of |
| kernels on a device without direct involvement by the host program; |
| so-called <strong>device-side enqueue</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Device-side kernel-enqueue commands are similar to host-side kernel-enqueue |
| commands. |
| The kernel executing on a device (the <strong>parent kernel</strong>) enqueues a |
| kernel-instance (the <strong>child kernel</strong>) to a device-side command queue. |
| This is an out-of-order command-queue and follows the same behavior as the |
| out-of-order command-queues exposed to the host program. |
| Commands enqueued to a device side command-queue generate and use events to |
| enforce order constraints just as for the command-queue on the host. |
| These events, however, are only visible to the parent kernel running on the |
| device. |
| When these prerequisite events take on the value <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>, the |
| work-groups associated with the child kernel are launched into the devices |
| work pool. |
| The device then schedules them for execution on the compute units of the |
| device. |
| Child and parent kernels execute asynchronously. |
| However, a parent will not indicate that it is complete by setting its event |
| to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> until all child kernels have ended execution and have |
| signaled completion by setting any associated events to the value |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>. |
| Should any child kernel complete with an event status set to a negative |
| value (i.e. abnormally terminate), the parent kernel will abnormally |
| terminate and propagate the childs negative event value as the value of the |
| parents event. |
| If there are multiple children that have an event status set to a negative |
| value, the selection of which childs negative event value is propagated is |
| implementation-defined.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="execution-model-sync"><a class="anchor" href="#execution-model-sync"></a>3.2.4. Synchronization</h4> |
| <div class="paragraph"> |
| <p>Synchronization refers to mechanisms that constrain the order of execution |
| between two or more units of execution. |
| Consider the following three domains of synchronization in OpenCL:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Work-group synchronization: Constraints on the order of execution for |
| work-items in a single work-group</p> |
| </li> |
| <li> |
| <p>Sub-group synchronization: Constraints on the order of execution for |
| work-items in a single sub-group. |
| Note: Sub-groups are <a href="#unified-spec">missing before</a> version 2.1</p> |
| </li> |
| <li> |
| <p>Command synchronization: Constraints on the order of commands launched |
| for execution</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Synchronization across all work-items within a single work-group is carried |
| out using a <em>work-group function</em>. |
| These functions carry out collective operations across all the work-items in |
| a work-group. |
| Available collective operations are: barrier, reduction, broadcast, prefix |
| sum, and evaluation of a predicate. |
| A work-group function must occur within a converged control flow; i.e. all |
| work-items in the work-group must encounter precisely the same work-group |
| function. |
| For example, if a work-group function occurs within a loop, the work-items |
| must encounter the same work-group function in the same loop iterations. |
| All the work-items of a work-group must execute the work-group function and |
| complete reads and writes to memory before any are allowed to continue |
| execution beyond the work-group function. |
| Work-group functions that apply between work-groups are not provided in |
| OpenCL since OpenCL does not define forward-progress or ordering relations |
| between work-groups, hence collective synchronization operations are not |
| well defined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Synchronization across all work-items within a single sub-group is carried |
| out using a <em>sub-group function</em>. |
| These functions carry out collective operations across all the work-items in |
| a sub-group. |
| Available collective operations are: barrier, reduction, broadcast, prefix |
| sum, and evaluation of a predicate. |
| A sub-group function must occur within a converged control flow; i.e. all |
| work-items in the sub-group must encounter precisely the same sub-group |
| function. |
| For example, if a work-group function occurs within a loop, the work-items |
| must encounter the same sub-group function in the same loop iterations. |
| All the work-items of a sub-group must execute the sub-group function and |
| complete reads and writes to memory before any are allowed to continue |
| execution beyond the sub-group function. |
| Synchronization between sub-groups must either be performed using work-group |
| functions, or through memory operations. |
| Using memory operations for sub-group synchronization should be used |
| carefully as forward progress of sub-groups relative to each other is only |
| supported optionally by OpenCL implementations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Command synchronization is defined in terms of distinct <strong>synchronization |
| points</strong>. |
| The synchronization points occur between commands in host command-queues and |
| between commands in device-side command-queues. |
| The synchronization points defined in OpenCL include:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Launching a command:</strong> A kernel-instance is launched onto a device after |
| all events that kernel is waiting-on have been set to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| <li> |
| <p><strong>Ending a command:</strong> Child kernels may be enqueued such that they wait |
| for the parent kernel to reach the <em>end</em> state before they can be |
| launched. |
| In this case, the ending of the parent command defines a synchronization |
| point.</p> |
| </li> |
| <li> |
| <p><strong>Completion of a command:</strong> A kernel-instance is complete after all of |
| the work-groups in the kernel and all of its child kernels have |
| completed. |
| This is signaled to the host, a parent kernel or other kernels within |
| command queues by setting the value of the event associated with a |
| kernel to <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| <li> |
| <p><strong>Blocking Commands:</strong> A blocking command defines a synchronization point |
| between the unit of execution that calls the blocking API function and |
| the enqueued command reaching the complete state.</p> |
| </li> |
| <li> |
| <p><strong>Command-queue barrier:</strong> The command-queue barrier ensures that all |
| previously enqueued commands have completed before subsequently enqueued |
| commands can be launched.</p> |
| </li> |
| <li> |
| <p><a href="#clFinish"><strong>clFinish</strong></a>: This function blocks until all previously enqueued commands |
| in the command queue have completed after which <a href="#clFinish"><strong>clFinish</strong></a> defines a |
| synchronization point and the <a href="#clFinish"><strong>clFinish</strong></a> function returns.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A synchronization point between a pair of commands (A and B) assures that |
| results of command A happens-before command B is launched. |
| This requires that any updates to memory from command A complete and are |
| made available to other commands before the synchronization point completes. |
| Likewise, this requires that command B waits until after the synchronization |
| point before loading values from global memory. |
| The concept of a synchronization point works in a similar fashion for |
| commands such as a barrier that apply to two sets of commands. |
| All the commands prior to the barrier must complete and make their results |
| available to following commands. |
| Furthermore, any commands following the barrier must wait for the commands |
| prior to the barrier before loading values and continuing their execution.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These <em>happens-before</em> relationships are a fundamental part of the OpenCL 2.x |
| memory model. |
| When applied at the level of commands, they are straightforward to define at |
| a language level in terms of ordering relationships between different |
| commands. |
| Ordering memory operations inside different commands, however, requires |
| rules more complex than can be captured by the high level concept of a |
| synchronization point. |
| These rules are described in detail in <a href="#memory-ordering-rules">Memory |
| Ordering Rules</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_categories_of_kernels"><a class="anchor" href="#_categories_of_kernels"></a>3.2.5. Categories of Kernels</h4> |
| <div class="paragraph"> |
| <p>The OpenCL execution model supports three types of kernels:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>OpenCL kernels</strong> are managed by the OpenCL API as kernel objects |
| associated with kernel functions within program objects. |
| OpenCL program objects are created and built using OpenCL APIs. |
| The OpenCL API includes functions to query the kernel languages and |
| and intermediate languages that may be used to create OpenCL program |
| objects for a device.</p> |
| </li> |
| <li> |
| <p><strong>Native kernels</strong> are accessed through a host function pointer. |
| Native kernels are queued for execution along with OpenCL kernels on a |
| device and share memory objects with OpenCL kernels. |
| For example, these native kernels could be functions defined in |
| application code or exported from a library. |
| The ability to execute native kernels is optional within OpenCL and the |
| semantics of native kernels are implementation-defined. |
| The OpenCL API includes functions to query capabilities of a device |
| to determine if this capability is supported.</p> |
| </li> |
| <li> |
| <p><strong>Built-in kernels</strong> are tied to particular device and are not built at |
| runtime from source code in a program object. |
| The common use of built in kernels is to expose fixed-function hardware |
| or firmware associated with a particular OpenCL device or custom device. |
| The semantics of a built-in kernel may be defined outside of OpenCL and |
| hence are implementation defined. |
| Note: Built-in kernels are <a href="#unified-spec">missing before</a> version 1.2.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>All three types of kernels are manipulated through the OpenCL command queues |
| and must conform to the synchronization points defined in the OpenCL |
| execution model.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_memory_model"><a class="anchor" href="#_memory_model"></a>3.3. Memory Model</h3> |
| <div class="paragraph"> |
| <p>The OpenCL memory model describes the structure, contents, and behavior of |
| the memory exposed by an OpenCL platform as an OpenCL program runs. |
| The model allows a programmer to reason about values in memory as the host |
| program and multiple kernel-instances execute.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An OpenCL program defines a context that includes a host, one or more |
| devices, command-queues, and memory exposed within the context. |
| Consider the units of execution involved with such a program. |
| The host program runs as one or more host threads managed by the operating |
| system running on the host (the details of which are defined outside of |
| OpenCL). |
| There may be multiple devices in a single context which all have access to |
| memory objects defined by OpenCL. |
| On a single device, multiple work-groups may execute in parallel with |
| potentially overlapping updates to memory. |
| Finally, within a single work-group, multiple work-items concurrently |
| execute, once again with potentially overlapping updates to memory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The memory model must precisely define how the values in memory as seen from |
| each of these units of execution interact so a programmer can reason about |
| the correctness of OpenCL programs. |
| We define the memory model in four parts.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Memory regions: The distinct memories visible to the host and the |
| devices that share a context.</p> |
| </li> |
| <li> |
| <p>Memory objects: The objects defined by the OpenCL API and their |
| management by the host and devices.</p> |
| </li> |
| <li> |
| <p>Shared Virtual Memory: A virtual address space exposed to both the host |
| and the devices within a context. |
| Note: SVM is <a href="#unified-spec">missing before</a> version 2.0.</p> |
| </li> |
| <li> |
| <p>Consistency Model: Rules that define which values are observed when |
| multiple units of execution load data from memory plus the atomic/fence |
| operations that constrain the order of memory operations and define |
| synchronization relationships.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="_fundamental_memory_regions"><a class="anchor" href="#_fundamental_memory_regions"></a>3.3.1. Fundamental Memory Regions</h4> |
| <div class="paragraph"> |
| <p>Memory in OpenCL is divided into two parts.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Host Memory:</strong> The memory directly available to the host. |
| The detailed behavior of host memory is defined outside of OpenCL. |
| Memory objects move between the Host and the devices through functions |
| within the OpenCL API or through a shared virtual memory interface.</p> |
| </li> |
| <li> |
| <p><strong>Device Memory:</strong> Memory directly available to kernels executing on |
| OpenCL devices.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Device memory consists of four named address spaces or <em>memory regions</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Global Memory:</strong> This memory region permits read/write access to all |
| work-items in all work-groups running on any device within a context. |
| Work-items can read from or write to any element of a memory object. |
| Reads and writes to global memory may be cached depending on the |
| capabilities of the device.</p> |
| </li> |
| <li> |
| <p><strong>Constant Memory</strong>: A region of global memory that remains constant |
| during the execution of a kernel-instance. |
| The host allocates and initializes memory objects placed into constant |
| memory.</p> |
| </li> |
| <li> |
| <p><strong>Local Memory</strong>: A memory region local to a work-group. |
| This memory region can be used to allocate variables that are shared by |
| all work-items in that work-group.</p> |
| </li> |
| <li> |
| <p><strong>Private Memory</strong>: A region of memory private to a work-item. |
| Variables defined in one work-items private memory are not visible to |
| another work-item.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="#memory-regions-image">memory regions</a> and their relationship to the |
| OpenCL Platform model are summarized below. |
| Local and private memories are always associated with a particular device. |
| The global and constant memories, however, are shared between all devices |
| within a given context. |
| An OpenCL device may include a cache to support efficient access to these |
| shared memories.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To understand memory in OpenCL, it is important to appreciate the |
| relationships between these named address spaces. |
| The four named address spaces available to a device are disjoint meaning |
| they do not overlap. |
| This is a logical relationship, however, and an implementation may choose to |
| let these disjoint named address spaces share physical memory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Programmers often need functions callable from kernels where the pointers |
| manipulated by those functions can point to multiple named address spaces. |
| This saves a programmer from the error-prone and wasteful practice of |
| creating multiple copies of functions; one for each named address space. |
| Therefore the global, local and private address spaces belong to a single |
| <em>generic address space</em>. |
| This is closely modeled after the concept of a generic address space used in |
| the embedded C standard (ISO/IEC 9899:1999). |
| Since they all belong to a single generic address space, the following |
| properties are supported for pointers to named address spaces in device |
| memory:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A pointer to the generic address space can be cast to a pointer to a |
| global, local or private address space</p> |
| </li> |
| <li> |
| <p>A pointer to a global, local or private address space can be cast to a |
| pointer to the generic address space.</p> |
| </li> |
| <li> |
| <p>A pointer to a global, local or private address space can be implicitly |
| converted to a pointer to the generic address space, but the converse is |
| not allowed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The constant address space is disjoint from the generic address space.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| The generic address space is <a href="#unified-spec">missing before</a> version |
| 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The addresses of memory associated with memory objects in Global memory are |
| not preserved between kernel instances, between a device and the host, and |
| between devices. |
| In this regard global memory acts as a global pool of memory objects rather |
| than an address space. |
| This restriction is relaxed when shared virtual memory (SVM) is used.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Shared virtual memory is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>SVM causes addresses to be meaningful between the host and all of the |
| devices within a context hence supporting the use of pointer based data |
| structures in OpenCL kernels. |
| It logically extends a portion of the global memory into the host address |
| space giving work-items access to the host address space. |
| On platforms with hardware support for a shared address space between the |
| host and one or more devices, SVM may also provide a more efficient way to |
| share data between devices and the host. |
| Details about SVM are presented in <a href="#shared-virtual-memory">Shared Virtual |
| Memory</a>.</p> |
| </div> |
| <div id="memory-regions-image" class="imageblock text-center"> |
| <div class="content"> |
| <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAnwAAAHPCAYAAADJWwcQAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAPaVSURBVHhe7J0FYBRHG4bfuENCgru7u7u08EOLlOIuxSnu7lCguNOWUmiBtlDcW6RogeLuThLivv+8c7dwCaGENgmXyzztklu5vd2Z+Wbe+casNAEUCoVCoVAoFBaLtfGvQqFQKBQKhcJCUYJPoVAoFAqFwsJRgk+hUCgUCoXCwlGCT6FQKBQKhcLCUYJPoVAoFAqFwsJRgk+hUCgUCoXCwlGCT6FQKBQKhcLCUYJPoVAoFAqFwsJ568TLVlZWxk8KhUKhUCgSE7UmgiK+UR4+hUKhUCgUCgtHCT6FQqFQKBQKCydOTbpTpkxBpUqVEBkZaTyiUCgUCoUiPrCxscHhw4cxdOhQ4xHVpKuIf+Ik+Pbs2YOaNWsa9xQKhUKhUMQn+/bti1bOKsGniG/i1KQbFBRk/KRQKBQKhSK+SWrl7J9//omxY8fiwIEDWL16NVq0aCE3hfmi+vApFAqFQqGIMyEhIZg2bRrGjRuH6tWro0OHDli3bh2yZctmvEJhjijBp1AoFAqFIs44Ojri559/ls3Ot27dgru7O8qVK4cxY8YYr1CYI0rwKRQKhUKh+FfQu0d++OEHKQQV5kucBm1s3rwZ//vf/4x7/8yNGzewZcsWREREIHPmzGjevLnxjPnw999/y1FRBQoUMB6JG7t378aVK1fku5GoqCjpzi5evLjc/7fs3LlT3uujjz4yHlEoFApFcuK3336LVs4mhUEb7MPHZt1Vq1ahffv2xqMKcyVePXycvqV27dr49ddfpYgZNGgQ6tati8ePHxuvMA/69+8vO5q+L0zckyZNwrZt26So5Va/fn1MnTrVeMW/49KlS7h48aJxT6FQKBQK84aDNij2KPSU2EsaxJvgo8JnJ8758+dj//790ht25MgRKfa6d+/+yitGDh48KNv/r169ajwC3Lt3T4oeHx8f6VE8ceKEPO7n5xdtn9y/fx/nz59HQECArBXxt0zhfS5fvmzcA3x9fWXiDAsLw6lTp3Dz5k3p5WPfA52jR49i06ZN+Ouvv4xHYmfw4MHYtWsX9u7dK99zwYIFmDBhgjymww6tFIUUvs+ePZPH6PmMee/r16/L52jSpAk+/fRT41Hgzp078llM31nn+PHj8tzJkyeNRxQKhUKhSDxYpnJEbr58+bBo0SLjUYXZwybd2OApfROCy3g0doTA0UqWLKlNnz7deOQ1d+/e1YTw0cLDw7XAwEBN1AS09OnTa4UKFdIyZMjw6t4i0Wg5c+bUmjZtqhUuXFjz9PTUJk+erLVt21Ze6+bmpglxJa9dvny5li1bNu3jjz+W5zJmzKh98sknmhCH8vxnn30mv6cjBKb8TSEqtWHDhmkODg5a2rRptW+//VaeFyJO3qNIkSLymZYuXSqPx6RixYqxvmPHjh3lbxIhRrWqVatquXLl0goUKKAVK1ZMu3btmiZEmpY7d27txYsX8rqoqCitZs2a8h379euntWzZUh7ft2/fq+96eXlpc+bMkcfJ6NGjoz3n119/bTyjUCgUiqTMli1bopW75gzLW0dHR+3o0aPGI4qkQLx4+J4+fSo9WRUqVDAeeQ378TVs2BC2traYOXOm9HzRI0dvV+/evdGjRw88f/4cKVKkkB43IZxw+vRpeXz48OFo1KiR3O/atStWrlwp7+nq6orbt2+jdOnS8hxnKD979ixmz54tz/O32EdPh/0Rra2t5d+JEyfKPnejRo1CmzZtpKeRTbP0OvIeGzduhBB10pMWGyLMjJ9eI4SgfHZ6EHl/IcYgRB4uXLiABg0aQAg6VKlSRT4TvYKEzbj0QgqBK/vvCREqvaAjRoyQ4cVnoceUz8cVTjj59fr162XY8Rw9m/SmHjp0SN5PoVAoFIqEhnPu/fLLL7ILF0fmKpIO8SL4KFQohCi0/gmKnZ49e6JgwYLyWgo+FxcXKWD4/WLFismmTZ4rVaoUihQpIvft7OxQvnx5hIaGIjw8XP7Nnz+/XIaG57JmzYqBAwdKEUR4jAJPRxd8RBd++rPu2LFDCiqKJzY9r1mzBg8ePJDN0XGFYs3JyQne3t5SOLIZmu/Gd2XzMo9R1FG8UsARNlMXLVoUuXPnlu/D77Mp9+HDh/I5+HwdO3aUAplCke/Gd1+6dKk8zyZ0PifvrVAoFApFQsOm3C+++AL16tWTjgxF0iJeBF+qVKmkYGHfupi8fPkSM2bMkOcoYjw9PY1nDHP5UPAFBgbKfWdn51d9/dgPzt7e/tU+RZEu2ijQPDw8pNDSSZkypfyOjqmHj9eZjjqmuKQAI/rv6OsE89yQIUNQtWpVuR8X2J+Qv8/78H4UnLw/75klSxbp9aMHkyOW2ZeQ/fnYZ7Bx48by+7yOz6c/v+l7MUwIw4j31Z+T4UKRy0EyCoVCoVAkNJxvb/v27dLhoEh6xIvgo9ipVauWdPFS4Jny1VdfyY2CMHXq1HK9QB0OWOBgDc7OTSFDkWTaZMrPpvs6FFYUTaYCk56u7Nmzy88Uh7qIJLyWYkoXffwtCk3CBOzl5YWvv/4aixcvloMwSpYsKQVaTPgsugDTYXP22rVrUadOnVcilJ95H96Po3rZrM3vFi5cGHny5MHkyZPl4BTTaVj4THwOCjk2BxN69GhYL168kM3EvL/+nAsXLkTZsmVl2CsUCoVCkRhUq1YN6dKlM+4pkhLxIvgIZ9imYGPTK5tHly1bhrZt22Lu3LlYsWKF9Ox169ZNCj42SbJpslWrVrJvW6FChaQAYlOoLvDYH477Ovo+z9MzyD6D/D7v8+WXX8p+eOyXR5ggOZKV06VQILHvIL+v35ueRn0ULN3TFFjsO8jn5DPz+WJb15D3YBMrf3PJkiVS1FWuXFmOVOrcubMUlGzKpYeQI3d5XZkyZfDtt9++akb+/PPPZV/EEiVKSBFHKE7ZHJw2bVp88skn6NWrl/xuu3bt5DvQs8n7P3nyRDYL8zm5zwkvOVJZoVAoFAqF4p+wGcvJ5WKB8+vocPh13rx5jXuxQ48ZxQwFCMUX++XRE0fhQgFG6MmrVKkSNmzYIAdbsB8ABRmbKukpo7Chd4zCiH0F6KmjF4zHKQi5z0EQFGqc7oVNoj/99JM8TgFGzxyhmOLADoo6ehw5lQo9jBSXPJ4pUyY5rQp/lwKKgyQ4GOKPP/6Qz0yBFtukzPQockoXvhu9k9z4zroHk3AgSY4cOeQACw5MYZMrBbA+Azmbv9lXr0uXLtLzR+7evStrTBz8QU8pw4J9/ehl/Oabb5A+fXrpyeOknPRkcqN4ZedZ9ntUKBQKRdKG05RxtQqdtxTNCsW/Jt5X2kgMKO4odtgPTqFQKBSKpE5SXGnjn+AqVFx4gYMrFeZBvDXpJib06LEJ1HSQhkKhUCgUig8PvZNczWrYsGFS+CnMgyQp+FgLYjOqWqhZoVAoFArzgY4YLq2q8z4zXigSlg/WpMtRqfpccuw39z7uawo9joY1HeShUJgjtCMO9uGAHM6ryLRuSbDPLgcR0RZNp0JSKCwJ2jGFDGdZaNmyZbTyMb6wpCZdhhXHAXAaMn2xAcWH54MJPgo9juzlKFkWFEq4KSwR2hFHr3MaHa6iok8dZClwYBKnCaIdKxtWWCq04+DgYFm5mTVrVoJMh2VpffjeBmee4GwUnN1Ckbh8MMHH+fc4+IKTEisUlg77tLRu3Rq5cuUyHrEMONqeq9VwGUSFwtJhn7RBgwbJ2Rbim+Qg+NatWydn/eD8t1wKtX379sYzisTgg/Xh0z0fCkVygF0YTCtRlgLfie+mUFg6bKZkmWWJdpwYMPz69+8vP3PatV9//VV+ViQeSXLQhkKhUCgUiqQD+95zflk25XJOXrU8W+KjBJ9CoVAoFIoEp1y5crLfL9fjZbOuKWfOnDF+ej84MKR48eK4fPmy8YjibSQZwXfx4kW5lNjHH38sV8dgv0Jz49KlS3JVjcRs4uJSdVyKje5yf39/2S+Cy869C66AQkNRKBISrh7AVWW4Yg5XtOEqO+bG9evX5RKQHE2dWBw5ckQOdKHNcjAA7fbhw4fGs9HhBPNc8pEr+5jyyy+/yLW61WAZRVKCnr6YAzZYFnFZVuYTXEUrrrBpmH0CKRYp+rggg+LtJAnBt3z5crksGhMK5/ShO7hNmzayo7g5ZXbsvM6lcRJzegouu1a2bFkZNufPn8ecOXPg7OxsPPsmLIAZduxLoQoKRULy/fffy+UCCZdX5IAVij+mPXPq98cJYrmcYmJOmZMmTRrp7eCSlFzLm/OKvu33uUTkd99990ZhxuMs6FSfMkVShs4KOnP4l2UoK0Jxhd+7ffu2bCrmMqfcpwDkvRRvYvaC79SpU3JpFq65u2jRIgwZMkTWxteuXSszaZ7XYQHTrVs3jBo1Sip/wjV46c1i7XjatGno16+fXA+XtXmOEOa+XnPmXGKcYuLChQtSOHXv3l26nnUolvjbnHtMh/fmSEVm2vRe3Lp1S2be+oAUjrzq0aMHBg4cKNfQjQ3W4HkfnaCgIPm+9DwQvtexY8fklABdu3aVz6iLNWb2XMeX6/wuWLBAvvfIkSPx4sULeV5Hf196Rw8dOoTChQvLNYcVioSANvTll19iypQpWLZsmbRb2sXGjRvx448/RlsWketh09ZYgXv+/Lk8RlukTXDdak6D0bt3b9lkExERIad16Nu3r7Q7EhgYKEf80445/Q3zANMWANok7Znrauuw/xC9CiwsmJfQfnhf3p9w4ljaLd9Bt8OYMO/h7+nilSsA0cNPTz/hiER68rgeNu123rx50YQu7fbRo0fS1vlsnKbqyZMnxrOv4fMzfNgUpuchzF/oya9cubLcVyiSMpymhdBxQW93XGAFiF5uluH8Pm2aG4/RW0jbVkTH7AUfxQ49WJzs0pT69evj+PHjciJMZn4sAJg5U9lv3bpVuoa5/Boz4QkTJkivFgXb4cOH5dD3du3a4cqVK1L8fPrpp1IghYeHywKK92atn4UOawvMkAkzcoomNsPosBDjxJLMyPnbFFb8nrW1tfweM2o22bBJmmIrtn4G/D4LNR0WYPwdveBgIuYz8b34PhTAffr0kedYcFLgUoTyHMOCok8XnDp8BltbW2kMrAWlTp1aTl6tUCQEFDsFChRA586djUcM1KhRAydPnkShQoVkpYVpmTV6VnL27t0r196k6KE9sYLWqlUraTsUV7Qf2jHFJG2fdkvBxPvMnDlTdvegUKP9cLqH6dOny99kZWz8+PGvKoGEtrlr1y75O/xt2j5FF22ELQqcJJv3odhjYXLu3DnjN19DMcffMBV8FI0UqWTNmjXSbul9YL7AqXkoRgnFGwUuf5Pf4z34fPq9dPh+rKAyv3Jzc5P3IpzHlOKvVKlScl+hSKpQ5LHcZTnIso4teO+C5SjzDXrJ+V0d2j3LRNoSyzlFdMxe8DGze9tktRkyZECKFCnw+++/y4Syfv16WZtmhDOzZu2bTSYsEJjx0kO2Z88e2VcmR44cspmEHjxmxsyA2RTKa1k7oDBizZ+1DW70PDDD9fDwiNZky9/nd9gngf1sSpYsKTN2Zsb8fXoe+Gzbtm2TXjX2uYkJa/qmE3lSLPJ39CYe3p8ZO5tw+H6cwZzij/D9+NwUvpwfKkuWLNLLQEFnCu/PwjVv3rzSM6IKCkVCQrt9W8bNbgjssE2vNb32FEb01lNA0bZob3q3hNq1a0u7ZV9VZuJsCqXdUqzx2hMnTkj7IfRY0255P9oe7YC2ThulPdGudHS7zZkzp2xmpm2y4GD/IXoDKQhpa/QUslmagjEmLKj4HnqTKv9yX69Icb9IkSLSq0lvBMUhm6wo6vh+3BhGtEvaLT2AzNNMoVilIGS+QuHJPIDQI8n758+fX+4rFEkddvtgs+y7oGOFlT3+ZcsB7dCUYsWKyYoVnTaqn3p0zF7wMVOP6a2KCT0A9BgwwRBmuA0aNJC1cmaWzITpWSBMHMxk9Wu5z8KATb+s5VNAmdYMGjduLGv99Cq8rY+NnuHTi0bxSG7cuCFFH8UfM+vSpUvLGgybZ94Xvr/peoQZM2aUz2kKCxF6+dgkRQ/j2+B7MrzKlCljPKJQxD+025jeqpiwls5+ffXq1ZP7/A69eOyLSltiBUu3W9pe1qxZXy3EbmdnB09PT5memeZpx6zd67bIASIUVOzjFhe7pe0T2iybgij+dLulSOOxd71PTPhcbHLlexEKXVdXVyk0dWjb/2S39BZmypRJvi8FHz2CbLpmBTVdunRSuCoUyQlOfs28g+mfLXCsoMVE78On/1UYMHvBV7BgQSm2YoPNmqw5x8xECff1DJ01ez2zZsbKTDbmvp4p8zv6Z8L76PfidfxrWoBQDPJ4THh/etUGDBggm1yZSPms7GcXE36f99Fh4cVn1t9J/20dvXD6N9Dzwt9SngFFQkK7ZZeJ2GB/VvZDjVlpITHtVk/3tFPalG63/Mtzb7Nb8k92SwGl25cpvC/zE3YR0e2WTbzsh2jqISS8lr/JexF6Grlvarf68xK9Mvg+sLWCYUlYMaVnnt59dvcoWrToG++sUFgy9OBT4LFyR+cJPYIcBMYuXHqfPXr12LJGQcgmX8VrzF7wsZmUfe/oKTOF4mnlypUyM6R3j6Jw9+7d8hxryuwYziYePQOOmbnHltlTCLEpmJ3Iddisy3vwN8jTp09fdaxmTZvPpjcpMUPXhRubjJnZ6zVzegqZQOlmjgk9klxqjn2JCD2BbLIxLaBie96YsFDkdf+0ziObzegZobdBoUgo2OeWzalscjEVPex2wWZc9u+j7dITrg+woKeN9kYhQ7uhUIuL3dI+WZM3nfKF9k970AcmsY+uPt0DhSi9iHpTEO1WF3P0/uuCU7dbfo9dQfTjOrRb2im9jOTgwYOy0Hlfu2X48F1jeusYHuxDyLDSYR9Gehz1fpAKRXKBdsjWN9oou33Qftldihs9+ez6xe5Y3Hitfo3iNWYv+NjkQ28AR+xVqlRJCkB27KaqnzFjhmxy4fw7HAVHtU8XL5tR2AzCARMUURy8odeumQGzL5C+z4yW+2z6JRRL7BjNJqGmTZti8uTJsv8O105kfxwWRvx9dibXRah+L4o81sg5Lx6bXekhYP8g3od9CEePHh1rvyaeY/MTEyqfn7UTFkD6fdmMo4tBwmflM+uf9WYtijh+ZmFLIRobFHx8BjVgQ5GQZM6cWfa94zRFtFsKFQ6qoE1yEBWnWaKQ4ehb2jRtl3ZL+6N3jQJOH3RFaLe0g5h2rDfZ8Hvsj0tbatasGUaMGCHtL23atNKbzZo+z9Fu2d+Wdq/fi/bAplPaKkUX7Z3PQLHHAV5639iY1KlTR/Yp5PvR5tjvj6JQf2ZWPFmB1OHv8Zn57PzM96Pd8h60b31Aig6FKQdnmPa3ZX9CNgHTi6G8F4rkBAdp0N6Zp5hO2kxvHz3e7AtLgce8hE6TuPQHTG7YCNES3XVmhAMDdChC2Nk/PmFmyA7XNWvWNB55O8yg+QzM8AkLE6p3ZuCEmSwzX3Z4puBhfzd2gGaTETN2DmDgSF99wWsWDvo+v8umEooteufYIZwij14wii52tNafkYmJtX5m0vQqsLmWfYoYNhSYLFh4T2boFKJ8DvYDYm2D7mWOxGVBFxP+PgsWvh9/l9Oq0DPBGjzvxyYm3k8vdOj9oLjkvelNYM2GQpTvT4HMAoHnvLy85PWmsKBhvyj2h1IkHsyA2JlYT4OWAtM2KxemfUx1OCCCAovpkTbB9MmRt02aNDFeYRi1S8FFDxxtkAMtmJnTbhlWtFOmY9opxRj7nurpmtdR9LCyxAEWrFAxb6DHjDZMgUloI7RbPgM3VqhYacudO7e0Aw54Yh5Bu6adUXjyvnw3/hbzgFq1asl7mcLnYZ9DjtrnZ4665fPRc8n7Mf+hWNMHnTF/4bvyN/hMtGemCeYNzOMYTtynACQs3Ph8zH/0lgPmO3xe2jffgfuKxIHpgy00FPh6q058QjuimNF5S9GcbKFt0C71Pr+msGymjVL80cESm2NFIRAZYKzwlL5t3rzZeDT+uHfvnjZs2DDjnnlw//59TRQC2o4dO4xHFIr4QYh47fr168Y9y+H06dPa+PHjjXsfhqdPn2qisqVt2rTJeEShiH+Cg4O1wYMHa97e3sYj8cuWLVuilbsKRXxj9k26iQ29Z6Z9jhQKhXlD7x89YMpuFQrF22A3CHpN2UWM3ntT2FIX22hfS0MJPhPYlMI5s+iyVygUSQM27XKQRmzNrgqFInnDrhEc7MEuIxw0xi4d7GbBwU+EQi+2wZSWiBJ8JtC7x740MUfLKRQK84XePdqtaUduhUKhIJykmbN6cDQvB3dwDksOHuMgEHr9OPUS+/hyiTZLRwk+hUKhUCgUFge9eNw4FRQHdOhw3WqOmKcYZEWRYjA5YMWOfMbP0WC/GB3Ok8VRpPEJ56/i8kccTWfumIaFQqFQKBSKxOMtMuWdUNBxbkx69WLC2TEo+jiDgr7ylqWjPHwKhUKhUCgsDoq92MQcV+yg2KOnTz/PyZstvS+fEnwKhUKhUCgsDjbXUtiZwn0u3EChx1G7FHpcvIEbR+tyQAcFoSWimnTjgGlYcBJWTsyqpoBQKBQKhSJ+4WTihw4dkivc6PzbJl167LjOLvvoceUN7lPs6c28FH8UeZy4mYs5cBJ0XsOFJzgJtqWt1qEEXxwwDQuuqRmX1UEUCoVCoVC8P/v27YtWzv5bwUemTp0qV/gx9fRx+VSOzKVXjx4+rt5humQbPX9cvYfr31sSSU7wHT1yFBcuXYCdrZ3xSMJjOronIcJCoVAoFAqFgd9++y1aOftfBJ8OvXpc/pRTstCbx2ZbDuqYMmWKFHcUhBSCXL6NI3vpGaTgowjk9C2xLemW1EhSffhCQkOwcvkK2IbaIAVc4BrlnCibQqFQKBSKpAvX1+X0LBR45NixY7IJd+jQobJ5lx4/Ts5Mj+Cvv/4qr+F39Gbhy5cvy2NJGnr4YoOn9G2zmayl6+fvpw0bOFTTfKI0LVQcCEqcLaHDQqFQKBQKhYHEWFdYCD3N3d3duGfg559/lsf4m0IAymP9+vWTx7iW8tsQIvIfz5sLScrDx2bmKC0KAX5+wMsosYXHbfM1+RvbFvP6mNcqFAqFQqGwGJo3by6bcU1H5NLLx9U4OIKXU7YQevi4z4EdscG1eblaR1IY2Zs8pmXRuyO62wGpTbZUYrO1MdQhTOG+qzjnKTbr130Z35cLFy5g4sSJsgPoypUrzXJk78mTJ3H27FnjXtxhHwu6vvl+3MaPH48jR44Yz/572EeS/SgUCoVCoUgoihUrJkfvtmjRQvbl4+hdfY1dTsbM8+z3x0EdjRo1Mn7LAPv08XoKRvbxTyojepOH4LO2RpRQcd9/8x3GjBwttxHDhmPpwsXiqFB3dkL02XCzNWxudtiy+ReMHzMWQSFBxpu8HyNHjkT9+vVx9OhRmWAmTZqEqlWr4u7du8YrzIOBAwf+K6HG9+GgGwpG9oXg1qRJE4waNcp4xb/jwYMHePjwoXFPoVAoFIqEQRdrISEhmDNnzhvrcdO7R/QBG7yO3jz29eM5TunCvn1JZfqWZCL4bBApdN2C5QsxftoEuU2eOQXdvvwCQ8YNQZSNhggtQlxn+BsQGoCXvi/x/MkzBIeHGm8Sd+jiZedQLti8detW6epljSAiIgI9e/aUf3XoKeMIIYpCnZs3b+L06dN48uQJvv/+e1nbIM+fP4+2TziK6MSJE/D29pYJl94x0/vzPqb35nV79+5FaGionOuINZjjx4/jypUrxisMU8/w2Xn+bVgLET1gwAD5blu2bJHvye/QaPhOOn5+fli/fj2+++473Lt3Tx6jyzymyKQ3lOKRhmU6HJ/GxPvqhmcKw4HnDh48aDyiUCgUCkXcYTPu9u3b5UhgDt4wnZWDZQtH7XJwB8twTuPCMo4DP+gBZNlKEZhkMHTlexOe0jdzGbThH+CvDRkwWPO/46tpTyM17VFY3LZnUVr4w1CtfMlyWoumn2uPbz3SHly/r7Vq2lJzcXTWnlx6qA3rO0SrUq6yVrZEGa1t0zbanPGztM4tO2i//7zvvcIiKChIEwlBmzt3rvHIa4SA03bv3q2Fh4drvr6+WpMmTbTMmTNrpUuX1tKmTasJwSavW7hwoZYxY0bt008/1cqUKaOlSpVKhlXLli3lta6urtrMmTPltcuWLdPSp0+v1apVS57Lnj27/PzixQt5nr/RqlUr+ZkI4aSlSZNGu3v3rjZmzBjNyclJy5Qp06vfFoJUy5IliyYSuXyGr776Sh6PScWKFbXp06cb917TrVs3rXHjxvKzEK7y+QsVKqSVLFlSK1CggPb3339rv/76q5YtWzbt6dOn8rrIyEitUqVK2tSpU7U+ffpozZs3l8eFiJTX8buenp7axIkT5XHy5ZdfvnpOPj87zSoUCoUi6ZMYgzbiAssflpMc4MHnYHlz6dIlWV5yn+eSEsnDw2eEXil/fz9cu3kdN2/ewnPv53B1cYWTs7M4dg2Hjh1Ctw5dMWr0KNy8dwu/7d6GrDmzGb8dN549ewYhtiDEl/HIa4TQghBjsLW1lRNBshn0999/lx42NgELESO9eilTpoQQQ+jUqZO8hp401ijatGkjr+3Xr5/09BE3Nzc8evQIderUked4PZtFhSCU59nR1MHBQX4mnMXczs5OhgX7FrKWwt+mS3rdunWyRsNmaG702rHZ9vDhw8ZvR0ekH+On17A2xGZr1nomTJgAIfYgRJ703rVu3Vq+I1cqcXFxkZ5Gcv78eemp/Oyzz+Q+zwlRLJ+P78zv0mPK52A/SD4X+1noz0qPJPticLJOhUKhUCj+K/TesQWMLXC6V4/lDcvUL7744tXSbIR9+diyx37t/I65knwEnxWQwi0Fftu5DZVrVkblOpWxc98ujBo0Cm6pUyI0NAyVylZCh66dkKtwbtjb2cNOCLMM6TIabxA3oqKi5F8Kqn+CTZpMNJznh1Dcsf/AuXPnpJCiEKtbt648V7BgwWj7/ExBxI1NsxRVffv2ledSp04tBeGuXbvkPsWl6STaJOaz6cKNgikoKEgKQHZknTVrlmyGZZNxXOHvUbDRAGgcTPxt27ZFq1atpEDje7PJmf39Nm3aJL/DOY8okNlhlkKRBsXvUfS2a9dOXtOsWTPZVEzBunPnTgQEBMiBInxOTt7N5+TvKRQKhULxX2EZxrKIzbls6uV8fSyfWOYQdqEi7HbEpl6W5+zfx3KM8/bx++ZG8hF8QtMEBAagSoXK+OGbtVi1aCUObtmPnr16AaEG0SOFUIC4NuzVVxAe9n7TsqRKlUoKntiWZGEfvBEjRkgPmL29PVKkSGE8A+l1Y+LS+wPQK6f3xaOoo5Ay3ddFGz1e9PLx+zrOzs4ICzO+hIAiSYe/YSoA+d664ONve3h4IEuWLFKI8u+MGTOk9zCu0DAoXPn8fM4MGTLI+3CrWLEi5s+fLz2YFHDsX8j+fPRKNm7cWH6fgpnPRzFLTN9Lf2eKUt5Df85MmTLJmpVaAUWhUCgU8QE9eCzP6EjIly+fPMZyhn352KJEIUixxwEchNeyLGWZxuMdOnSQx82J5CP4BP4B/sifJz8+b9sC7Tt1QJUa1YBgIXaihMYLD5MCRSL0ULgQV9wPFuLifaCIa9CggfQ+xRxtypGtbIrlNenTp5dNkzpsjqUQzJkzpxR2FD66ECOmwswUCqurV6/i2rVrxiOQzZ16AqXw8/HxkZ8JPYgUdrp44m9RoJK0adNKgUU3Nd3XnG6FwiqmR5DwWfTv6VDkrl27Fg0bNpTCkcKzaNGi8j68H2tAfC+KVC5xU7hwYRlO9Nbp3kvCZ2LzN6/j8xKKPHoc2WSeI0cOKYD152S4enp6vuHJVCgUCoXi36KXo4QDB8eNGydb0DjQg7BMoxNFn8aF8Dv60m2PHz+Wx8yFZCT4NKT2TA1He0ch8sTu8wjAL5zKRZ719EglznvxMikAU7i6IV3qtGL3TZH1LtgkSvFE5c/JG9nkSBFIscfRqvSA9e7dW9YI6OmiYGH/Ns71U6BAATmSlu5gXeBReL58+TLavn6ego8jYfl93odNoBxdq/ctoGuZo2jZD5DPwr5w9J5RTBGKMo50ZYLt1auX/G32M2RNhs/MBB6bkKKQZJ8//iYFHX+P086wfx6bcAld4BR0ffr0kdeVKVNG9tujWKPXUe83yOMUeMTf31/2gfTy8pLvxHDi/Zs2bSrDju/buXNn+Q78PT4n51AaPny4/L5CoVAoFPENxRtFHZ0MhJ4+isAhQ4a86pqlozfn6i125kLyEHwREbC1ssbaFd9j3JAxQugJsWdlFHIUPmERWDBjPlYtWCmvhW8EBvYagD2bd8PDNfq8PHGBXjH2Mxs8eLBstqRLOGPGjFKIURCRUqVKYffu3fIzz1NsLV++XO6zzx6FIIURyZ07txRHetNs3rx50bJlS7lPsUfBxJoGm0bpoeMgBgpHwkEPS5culS5mDghZsGCBFFFsUiZMvPTGceBE1qxZZT+7XLly4Y8//pBeSA4q4e/FhM9DUUvPJPv4nTp1Soo+9mvQn5uCbePGjdJzyb57PXr0kKJNb6atUqUKunXrFm0OI07Jok/LQqFMscjv0qAYXvSOUhxSOLLvIp+TAprPTY+hQqFQKBTxDcspOmno0SMsU4npNC46vJbOlZhC8ENjpeluoxiYenW4+kF894+6f/++HAHKQj2usA/exDETMLLPcLg6uRnE2vtgL4QG35b98mI6rShCeIzneI0dJ2EWB0IjYJX+dT+yhAiL/8KSJUvkKh4UewqFQqFQJHU4QM+0nH2LTPmgsMmWrUucJYP9+d4GHSFz5859NQiEApGOlpiTPCcGyaoPnxRzHAzwZgul4bg+QIPn6ekL5b75JTRT2N+NfeBe9T9UKBQKhUKRoHCRAHrwODhD76vHqVnYh16H59gtigNA2G2KQo9NwVyh40M09yYvwWeBsBZE1zH7tikUCoVCoUh49MEabNpl9yd2jWLXKnrzCOfuY/94evLYz4+ijwM+uBoWv0MPYWKTvJp0/yVW6Q393UhChAUHQMybN09O20Lh9j7ua17P/nj08pmj21uh0GGewrTOPq6cN1LvC2MpsMnm66+/lu9oOhWSQmFJ0I6Dg4Nln+/u3bvHOovDfyUpNOnq0FNHYUcvHxce0NfdpQhkUy+P0fPHQZP6YErO20cByNG8iYnlCD6+BfvdpRDPzcMcN8A5kNnSyXKFr+MnNjbb2ogEmkJkyMyTeY2f+DKbcD2MffV4LdMwR/Oya59zwocFR6KyFpAQxqNQmAvMbqZPny5HjXMKIkuCA7SY8fPdFApLhoKPHizOkpAQfdGSkuCLDYo/Cj62vlEU05vH5l1O2cI5/DgtmS4AWVHkqh5sHk7wQR4UfLHBU/omRI7xaPwR72vpekdpt05d14b0GaytnLNc69i6ozZz/Azt/KFzWs+OPbT+X/TXnl9+omm+4nvemrZwxnyt+afNtSmjJmthT0K0qCfh2uSRk7WF0xdow/oO1Xp16SW/O33M9AQPC65rO2LECOOeQmHZjB49Wrt27Zpxz3I4depUtPWeFQpLJTIyUhsyZMirNdvjG3NZS/ffcuvWLfncQvAZjxiOcS1e/Z3++usvbf/+/ZoQzK+O9evXz3h1wmA57iR7Kzx88gjTvp6OafOnA1EaBo0ehEatP0F4RBgWLJuPMdPHAi7WGD1pJGYvnI2ixYrix19+woARAxFpo2HxykXoPbQPfF56Y+OvG1C+bgVcuW4Yep2Q0JuqL8mmUFg6+moqloayY0Vygd0WhH6wSDuOD+ipY1Mu1+HVB2fwGKdg4/y0nLaFc/pxQAe9fly0gJ4/thAk5AodliP4hD62sbaBtZUQdINGYcWalcicMTMqlC6PJd8sQ70a9XD52hUE3HuJ735cgzSp08LD3QPp06bD/OXzcfnSRbh7eOCzRs2waNUS1K9TH26ubli+fIXxBxQKhUKhUCjeDeekZdMu++ux6ZZCjtO4sClXX4eX8Br29eN0LbroYxNvQmBRHcZY47CztYVHSnfZX8/WxhZpvNIAEdSDGlycXeDn6ytqJ4aVJvbt2ytXdBjUZyAc7Z0QJY6l8Uwt78UaDFfm4HcVCoVCoVAo4oru0ePgDI7cZT8+9ndkn73bt2/Lazh4jZ85upfo8/npkzrHNxY3QiBKi5Jz09Hjx+YVronLzxo/h4fDM11auLq4oHD+QrI5d9SQEahTo7ZcNSJUiDx90X6KR7n8mBm20OzatUuuPcvVOrjKxvz5882uKYkrcIwePdoQhonEtm3b0KJFC+lC54hnrnTC1UXeBZ+TS+QoFAkJp3D4+OOPUbJkSZQuXRpfffWVIa8yI86ePSuXKWSFN7HYt28fPvvsM7lqEJeQpN3eu3fPeDY6XMGISyoePnzYeMQAPSP9+/eX+bZCYS5QwHHgBtez58Z0SoGXPXt2OV8f1+TlVC306nFjMzDzCX2kb3xjOYLPioN2I6TA00VbYGAgQtl+Ls4FBQfLzMTB3RETR07A2o0/oEyJ0qhQsxL2igzHzs5eLtAfEmpobw8NCxX7gfKzOUHXMEVNjRo1ZF+AVq1ayfVquX6tOU2+TAHF5c8Sc3oKLq3GdXY53ceFCxfkOr1OTk7Gs2/C52PtiwXvh5j1XJF84MjkJk2aoGLFihg2bJhsvpk5cyaaN28uRzyaCxRSFFX60ouJAfswde3aVS6beO3aNaxdu/at84qyUsflHrkuuSlcTpLrgKs+ZQpzR+/Tp09LxcmY2Z+PXj4277JMSqjyyHIEX3Ak8uXKi59WrUe5EmWBsEisWrgC3dp3BfwiMXboGEwaPRHwj0Czz5pj96ZdaN+yHb5b/C0mT5gKRxs7LJm9GD069wB8ozCgR38snLVQKL/E81C9C9aEuRbupk2b5BQuTZs2lS5h1hQocM6dOyevY+2c07ywlsA1d2/cuCGPP3v2TPYfoIewZ8+eaNiwoVySjV6wLl26yH19fV/WRkaNGiUzUtaceS/OJaTDPgYDBw6UIlqHYpRCj8/BzqoXL17EoEGDXnkf6Ymkh4MFHz2AscF34TPq+Pv7y3vo78Z5i/j+9MrRy0lvAK8hNJa///4b169fl9MF0MtHARjTy8cClmv0fvnll3L+Qvax4Lq8CkVCwGadGTNmSCEzYsQIabe0P9oWO2ufPHlSXkdvH4XhRx99JIWg3qzDJiDaFoUY7b1+/fpS9DB9s5Dg9BVbt26V19IWaD+0Y+YRtFvODajbIG2S08a8ePFC7pNJkybJPOHKlSty3W3aD+1DrzjzGH+T/Y+4Hnhs0CvBd9M9+izUWCHV343P8NNPP2HChAnSbpmn8L3I06dPpWeR+RTzLT4b19jmdFWm8B3u3LkjBTPX/tbDh+FGG69QoYLcVyjMGXrx6PnTJ2im8KPN0mYSuqXJcgRfeBQ8PdOgacvPkCFjFiAyCvU/aYjipUqJ3CcKlatXRbWaNcRxTeSK4ShfuSJ69O2Fug0+EgqAzb4a6jdqgJKlSwNBkShTvrzhXIT5NJUyw2RzBjdTSpQoIYVbkSJFZKLhCCC6jitVqiS9lsz09T4DzLzpQmYTNmvxjRo1QseOHWUCtLW1RevWrfHw4UN5Le9BbyIzfjYdUwAysyV3797Ft99+G807QY8aM3jWTjJmzAg3NzfkzZtXzi3I71Hw8dkzZcqENm3avNEsQ7g4Ne+jw/fh7zCjJ5yfid9lbb5y5cqyEO3UqZM8R9FLUUqvYq5cuaR3r0CBAm94C1hA8H1YaLKwTJ06tXx3hSIh2Lhxo+x+EbOZhmmTdsu0yEpau3btZIWuvMh72DTJ669evSrth809vXr1QqpUqeTE1RSNtANPT0+4uLhID//Nmzdl2l+zZs2rJlLei3OdsnJDHjx4IO/Fio7Ohg0bcOTIEWmvmTNnhqurq/S62dnZSYFGsUrPJOdNZF7BimdMKMBoi7rg4/vwOfTKJgUln5e/X6VKFdmfiXkNocDknKx859y5c8sCkL8fc2JuNvPyfszfmL/8+OOP8jjzIopDNpMrFOYO0zXLVjo3uMQa5zOcNm2aPEdPX0JiUU26oiQHXohaKWum3PcRf4PExrcUIk9uusefn5+LzVdser8PftavDzSeM6MWAmaWnMwxNijeKGzYTHnw4EEpjEaOHCkzVn0CSJ5nJk6vFz1kzKDZBMLmYWbsFFbM7Fnb5rUsaOghpFBjszHPsymFz8HCgcLOdKJoNsmQLFmyoEGDBnJySf4WPQfMnOmdo+eABRALIhYkMaExsEDT4f35O3oTE2v59ETymfh+fO5Tp07Jc87OzrLw4wzwLAD53vRyxHSP89lZ2PB3WNCxxqVQJBT/ZLe0R9oaPWfbt2+X9krbpL2wskQvAK9hhYSCkJ4A2i3TOtMtPWLfffcd0qRJIyd+pp3QZuhFp83zelagKOoolmijsdkt84EMGTKgcePGUnT16NFDVrJo8/Q60iPHPKBWrVrSex4T3W71JlX+NbVbijl69lghoyeQBRy99hSIrJjRbiniOJKRlU/aLQfUmUJhyPvSG0/BS68mv08hyN9hJU+hSAqwMkfnBgd20LborebIXVZ0EpKkK/io0WLbSGyfY9t0TPdjntf/mgHMVN/WmZpeOHrD6MkrWLCgFFs67BPAzJ7fZSZctGhReZyZJTNX031mvKz90wtG8UdxpcNaPp+BAo6FUEyYGesZPj2L+rOy9s1Cj01JrMGw0zqF6dve5V3oz0v4jCz8TOF7sGmLYaI3G8UGm8QYLsozoEhIaDNv619LO6OXnOKKQovdC3RYEaM9064pyvTaP9M3BZ6+r9sq+yzzHAUUPfc6ZcuWld9nc+677Jb30O2Snn7aLQdx8LfYksCKJH+Pv/M+UPCxj60ObZab6SAL3W55/9jslhU7ViYpVtnsTfs+ceKEPK63KCgUSQWKO3r6aAPsQkXPdUKTpAQfA4bz7LnSA+QhHt1dZF6JsZkJFCZsMo1tRC5r9Ew8bPJhpm0KM1HWgPVMXc+seR9uel8dfmYYs1mI13Kfma8Or+PGAoXHeQ0LMx3um2bg+u8RNj2tXLlSLhzNJi4KPq4fHBPe17R5lb9leh9+Nn0m08+xYerJiMmlS5ekdyVPnjzGIwpF/EO7pdc8tgoOu0zQE8eF1yn8TG2bdkuBpqd/3W75l5up3XIztVv9HKGN8LdpS/wer+FnHdrI2+yWFcQlS5ZIz6Nut+wWEtOu+Bv8fV1Q6nZret//ards/tZFI8Uiu4ds2bJFVkAplE2fW6FQvEmSEnwULY+ePMbcRXOwavEKrFy2LFE2c4HNlOyXw74weqdrFhJsIvnzzz9Rp04dmfFxpNvy5cvleX5mXxp6+ZiJMsM3zYRNPxN9n6KL92afIl1AshmGgpJ9BSmUWPtnQUbYH4EDJvSChAWMXkDp3kY2NbPfEj2QLOQ4sCMmLPiYget99thcxY7tpk1DMZ8/5j5hgaIXQm+DnenZl5GbQpFQUNTpf/UBRLQPNseyPxybd+i1piec9kbYL40VJPZ3o4iKzW5j22d6p9hjnzh9QBVHA9Mu2VeQ9+IzsPmXcLAFK5G6l5zPpYsxNinTzinyaMO0Wz4TBV9McUVhyLyGfQ4Jm525z++TmM9LYj4/4XvyGWIKPuZ77KPI/EOH3TI48IV9gU29hwqFInaSlOBzsHdAn/59kDF3Jnhk8USqrKkTZTMXKEzWr18vBRH773BQBjuDs48OvXvsVE03MYUZR6+yKadmzZpyYAI7W7OpluJNr/0zk2XTq57Bm+7TS0BxxwycTUv8HfaZYZ8iNvtSWNKryCZfjo5jXx8OxmBmTdj8wz4KbFpi3x4KPHr02JzLzJmFiOni2Dqcl4iFH9+PTcgcWMFmZ71JjCJU/w3CZ+UzE76X/n4MCxYe7Df0tlnLWdCxGU0N2FAkJKzE0G4fPXokbYV2SztgpYziiSKG83JRmHE0LoUZvVespLEvHdM3bdfUa0c70CtUMe2W4ov92mrXri29i3r/WTbrUrRxKqdmzZrJfrT03tFudfui7dHmaTcUXTzPvIX2zIre5s2bozUX67CJle/FjXbLCiD7Ler3ZbN0bHbLZ+dn3W7Z/5YikaOCTUfy85nYzMuw0WEYMi9i/yfVD1eheDdWwuCiV7uMmNbgaOSxFc7/BdZmWQtlB35zx9zCghkjn4Pt/mxSZWbLJlNT6PGj942j7jgVCmEGy0EKFFwUj8xo6XVjJ2juM0P+448/ZKHAzJ4dtNlhm4UIvQJ8b9OO1Ew6bKJlRkzhR48fPQl6Eylr35wKht9jHyPW+Pl79DJwUEfMZ9Zh4cYmJD4D78sRgOzcSuHH5+OoWr1zK8OOApjClr/Pzxy9y9+g4KTYY8HHQi0mFJN8b3oyFIkHR3tzHjqKckuC6Y193Ph+sUE7+vXXX6V3nqKGHvmY3mVWQuh9o1jS8xmKO9otvWwcWMH70I5oZ+y7RjumXbDyQjtjBY0DP+i1o/CjeKLtmMLn0G2TfVlpa7onnlND0K54jpU1etjpiaT3kHlNzGfWoahjfsDnoSikEOPz0vb4/LwX8xZC8Uu7Zh7DvIUj7PU+wmwpYN882jQFIOHULbyeHk/TChqFIJ+PNh7TK6hIOBjXHBDEqXdYoYlvaEd6+idvkSmK94WCLzZ4St+EuDAejT9ERqQNGzbMuGfeJMew4DMJkaUJwzMeUSjih5EjR2rXr1837lkOQqhp48ePN+59GIR40nLlyqWtX7/eeEShiH9EJUQbPHiw5u3tbTwSv2zZsiVauauIH5TgiwPJMSxEDVyrVq2atnfvXuOR2DENG7WpTW1qU5va1JZ42/ugfOCKWOG0D2z2YfOoQqFQKBSKpI0SfIpYYX8YdvLWp1lQKBQKhUKRdFGDNuKACou3Yxo2XASao/T00YMKhUKhUCjiBw6c4jREHCyj8xYJFytK8MUBFRZvxzRsOCqXI+sUCoVCoVDEPxwxb1rOvo/gU026inhDnw9PoVAoFApF/PNfylkl+BQKhUKhUCgsHCX4FAqFQqFQKCycJNmHz9fHF/fv3oaV+E88qPFowlGoaFHjJ9WHLyYJnU4UCoVCoVAY+C+rkCRJwTdw6FA88A+ERyoPaFFRxqMJx+LJk4yfzCss1n6/Vi5f5GhcoPxDMGLUSOOn9wubGzduyOs5opfLvzVv3tx4xnzgEk8cFWW6YHtc2L17t1zijUtMES6FVb16dbn+8H9h586d8l5c3kqhUCgUyY9kJ/h6DRiAut17ysmBw42FakJS2ev1WoHmEhaBQYH4snd/tG/eDilcUiSK8I2NwlWKGT/FPWw4fcuyZcvk+ric54+ilevZfvvtt2+s+fkh4TqfjRs3lgvYvw9cE5Tre3LNYgpaijQKwN69e0cbTv++zJkzR97ryy+/NB5RKBQKRXIi2Qm+fkOGoGLLNkjt5fXKi5KQ1M6W2fjJfMLCP8AfU8ZNwvhB42Dr5AB8oKnvrDzeL52sWrUK/fv3x9q1a/Hxxx/LY3x/LvCePXt2bNiw4dXi6Fwg3tvbWy64zoXiyb179+Dv7y8Xl+eC8fxbunRp+Pn5yUXf9X3C+/r6+kphyXNcsJ6LrOtcvHhRTjCdL18+uc9rKT5LlCghvXvNmjVD3bp1MXjwYPls5OjRo3Lhd+6/zWNHwde0aVP5njpcVL5169byLxfNJ1yAnEPsw8PDUaFCBaROnVp6Pvkupve+fv26XEDf3d1dXpsjRw55/M6dOzh16pT0kOrvrHP8+HH5/lmyZEGpUqWMRxUKhUKRlPkvgk8N2kiiUJBHiYimaEBIlNjC328LFUI5VKjEV5vYj+06bvq1sZ17D0JDQ7FgwQKMGDHildgjmTJlkom4Y8eOcp/Dzjt06IAWLVpg9OjRsjl0y5Yt8tzWrVvRsGFDdO3aFSNHjpTNm/QY0nvG+3J+IopnwiZQGgabi4cNGybv+emnn0rBSMaNGye/q3Pu3Dnp0Xv69Ck2btyIhw8fSoF26NAheX6IqGhQBPJ7DRo0kF7K2GDcxKyI8Hc///xzrFixQu4/ePAA9erVQ9++fTF8+HApAins+Ax8XgpdQmPu3r27DJ+vvvoKo0aNksf3798vPZDcZ1jOnTtXHidjxoyR78HnbNSoEebNm2c8o1AoFIrkSrIWfCxMbWxt4ezqGm1zcHTkSXne3kF8tkQcbQEXm9ebq9h3sBPvbTyvw307cc5JXMNBMnGvTLwBhdSzZ8+kNysm9FJRyNG7N3PmTGzbtk32hfvrr7+kmGOz6vPnz+Vyb2wu/eyzz3D69Gl5nIKJwob7FIIrV66U93QVcXn79m3p/eI5zlB+9uxZzJ49W57nb7GPng6FGj1+/Dtx4kTpZaOgatOmjRR+FJ30OvIeFITTp0+XnrTYiK3WpTf1hoWFyftnyJAB165dw4ULF6SA7NevH6pUqSKfiYKOXLp0SXod6TFkcy69lBSTFLcMLz7LtGnT5POx+ZiTX69fv16GHc9RKM6fP/+VaFUoFApF8iRZCz4WrP5sxjt7BpfPGLZLQmA8eXAfzm5usvB/dPeO8WoLwcYWkUKMjBg7DDXr10DVulVQsVYFtO/UFs+ePjEIQUch/JyNW1o7LF29GC3aN0dASCDgKY6xyZWCRoTP+0ChQiGkN9m+DYqdnj17yqZcXkvB5+LiIgUMv1+sWDHpMeM5NlcWKVJE7rM/YPny5aUnkU2f/Js/f37Zb47nsmbNioEDB0oRRHiMcayjCz6iCz/9WXfs2CEFFcUTPW5r1qyRXrojR47I83GBYs3JyUl67ygc2XTLd+O7snmZxyjqKF4p4AibyYsWLYrcuXPL9+H32ZRL7yOfg89HzygFMtMz343vvnTpUnmeTeh8Tt5boVAoFMmXZC346M07cXA/utathU61qsutc+0a6PZRXRzZtROuKVNi+bT372No1hiddPv/OIADhw7K/mhPHz/FN+u/Q4deHREWFoq7QuTeunEDF86fx6k/TyGNhxeK5isCXz9f/HXiNAIC/IVashYC7v2adFOlSiUFC/uWxeTly5eYMWOGPEcR4+npaTwj9KejoxR8gYFCcAqcnZ1fNZmySdve3v7VPkWRLtoo0Dw8PKTQ0kkp4lQ2gxsx9fDxOoo8HYpLCjCi/w7vSXiOTbxVq1aV+3HhvAhP/j7vw/tRcPL+vCf72tHrRw8mm3T//PNP2Z+PfQbZPEt4HZ9Pf37T92KYEIYR76s/J8OFIte076JCoVAokh/JWvARFoyREZGo06QZ+k2ajI6DhyA8LAwLx41BkL+/KDANBaelQaHxRcduuHrzGq7dvo7+3ftiz8E98HnhjbFTxqBEtVJo3LYxFi9YhJPnTmPHgZ24efMGqtatip9+/QnwssXO/buMd4sbFDvsd8Z+cxR4prB/GjcKQg5e4GAGHQ6g4GANDr5gfPHZTZtM+dl0X4fCiqLJVGDS06UPwKA41EUk4bUUU7ro429RaBIOmPDy8sLXX3+NxYsXy76IJUuWlAItJnwWXYDpsDmbA1XYV08XofzM+/B+kyZNks3a/C5H93KQCgfx+Pj4RJuGhc/E56CQY3MwoUePnrwXL17IZmLeX39O9mcsW7asDHuFQqFQJF+SveDT+6TVbNwYXYcPQ4cBg5Atb148ffgQIUHBLL0NF1gYFFZ/HDmE4YOGY/iA4fhl22bkzJYT7l4eCAgKgL2dHX75/mcsWb5EiKBgXL91A4WLFUGFMhWwadvPMtw2/rbJeLe4wwEFFGxsemXzKAc+tG3bVg464IAGeva6desmBR+bJNk02apVK9m3rVChQlIAsSlUF3jsD8d9HX2f5+kZZJ9Bfp/34XQm7IenD3yoVq0aNm3ahKlTp0qBxL6D/L5+b3oaef7EiRP44osvpMBi30E+J5+Zzxfbuoa8B5tY+ZtLliyRoq5y5cpyNHDnzp2loGRTLj2EEyZMkNeVKVNGTkujNyNzgAf7InLEMEUcoThlc3DatGnxySefoFevXvK77dq1k+9Azybv/+TJE9kszOfkPgerBAQEyHsoFAqFInmS7AUfB22QsV06o4KXF+rmzI6/jx1DzU8+FeLHUzaPWRxWgKODI85d/BtTZk7BlK+mwNbGGou+WgQHNycEB4egcP5CyF+oIKwdbGBl7M/m5pJCzvt36swp3Dh2BWcvnDPeMO5w7kT20WOzJQcXUORQyHCQgT5yl82kFGZXr16V5yluvv/+eylo6J2jl1BvimVTKKdO0Ztx2U+Po19l/0x/fymkKH7Y544DJjjKV5+mpEuXLtKLxn5yHNBBzyOFnH5vilN6IjmlC8Ua/1KsUohRQO3du1d642JCjxw9hXxmevXWrVuHTp06yX55FKGEg00odjnI4ptvvpGDNnid3kzLkclsyqXA1OHgE/3Z6Q3leXr26PXjiGR69ugl5D35O3xOehYZtvRGKhQKhSL5kqzn4XNNkQK/rf0ek3r1QJ7CReCVLh0iwsNRvFIlNOvSDY4uzhjZoT0ObNls/Ib5hEVAYAAmjpmAkX2Gw9XJjW19xjPvQAhcvmPV/1VDpiyZMG3qdIQHhMIrpSc8MngBwcD/Pm8g779/ywERSMCg/gOw7uf1uPTnRTnRdaV6FVGkQBHZ1Hv91nXjjRMmbP4L9K6tXr1a9oNTKBQKhSKpw4F5ah6+f0lUlEEodR42HEt27MTcTb+i/ZcDYWfvgPDQMDmIwRLx8fORXr5sebIhd6688EglxF6AYYACxZ6fca46egODgoPw0u+lbNr1yJEK9WrUw7pff0TxQq9X2TBH2EePTaD6IAeFQqFQKJIryVvwWVkh0ughDPTzR8BLPwT6+yHAzw8cgUov52s/p4UgagN8pzrV66BE4eKAv6gdBIkwCA039FeM0lC1QhXUrlpTfkaYhuKFi+GTjxvCztYOCNbQovHnqF/7Y/Ts9H5LjiU2rAWx6VNvRlUoFAqFIrmSrJt0OS3Lvl9/wbKpk9FzzHhUrFsXwcZRm+wTZm1jg4Xjx+CnJUvkMZLkm3R1XIR441eChdCLqWqdxDkeC6IIFH85Lx+7MgaKsKYI5ATN7GoWJi5LlbDphP3T9LnkOOr2fdzXFHrsE2c6yEOhMEeY33KwDwfkcF5FpnVLgn1eOYiItmg6FZJCYUnQjtmixFkWWrZsGU1HxRf/pUk32a+ly9fnZm3N940lcsS52tmzGHcsSPDp8Rtb9Mc8J/fFphmafCVW1nLfKv3rgikhwoZCj4MnOEqWBcX7JG6FIqnA/JYDgpgPcBUVfeogS4Er5nCaINqxsmGFpUI75rrnrNzMmjUrQabDUoLvP8D35EhdNu3GFhT08tXMbJgWg1iM4IsnElrwcf49Dr7gpMQKhaUzduxYtG7dGrly5TIesQy4tCFXq+EyiAqFpcO12wcNGiQXG4hv1KCN/wADi6NW3xZoUR9ISCkM6J4PhSI5wC4MppVtS4HvxHdTKCwdNumyzDJHO06agk8EpOxjl0hbkoSJjXMM8vn5V+83w8/cdKhzrcU5zjdo2rdGflfs85h+vX6dBRZICoVCoVBYMklSzQQFBiIoOBjBoaEIDkn4LelhhSgtCuGRYYCDDYLDgqFRo7nbISwi1HhcCDeKPQ7QsLOGf+BLkRrERc520tsZFi7e294akVGRCI0Ikd9lagkKCRTfpQAU1yrhp1AoFApFkiBJCr5sGTJg1/Kl2Dz/a/y2eH6Cb0kOZ1v8feUCytepgNYdW6J0jTKo/3l9LJg7DxXrVETJ6qVw7PhRwMMOjx49RNO2jVG2VnnUaVoH169dhZUQg806fIZPWjRC7cZ1UKp6Gcyb8zWatGuKwhWLYMnyRYCLEH3id8yNixcvyqXEuGoHV9hgv0Jz49KlS3JZucRs4uJSdVyKjc0NXIFk9uzZctm5d8Gl2/7880/jnkKRMHBVHa58w1VqGjZsiA0bNhjPmA/Xr1+XS0ByNHViceTIETnQhTbLwQC024cPHxrPRocTzHOlIK49bsovv/wi1+p+n75eCgtFJIJY4Sl9E4Wm8Wj8ce/ePW3YsGHGvfcnyN9fC/T3Exv/JuxmjmHhH+CvDRkwWPO/46tpTyM17VHY6y1A047uOCyft37tj7Rf1mzS7O3stRxZs2ub1/+qZc+cTWtY939aVECk9r86DbQKpctrx/84rjVp0FirXLai9vKOj5YzW04tjWdq7Zd1m+R53mvN4m+1lk1aaJ7uqTTfW97a6b0nzSpsli1bpnl6emrdu3fXpk6dqvXp00dLkSKF/H5UVJTxqg/PV199pVWoUMG4lzgIIax9++238rMoRLQsWbJoAQEiobyFK1euaK1bt9acnZ3l9YrEYeTIkZoQFsY9y+H06dPa+PHjjXvRWbNmjebl5aV17txZ2m3//v01d3d3rV+/flpERITxqg8P85cSJUoY9xKHa9euaatXr9ZE5VA7e/aslilTJk1U1IxnozNw4ECZD3/55ZfGIwbatGmjNW3a1LinSGiEMNcGDx6seXt7G4/EL1u2bIlW7r4PSbSDGuDk6gpnVzc5l15Cb0kOY1Kws7GVkyM3avkpMqXPiAZ1GuB/nzWUEymHh4fjxZ1nOHP+DJ48e4rxE8fj4pWL+PPEMVwTtW1X8d7N/tcUjZp/igJ5CyB/rnxo1aUNalauIX8iMjwC635eJz+bA6dOncLQoUPx9ddfY9GiRRgyZIisjXMtW67Hy/M6XOO2W7duGDVqFHx9feUxHx8f6c1i7XjatGkQhQ1u3rwpa/McIcx9vebMucQ4xcSFCxcwZ84cCIGJ7du3y3OE3gr+Nuce0+G9OVJRZODSe8F1fTkptD4ghSOvuL6uyLRx584deSwmrMHzPjpBQUHyfel5IHyvY8eOySkBunbtKp9R2Lg8xw7ETk5OckT4ggUL5HsLcYEXL17I8zr6+9I7eujQIblWsCjkjGcViviFNiQEilzHmmtL025pFxs3bsSPP/4YbVnEn376SdoaR/o+f/5cHqMt0iaEGJLTYPTu3RuXL1+WszcI8Yi+fftKuyNcs5sj/mnHnBWBeYBpCwBtkvbM9bN1OAcoPdy3b9+WeQnth/fVZ4fgGta0W76DbocxYd7D39M9+lwBiB5+evoJ19CmJ49ratNu582bF837T7t99OiRtHU+G6epevLkifHsa/j8DB9OgaPnIcxf6MmvXLmy3Fckb5Ks4FO8G84tGBkpBIXIv1jw23DQRbj4X4g9O1tbkRlEys+Vy1dC+7btMHnsJGzftA2ZMmZGaEjoqwErFAF2HKwh9EtwcJCcD8/axvo/T4kTn1DslC1bVk52aUr9+vVx/PhxOREmMz8WAMyc2bS5detW2YTE5deYCU+YMAGiNiwF2+HDh+XQ93bt2uHKlStS/Hz66adSIDHMWEDx3gcOHJCFTosWLWSGTJiRUzSxGUaHhdj+/ftlRs7fZpjyewxjfo8ZNZts2CRNscVCKyb8Pgs1HRZg/B294GDhxGfie/F9KID79Okjz7HgpMClCOU5hgVFny44dfgMtiJtsBmITeOpU6eWk1crFAkBxU6BAgXQuXNn4xEDNWrUwMmTJ1GoUCGZdzEts2mTlZy9e/eibt26UvTQnlhBa9WqlbQdiivaD+2YYpK2T7ulYOJ9Zs6cKbt7UKjRftq3b4/p06fL32RlbPz48a8qgYS2uWvXLvk7/G3aPkUXbWT58uVykmzeh2Lvk08+wblz54zffA3FHH/DVPBRNFKkkjVr1ki7/fnnn2W+wKl5KEYJxRsFLn+T3+M9+Hz6vXT4fqygMr9yc3OT9yKcx5Tir1SpUnJfkbxRgs9CYUEeKjKniEih8AQhoSEI5brAVgYB5x8YgNSZ06FQ/kK4dOUSSpQqiYePHuLEyeNwdnYW1wfLDIaEhYdJkUIo8oJDgsWxcDRp2EQeMweY2b1tstoMGTIgRYoU+P3336UoWr9+vaxNUwQxs2bt28XFRRYIzHjpIduzZ4/sK5MjRw5899130oPHcGMGzPDhteXLl5fCiDV/9q3hRs8DM1wPDw8pjHX4+/xOvnz5ZD+bkiVLyoydmTF/n54HPtu2bdukV419bmLCmr7pRJ4Ui/wdfVUG3p8Z+6ZNm+T7jRs3Too/wvfjc1P4cn6oLFmySC8DBZ0pvD8L17x580rPiCooFAkJ7TZbtmzGveikT58e7u7u0mtNrz2FEb31FFC0Ldob0zSpXbu2tFv2VaUgSpMmjbRbijVee+LECWk/hB5r2i3vR9ujHdDWaaO0J9OZGXS7zZkzp+xjSNtkZe/x48fSG0hBSFujp7BixYpSMMaEK/7wPfRpOviX+3pFivtFihSRXs3Vq1dLccg5Cynq+H7cGEa0S9otPYDM00yhWGV+zXyFwpN5AKFHkvfPnz+/3Fckb5Tgs0Q0wEGIgKwZs8DZQWRyIsPKnD4TUrl7gMuppfFKAy8PT1jZWGPxnMXyK1WrVcG8xfORP29BODs6I0PaDEglMj9Eies90yBjepHBiPumcHVDloyZERYcigo1KsnvmgPM1GN6q2JCDwA9BtWqVZP7zHAbNGgga+XMLJkJ07NAmEkzk9Wv5T4LAzb9spZPAUUPmE7jxo1lrZ9ehbcti6Vn+PSiUTySGzduSNFH8cfMunTp0tKTx+aZ94XvX7VqVeMekDFjRvmcprAQoZePwp0exrfB92R4lSlTxnhEoYh/aLcxvVUxobebE1HXq1dP7vM79OKdP39e2hIrWLrd0vayZs2K6tWry322THh6esr0zDRPO6ZXT7dFDhChoDpz5kyc7Ja2T2izbOal+NPtliKNx971PjHhc7HJle9FKHTZpYZCU4e2/U92S29hpkyZ5PtS8NEjyKZrVlDTpUsnhatCoQSfJRIUgaIFCuPUwROoVkEIltBI7Ni0HUP7DgF8IzB/5nwsn7cM8A8XNddc+P23Aziy+xBO7juORp9+AhuRz/y2fgtGDhoJPIvApJHjsWnNRpHjRaBFkxb4fftBpE+TDnhpPk26BQsWlGIrNtisyZpzzEyUcF/P0Fmz1zNrZqzMZGPu65kyv6N/JryPfi9ex7+mBQjFII/HhPenV23AgAGyyZUztPNZ2c8uJvw+76PDwovPrL+T/ts6euH0b6Dnhb+lPAOKhIR2yy4TscH+rOyHGrPSQmLarZ7uaae0Kd1u+Zfn3ma35J/slgJKty9TeF/mJ+wiotstm3jZD9HUQ0h4LX9TdosR0NPIfVO71Z+X6JXB94GtFQxLwoopPfP07rO7R9GiRd94Z0XyRAk+S0RkJLY2omabKo3IvNhsoMHD3UtknG5CNWhI4eYuNg+R04hTgeGwt3NCpoxZ4eIsaoFCBBIPd0+xb7je1cUd7ik95X0cHZ2Ryj21IQOJfDMj/FCwmZR97+gpM4XiaeXKlTIzpHePonD37t3yHGvK7BjOJh49A46ZuceW2VMIsSmYnch12KzLe/A3yNOnT191rGZNm8+mNykxQ9eFG5uMmdnrNXN6CundY9/AmNAjyaXm2JeI0BPIJhvTAiq2540JC0Ve90/rPLLZjJ4RehsUioSCfW7ZnMrBGqaih90u2IzL/n20XXrC9QEW9LTR3ihkaDcUanGxW9onu6aYTvlC+6c96AOT2EeXzbWEQpReRFasCO1WF3P0/uuCU7dbfo9dQfTjOrRb2im9jOTgwYPSE/i+dsvw4bvG9NYxPNiHkGGlwz6M9Djq/SAVCqIEn6XCDCRUiDdjzRdh4rPI2KTIo+dH9/5wP0J8DjE5Rkyv53nuE2bK/ByHDCoxYZMPvQEcsVepUiUpANmxu3///pgxY4ZscilevLgcBff555/LQRZsRmEzCAdMUERx8IZeu2YGzL5A+j4zWu7r/Ropltgxmk1CTZs2lesgs/8O105kfxwWRvx9dibXRah+L4o81sg5Lx6bXekhYP8g3od9CEePHh1rvyaeY/MT+w7y+dnvjwWQfl824+hikPBZ9Q7o/Kw3a1HE8TMLWwrR2KDg4zOoARuKhCRz5syy790PP/wg7ZZChYMqaJMcRFWlShUpZDj6ljZN26Xd0v7oXaOA0wddEdot7SCmHet9kPk99selLTVr1gwjRoyQ9pc2bVrpzS5Xrpw8R7vlOdq9fi/aA5tOaasUXbR3PgPFHgd46X1jY1KnTh3Zp5DvR5tjvz+KQv2ZWfFkBVKHv8dn5rPzM9+Pdst70L71ASk6FKYcnGHa35b9CdkEzBHGfCeFgtiIwii6S8QIO3zrsHBhJ+74hImcHWlr1qxpPGK+mGNYcCDF7wd/R7VyVUUtV9RAqb9Ys0yUTfyWjS2QwgbjJplP2HBABJ+BGT5hYcKO3czACTNZZr7s8EzBw/5u7ADNJiNm7BzAwJG++oLXLBz0fX6XTSUUW/TOsUM4RR69YBRd7GitPyM9Aqz1M5OmV4HNtexTxLChwGTBwnsyQ6cQ5XOwHxA9BOxvw5G4LOhiwt9nwcL34+9yWhV6JliD5/3YxMT76YUOvR8Ul7w3vQkc1EIhyvenQGaBwHNeXl7yelNY0LBfFPtDKRIPem2LFSv2Kg1aCkzbrFyY9jHV4YAICiymR9oE0ydH3jZp8npQGNMiBRc9cLRBDrRgn1vaLcOKdsp0TDulGGPfUz1d8zqKHlaWOMCCFSrmDfSY0YYpMAlthHbLZ+BGMcdKW+7cuaUdcMAT8wjaNe2MwpP35bvxt5gH1KpVS97LFD4P+xxy1D4/c9Qtn4+eS96P+Q/Fmj7ojPkL35W/wWeiPTNNMG9gHsdw4j4FIKGY5fMx/9FbDpjv8Hlp33wH7isSB6YPttBQ4OutOvEJ7YgVJJ23SLjYEQk7VnhK3xJiQt27d+/KSUaTAgkdFv9m4mW/AH+tX8++ms/tF1rE0zAt/FFwom2RT0O1l7d9tL2/7jHLsElo7t+/r4lCQNuxY4fxiEIRPyTHiZcTi6dPn2qisqVt2rTJeEShiH+CzXjiZSv+I770Bqb9ENh3gp6F+IR9GqhMOaFtzE6u5obeGZYkVFhwegDWNuMK17gdPmQ4QoNC4CpqiLHHYsLAWue9R/exYtUK4xED5hI2CQ2bT+gpZFOx7h1QKOIDNi9yFCm9XpYER4tycnG+34eCUybRU0gPH7tPKBQJAT2unByb0+iwVSa+oR2ZlrNvkXCx8sEEH5uMWJDTCE07r5ojjDwdcxI1HIXp+9LX0MSaiFhZWePypUuG2dtNUk9yEXwMd3Yi1+f3UyjiCyX4Eg42tXFwA5tG2cyrUCQE5iz4PliTblIiocPCHJst3wXXZrW2tlZho1DEI6pJV6FI2phzk64apav4V7C2rFAoFAqFImmgBJ9CoVAoFAqFhaMEn0KhUCgUCoWFowSfQqFQKBQKhYWjBJ9CoVAoFAqFhaMEn0KhUCgUCoWF88Hm4UtKJMYk1OY219y7+Pvvv+XyPlzaSMecwubokaO4cOkC7GztjEeSD4wTF1dXfFSvHtzc3IxHPyxPnz7Frt27EBEeEc2ekgsc1c7ls7i03T+h5uF7ze3bt3Hg4AE5+URyTDNc+o1LttUTdmwOc9UyDe/atQuPHj16tYRb8kITeasm55/l0pRvw5zn4VMePoXFERIagpXLV8A21AYp4ALXKOdktbk7uWPP1l04fPiQMUQ+PNu2bsOpQyfh7pgy1me25C2ltRuCngfim5WrjaGhiAvr163HrYs34e6Q/NIMN9rKz+s24cLFC8YQ+bBcv3ED679bJ+PDLZbntfQtpV1KPLh+Hz98/3od26SG8vDFAeXhe5NbN28iRwwvhLmEjX+AP6aMm4zJI8R3nEXcRRpPJAfocHUBVi9cBfeMHvik0SeG4x+YZcuWIqN7RnzcrD4QbDyYXLAHfO4+x6ylszFxyiTjwdhRHr7XTJsyDXUq1UbxyiWSX5ohTsBXE2ehXK3yqFCugvHgh+PM2TPYsXEbho4fnmzj4/Lxi9i06xcMHynC4C2opdWSOOYs+Hbt2o0TJ0/AwcHBeCThoTuf68kuEM8cHBhoPGo+YRMQGICJYyZgZJ/hcHVyY9uI8cw7oCUwqt9mP6+TwWtMr43t/D/xX777NnhPDzssWbgY6XNnQMP/NTQc/8CsWLEc7rbuaPJZU+BluPFoHEms+CD69+MrPoi9He7ev4WlPyxXgu89BN/0adNRoUh5VKpUGQiMpzRD/ind8Bw/v0/8J0SaISnsMG3aVFStXw3lypQzHvxwnPv7HH794WeMGjbm/eODvC1O/ik+yL8J1//6/dhwtsPJk8ex++heDBsxzHjwTVSTriLBWLdpI0LSZYBD3vywyZknUTYta3ZkqVINy3btMT6FhaBnDO52QGqTLZXYbG3ezLC47yrOeYrNWnw57nZnuNZGmJ/IROK9oLAkGE6OIoxM44Mbwy22+LAR8eT1lvM6/3TcSXxPCLS3XqMwfxh3tEfarWmaERUhWAubixm33E9pPE/exx75XfZnY3pTvB2GE8PIND640bZjiw/aIO3YIZbzcYG/lSz7Gf4zSvAlcVK4u6Ns5SooI2rBZSpWSqStMkqULY+sufMYn8JCEIVBlMhdvv/mO4wZOVpuI4YNx9KFi8VRkevYCTFBQWEjMhJubnbYsvkXjB8zFkEhQQaxQG8wMyj+ZYaje4d5vZ1JJmQrTE8UShf+/ltcLq7hdfI7KqOKhqMNzv99FhPHjJfxMXrEKIwR24Xz52T4i0AzhBfjxcUOL3yeY8TQ4fjj94OG8wx3HT3uiB7WjBNdBAjxfvfObTx6eF8UNOI6HtPjjdcokgaichYcEowlCxa9tuOhw7D22+9leoKNiHvGK9MD04AQB9+sWoXZM2dBLjZKkcH08cqOjfuEaY3pgd/neXsbhEeE4tL584ZzxErcRL9GYUCE+9HDhzBu9FiDHQ8fhQnCpu/fvyPt1hDOxjgRdnvr1jUMGzwE5y8Y7ZzHdfS4Y/jTLmW+arwHj4n7Xb96FT4+L0T8GOOA9zaNx2SKysWSOpqG4KAg2bQaHJS4W4j4XYvC2gaRIsNYsHwhxk+bILfJM6eg25dfYMi4IYiy0RChRYjrDH8DQgPw0vclnj95huDwUIREBBsyFOYpNtYIjQxFWES4LFCirKLgH/QS4VFhhn1HK0yYNRE9BvdEkFWoIWNythX39EeY+J70HCbzzEniaI2TZ09h1OQxMj4mTJ+I8WJr0KIRLl+4KES2KHCjRBiL8GZ8BArh/fTRYwQEBIg4CTbEl4wTKyHmoxAcakyzTrYIFGEdEOIvC22G97Wr1/BRs49x+NRRET8iIYhjUVaR8A9+aRAKyvOXNLCzlhWwKV9NfW3Hs6aiVbfWmDt/tohLW4MdigpXWFSoSAeB8HnhgxfPnks7Do0IMbFjG4QwHUWKdCSEBNMa7ZjpQu5bR6LX0D4YM30sQu3EPSkWRZr0D/ZDJAzfUYiAFHa85/e9GDtlnMGOZ0zEaGHTTdo1w5OHj6DZWwlbpR1bSZsMEOXZk4ePEcSyLTwIURq75Yj7CIHHcA0OFXkt80wHGwSIsA4Uts94pTg8cvgwPv6sPi7fuSruK74m7Dg8Mkzc10/msVL8JVM7VoJPoXiF9LVJWjT9HI9vPZKjslo1bYmFKxYJYfdUZFKjUbVBNVT6qBJ6du+BF94vZOZzUdTwy1Ytgx17d8imipN/nUTZWmVx5u8zOHP6NMrXKY+K9Sqh6sfVcPrUSfx14pQQLuPx+9E/0L5LO1nITJ42CSUql0DZmuWwadMGUViIjOnVEyVTRMbMPrSpUnrgzz1H8OTOE+zYsB23793Gtp3bpIe0soiLj5vVQ8WqFbF33x5RAAQiUgjtYYMGo233toaCQWwde3XCoNGDEKSFYcDQL1GiaklUqlsJw8cMRVh4CIaPHYKL1y6hz9C++GPvQVy6fFHcuwpKVSuNrj0746W/ryxgFGYOC3ORZmxsbDGk3yCRZh7jzuXbqFKuMuYtmw+/F77o2r8ban1aE+VqlcPokSPgH+gnKlphOLB/H0pVKYVz9CwJO96y/Vdpt/cf3sfunTtRsppIMyJN1PqkNu7cuY3t27Zi6bfL8Ov2LRg0aCCCtUD0HdgbpaqWQqV6lfHHwd8NlbfkXlEwvn/WjFlw5fRlGSerF6zC8b9O4Ojxo8Ju96KisMU6jeuidp3aOHPuDPwC/KVjoX3bthgsbBMpbRESFoqGLRpizuI58A70RtsubVC6RhkZR18vmIuQwCD0H9Yf125fR9tu7XD98mURBwdRtnY5lBRxMnyUsHWKfVEpSI4owaeQsOOnnb09UqZKFW1zc3eXGSfPO7u6vnHeErEWtUh/fz9cu3kdN2/ewnPv53B1cYWTs7M4dg2Hjh1Ctw5dMWr0KNy8dwu/7d6GrDmzITw8Aj9u/knUUoH1P6/H/Qf35Ujm3ft2o3b1WhgxYDiu3riKYeOHyXmcypUqh7w582D4iOFYtnIpvlrwFeZ9NQ9tWrVB1z7d8PdfZw010mQOBV9kVBTu3rsrw59/SSqR/jhA59jpE0iRIgUWzV+IwoULY9PWn/HE+xmKFi4qCuLNePToAR48uIfvN3yPAnkL4O79O3jy9DGmTZiGwgUKY8rX03DmxF9o0qiJyBCtMKD3AGTJkhkNmzWU91u1ZBV+P/IHxk4eI4SjyDLp/VGYPdbWVvD29pZphrMK+L70RcoUKWHvYIe/L/yNv0RlbMSgEejTry9Onj2NvX/sR8FChfDw0UNh01ulHa/8YTVCQ0PgmdYLew7sQZvP26B3l574Q1TUpsycgnJlyyFXtpwoW6oMevbuhbGjxwqRuAXLFy9HhfIV0aZ7Gzy8+8DgfUrm0I7DIyJw69YtGScPHopwEXh4uMPb54UUf/nz5MX8eQvgldoLG7f9jPCoCJFX5sG6TesRFhiKM+fPYJuoVBcvVBwX/74Aa3HPGRNnIo1nagwV+eqjBw/xyf8+gZ0os8aPHIfAkGA0btNEHls0bxFWfr8Ki5YtEPlq8qy4KcGnkDg4OeHi6dOY3KcXxvfojrHdumBs185YPWsGIiLC4SjO//LNKkzs1QPjund9tVkcoixP4ZYCv+3chso1K6NyncrYuW8XRg0aBbfUKUXmH4ZKZSuhQ9dOyFU4N+zt7GFna4sM6TKie7uu2H/kIPxueuPPU3+iTbNW8MqVBiWLl8TV69ewdt1aOIlwfOHjDTfXFEiXNh3SpEmD4mVL4A8hKFh7Xbh0EbZu24oXL72x9+BeETHG50rGONg54KX/S3zW4XNUql5JemcqlamA/zX8n2zycRBx0LdLH1SoURGeqbxknHDS2hbNWyGFqxv2/74PJ0+fRGqv1Gj6aVNkyJwRGdNnwlIhsq/fuC4KDWs893mO3MY+qTUrVYevz0tcv3MDZ8+dxYzZM0WcvcCWHb8h1DfY0CSkMGsoBFhJW/btCpFmKqPaxzVw/dZ1jBw4QuRlznJy8ga166NJm6bImje7iFI72Ih0kDVfDrRo/Dm27tkGvxveOH/pPLq27Qq3TO4oXaI0jhw7gl+2/IKUKd3x+NljpEmdFh7ic/as2ZG3QF4cPPy7FBlfzf0KR/48gjsP7uL48WNC8KlKgrMI94dPHqJek49knIyYNBJNGjRG2coVEBgUCFdnFwzo/iVKViwp7DaFFG1swv2iwxdyqq2Tx47j6PEjKJAnP6rXrI5cOXPJey5ZvhjPnj8TlcJI2RScJ1du2NjYoF61urhx44aw7Rc48PsBfD3/a/j6vcQvWzcDYeKBrJOf6FOCTyHhtC63r17BL6tX4bc132HXxp+wbd0PWDxhPJZMHC+9f4d37cTmb7+Rx3f8uB7b160zftuC0CC9RlUqVMYP36zFqkUrcXDLfvTs1QsINXhC6QFEgLiWmYbhKwgPC8f/6jVEpKjBzl44B4+fPkG75u0Q9DgAHft0kp3IFy9agk8+/gRRQoxoosDh8H05pD4SCA4OQfYs2dC0cRN0bN8Rm77fgP/VrQ/4v17JJLkSFhEGN2dXzJkyG2tWfIe1y7/HlrWb4Zk5tQxDxkd4eLicgzAyIhJW1lZy3zGdE2pWqYEfNq7HD5t+QK0qNZEmTzpM//YrLFyxEN07d8eK+cvhIgoNWxs7sC8sB+cwbkJDQ2EjCoS6Neug8aefYtGchVg2bwls2SE/rtP8KD4YtCtWBpo2amKw44Ur8fvWg/i0eROEBoXIa6ysRIHPLp3GLntRtEWRhj5r9Jlswp2zaI70SrVo8jnunruNTn07w8vTC999swZlS5ThjyAqPFKmFX5mlz1O+l4oX0E0adwUfXr0xi9rNwmhWAoIVGmGeWBqEX7Lhc19u+wbbPjmR6xdsgaOKRwRFhou7NgGoWEiUxVxQEHOsA8NCUWmfJlRomgJLP9uBbbt2Y7G9T+FQ2onjBg3Ar/u2ILBgwdj5sQZclUlThlG8SijMlLksSJfdbR3QMOP/ocmTRrj++XfYfKYSSKiRHxoyS9vVYJPIWEGacOpRwQTVqzCny98sPPmHRQsVUqKP9/nz4UodETazJnxy98XcODhE+y+c09eb2mwNplf1CI/b9sC7Tt1QJUa1URuZSgMwsLDDBk8EYUEmyi4T7GQvWhOVC1fBeNnT0KmDJlQrGQJBPkE4rn3C2TLkhXPfZ9jw+aNsBcZkI2dnWxeevjoEe7euYMK5crjzt07KJCvgPQW/PHH79JTpSxU6GwWAiIc2n7WGq06tkaLNi3h7uEpC2um22BRyNKjx/jgPgtdxhPp0rYL9h7aJwuG5p9+Lo/5X30hC5PcuXPJZl7/oAARJ3ZI4ZJCivfjZ04ic5ZM8EjpIdNCzTq15GoHjx49ho2ziBOWJgqzhuKNcVe2ZNlXdlyyTGmwohYlCvrQsFCEiU0nTFQQQkWa0YIiUblqFeTMlgPjhB2XLl4aqXOnha+3j+xTlj9PPly5dhl7f98HJ0cnWDvYSm/9zds38eT5E9m0e/3mdZQvUw5ubq7488+j0gslFWUyh5UzZ0dndGrTCW06t0WT5s2E3TlKwU2Bx/NyqU6Kb/GXA95kHAmT69yqI1at/wZnzp9Fk4ZNZV789NkTODo6IH2G9Fi1djUCgwOl4HN3cxdxGYrjZ0+gYKEC0lxp79WqVcex48fg7+cnB5EkRztWxYniFVb0Xgj+OnwYW9etw64NP+Lh7TtImcoTdkLsWVlbIzggAPt//VV6+HaKzfLQRC00tagVioyIs8k/F9V2v/BXmYOnRypZS5XKQGQ6bDJMlzqt9Awxo2omMiM28bT/vB3gYAWvDGkw8ssRWLdxPTp0aI8yJUqLy6wQ6O+PVk1bIEjURrt17Ipu7buhaaOmaNC4AT5r/Zmo7drCw0v8DocNJ3OcnZyQziutyKj9AV9x4IWIjzCxCSiKM6XLaBDHIj7YlJMhbQa4OLkINQ7ZT7J4oWIoUbgY6lSrBQQCuy/tR47sOVH749q4cvkKCuUrJPsU5S9SEB/VqIfRk0bj73N/Y/3qddj46yaUL1cOW3dsQ3bxHcaxEnzmD5vp06ZJK5tpKShkmgkwpBnaH23cXdiptGOxebp7IE0qL+mht3KxxqcffyoHCnVq2VF68vMXKii7DUz+agoGDRmM6pWrwU/YMCsY7Vq0FSLwKoYPHIpJYyejYP6CqFqrKnr07QkPd0+4pkyh7Fi8vpvIKz1FWRLoIwTXC3HMW8SHCG9CUZwxfQZhvyK+hB1z7eAMadNL7xw9p3Wq10FOURGuUak6ihUrLit7g/sOlt/lII+wkFDZH/rmrRuoUqkKShUuga59uopwt5Je/GlzpqNS5Yo4ffY0sor7yHhPhqiVNuJAQofFf1lpo9+QIajYsg1SC3HAxa3/La4pUmDrD2sxsecXxiMG0mTMiEEzZqFK/foY0b4d9vy8yXjmTZL8ShtGngf4wE4IrpQuIqOOZh5W8An0lZl8KjfDDOp+Qf4ICQ+Bl5unbFqM1CLx1Pc5Uqf0gi37iDDt2Nng/qO7cLRzgJdnWjx68gBeKVJJEf3o+UNZyGRKl1WUUhru3L8FOyFeMmTKBISKnC/c4LmKM3xcS1ppQ4QfR0H7BQeIMPaAjYiXV7m1OEdPjU+QL1K5eEjRx+kzXvh7w9XRFS6O9KxYwyfAW1xqDXdXUcBHiPB0skOA30s883mO7BmywS/QTzbJe3qlRpBIO099nsLT1RNuadzx4vFTvAx4KeInE+xdnETiEs/+PvFB1EobibzShpX04j0X6cDZwUmkBSH+dTsWaUaL0vBCpAlbG1u4u6SUh30CfOXAIE+RxtglgB4/b/H9tB5pRCEpIpzzZoo/dx7dkd9J6ZYSD589QnqPtPL6+8KOrTVrZMiQCZHhYbgr7N3FyVXkn+kMzbn0XL0vlrTShgh3jp4PCg9GatdU0nlgGidBwsb9g/1F+KeS8UIPvXegD9yd3Q2iT1z//OVzmYe6inCVAtrZFj4vnsM/0B9ZMmSHt+8zKfBTCpH90s8HPmJL654GTqlc8fjBQ9mknD1jNpkfiweR8fleOKuVNpI8wcHBuHL1Ci5dvoTLVy7HuiUX2LeMdB46HEu378KcDZuwYPNWVP6oPoIDg0RCDoZX2nSY98tmfHvwEJbv3iuvtzS8UqVBypSpRIDENCRN1Ni9kCpVakNmJc6ncHNHmtTppUeB+xQk6dNllH3C5PcjDaItU4YsUuxxn+fteF6ENz9nyijEHufrE5lY1iw5kCG9EHtBQry/r9izREQYOjm5IG2a9HK0OOPgFeIcuxmkS5tRNpNzn4VFWnr4nEWhwPCPipRx5s74NDb7Ijgcrq4pkT0rRZUVUqTwgKeIc4RGwNnZDdnEcTc3IfaFuPP0TIMc2XPD3tbx34k9xQdAk4M20qROB1dW2pgOdITdilPSFt1TehrOiWNMI14irmX0CjtkekonbNNKFpHiGtqiMOWsmbMjpaiscYbmDKISYEgOVtK+pd2GhIs8wA7Zs+WSvw9/kWb+jdizNEQ4u7qmQBqvdCL8RaiZihRxzpk2LuyW9st9Gf7Crh2Ffcs4ErbL+KHdyvC0EseEHXt4eCGLiBMeY76ckhXx0HARRx7IJvJSNrvTbtOlyWCwd4r3fyP2LIRkL/gWzJuPebO+xobvf8JP3/wY65ZckM2SgtyFi6B87dooW7OW9PAF+vvJ44S1CRa8Nra2sGUzmiXC5kIOAogtU+BxY3OiPE+vqshgGHpyn5mRyPQpNOS+6TF+j6JDv56ZHo/LfQHPcZ8bz8X2+8kNhoEeZqaFBIkW3iwExL4eprq4Iwx3Pc4Ij3Nfv46fKbh5nPErChJ5nPB3uc941u+nSBow7t4Wb4xzUxuPade6Leod+/VjTAu8lhMx63Zrat+8jr/J6/TzitfhEluYRAtvY74X064Jv8uwN4XHdDvmZ/7l9bp98/sxr9PvlwxJ9oLP29sHA3sMwKjRozFqaOxbcoC1rnB2jhf4+/rKjq0BL18iLMQ4hE3AUU8vnj5Bj/99jFYVy6F9tcryuCKRoN7hlCBq9v4PC5fQSyE2feUNbmyi4hJQPM4lnHhMoYgNpg2mHWexKT4MLNOYj0p7FXmqbsf0MPKYvpybhdlxshd8dnZ2ssMnO3NLV29sWzIgJDgYhUuVQf+p05GvaFGEin0dTlPBfmaNO3REv8lT5dZ38hTxd4rxCkWCw4xHFBDh4WH46/QpREgPYjKuqn4QRHhb2+DG9Ws49McfePrksaFvl401okR8nDh+HEcOHcbTp48MxxWKmNCOhZjw9/fFubNnDDas7DiRMYT3xQsXcPTwYfj6eksbps2GhATh6JEj+PPoUXHcx+LsWOVKCklYaCiy5smDFj16IVOOHK+8fYTNuJz2onztOmjVuw9a9uqDVr36ir99jVckIZjhskaXStTgUorNU2weYmNtm8e4z8W4eR29Nu7GY7yGtT8e5zFuPMZz/C7v5SU2en94DTeuq8nzPM5aIzN2Hudnfpe/p2+8ln1V+Bv8Dvd5LeH3xDX+If7o1K8zOvXqxO5EhhpoUsY0jPS44F/WvPmZYcSBL7yOcaaHN69hn0nGD8OO+3o4Mi54HcPcNAx5nMf4fdNw5bUx44K/xbjQn033ANjbIiDQH5+1/wyV61XB6nWrxbOK53O3wS87NqNMjbKoIo5funpJrqeqSEBkfBjjxzTtMJ75mfGo22vMtMN0Y7SpOKUd2jS/y43LpEnE9/U8QP8+N3p3mXb0Z9PzEm78XXHvx6Ki0LhdMwwfN9ywAkdSF3x8N4Yd35/hyfCjh4xhxc8MJz3vY7jwOoYNryGMHz1u+JdhqsejaRgyzPV78rjMa8UJ5oO8p55X8zPvwfBmXPA6HuM+7+Nki7sP76J2o9qoUKcStnM5TDdxjxQ2WPzNElSoXRH1mzXAk+dPRTqwLDsWIaBQ0B4NTbq+L57Lv6Yjkwn3gwIC4PP8ubxG35IcIoO9ffcmhg4aglVLV6BTx06YNX2mXJO11xc98WXfL/GChs6ld+xssGj+Anze/HNMnTQF4VoYNBsrTBGfF81biOFDhqF3z97yuzOmzZATJp86ccIgWESGdf/eXfQWArrl5y2xcf1P4rjI2MT32W906sQp4rf6o23btujXpx+uXhEiIaUtvL2fYdCXg3Dw9/0yY4K1FaLEo6z7/geUrlgK3/24BtUqVoO9GzszG/unJFWcbXH8+J8YPniYXIqqXZu2+G71tzj+559o17YdJo+fhPAIUfEQ14WEBWPsqLFoIeJi5bIVUmj5iJr5iKHDsVLEY08Rd2NGjsblixcxRMRtj65f4O6d2yIMReCJ+Pjr1Cm0b9MObVu3xeHTf8rCwT8oEJPGT8TMqTPwRbfuaN+uPUYNG4kXL56JzN8W10Sc9OvdF1co4Fgwi/8fPH6AO/fvys7k9x89EAUYEOodjBnzZ8qpJTJlzIQcosLEybQVCYiwjb/OnMKwQUOxcokh7axcthynT55Ah/YdZFqht4Zph2vkTp4wSdrx4gWLRFzayLkXR48YheVLlqGvqMAyHTHtjBw+At06d8PN69fkd5l2aN+dOnRCm1atsZ8D1YQwCQ4LwbTJUzFjygyR9nqItNMOwwYPxZMnIk0IO7518wb6C7s+f/6MwY5trEX+EYEFc+ejVKWS2HNwD2pXrSXyGPEuSX0CYBFOO7ZtxdiRY2S+2K51O2z55Rfs27VHLhPJY9KDJsTaC5G/Dew/QOaJv278WQqzm7euY8iAwVi9bCU6duiI2TO+woVzf6NHtx4iLxwIX58XMs6YfzL8W7dsjS6dOuOiiBekssfjxw9lXM6aPgud2ndChw4dMG3SVDkfJyvXx/88KvNaLqco19UWYX799k14+/pIO35AOxbZ6bNbT+Ray1yhJVvmrMiSKTM4tZMloQSfpcCaTjxsUubFclzfeN50S3LYW+Hhk0eY9vV0TJs/XdYAuaB+o9afSHGxQBj8mOljReZijdGTRmL2wtkoWqwofvzlJwwYMRCRNhoWr1yE3kP7wOelNzb+ugHl61bAleuXcfTYEbTv1QFBgYF4+vgJ6jarh2Onj8HVzQVte7THihXLZKb1/U/fY9jE4fAL8EPxwkWxbuM6rFy7Sv7mrt/3YKYQDxp9eHYihEVhcfzEcSxYPN8wh58Q3sUKFTMUFEld8Dla4cKVC5gyZyrWbPhOjgJv26Mdeg/pLXSxFUZMHonla1dAc9TQ7ov2oia+DUVEXEyaNQlLli5CWFQEJs+egpHiuojIcMz4eiaqN6qBl36+cu3NfsP7ifCzxqnjJ1Cv2UdyebQQUVAXqlIUf+w9KAohYO6iuRg9dQwcnByQP1dezFowCzv2iRq/qzVWrF2N+SI9ODs7S+FNwXf2/Fm4urrKpd0ePnwojy1YMh/3Hz7AZw2bImumrPDySA1ECHtRJBwi7Vy5eRVT506TaYQrq3Tq2wWd+3WVaWfc9HFYsEoIDScrdO3bFRuEnRYtXhRfLfoKs+bORKQQWVNE2hk6fgg4Se+8pfNQpX5VIfaf45fffkGPIb1E3Frh4rnzqNO0rhD394RNamjYuhF2bdsBG3sbzF++ACOEHVvb2qBg3gKYt+RrbN65Rdrx2k1rMWfxXDg4CiXBtCMqKFu3b8W6n9ahokg7zDuLCNuXJPWkIuLi8PEjGDdjPHbu34Hnz5/gk7ZNMGXuFESEhaHH4J7SdkMiDOvanr9yHvnz55N56M7ftsPX/yWmz5uBWSJuOIvBl6MG4NN2jaVNc7WTcdPHiwqaNX7bvFmGP0fo3hWVrtoiXq5duIrA0CBMmDlR2O5MeKXxQqa0GTBG2PTpc6eFHVthprDpHzb+AGc3N3ou5COfEpUFToZfskgJuaoKI4Rphktf1qteBzmyZIeTs0vSz2NjoARfUkckYM6h5+ruDteUib8lOUTmyiWzOI3K6EGjsGLNSmTOmBkVSpfHkm+WoV6Nerh87QoC7r2U3jS5Vqa7B9KnTScy+Pm4fOki3D088FmjZli0agnq16kvJxRdvnwFBvT4Evce3EOQfyC+W/ctbt25hc1rf8XSVcvQsvHnUtgEvHgpBUStyjWwfPUK9B8xAK2btsS23dsBvyhs3rEFlctWQpWKVYEgkdkER8i1I3/bug2tmrSEs6MTChUoZBk1T8aFja1cM3P+9HlY9vUycO7C5o2bY+Wa1ciTPTeuX7+Ouxdu45dtv8il5xgX9KRNnztDrn7ANTf7de+LJauXokjBwsiXKx8Wr16CFuIel69ehhYQgVkLv0LKlCmxZeNv+HHDj6hXrQ6mzp4q+6Y6iXt1ad0JcxbOxZDxw+RKKWyeRUAUduzdgc7iXObc2SCXYhK55eETR5E1YxYh1ItLD4L/LV/MWjwHXVt3BudhzJEtB5w8RUHB+f4UCYe0Y1uxWWP2xK/wzaLVcrL0Tz5uhOXCposWKIJr16/h8ZX72LB5A7JmzirTDufPmykqBo9FpS+VRyr07NgDi4Udc0WNbCJ9LRJpp13zNrh6/SqiAsPw9dKvRRq1wfaftmHNj9+jbImyQihORZgQMpwQvF3ztkLozcOgsUNk3vHLdqYdSHumveYumM+QdkQ6rFKxMnbv2i0nD+bEz3ly5Ia+PGOSRsQFlzXjJPTfLPoG08ZPFzopCn269cGapd/BPYU7bt+5g7PH/sLvf/6BHFlzIJWnJzjX4cw5sxAVESHDeOyQMVj57WpkTJdR2uFSkR/XrFJTVAovQvOLFJW7ySgj4mnN+u+xdf1vMh+ft3ieXBbUzcUVQ3oPxrTZ0zBhzCTkFmG7eddvCHkSiEPHDqOfeBa3NCkMdin+px0XyV9YxgHj8tG5+/hm/bfo26W3nMe1sMhL4CJUIEf1WhBK8CVx/Ly9sXnNGvy65jshLtYk+pYUYZ9EO1tbuSIG/ERFXgiONF5pRGbAvEuDi6jZ+fn6iowgXPZd3LdvL7y8vDCoz0BRqDiB8xWmERk2YWbBzJvf5TJAzHw4WzyXWsqcIRNSu3vJ64oULIKXHPns6yc0uhXcU3oYBgqJ7dP6n+DR00dYK+Lx0J+HZCFi7WpryGwiNaQQz5nSI6UQIDuFAE2DvDnyWEZBIWDB4GAvMmxHV/j7+8smllTuqWS8WItwpLh7/vy5+GwDbxEne/fuQelSpdG1Qxfp1WFYc/Z+hj/r7jIeGWwi7BxFgcy1de/cvyOFIL1xdJx2HtBNhPdjhAQFi/taIaUokORqDKFAk4ZN5Gz833+7Bvce3kObz9rwMQ2IML9+6wbKlCwjCpRcePr8KYZPGCFXX2nboq0oWA6hUH4hxm3EtfSIKxIUTYsyCA0XN5l2HOzt4cUl94TgYoWOaYceO8YEl1nbu2cvChcqhJ5de8hWVNqhp4dh1RwuvE/bYtrhBPaOomLFgVE3RaWNcc0l1HiO8fv02VMEBwTJ73P5Pbkij9iYds5dOIcfvluDKzeuGFbbYQlLL1GUJkROajjaOWHHvp3ynhkyZBAVN8tIJww/NoVy8vMAUeHlPKMUgAEiXrjcGcX406dP5ef7Dx7gwIH9aPBRfTRr3FTOhcuKnswT/Qx5c2pPQ37MuKHXLSIoDA8eP0JhIdKIrZM9cufMJb1zEWEUjLZSzEs7dgD+V68B9h/aj9VCQEaIvIDrI8tKskgXkYHhuHvvDipXqIyMGTPihrDpgWMGoXyp8qgmKtqnz/2FgrRjCzRhJfiSOL26d0elbJlR2N0NxTzdE31LqnAmfrkyiTBqig6uicvP9PpQSHimSysyMBeRwRSSzbmjhoxAnRq1kTZtWrm2q1ysX6APaKGQ4D05iz/ziXKly+Hqres4deG0zGg279iM7FmzwSOtl/yu/tsUESWLl0LenHnRfXBP6SWqU62OFB8SqhhxXeSLcBw4+jsK5S0IF08u1SR+0wLg6zH8uUIGw5JhKMPTGC9hEWHInCWzLMAbikz8p183oHvHbqhRtQZcXF1lWOpxJ+9jEo+RkVGwdbBH2eJlpJB+/vAZAl8EYOLgsShasCic3VzE9ZFiExFkjIu61evK3/9CxEW+3PlQqlgpUYiIk/Y2ePHwCS5cPI88efPIZzolhOH8VQsxY8w02VT8VAjTSmUqWowYTwrQ3l6lHdputLQTjgyZM0lRWKtqTZF2fkLvrr1Qs1pNpEjhZkw7hrjn92XaoR2L73LUNb9XQYiAY6eO4/6dewh9GYKdQqwVyl8QriK/ZdrRv884r1m5hpzot9ugHsiWKSsqiDxAChDChC7wefAcf54+jpJFS8GKfXotxI5Zv6HdSNsVAUIxzs96vERoEcieLbusgHUTlTXacatmLeQyaFxXnKKM4f/qemO4Gj5HwC6lI4oXKoqdB3bJeLh76zaOnzqBUkVLwkaIcf7Wq7gQj9D4409x7cZ1IeSGoEq5ysieK5eICxG5Dla4KsQ41y3Ply+v7HPLbjTrN/+E2ZO/wo27t/j0KC3u+yoPtiCU4EvilChRAq3atMFnn7f4IFuSQ3rpI6RI0EVbYGAgQuV8g0CQqG2+fPkSDu6OmDhyAtZu/EH2natQsxL27tsHLnsWFBRk6BAs4NJeXA+XcHkuLvMT4BeAz1u0lM2+/2veCMWKF8Xd+/ewcOYCODg7wc/PT/ZXM3wpCo6pnNH0f03EdwNQp3ptZM6TVWROJgWByKRu3rqJC5fOo1JZISikp0pkXkkdEd5cQonLKtFDwMI7SIQLvabMuRmuviIu0uRJj2H9h2LIuGEoW6os6jX+GOfPXxBxYYcAcQ1HmJOg4CC5fBIJFccCgwJk7X/wl0Okh690tdIoUakkMmTIiIljJ4r4ikBAgL8hHbBAFmGeOWdW1BOij3HB+HPwdBJxJISAPXDl1lXce3hXeljZlExxWqtSDdRt8jF+27FFTl2UPVs2g2dCkbCI+GK8hYoKgS74Ak3SAj+/9PWFRzYvjB48ChNmTkLZkmVRq2Fducwb7TggIEBcL9KauBeXw6KnSU+TbNYLDQlDn159UVqI/gq1K6B4ueKy+8a0CdNEWoVMO4a0KgiNRJos6VG/9scyD/j0f5/COa2omDHt6Ig0RA/g46ePZR9QKU4M/yRtGGYiH2R4SOFM8SbsmUItSuwzv/T18UWh8kXRtV0XtOrcGmVLlMFn7T6X+SKbc2n/FGwUWwx7PX9lPhko9mFlhcljpspjxUoXR+WPq6KmqPT16dMPgf4BcvS8FHy042BNVKJLit8ojcDgQLlmOb1+IuOXcXDmwhn4+fshJ1fUEfFJOnzeDgUrFsYvW3+Bm4ubzCMssR+uzViB8XM0xo0bZ/wEtGjRAnnz5jXuWRYH9h9AkTyF5DqaIpUaj0Zn3KwJxk8JExYUACdOnEDNmjWNR5IOCZ1O/k3YMMP+/cDvqFK2MuzthKWLTOcVIopdnJxRumRplC9RDm5OrihQID+qV6wm18Vk/5LqVaojW5rMKFi8CKqXr4Z0adOiU+tO6NblC9hGWol3zIfqlasjQ6r0yJohs8h4aiJX5hxI7emFqqLGWih3fji6uKDxR59IAVC4QEFMGDYe+YsVhOYfjjx5cqNGlRrIki6TyITEA3nYIMQ3GN+s+xYTh01A7vx5ogs+Pr4QeKVKlEL9Wh/J5k+RkxrOxYaTDU6dOAk3Tzezsdu//joNR2tHFChYQBSORjsTr8hF69m0UrxgUbg6uaBE8RLSS+bhlhL58xVA1YpVRbykQ5VK1VCycHHZ0XpQzwFo8ElD2Ij8ndcznlO5uiNPzjyoKcI1c+pMyCTihWGcPUNWpPDyQLOPm4h4TIdK5Sti0rCJSJ0hjQjjKBQtWhRVK1RF2pTC/rk+p6c17l69jT0H9mDupDlIxeZiIcqZbtjsVKFcRVQuXQEeKVOhVMlS6NHhC6RM6Q4nW0d8XOcjFMpTENaaKHVM05wo0DiQ5NT506hR65/T8f79+1GsWDHxu6mMRyyDx48f4+rVq6hatarxyLs5fPgwMqfNjCwizmUcmCLSjkcKdxEfFWS6oE0XL1YClctVgqeIm7x58srmuYye6VFexHkZIdqyZM6Mvt37oMlnzWTaYThXKV8ZXq6pkCt7LtlfLGvaLMiYLoO071xZssPVIyWa1W8qBEB6lBOVjUkjJiJ91ozQgsJRqHAR+RvpUnHJRBHfqazx+PYjbBHif87E2Ugj0hvCTOzYmIYqiuepVakmHG0NywG+FQcbEQaHkC1PNumJ+tA8efoEV85fRtXK1aLHh3jFdGnSoboQYAVy5JODmsqI/LVM8TJyPfJiwsYqlq4ILw8v1K/5MfLmzo08ufNgzKBRKF+1IhwibVGmdBmUE9dzndyCBQuiWiURru5pkTN7ThkXWb0yIXXmtGhS9xPZveZjkQ+OGzQWjq7OsNNsZDcPmW+4uMv80iq1Df46ehrXb9/AV+NnwtHeWTyneGbxrE4OTrKFoFShEvD08ET5suXQpVUnONs5w13kOw3r/Q85jMu1RcPOBg8fPsDN+7dQucrbFx2g0D1w4AAqVaokm6PjG9rRDz/8YNwD3iLhYkco8ljhKX3bvHmz8ajlMXrkaO3Knxc1zUfsPAqLdUvosLh37542bNgw417SwhzDxj/AXxsyYLDmf8dX055GRo/Ph2J7JuqdoeLC52LjfrD4+1JsD8TnAPGXG4/zen4Wf7QgsT0ONxzjZ/16P+M5Xu8t/vJeTyLEvviBp+J3uM/fYvrS7xkoPvuL7ZG4n3eUNnfKbC1j+oxaxdIVtMB74sRz8T39ebnxe3yPEPGdFyb3iW3jOfGbi2ct0n7d/Ku42DxYvnyZtmH1T4awMn1Wvg/fi2HGjZ8ZjjynhzM/PxbnuC8+yrDjMdPrGRd6uJrGi/wdEQH8HcYDN36XxxifjB+RTLQnkVr4wxBtcJ+Bmqj1a+2btzUeF7+hPyvTDX+PccFNj1f+Hq/l7+lpxHQTv33n7E1txNDh4oJ/ZuTIkdr169eNe5bD6dOntfHjxxv34sa0qdO0P7b9bojLmGHK+NDTDuOC4R4z7fB7/MxzetqhPdPu9Ov1+DO1e6Y5PS6ZTphP8FrGt25/PKfnGyJtRon9kQNHaB4p3bXPGjbToryNaSTmM+v3Ylrivun5mJtIz1NHT9GOHjsqvvDhOXvurDZ+2Ng344PvwfTP8GDY6vnrM7HFDGeGiZ4n6nmoaX7M++nhahov+u/wPrxWD8MHYof35D7j/lmk5nv9hdaxdQfN3s5eG/XlSMP3+Rz6PfR8msf0fIF/+XvMP5iP6O9muolnOrH3mDZ54mRxwdsJDg7WBg8erHl784finy1btkQrd98H1aSrSF7Q5S9qYHghqvh6U56P+MsVVWgNXOycG48Tfn4uNl+x6V4bftavDzSe4/Vcr5H3Ys3QShzgepvc529xHUf9ni/FZ30hfnFPdvzu2Lo91i1fC2c31+jNQITXsTnCW3xHX6/TEuB78H34XgwzbvzMcOQ5PZxlOIlz3Gdc6GFnej3jQg9X03ghjAv+DuOBm36M8cn44bqnYpe3TJc6HUYOHI55U+aJMBfn9Vo+TzLd8PcYF9z0eOXv8R78PT2NKBIWxoeedhgXDPeYaYdpgJ95Tk87tGeWk/r1evyZ2j3TnB6XTCfMJ3gt41u3P57T8w3uC9J6psHAPgOxdNZiWNHLy+cyhdfp92JaMn4vycP3YPpneDBs9fxV9qmLEc4MEz1P1PNQ0/yY6OFqGi+Ev8P78Fo9DDnlDe/Jfca9wFrEWdZMWTB78iyMGThKPJuwYT4H4T30fJrH9HyBf/l7zD+Yj1gofEWFwnKhnce2kdg+x7bpmO7HPG/6mXD2eG56ph7b9WzOCY1Em7btMH7SRGTKnNWQ0Zlea7qR2I7H3Myd2J73XZ/1fRLzWGyfY+5b20DO8s8JYEnMayIiYWNljf4DB2Dw8KFwdUsh4kYUKPp1Ma+P+Tm2fdNN8d+ILUy5kXd91vdJzGOm+6YbsRFphitniHTxipjX8G9kFKyELffq2wfDR41ASo9UsacdfSOxHY+5mTNve953fdb3ScxjsX023Si+GR+2HAZvPKZvhH9FZdnNJQVGjxuLHr17ydG7sgJteq3p9TE/x7ZvejyJowSfwuLQRM2NozpdU6YEPEQS55I7ibVxSZ8UdgiLCkO42F4toxbbtfpGKxR5Emd7j/X8+27iPg6ODohinxUzgaPtnJydAHZpie2ZE3Jj+NtZITgsUI62fbUMU8yNSzsxY2dcuMTjc3oAbimEgFS8FxzE4+IqIoL96mML14TamF64CbsMjhBphqu1vC3NmG6EacdZbLGdf99N3MdOVFJoO+YAn4MDpRI9Prgx/LniTkQQNGthpHocvXGtvVwijX312GcSbsz/xbE3rvsXmzBh9k9k+ZJUsWK7rvFzNDjHkM7mzZvxv//9z7hnWYwZNQatGnyOPHnzG9zFsWCVXiQYIwkRFvfv38fChQsxefJk45GkQ0Knk38TNhw5271zdxQrUFTO0cUpAhILO3t7Ocfb2h/XyklhW33eWs4NFqE3VyQ0wpptHe2xe/8etO7QGnXr1jWe+LCsXr0aRw4cRuXylRDOkZGJhhXsHO2wZetvOP33X6haoQoqlilvPJc4cA5BLsP27OVzzJ0313g0dkaNGoX27dsjZ86cxiOWAUfG/vbbb/L94srUqVPx9N4TFCtcFBFsckskrERlkZ2dftr0k5x38X/16ssBUyGBhlG8iYW1nQ127t2NIaOGoFjRYsajH44rV69g7LAxqF2jlhBUiSh6xE85uDji7N/n8OvWX5E5Q2Y0b9Zc1OFshQiN0WyegNgKsXvh8gW4pHLD6DGjjUffhCO+x4wZg6FDh8LDQ9T24hnakWk5+z4CVAk+Jfj+E+Yo+AgLmBs3b8iJPhMTG/F7N2/cQL++/eT+goULkDlzZhjmp0ocWBPn5NEcJebiQlfVh+fFixc4cvQIOILNNM0kOOKnuCLDlKlTcPTwETT6pBG6dDFM2pyYcP6xgoUKIl/efMYjsaME32sePHggR+izgErUJCN+jMXiwIEDceP6DXTt1g2NGjV8PQVLIsF5JFMJwVCxYkXYi4rkh4a2e+TIETx7/kxOpZKY0LO4a9cufD33a2TImAHz5s2Tz/A+Yue/wp+i86BkyZLIypHjb8GcBR8vjhWe0jdRkBuPWh7/OErXOKInocNCjdJ9O0kxbG7cuKGJzEhzdnbWHj58aDyq+JB06NBBptFx48YZj5gnapSu+VC9enWZZr777jvjEcWHZOPGjTI+SpcubTxinqhRukkVO2vcuXXTuJNw0CNjLv00FP8dTuQsbEtu/Kz48OgePU7IrFDEBXq0CD02ig+PnBhbwNYSPW4U74dq0v2nJl0PO8yeNhNfjhlkPJAwYeHr64v+/fsjU6ZMZuG6fx9Gj37dlyEhwiYpNnf//fffclJXrqt77tw55OKyPooPSps2bbBmzRoMHz4ckyZNMh41P1STrvlQpUoV/PHHH1i2bBk6d+5sPKr4UHz//fdo3bq1XF3q2LFjid5dJ66oPnxmzLsE35wZX6H/qAHGAwkXFlxY+tmzZ4nbvyke4KzoOkrwGVCCz/xQgu/DogSf4r+iBJ+B/yL4VJPuO+A6jYlBmjRppHgqUKBAktoUCoVCoVCYP0rwKRQKhUKhUFg4SvD9E1ZAcIiho6hCoVAoFApFUkUJvn8iVEOJwsWNOwqF5cJ+ki1btkSLFi3w888/G48a4Ii4iRMnynPsQ3PgwAHjGQPse9qtWzd5jn3lLl26ZDyj+FBcu3YNHTt2RKtWrdCvXz/ZR9iUvXv34vPPP5fnR4wY8caox7Vr18r0wGuWL19uPKowZ3x8fNCjRw9ph4zX8+fPG88YuHLliuyLyHjt06ePnBvTFPaL43d5noPxgoKCjGcUloISfP9EQATqf9TQuKNQWC7bt2/HDz/8gHXr1smM3xROg7BhwwZ5jh2nYxYkL1++xNKlS+U5DozghLmKD8ujR4+watUqKdz4l3FkCgcTrV+/Xp7n35gTg3OwAtMDz+3bt894VGHOBAQEYMWKFdIOGa937941njFAu+R5xivThJ+fn/GMAVYS+F2e56amMLI8lOD7JzhgNjRxZ+RXJH0cHbkorgHTz+aMaYEf25yQ/3Q+5igxc5xTUl8ZwFxH9sU3pnFA790/xRE/xzz/rvSQHLC2NhSPcv3YJIJpPMaMN9N9XvdPaYLxH/P8h0afsozxklzsOL5R07KYwdJqSZmETif/ZVoWXx9f3L97W+h28YyJNN0NM6KLFy+icbNmcn/rr78iR86cb3hQEgxm5OJP5mzZkDJlSsOxOMCh/pcvX5afK1SoIDcdPvtPP/0k44KZbc2aNVG0aFHjWcM8kvTs0SPA802aNEGWLFmMZ1/D+9y+eQNBgUGvCtPEwFaIvd59+2D33n1o37o1Bg56Pa9mYhAl3juFuzuyiDh517RL8TUtC705jDOKPTc3NzRv3hzu4hl0zpw5gz179sjn4QwBbMYzXS5r//79OHXqlPxcpEgR1KlTR37+t/yXaVmePX2Kxw8fiDSTOMt5MUxYLH722We4eOUKRg4bhrZt2ybq0mr8fdpINpEOnJ2djUf/GXr4aIec7J3v0LhxY2QTaU7n3r172LRpk5yEPEWKFLK5nn912OS7detWKfzSpk2LZiIPi63CynC4deM6wkLDEs2O7YXo/mnDBowYPRrZMmfGZpGvMq+NSkRRSjv2TJMaGTJmMh6JHTUPnxkzdvRYdGzSDlnyZhcxZTwYAyuP5BEW/4aETif/RfANFAb3wD8QHqk8oCWSl4ILr0dEhAvxEyaElwZHB0eRMSXemo/MgJ8/e4ZcImOaNH688ah5sH/fPsxYvAQ58+dHuBAiiSPBDWk0WGTCWpQmRI21LMQS02tlLYTUHVGYThs1EgULFTIejR01D190wkQl4ou+fRHp4gonRydxJDHsiClTQ3CwoUCgsHBwsE/UNMM1ue/fvYPqxYujb58+xqPmAbt2fLd5C3LkyYOIRFqTmvkaK5ThEaw4ayItOMq8NnHSg4FIkYd7izhZMHMG0qZLbzz6JkrwmTED+n2JyiUrIk/evIgMi90LU6RyMeMnJfhiYs6Cr9eAAajbvaf0YFBgJArCnJg56c0PoaI2LMWmSTglJPzde3fu4I9vVmLOjBnGo+bBjz/8gNPPvdHyix7w8/VNtDBhnNjZ2UuxFyEKjMSaW1MiftvNPSWWTpqE5pUrokqNGsYTsaMEX3T8vL0xQFRcWo8YDTt6dBJRdNGrRFtm3hHJ/COx0qvAydkZp4/9ifsH92OcEA/mxNdz5yIobXrUa9IUATH6ASYYwo7ogWbzepSouIWFh4lj4njiRQkcnJyxZPQIDOrYAXn/YQ5aNfGyGVOtZnUcv3gKP+/8BZv3b4l1UyRNWDMPCQpCcEAAQhJrCwxEkL8/fF+8kFuw+MxjsV6bABvfNVS8szn2cbG1EwW2KDiDAhIvPOQmwt/f10fGR8BL39ivScAtyD+AHaSk10bxflgJwWVjbSPSdWDi2rHY/HwMaSbw5ctEtWFuwSLNhAnhYI79B/lMEaFh8hlje/YE2UT4Bwpxyfjw8/E2HotxTQJvwQH+0sFh2vUhqZHsBR+V8uQpkzFi1Mi3bgqFQqFQKBRJmWQv+BSKd0GXOb0zzq6u0TYHdmgW53je3sHxjfPcbEVt+F0udwcnJ+mRex/XfHKFYWRnb/9GOPOYHn6OIjxjnndycZF96WKGMfftHRzENW4yHvRjrMnzOzHvrUi6MA5pjzHTBuNfj1+mgZjnudGr849pQKQXRyfnd1+neIXB7qKHs55fSvtzdn7jPG2SXl9xkfEuOprMj2nH9saBJrwPm+SdXYz3VnmsEnwKxbtgJu7v64vLZ8/g8hnDdumvv/DkwX04u7nJTOXR3Tvi+F+vzhu2v/DyxYtYmwD0zMhFfP/RnTvwfvZMXKea/N4Fw/LFk8fRwplx8dLHR4Yl+0veuX4t2nluV/8+h+DAwDfigoXA88ePcfH0KdwV35PxIq5hgXPj0kVcOn0aTx88iDUOFUkLxqGPsDPTdMG04/P8uSHtiLi/d+O6OG5qx3/hirD7QH//WNMAvyMrg0KI3L1xDf4vX6q0EgdoX4/v348W1oyL4KAgKc7Cw8Jw8/KlV+f0uLh+4TzCQ0NE3hk9jG1s7EQefFfY8Uk8vH3beMxWzgxA27/012l4Pxd5rIir5IwSfArFO2AGdOLgfnStWwudalWXW+faNdDto7o4smsnXFOmxPJpk8XxGq/OG7Ya2L1pA1xMpj7QYQHjKo7v3rQRXzT4CH+fOC5+x8V4VhEbutdty5o16FKn5qtwZlz0a/Ipbly4IMXalL69TeLAsHWsUQ0XTp6Ak4hLHQpuFgALxo6W95vWvx8iREGT0sMD544fQ5faNdFFxPmx/XtlGlAkbZxcXLFzw48yTvV0wbTT+5OGuCgEAT1OMwcNEMdN7bgGOtasjtOHDsnKXUzc3N2lZ+mnZUvFfRrh/q2bcIzjNCrJFdodw/rb2bNE+Ee342FtWskKWHBQIIa2bW0SD4a46Czs9IEQdA7OBm88oQ2Hh4dhUp+ewo5rYenkifJYCg93HPxtCzrWqobuH9XD1XPnpNcwOaMEn0IRB1hTjIyIRJ0mzdBv0mR0HDxE1kIXjhsjB2lw9CfFSPsBg9BjzFh0HT4SXYYNR+EyZREaFH09ZhYQ1/7+G8PatcGYLp3k1BN5CheR91O8G2buHK3ZrEs3GReff9EDty5fwqqZ02VzT2hwMNJkyIjuI0ej+6gxIi5GoJv4nCl7DtkRXofNRy99vHH7ymVZANEDGCnuy3hYt2ihvMZOHM+WJ1+ijg5VJBwR4RFyPrVPO3SUaadV7z54IETa8qlTZByHivThmTatSDOj8MVopp2R6DZiFLLlzRst7RDa8elDf6B/08aYM2yIqMC5IWuuPMqO44SVDGt2l2jT70sZFw3btsPZP4/ip6VLhD06ygF3uQoWQs+x46X9dhk2At1HjIaHV+poYcx7PHv0ULaU2DnYy5HDFJX03P64eJGIJydZKc+SM3eiTSNjrijBp1DEBWPXj5qNG4tCYBg6CGHHQuDpw4ciYxKCTtPg7umFlr16o9PgYVL4dRw8FPmLl0Bo6OuCgoXEo3t30f+zJjj1x+9wY0aUKzfSZMwkJ8lVxAER1hRon4hCu5uIi5a9+iBVmrR4fO+enD6DBXfmXLnQYaCIg0GDRVwMFvE1EBmyZZPiWodNPg9FIRHoH4D8xUqIcyGyifevI4dx9exZFK9YCWnSZ0C6LJlV3FgIhiZYGykumHZa9+knKwdP7t6TYoBzNWbIll2kmQEi7QyRdsx0lCV3bilQdFi5YzNh38af4NaVK7LfaPZ8+eHu5anSShxh9ws3dw+06NFT5qlNu3SV9kc7JhTm+YoVQ+ehIr8VcdBh4GC06tNXhLFXNMHHJvQ7V6/KFoA8hYrI0bSsqP2+9Tf4vHiOAiVKIn2WLPBMlzbxJsA3U5Ks4Lv/4AEuXb6MK1evJPimUOh9P8Z26YwKIsOpmzM7/j52DDU/+VRm8pyq4LEQck2KFUb1TOlRJ3sW8bmI7Ntn2sTDAoeepPZfDsTXv2yWTYx5ixSBkygwlBcpbrBGT+HGJvbyIi6aliwG76dPUKtJE3mO4f3XoT9QW8RBrSyZUDtbJnStVwdhYaHSq6fDgv+WyEMY7ixYeE/GzaYVy5GveHGkTJUKaTJlhFfadIhM5p4BS8HO3k566ns2bCDTzqdFCuLx/Xuo3bSpFG0OTo44f+I46uXMhppZMoq0kxntq1eVXnymLR2KEa44MXDGLExcuVrmD6w0yIFByo7jBAfIvHjyBJ+VLiHz1A4inCmWqzdsKPLJKCmqt69bh6rp06BONmHLWTNiWNvWMq817SdJoXft/N/y+lwFC8oJs32ePccv36xC2Ro1ZdywUs0uNHI+xWRMkhR8XBZo2MCh+HHNOqxb/UOCbwoFhRrJnDOnrDEWKlUK3UaOQp+JkxElMicuV8QCIW+x4vJcQbFRRNjZO8jCQYfNQlly5kKHQYPlpLIcEJAtbz6ZKamCIm5w4lVm8jnyF5CFbIkKFTF0zlx83r0HQoKDZKbumiIlCpYwxEOhUqWRs0AB+R16B3W4zw757OuTNU8eGQdH9uzGyd8Pomr9BrLTeLbceWTBZBqHiqQLPXgi4pFD2By970XLVRCibSba9OsvPXhMOy6ubsgvbLxgSZF2SpdG7kKF3hjhHRIcLNNV6z695UAPDurIJtJQIi78kORhfmdnZyu7s+QVeWU5Ic4onms3aSrnXYyMikSqNKlFHJRBgZIlUVj8zSrskfGgxwVX22CcXTl7FmkzZZLeWc7FvHvjT7h/8yZKV62G21euiLwiv/Tom8ZhciRJCr4Hjx6gbLHSGDNxLMYMEdvQhN0UiiiR+ZDOw4ZjyY6dmLvpV+mlo6ALDw2T3qPU6TNg7safsWrXTizbtQezf9okm4ui9f0RhQ2bFTiJKEeGUmTkFrXSyMRc/SGJExkhxLWDA4bNnYdF23dgtgjzhm3avepnSdFHD92y3buwXGzLdu3FmMVLYS/iSm9uo4eAIwLZkZv9hCjkGScrp0+V/S7zFi2Ke9evS1FAYajKccuA4oBxT8/c4u07MWfTz2jcqYusCDBtsP9nLiHwlu7cjRVMOzv3YMKK1XB2donW/4tpgvd66e2LC6dOyq4ZWfPklmlTETfoUU/h6YmJq77Bot+2Y9b6n1C9YSN5nGIvJDAIlep9hG927hC2vFtse9F30hQZ7nprCL307Id768plQ9Nt1iyypWXVjOmo+emnsr+fz7On0p7pNUzuJEnBx3Z+GijYFz5IZOAJvSmSN8bMnQT6+SPgpZ+o0fvJzsFcN5eZP2uVD27fkk1FbURNlaNCO1SvgvVLFr0xuo8diukRPHHggPQmsFYaEaYKirjCsKOIDmAcvHwphRo9LCwEGA+s9Z85cliEf3W0r1YdHWtWkyMt/9i+TY6OJhTqD+/cxpVzZ5AxWzakFAUPZ/H3fvoULXv2xvXz56XHJ0vuxFsvVJHACDulvdKWmWZepR2xsbIg7VjYJpt0O4n00q46R+gy7VTF7l82ySZBU1hZY7qjRzh1hgzwSp9epZX3gE3i+goazFOZnwYFBEgvrMGOrbD3501oXbOmtGXmqRxNf+HUKTlqnt46Du64efGi7PeXKUdOKbx5nwC/l/is6xc4ffiQHMiRMWs2NZhGYAGDNlj3TuhNkZxhc55bSnfZcZsZDQuHV00D4i8/c0AAR4GyGeGGyIBuX72CW2JjHxU2B5lCwcclvihQytWqJacBYUGkeDcMM880aWRzrr2dYUF7PS7kX1FIcDANC1/2z5PblSsyPjiXIgtpxpmVtZUUeOmzZEOewkXh5Owim9ZrN26KEpUry0KkaPnyyJwjhyrELYSoyAjp8cmWJy/sHQ1dLaKlHQH7eqXNmEmml5uXLsnmQG5+L7xjtWPfF8/BNVbL1qwlJ15O7oMC4gLDmt62dCKcc+TLL8ORLSiv4yJKNr/mLFgQLkLAXb9wQY6kpxeP8RIcGCDjwiAKAR9hx1ly5ZLx6uKWQnrrP+/RU9hzHtncXrZGLXilS6fsWGAlAtkQyjGgutZJiEXx/ws7d+/EtVOX0atvX8BXROLrR00QrNK/7qxrbmERn2zYsAGHfv8Dbi5ucZa5k6ZOMn5KmLC5f/8+Fi5ciMmTJxuPxJ1+Q4agYss2SO3l9aop799iyKQ4WbLMZgwHTRHnpIfJxG4M14s6lckxidjXRMHAKUDs7Q2rOLzFDN8b9iN8IGq7p3/egJlTphiPmgebNvyEP+89ROMOnRDg6/NmuMQRGVZikzPux4IMT5O4kCErjsUssBlfhE18UcbvyEEd4jOblfiZ9/hPcSO+y0JrzZzZaFmzOipWqWI8ETujRo1C+/btkVMUWpbEX3/9JRd95/u9DxTpg8ZPwCe9+8HO9r8PiHjftEN4LGba0dErHLQ7mZ54/3iA4vHs6ZPwEdvI4cONR82DRSI/fuGSAjX/11C2dPxbDHEhsgGZp74JPX38Tz+rh6zMU02IZseMD7GxywcFPb16+mAb+Xv/AXsnJ3w3YxqGdO6EXKJS+TZCQkIwZswYDB06FB6iMh/f0I5My9n3eS8L8PAp4ovjR4/hk9qN8EXHHujRsnuctuQCMxlOBcLmwtiwtrWVS/qwqVDfuM/jbyAMlAUOp2ih6PmvGVFygxk7M3HTQtkUdvkwjQvGG/djFvK8D88R3ol9/Ai9NIwbOZBGxY1F8b5ph8JB2vFbBCLv58A0xHSi0sp7QfuytX89aj4mPEf7jGbHYosZd7yPbrsynxbxRdFH2+WAKx5TdmxACT7FKzgLedaMWZAhQwaxZYrTllxghsEmgbdlHKxN8jybZl9tYv+fRnfKzsf/cF4RO6zF02P7trigYIsWF/zMuDN6AnRiximvZXywQOE99H6bCsvh36Yd3YsUE5mGaMdvOa94O7S1f7IxnostLmLGHe2a53lcxodJfPEeqpn9NUrwKaLBDvFgVwf5Nw6bOSMKbtbukuNmrtDLFtvzJuZGYjuekNvbPEqKd8Owiy1Mk8NmrsT2rMlhS+p2rASfwmIJCgxEUHAwgjmhbkjy2QL5zmIzN8LDwhEQEICQsBAExfLcibWFiueI7XiCbSL9BXDZNjX1zntDjw3DLjgk5M1wteRNpJnAoCDZH8zc4OjagCARJ8ksX9XtOCl7c9WgjTiQXAZtjBk1Bq0afI48efMDIXHz3iV02PyXQRuTp0zBpVu3kSJFCjk5cnLA2soavr6+KJ4vLwYOHGg8ah4cP3YcXy2YD8+06USmmZyaWazg7+ONccOHI2euXMZjsaMGbUSHTXJDRLi9EOLHycFRduJPDtCb9OLZM9Tj1ELt2hmPmgfbtm3F6nXrkTqZ2XFkpChDhOibOnECUnl6Go++iTkP2lCCLw4owfd2zFnwkWDO6yQLiaTtio87mrRdJxdX4755ES4yTE5S/bbBL5YIp5lwdHSCjcmybm9DCb5YEEUU52czmHAysWPxztY21nB0djEeMC/CQoIRHh6R5Js43wdKJfZzf9uIbR0l+OIZJfgSBksUfApFUkIJPoUiaaOmZTFTzlw4ix37dxr3FAqFQqFQKCyTZC34hk0aKbeQUPPrGKtQKBQKhUIRXyRbwffLjs3Su0cv3+JvlxqPKhQKhUKhUFgeyVLw0aM3bNII4x4wbuZEPH762LinUCgUCoVCYVkkS8FHj97l61eMe4Cvny/GzZpo3FMoFAqFQqGwLJKd4KMnj/32THF0cJQikM27CoVCoVAoFJZGshN89OSxSfeTeg2NR4AhvQbJv18M6SX/KhQKhUKhUFgSFiD4OAlf3LbL169KTx49eoumLRDHDAztPRjp0qTDn6eOycEcb35X8aHgHEM275joUqGwFJjW32deraQC38nW1ta4p1BYLo6OjnKlFHO04yQ58fK27Vtx69wN9BzSB/AzHowDBw4dQPX61TFl7BQM7T8UVikN76i91LBjzw581OQjLJq9CN07dpfHdfTriJp4OTqJMfHy2LFj0a9fP2lEyRXao4uLCwIDAy1SELwLCiEnJye5Fq+lwjU6586dKydstbSJl0+fPo2lS5eiTx+RZ1sYtEemTcI1rC159Qm+q7Ozs0yrnGA4Oa20EVeYBhYtWoRZs2YhZcqUxqPxR7JbaePEyZP4atosFMxf4D8tZDxm0lj5d9wIw9+3oV9Hkq3gYyqxtRGbEF2RYsdWpI9wDVZpXouwhAgbLtTNlTaeP38Oe/vX4jI5QVtkOmehWapUqWQn+Pj+LFwuXbqEMmXKyDTxX4iMjDRLr3F4eLgsIHr27PlKQFgKXN95wYIFMu4szWNPz+W1a9fke1GoMx4tFTs7O1y+fFmmz8yZM0tbUkQnNDRUhk23bt0SRBAnO8HHR77/4L6s7f8Xr0++vPnk38tXLsu/b0O/jiRbwSfSQ2BwIMIiw+Hm7IrHz58gY7qMsE7zen1QSw6bD83Ro0fRsmVLbNy4ESVKlDAeTT5s2LBBer5+//13ZMiQwXhUoTAPaJv07Pz888/GI5bLxx9/jPTp02PFihXGI4rE5L8IPl4cKzylb6IgNx61LPT3exfJISzI6JGjtSt/XtQ0H7HzKCz6FqRpS2Ys1LJlzqrVq15Xy5Quo9boo4bJJmw+JBEREVrNmjVlGNetW1fuJyd8fX21ggULyvdv37698ahCYR7s27dPs7a2lulz/fr1xqOWCd+P72ljYyPfW5H4bNmyRcaBvr0PybdTlOL9ECklMDgIt+/dQf269fHVpK/w63YOcFEkNN988w327t0rP+/cuRNr166Vn5ML7Nd24cIF+fnbb7/Fnj175GeF4kPDJs3x48e/6lo0fPhwPH36VH62NLy9vWV/asL3HjVqlGy+VCQd4iT4EqIdWpH0iIyKRErXFGj7eVuUKlEK9nbJs09dYvLs2TNZoJjCffZpTA5cuXIFM2fOlJ/1voyjR4+WffoUig/NDz/8gAMHDhj3gBs3bmDiRMucxP/rr7+W/WgJu1IdPnxYNesmMeIk+DjMWKEgNPSQ4BAEBwXDWlUEEhRN0zBp0iTcuXMHNWvWlJ3CW7VqhevXr2Py5Mnv13cjCcLO7/SY8G+VKlVkR3G+P/szciCPQvEhYWVs3LhxsoN+2bJlkS1bNhQrVgzz5s3Drl27jFdZBmfOnJGjTjloKm3atPJ9S5cujTFjxuDWrVvGqxTmTpwGbVSuXBlZs2a1uNFH69evl3+bN28u/74N/TqSbAdtpLLD5PETMWbKWNw7fw/PXzxH4cpFjCcNqEEb8QuFXe7cuaXIadCgAVq0aIHdu3djyZIlchADvQk5cuQwXm15HDp0SOY9FH2enp4YNGgQjh8/ju7du0tPA6fscXd3N16tUCQu06dPx5AhQ7B69Wo5mIger8WLF+Ojjz6SFRR2v7AUOCiF3syDBw9K+ytYsKD8W6tWLQwYMOCVF16R8CT4oA21vd6S7aCNQE1b/fUKrUKp8trzK0+16yeuaiULl0g2YfMheP78uTZlyhTtwYMHmshsZRjv2bNHu3Pnjjz+4sUL45WWye3bt+V7+vv7axMnTpTvf/XqVe3MmTParFmztODgYOOVCkXis3fvXm3ChAlaeHi41qxZMy1dunRygNH27ds1USgbr7IMNm7cqK1Zs0a+a4YMGTQh9OTxhQsXakLYys+KxEEN2lAkPH7haPtZG/y+7QA8U7gjZ6ZsOLbnqPGkIiGgV4tTkXAaEk64TIKCgpAlSxZ5PFWqVPKYpcJWBb6nq6vrqz57nIqpaNGi+PLLL1VXE8UHpUaNGhg5cqSch4+TEdM22cxbr1491K9f33iVZdC4cWPZ0sB5FIVueDX/3hdffIE6derIzwrz562Cj5Fq6ZtObOdMN4UBKytr2ECfd88KNtav5+BTJCx6F4vkOoAqub+/wrxh/9rkUF7o76fsMGmiPHyKuMOpByIjjDvC8CP0zwqFQqFQKMwZJfgU0bC1sRX/iA/8G5dNoVAokjkpUqSQ3Q7YrKtQmCtK8CleESwyq6fez+Dr4wPvl8/jtCkUCkVyh2vMco7I/7K2u0KR0CjBp3hF3gL58N2mNZi5YCZmLZsdp02hUCgUr/uCKxTmihJ8ild06tQJcxd8jdETxmDMpLFx2hQKhSK54+bmJr17qklXYc4owaeIBvvwcck0e9u4bQqFQpHcYZOuQmHuKMGnUJgpd+/elTOqnzhxQnYKJ/QkcGkxHn/w4IE8plAoEp+rV6+iW7duuH37tpwrktBOuSIF7dPX11ceUyjMBSX4FAozhesW79mzB7169cLTp0/l3Fc+Pj7o3bs39u3bJ88rFIoPQ3BwMJYuXYq+ffvKyZc5F99ff/2FgQMH4uzZs8o+FWaHSpEKhZmSKVMmzJgxQ64fywXZWYBwAfNTp07JdTzTp09vvFKhUCQ2XPGF4o5riK9YsUI2606cOBEPHz7E7NmzX3nlFQpzQQk+hcKM6dKlCypWrIjLly/L5YwOHTqEypUry+MKheLDMmLECBQoUAAnT56U8/Bdv35dLqvGpcgUCnNDCT4LICg4GM9fvMALH+9E3xQJi4ODA8aNG/eqUzj3J0yYAHt7NWBGofjQuLu7Y8qUKa+WGnNycsKoUaPU0mMKs8RKS8YTB+lG+a4gMDVeuu/ZIddcoOdn1vRZSO3lZTySuEyZMdX4yfzCxpLo3r07lixZIvvzsXk3uTF69GgpdNlHqlixYsajCoV50Lp1a3z//ffSThctWmQ8ankEBgYid+7cyJ8/P/bu3Ws8qkhMfvvtt2jl7PtIOCX4BElZ8G3dvhWXT1xA34H9oflFGo8mHvbpnYyfLFvwsYP23Xt35VxbiV17Z9+9S5cvoccXPbB02VLkypULWlTimi3fO7VXaqROndp4JHFRgk9hzty7fw8dO3bEN998gwzpMxiPWh5K8H14lOD7l1iC4Nu5eyeun76Cnv36AD5C8CWuFoFVutfr6Vqy4Js5fQZu37iNtGnSAomtq0X6s7Gxlk33zk5OiIyMYqI1nkwcwqLC8fjZY0yfOR0eHh7Go4mHEnyKd3Hh/AXs2LkDdrbs/pCY9mGwz0ePHyN9unQG+0zU3zfA302RMiVatPgczs7OxqPxixJ8Hx4l+P4lliL4rp26jF59+wK+4cx7EhWr9K/7klmy4Bs+dDi6tuiMbAVyAMHGg4kJ45XlmIjiD1CWAI4iDIYPQ8cenZArRy7jwcRDCT7Fu5g8aTIco+xRumwZRIYmbq2MRYSDvQNCw0ITuy72CisHa6z5fg269+2OkiVKGo/GL0rwfXiU4PuXKMH330kugm/MqDFo1eBz5MmbHwih6kpOiETlaIuRk0egU4/OyJ4tu/F44qEEn+JdTJ82HTVLVUPJGmWAAOPB5IQbMGvyTFSqVRlly5Q1HoxflOD78PwXwadG6SoUiQlt08YWcLUTf20SxlvHe9om8G8oFGYGK+bsayvFXqColCW3LQgIDw+P5qBQKExRgk+hSExsrOHn54vTp07B3/+l3I93bK3h4/Nc/MZJBAaI0i8hfkOhsFRkpUxUlDxEhclBbAlZKUsl7m+fQL+hUMRAlQQKRWLiYoOjp/5EpbqVcPz0CbkfHVE7p2fOS2yeYnMUG2GBwIKBBQTPpRAba/I8rl/PzU1srjbYfWAPKtaphL+vXACcY/6GQqF4K462uP/wHnp90QOHDh0U9vN6YJqENsdl02ib3PjZVLDRTp3EZpw7843reVz8xo2b19CtSxecPHXszd9QKBIAJfgUikSGDS5sejEtIyQUcK622Ld7Dzq07YDePXrjxvVrojAwFBQvfbwxathItG/THuvXrpOePJ7bs2MnOrbriG6du+G3X7aIaw234m8oFIr3xM4Kz7yfY8GqRTh/WVSYHGixRmi0FHQONrh3/zbuPbgj9kWFSvfSicqXn58Pbty6huDgAKPwE3YqruG1t+5cR2hIkKiwWeHh44dY+u1yXBHCL9pvKBQJhBJ8CkUiwz42XGz9jb42Lrb4eeMmNGr9CULDQnDm/F+o06Qu7ty8hdDwEDRq8yl+270VERFh+LxLC2z6bROuXb2CERNHwi2FGx4+fIBW3Vrh1l834OziGvtvKBSKf0YIN1sbW6RwdYOjg6g9mdbMhHCjLfYb3A9lapRDWbH1G9wHYeGhgLuofO3chSr1q6JqvWqoUK8iTpw4hlAtHH0G9kalupXR8PNP8L+WjeDzwBuurq5CJ9rL0b1v1v4UivhHCT6F4kPDzF6Is/DAUIyfMR6VylXC2g0/YMeP2xEQGIiV36/EiePHcPDo71g4cz7W/LAWs8fPROEChZAhY0Z0btsJGdNnxAufF/AL9MfFy5ek2FMoFPEIK09O1pgzfzYWrlyI1UtWY/WiVVi0agkWLl8AP29ftO7WBiWLl8T2Ldvh5+eHg4cPItA/AA5C2C2Zsxj1atXD7t/3YOtvv8HR0TGxJ1VQJHOU4FMoEhm9Ms8aPlzEB3YOT2WFsJBQPHj0AMULG6YdcXFzQ56cuXDvwX08efJEehy83D2BCKDfqAHIXTofdu7cgWETR+Dv8+fQs3MPuDq7IErjxK8KheK/Ij3kVGVWoqjk6PoQDT9t/gn1atRB3U/qoU6jevhYiLjte3fg4rkL8Hnpg1ZNWqJw6SI488dZfNlnIOzs7RCpRWLclPFyxRwnRyd4v/RWTj1FoqMEn0KRyLAQ4dxJB44cwO7NO7F18xbs3LwdEZERKF6oOHbt3w0tJAq3bt3AqbN/oXDBQsiRIwf8Avxx5uI5qRh7tOuO3Rt34Pcjv8vmp+/WrJFLOgWHBCOlWwpERWnvNT+TQqF4EwcHB9knlgOhZOXMjt0x7OQEywYhKDRgSAhsbGzEcRu5BCHtmPgK8RcSHoyNGzZgzpK5GDN0NH765kdpn2zKVSgSGyX4FIrERBQQXAc3NDwMQ8cPlx6CBs0bot6nH+PchXOYPWM2vH18ULxUcdRoVBMf1ayLLm26oGjxEujSujN6DuyFUuVLYfG3S+V1jRo0gs9LXxQrURSDxwyRBc7dB/cQpUUiLCIcERGi8GHBpFAo4gwrS+HCfoZPGonqVaujcu3KqFyjMo4eOoS+XXtj3x/7sWzeUiydt0RU3A6iZZMWKFisCHJkzYGpc6dj++ZtqFC3IkaOGgF7BzvpzfP29ca0r6fj8bMncn3sqMhImQ8oG1UkFkrwKRSJSXAkihQojHXL12LN4m/k9p3Yvl/6HfJkz4UCRQpi/y970LV9F0wcMQE/rlgPV7cUsI4Els4RBcxXi9CuRRsc3X4IzZu3EIVRTezasB1d2nXBqrkrsXvjLhTOXxAlCxXHD8u+R96cueVvKhSKOBIF2exasmhJ2T3i+vXruH3nFm6J7enTZ2jRsTWmjZ6KqbOmYubXszB/6tdo3bItnJyc8dPqH8X3NfTq3Rt5cuVBh1Yd0OjTxmjzWWsMnzASd27fwacffwJfv5dwcHBEsUJF4ZHSXXbTUCgSGrW0muBdQWA60tFSl1Y7c+EsHj99jHrV6xqPxA21tNr/27sPwCiqLQzAf0iBUEIHEaX3HkoEgaeg0kFQbIAFRFQsgIqCdAQBEcWGigUQQZAivSpIL4aqICVA6EgNSWgp7Dvn7myyCZuQBiSb/5MxM3f67JQz996ZSSbd1fQ9XH72zjhCpWeEnPn1NSxafKRV8cIkLdK6Gnh5Arm0LpG0X5Mm3FoOfSef/DPf+NW/2k9H0XnoNHX8VOUgyMj8tBqlc6M/Go16lQLQ4IEH7F+eSAU9TCM9ok3AZ87/kqBp3nLwafEtsnnicli49MsC31zZgctyUxUtB2wOOQAjryPsShhyZZcDMIuMGy1jyt/wS6HImVPSpPPKpUtySPkgAtFmmlnMAapzSAU5D4wcPQKNWzyEgDoBVmLa4qfV7jx+Wo1Sre/w/qa5eu2qlUK3hJ7Xo+RidM5Fo0U7ekRqQHlWmvNWmo6jTbRcVC5Y/RzBngq10i5Lo0G/ju+YB4uLiJJNgzwfz6wSlGVHVk9fZPXylXZfeHpIsBclgd3lKGT3yQlfbwn2wuUYuy5pepzpMSituXxz2wM9PRb1hkuCwJy+EuxFyDEs4/tm9TXzyOqVTWJBHTGVwR5REjDgI8xZMg9LVi41uXxaN4xuA0cQ59w4c5WmEkt3/qtcDeeKfgUgi2YbEpGhuSZ6s6Q3Ts6NPgGvx5Xpb6XFD9b0xkxfeq5/Ha5baRoYaro2jmkklkOTSC+i5GLAl8lpjl7f4f2sLmDIx8NM0S6lQlJO0rfyRJ7Uaetw+r6+bJ6IsumFi4jSBT02tepH/G/tavUNLTa+lecPclsM+DI5zdHbE7TX6gJCQkMwZMwwq4uSRE+++pF1PRnrp5T0vXr6zUwNpvLIXz1BO4bT4hv93q1jGLnhNx9qd4yrf/XbuJrjpsPl1nY5THVcbfQioNPUdG3X3AHt77gQ6F+dto5r6h5Jfx1Oh9f56DQM6adpvh54692eGDhikH2+pniJyA2ZfVsa/avv1TOc251omnO6GccxvnO6tmu6M2uYOMeSpmm3o1+88WKmb/HOgnNn/sPcGb/hzH9yA57VPr3Vf/yJDWvXybEcf/pEN6d7HWVg0VHREhvIhdxXOvSCnYzm1KVz6Pthf/uELPr2dw0Ctx/c5XKcGxoyJ+fDhw5iw+q1CNq7F/Nnz8WJY0dx5XI45s+ai3+277ACQDncsnth45p1mD19Jo4fOWqCt7CLF7F2xSoEBx3E0gWLsO2vQDPsymW/489lf9ivC3qCz+6NS+GhWCDTXzx3gf2bnDl9cOXKZWxYtRa7tu/E4nkLMHParzKP9biuxUg+ngg5fw4rlv6OCxfO2ZdBJ5jDC1s2B6L1Y63w6befIV+efPaHQRIrXiLKyOTYQ25pcmlj3WQ52h25ZhpE6c2SvnfPOT2rDOdnNdpPxzU3ZzqcpDluyjQ3TofJYaXrjaDe1PlY4zr6ZddpS7s53OzHoz4YFXNDJtOdv2wB2j77GL6e8LUst6d5x+YLr3XGL7N+sS8bUTLxKV2RkZ/S3bR5M8Z+9AmqV6uO6/qUWDLMXTgPm7dsRqUKFc3nuFTjBxpjxaoVuPeee/FKl5dNWmL6DY0NGDPtU7p5vfHpqI/x9qDeqONfB6fkjjybbzaUK1UO/+77FxdCLmDxr4sQ0KguRgz9EN//9D0K3VUIl8MuY9pPvyBLdBZUqlsZZUqVkXjMCyfPnEK92nVx8uQJ7NzzDz4eOho93+2FE/uO4ekXn0Hw0WBESzBXpUIVzPh5BsLOh6Jmo1omrVTx0sjrlxtb/96GZbOWwl/SP3z/A3wwZjj+3bAbJUqXMrd5s2bOQO+B78qqXMXpM6excckG1K4XgDgPg8SQ/Z9P6VI6l+BTunJDrDfG7w3rY95/d+7cOZw+fxqvd3kNK9aswObtgejVrQfatGtrBv/11+n4+sevkSN7DvR/uz/qPlIPP3w2Hhu2bEKBvPnx146/8OwTzyIyKgo/z/wZTR54BH169YWn3FyFhoRi0IhB2Lx1sxyflfFB32EoVLow5vwyG7MWzjZfwjl4+BC8JRBs26QNunaTc+xVGwaO6A+PLB4Y0meo3MXLQuTKgtdf646vJNirUr4StqzeiiNHDqPWg7UxbvSX6Nj5OfsDWs4kAOVTuu6PT+lmYnVq18bw0R+iRbuWaP3ko0luqtSpZoI9fZP8l9+Ms6YGjPrkIxQoUABHjx1Fjvy5XI7r3JCdh1xI9LAbPmA4Zk+ejX0H9ptvam5avgFR0dH4fdXvOLo3GINHDkHHpzrim6++Na986Dewn/yNwnUZu23LR7Fp9Ua50GTHmfNnsPrP1Xj4fw9h2qxp5lUrH3z0gSl+D1wbiHVL12Jj4CaM+XQMfH19zdv9Wz3SEhvXb8TcX+bBL5cfFixdAMg1Yc6ieWjVpCVKlJFg75rcFEReR6GChTHzl5no/sIruKvQXSh+b3HwXWDklvSGXf7p8TDmqzEoWbIEgg8Ho9lTLWDzsEH+4eW3X0FYyEUsXrQI3d/qjnaPtkOF8hXQ4aUOOBP8H/YG7cMPU35E+OVLKFSgMDq/+SKWrlyKGpWro/+IgVi+YhlsWW144dXnMXvBbLRt1w7r/tqA9p0fx7UrVyXIO4ifZ0zBhdAQPPvss8jvlw8jPhuF6IgonDp9Eh+OlXZ9qjeHXJIl8IsKjcCe/XvQMKA+QsPCsHVrIIKC9sPTyxO1q9e2v3qJKJkY8GVwesdaqmQpVKtazXyCK6mNfpdVDR48GI0eeNC0q9o1a2Hy5MmmPauPj8txnRuy04ArT67cqFOjNnLlyiXbLisCatRB/rz5kMcvN7JJd3DQIfNNzV9n/4pOHTsiMjISPpIeHnoJOXyz4/469yNnfj/kypELAf51kLOgH/LlzmteAnv9UiTW/LUOLR5qikLFC6NEuVJo3OBBrNu0Vi4oV+Dt7SPzroMs3lmQLZ8vmj/UDMv+XIYtqzcjKPgAuj33EuAlC6rFvNei0fDB/6HmfbWwbvMGVK5QCQULFTaBIJG70mOkfev26D98IJo0aoIicqPz0ciP8WrnV3Dp8mWEnL2AeYvmIiI6EkePHEVISAgOHQ3Ggt/mIWeOnLi70N34cuxXeO2l18yrVN7v1QfD+3+AnNlz4tyFc/h36y78tnguxgwdjd59e+Ob0V9hzaZ1chO3wXw3O3dOP3w+bCw6dXkWPbq9iTNnz2D7jq1Ytf5P87m1lzq9COhbsXw8cPjoEez892/0erkHHqz/ACZMmYi/d/0twWYhlChWgjdnlCIM+DKpBx980GQF9+nTx0qJ1axZM9PvlVdesVIoKTzkv6vXriEqMkozFCSgi0BERIT53JnK5ZfL5CaMGvwhtm3ZhoUz5+PjkaPlrt0LUVHRMqzctkdITGbT73FKYKZvhbC+y+nh44lC+QviQPBB+1Er0zlw+BAKSJqXBOZa9y5C5qc5elpn6PHWj+PAoYPo1usVFL+nGBoENLC/mFmZhQNOB51E4PZA1KxeE+ZFz86vkSByJ3K8mOp5Ergp/f5tLr3pvXrdFFP6+HjDFm1DWFiYKbbVYzBv/rwY9cFIBDSoi7DwMGTPnl2OGxkmNNR8CzeLRxYJCi+am24tKTkfcsFMu0jhu83fwgUKy3BZceHCBXPce3t7yyEmB2c4UL1qDVQsXxE/Tp6An6ZNxkP/ewjF5SZOb8a0Lu2JE8fMDWHVKtXQulkrLFy+CD/PnoraNWohay5fOVZ5c0bJx4AvmZzr8xEZsktoheoLYSExwdpVCd6uSbCngXPIxRCcCzmPirWrIqBmAAaMGIwxYz/Bo0+1w9KlS823Nq9F6vAS8Mm0dHi9wGi7/tVvcHp4Z0Hv197Blh1b8eqLL+P5Ls/hv/9O4Z033zZB4dnzZ80ymGDuis3kFt5btJipy/dYq3bwLSQXOscXO5TEiH9tDcTZC+dwn3+Avd4QkRvTOq4aRCm9CTPtcnzqMWpy27P7mCAsNCwU7/d+H33e7mNKQooWLWqOMb2B0/FkDLlBi5LgzX7Q6N9rcqNXuXIl5M+dFz/NmIzwi+GYMmsqPOV6Ud2/Bq7K8a3jmJs/OQw9c3ujvdyUjZvwDZb9uRxPtXvSemhK+ssxrHUAveRGMH/+AnikcRPzMN3O3X/jvlr3AVllAM2pJ0omBnzJpAceURzXbKhZ1R9dO3ZBdp9syJc7D557ohNKFStpcgE6d3gB/lVqmFwA/dZmnep1sPKPFejQ/hl06vgscufIjeeffBZlSpQBImzo1L4jGtd/0ARuzR5qZgI2XIpC89YtMWviTBw7egzhoWFYOG0BajcIgJdcKV7s9CJqyDxMHb2o68h6jy/aNm8DL09PPNZSxtfrg1zYYkTZZF/Oihc7dEa9WvVMxXEid6VBmuZ86w2Z0vsipeka8Nmu23D50mV0f+11VKlYBVXqVEX1OtVNBfks3vYnYnUYHSPmODKtNjOtq5evIG/xAvjus+8xf/F8VK9eHT9MmYCJX01AiaqlcCn8ksks0OENiTU14NPqHiXkPNG0cVN7Dry+rkUWcfXGNahcrhJy58mL3HfnlWP5UblYe6Bc6XJmvkQpwad0xc02gXOunhaFlihRIuZO0V1MmTLF/O3YsaP5m1SO8VSmfUpXdx997Yq+GueiRFa6v/jJifuSdGuumr4KQitZ62eX9F17OpxjlwvTC5B0+MlF5bK0XpNh9P14mhmnTxrqq2/0tixM2nW6+voGrYunIqTRYfSVLTq+XjAiomWWkVi4bgn6D+yPgvkLYMX8P+ARLeM6F9nq/PWVEdnlry5DlC636eOC9OBTupTOJfiUrhVo7dj3N3L45kTZUqVxMPgQQsJCULNidZw+fxaHjh9G1TKVkD2/H8LPX8S6rRtMvdv/BfwPHlmz4MC+IISEX0TNCtVlvIvYE7xPhq8MHy9vbNu7AyXuLo7CBQub160E7dmPf4N2o0KpiihbWQK0y9E4fuI4jp85iRrlqpriYOT0wsWzF1AhoCKeavskxn7+uZw7rBx4Odz+3rcL2bNlR+nipUz3mbNncfDYQVQvXw3ZsmbTLEr7sM74lG6mkJqndBnwieQEfJSwTBvwxdD9xLEvJdSuHPtT/LSExlVJHN/by9Qx6tCtAy5fvYJxo75E+cqVJBhMyjInRIZhwEfpXIIBn4PePOk9j+PGS2+c9DVE+mJyLbi5JD31xierBGR6I6SHxSUJrPSmLbukOYbXF6pnl2NC+2mun76LTx+2iJB+ejjptLNqtzQ6L52O3lxpmn53N4cnli1ZitffexOXL1/G0pmLUbla1dhl1uEd7//T8ZWOr8sYLvPUGzedT3wM+DIFvpaFKF1wPvASalfa7SrNIX67q2FdpQm5OOXyzY750+fhj4UrUL6SBHuOi4ZL8adD5KY0WNMbHw2W9KbN8c5JLa0JlUZzzbJIT+3Wd9xdlEaDK03T4TWXXek3dh39tIhYx9VxHEGYzuOCNI7jTtM1GNTh9OIcYUPxosXw1mtvYdnMJahcVYI95/df6vA6rmNZHePrPLXunmM+RMnEgC8JNIJ298bBVb/EmsxCc3lN/U29y9bi2/TeeNnrHRma4+BqmCQ3XqYY2tPTM1P95pTxaD3ZFB2j8Y8RU/XCRdrN2pOS5pEF5WtUwitvvYJKAVVMnT2Xw8dvbjaMHKP6oAePUUoIi3QFD5CUbwvn4m53LtJ9u+dbaFirPsqVL4/oCLnLzkT0F74uMd/n4z5Dvw8GomTxEvYetxGLdOlmhg4Zirtz34X6Deoj6qpVHy69MqdZ61ybRlWGPLN54qtvxuG5bi/gvgAW6bor1uFLIQZ8sRjwJW7+/PnYsH6D+QpGZqQPKfnlyYPur3VHNs1Fuc0GDBiAYcOGMeCjBK1Zs8Z8KUNfhGzLhFUV9NOa+kTxq6++inz58lmpaUvfX1iyZEkT8K1YscJKpduJAV8KMeCLxYCP0pvt27ejf//++PzzzzFz5ky89957CAoKMunTp0/HDz/8YL5qQkS31vDhw3H69GmMHDkS5cuXR6VKlUzg0bVrV9StW5cv6b+N+NAGEbkdvZlYuHAh3n33XZOzoF8qOHjwIF5//XUEBgaaLxwQ0a139uxZc+M1depU+2ficufGTz/9hEmTJiE0NNQaitI75vAJ5vAxh4/SJ83V++ijj0y9oaNHj8Lf3x8bNmzAb7/9hrZt21pDEdGtpLl7AQEBpmqH1uMrUqQILl68iAIFCmDt2rXw8/OzhqRbjTl8ROSWNHdPg739+/ebXD4N9p588kkGe0S3UaFChcxDUydOnDCB3p49e3Dy5ElzM8ZgL+NgwEdE6Vb+/PlNPT6HvHnzYvDgwVYXEd0uzzzzDB5++GGry/5VpmbNmlldlBEw4COidO25555Dq1atTHufPn3ME4JEdHvpO/70oQ1fX18ULFDQPDVPGQvr8AnW4XPfOnzHjh9HWFgYsujb8ilD8pQLzcoVKzBs+DD8+uuvyJMnr+6oVl8iul30wamXX37ZFPHq8RhxTb8flzlcv37dlDgUKljISrkz+FqWFGLAF8sdAz59fceYUWNQpnRp+9vsKUPSXcwjSxZTh09zF6LNJ62snkR022Tx9ERkZIQck1ngJe0aBGUKcg6Kuh6FEydP4sNRH6Jw4cJWj9uPAV8KMeCL5Y4B38LFC3Fo5wHzkXJclITYRaWMRiuf6MfrM0+GAlH65C2NXibS+cdM0lx2YND7/fHEC0+jSqUqVuLtx4AvhRjwxXLHgG/p8qXYv2UPXu/RAwiRsxMDvgxO903+iER3luMakZmORVlXX08MHjEQT3V+BhXL37l6xHwtC9FN6UHBJn02zhLq7/z3Zo1yle5olKt0bRxc9XNunLnq746Ns4T6xU/PSI0zV/1T0ji46pdRGwdX/dy5yfgY8BHR7afnTw85/eT0BvJ62Zt8+le6s2mZkTWMp6c9Pbuk3eycq/19rOn5JmF4V3LLuNroHb1ZRvmbW6al09PqSrrMOax5mOWVJpd063KmZH7Jpcuj89f1TO38dHxPWX79DfSrJYlNT9dbt4vjt3Ksrza6PLottNHfLrXLdTvpsmaRddFt4FgHXT/t1nVOzbrob5VHpmX2J6I7T/ZoIqLbSC+i3npR9cTaNavxYpfO6NjpGXTs8AwG9huAEyeO2y+42bwQfOSg6T99+lQJumQcRxUCnYajcZD+fwVuQufOL2Du3NkyDRk+/jAO8ceXACbKdh39+72PAQP6ISo6SoIqL9hkdkMHD8KPk763Ty+HJ7Zv24ZXX3kFHZ55Gs891wnz58yV9ZEBs1rzc3CevjPn9JsNE6effR6bNmyQZdgiyyeBioPL4YVzd/z+XlkQERWBZYsX4/SZ07IOTtNz5uWFsPBQvN+3j2zb5/FWr144d+6MfX1lm8+ZPRtdZJtrs3jxAgnOJd3B1TIpR1r8/gkNrxLq52r8+MMlNJ78xsiWxTwF3vn5581v2vXFzli3eo2sh2wP2UYxEpq2it9P9u+LoRfR8803MGzoEFzX9MSCaudxiW4RBnxEdHvJRfS653UMGNgfDVs8gB+nTsSCJYswa/5v+GDMMNRuXAcL584HcnvgPwksfpwyEavWrpYAQwIevShKAIJ8EhAWlKaANFmlUdJ/34F9mPjLJGzauhnIJcPrMDqs5uLouJpLp4GjpmuTXxqdXmSUXJSv44cpP2LClEmI1qcPs3ng1H+n8OHYkQjT74X6eeDzL8aiVqPa+Gbit1j0+xJM/nUK2nRqi2e6PIPwK+H2oMmRC+eYh+YAOucWaS6mIydTl1+HceRgmvWTdl0ux/jaT5e7oBf+XLUCD7V7BEGHg2QYmaZZH6dhHeujEYbmwun0NXh2LI92a+6gLk9+T/Qe1BudXn0eOXLmkGESCEg8PXDl6lV8N/kH2bY/4dOvx9q3b079PTzwxXdfYsLUSab5a2ug/XdSutzO66B0+n7Srr+Jrr9jmXSdva12TYuTgynTc56Wju8InnRb67Q0F1YbxzC6HRzD6F/t1v7OzH5ow1vv9kTjRx/CxGk/YdHyJbIPTESDlv9Dn/7vIUr2U7OtXG1jnbY2mkvqvD/qsmfxwOWrV/DVj1/j51+nIouuayH5PXQY3V8d4+q0dX2cx9V0oltA9jYiotsopycmTZ6EYZ8MR8O6DRG4+i8E7zqIg/8cwNuv9kJUZCSCjwabYMZbAwGRI3t2IFpasnmZ1yNM/mESBvUdgI8+GInjx4/agxq5UGb1yWqGz+6bHYtnL8LAPv3NsCYHTnNr5MIctHcfBrzXD+/0eAvffvE1Iq5dlRl4SVjhgdx+uZFHGvMwkkxq49ZNyJUjFx5v8zh2rd+Jtwf0RqnipbBu2Voc3h2M7Wu3oUr5yrhw8QIuhV+yzyOnF/7asBFD+w/G4PcH4o+ly2WB5GKf1cu8xuLHb77DtJ+m4lBQEEYMGY5hA4di146d9qDGxxPXrl3B12O/xGBZv2EDhmLn1u0SLHhjx+btGDRqMC5dvoTpc2Zg0cwFia7P+XNnMXrYKKxZuQqBGzeZZflk5McmXX+DX3+chp9+nYyLoSEYKoH2vr/3yPaV5XQhiwRNuXLkRE5pcuXMaQ/4ZHFPHjuGoyeO4q6C9tdU+GbLZv5qcLVz+3YM6TcIHwwYgr937LAHXD5ZMOOXafjuq2/t6z94OD7+8CNcjbiM8PBQ066/6elTp+yBkf4Ofl74e/sOsy30N1/w2zz7ckoQdvnKZXz92VeYPX0mZkydbrZDv3ffxzefj5PtKNshqyeioqLwxZix+HH8d/bpaQCocnhi1syZ+PTbz9Dwvgb4Z/PfOLznMH6fsxzFixbD+ZDziLwcIfP3xL5/98Rs4/FffmOftgb3PvKbyo454dsfzLLp9j17+j+ZtsZ8HsibJy+KFC6CI4eDMazfBxg55EMcP3rEHuzqviLLMG/2HLOffvbRJwi5cE7SpB+DProV9CndzEpXP5Nvghgp3RaO8bSZN2+elZo+LFm2xPbFiLE222XpOBFhs51kc8ebs9dtV45fstWuXsuWO1du2+Edh2y2KPl9Qs1PZlw7c9Vmi5aWcJst8PdNZt9655VeNpuMfv7gOVvLR1rE2e9K3FvctmbBKjPuzO+nm7T8efPbsnlnjRmm92tv22wy2b2B/9oK5itgK1+2vO2xVu1Mv06Pd7RdD79uu34myla+TDlb5XKVbBFHZaeR5ZIA1Fa35n1mH3qty6tm+J/GTTTzsp2TJkyW6cBZW+Qpmfh56Zb1+GLEZzYfb++YeWvTr+f7Mux1W9SJazYJEG1eXl62oncVjelf/J5itv1/7bNFno+wPdH6cZMmAaj5K0Gsbc3SVbafvpwQM7w2L3d6KdH12bfhX1sWjyyyLfLZ8uXJGzNey4db2C6dDre1kr+ONG1mfDfNfqzE/81kvc7sPmWWt3zpcranHn3S9nDDxmZ7zpk821axTHnbi890NtMY1f9D3TK2eVPm2CTYiZm2ti+ettD8rs0aNzFpJe8tEdO/TbPWtv/VaxjT3bbZo7Zruk2v2WyTvppok0Azpp82r7/Y3RYdGm07t++M7e677rZJQGrS/XLkslWS30/b/5z7h1mWTUvWm+4Xnnre/F62U/LDnpHf4kykrXGDB20S3Ns2LFlnhjW/qfyGp/eekmFkYWUf3L5qq2y/fLYK5SrY2rVqa6bVqb1s43PRZhod2j1t0hxN1YpVzO9y8cA5W7G777EVKXyXLFPFmP73+QfYLkg/nXa/Xn3jjBtQs44teJscExeu3/g7sLmDTaTNFmKzDXpvgG33nt32feUOmT9/fpx9JjmYw0dEt4+nBy5cuIADwQdQtUIV3FO4KBAGnDx0DD9/OxlTvvsZs+fPxu9zlpkcPglYzGj64mXNUfrk8zFYuHwRunTsjH+2/40p439G8NHD6NGnJ6IuRMBbi8SEBDhYPHcxNq7cgEplK2LMuE+wK/AfBO3dj1ZNW2L9krWYNXe26Td3yTyE/xcKD6c6bPp1j+gLUVi9YQ3q1KwNZAN27/nX9CtfqhxwSVoiImXZI5E3T354efrISMD2wC14e+A7kCAEKxb+ga2btqBe7boYPvZDk9PnmdMHeXLnNrlOr3R+GX9v+xtPtG6Pw8eOYO361fjv2EnMmD8LdfzrYP0f6zD9+1/w9KNP4MiBw2j/zFN4+7W3zDKMGjgCH44amej6+GbzhV+uXIiIiMB3n49H4Nq/IMEZFv6+CHv//hfffDseEpwgt58fVs5bgWbNmsv6aDZqQmym2LvhffVx4PBBhBw5h23bt6Ho3fegVImSZggfn6yIOheBt/q9LdvECxt+X4+1S9eY0PW9wX0QEXIVBfMXNMO2f7Q9tqzfYnJI5y2Zj5LFSyJw3V9mHeYvX4Azp0/j6L4j6NG3B7LLuiyasRA7tmxHs8ZN8eUP4zBv9m/ImTMH8vrlMTmn34z5Grv/3o0fxo4301+4bJH9r6yvelH2GS0dhqyDKXINu4T9hw5AAmbcU+Qe+7s69Te9FImCmmOpxeJRNhw5fBiPtmgt23gNZs/9zfz+85fOx9VLV7D09yWY+ts0SACIf+S3fOX5bjhy9AiCgw+bfUhfUPyfrMfr3V6XfWM75OYBm7ZtxsFDB7FTuod/OgItH26Of7f/i3Eff4nNW//C2K8/lQ0pC6q5kURpiAEfEd0+cg3Vz9xpEaE+GGGKTnMAW3ZswbOvPIdO3Z7FM106oO/QvvaAT+tHCU+tg3cZWLB8IfLnzY/Rgz5C5WpV0OGFjujw2NPY+s82HNwXJAGHBF7i1S6v4sHmjXDfg3XNhf66zYY161ahhVy4e7z2JsZ9Pw7+1f0RfOywCcCu2+IGOlm8vXH08BFTJ7Bx/UamONlT68SJK1evWIGD6TSBngaykFmvXr9GYoZIDHx7ABq1aAz/gJoY8u5gM9jSlRLEyhlXA7ACEmS81a0nqtSogkeb2d+pde3aNeQpkMcEFH9t+wsdOncw9eJq1qiJVq3bwDefL4oVLWaGLVeyDPIVyZfo+tjkv8tXrqDBfQ3w2NPtUat+bdwfUN+Mfz0qGkVLFkWunLkkMPNGzco1kDOPn6ynbPSEmPwEoFb1moiMjMKqdX9isyxnjcrVJWiyB3H66a0Th47j2Mnj5oso/YcMwIChA3BV1m3/of04dfykGU5/zy6duqBmvZpmfNX79XdQ6/7aqFyhshk3KioSgVv+QkjoRbzT/S00b98C1WpWx9A+Q8zwC35fiGhZT92eZUuVRdcOXVC02D0SoAfAX6Y5b8kCXAw+j3mL56GCBLr+NWrJRjajGrrvaVB6Tca/FiE9bvhN5X9Xr6N167Z4s3sPfPWdbuMaOHLyqCmq1f143eYNZvAXO3RGZfktPx32KfZt2YcmLZriUmgYLl+9jOpVquPVF7ujeq3qeOh/jc3wV69cxvad20z7/kNBeKPHG5g09SfTHbg9ELYruvPz8kxpi3sUEd0+UdeRv1BB1KlRxwRpmqOhOXeNH2iMlUtWYt60OciRPYc9uDIZHI4rsEXSNEY0vWLYu5zfPxqhF3CL1udThQoVxqdfjEHNBrUlkJqI5g81Q5mSpREpgYXzC8QNCd60/p4GBP7V/E0AULFcBdNr+64dMlFpMa/y8MaR4GCc/u+UWQ/H8jpPLrbd3s8mC5rd1xfXPeSiLknmiWChgUeOIn5YvnA5er3cA3cXuRtrN65Bj35voVfvnibo1PqNyiyv/EvK+mhQZ75QInGqTXO3hId+W/qqTDJKgm6TImJHcUmDZg3oypQog6KybJqzFSTBSu0atU3dR+X4DXRdSpUohR5v9kCPN3pi7oy5WPTbQuSTQFcDW12+CPkLXR1rvjp9O/tfvSmIFbtwMW3W4PonW9asJvBDiPxUft54ou0T2HdwH36c9COCjxzGc088ixwFcsp2sD4PIYFt9lw5UE4CxYthF7H/4H5A4l3zm8r4+/bsQZika/29MZ+NtrbxJLR4uDlKFy8lQb1uUFkSa5m1/qfKmtVHguxL5mbF8cNn9Zad6Zr+eDJba/ubnGtr+Rs3bIQ3e76B/u/1x+/y248e9rEMLwNnls+W0W3DgI+Ibp/oaHhl90b3Lq+aC/TjnZ/A3F/m4Pj5kyherBi2bttqHkqI1KK12Gu8jCYXQAmymjVqirPnz6H3kHexe8cuTJ34M36ZPQ01q/qjVPky9vHEl999hVVL/sSmPzfii++/gqcED1XLV8Y0GVZzvjat3IAPR44wOWB64TU5iEovwtaF+s91q1ChbAXcU/ReExw99/RzJlAbNuZDzJgwHXsP7MXiBYtQr+n9+F/LB3B83xE83OgRE6gMGT0UKxeuwNZNWzFwlD2Hr2mjZiYQ0MBGi6g9NKiV+WkAqPTBlEOBQXi77zvIlzcfvvn8G3w8dLTpt3P3TtkIGhzacyKDDh/A8aCjN18f4eUl7daZ3jEve7CiDydHIVKCyMC/t+Li2QsyotNGd0ED6fwFCiDAP8AUPZ86fQp1atXGtUh7gB0lgVCRkkUlKCyFIAmi8st6VCxfHjNnzcDmTZuRM3dOs7zKsSyOv47vsjq6NTAMqBWAnNlzYvS4MVg0YwF2Bu5A/xEDTf9Wj7SSxfWU4a+bcWPWTXaVZ9o+bYr1B40eAi9vLzzWup1JNyutZDtmyeaJl557yXRqEfSyOUtNju7PkyebJ7GffPEpXDh1FjPnzZQhrsu+tAHDR8g2vnQZNvOeFaB+wP3m75c/jjNFugNGDkSFOhUxacJEZJcbFw1sddkcwaxjGTXw869e07Tv2bcX1apUg48E0xN/moizp0/Dwzy4YS0rURphwEeURJqzs2TlUquLUiw0Gq0ffRTffPy1KUpr26EdyvmXR6lKpTF41FDUrOaPAe/0hz4lqxd9FX7pkrlg93ytlwROTfDDlAmo7F8FHbs9i3vvuRefjfgM3nl9zLvPDIlbtEi3bqN62L3/X/R/ux/KBlREm2ZtzCW/Q5dOaNGqOY4eP4pzF87j9NnT5mwYGhpqnvwMOXUOS/9YghrVasAzj1x8L0ahdv0ATPhigoxtw5NdnkYF/wpo0b6lGffRlm2QP39BVKpWxdSvO3byBBq3egi16tbChsCN6NezLx5q+giiwyPMPC5evChBgwQ4Ms+rVyWaFOGXwlGgWEFTd23AyEGoel81vNr7NfNk7OsvvW5yEEsWK2GGfWfQe+jRo0ei66PxguZEhYaF2oNnaTSYVqYIMxtQuUIlXAwPxUNtH8Yv+q5DP3sRenwatOiTyBqke/h6oXTJUiZ4KVSgEO4tUVwmbQ8UQy6GwDu/Dz75YIx5tU39hxugvH9FfDtxPArkKQj4epjfSHM1tR6jjhYeHm7GNd0izOoODwtD0cr34pNhH5tcs5ZPtkb1OjVM0fhrL3ZHm8fbyriXcCHkgpmvCaZ0Ma5Eo0TZ0rKfNEWYbNMA/zooW66crHS8HLNL0Xj8yfYYPeQjUyexabtmsqzlTdUCLwm+WjZtCb+78uCRBx+xb+POso1bN8fx/07INj6H4CPBaN66BZ557GnMXDALVWtWw/BPRqBA/gKoULGCrH80zp8/b98nrWXTfUvpMletXx3v9+iDP9evkuUtiaaPNcfK1X+iqNYndMqhJUor/JauyMSbIEZKt4Vz0VH6/pZu3ByjlGjeobXJ0diwcA2yZbVeP0HJp7uYp0Q6uTxx/MARTJs9HaESdOi+51/FHy2at0DWHL7mAn3i+HH8OG0C6vrfZ3LP9FUWUdciMXXGFFNkp69M6fhER9xTshgQeR27/v4Hc5fPR7umj5oiYw32alapgccff1L6R5tSsikzfsaWv7fiPv8ACaBKYvmq5ej4eAeUKlUa30z4Bj7ePmjTpBUm/ToZTR54BFWrV5OoLFp3dllmLxzZF4xffvvFXLw1J61Vk5aoWbeOBBAycT1+cnpi05oNWLxisczPZl4980iTJjJ/G6KvRmDSjJ/MO9q6deoKn1zZsGPLNsxZOg/NGzVDQIN6iL4UiYm/TMTh40fMLtv0wSa4v2FDswzR0dcxeeZkE6BUr1gNj7V+PMH1KZS/EL748StUKFMO7do8Zjb9/EXzsWP3TnR+4jkULXMvjunDMrItr167IuvcGjVraj03ey5iDE9PXJbAafzUH+An27vLs11wODgYP8+agnKlyuGJ9k9h367dmDb/VzxUvzHqN2gAff3K5rUbseiPReZ3bfZQM9T7X32JeKIxY+5MUxTc+ekXcFfRIpgzbw527duFrs90QeFiRTBr5iyTe/ri051R+O4iEphmMQ84zFk8F5ESwGruYuvWj5rc0sshoZgwfRK8vLzQ+ann5beTuwR9+CYfMHLAh+g7rB8+/3As3nhbzgHn7bm/MXQ/1NzPHDr9HZi7eI4JRLP6ZMNT7Z5E6YplJXi8jqjIKEyZOQXbZH+qV6suit9bAstkGz/d5gmUq1oJ0ZcjMWnaTzh45CBy+ObAU22fRKnKZRB+IkS22ffIkyuPWTYPX0+s+OMPrAtcj2faPIUylcrLOnhgxqzp2PHvThk3O55/5nncfa8EfOGpP19RWpIfQ250Mvq3dBnwiUy8CWIw4EvcnCXz0K5ze9P+6dCP0fOlN007pYb8INm8zEMbMb+NXpM1EypKWnRX1C9y5JGeV6RdL4LK21sCL/mrpZY6jA5/1Rpe32+m/TRNX8mnGVY6WqgEMRrtaTFqbgk2dVythqWZPhq7h8jIcmE3L9DV6ejweWQgzZC5IhNw3nd0Hs7LrMsmgYyZvqbpMaFfm5CY1dBMynCn/ppjqH8vyPw0LbuPBIk6jDQSPJivP+hLo3UZlWYAXtJhZcE0UM4tPbSfTleDzITWRx/AyCc9ND3U2nb6EmhHfy3+zibz1u2ly6Pzj7+uSreH1qfLK9PS6V+QYfQdeVrnTSer3bpNtFu3uwSs+hSsvgswZhvoNtJ10POLeR+fdF+QiUkQbrr1t3LVHSXdju1pr4ppX59w6afF27pc+jsp3Z4SaAYdCMK0edPxw8QfEBIagh2rtqNYyRL2dYvPrJtMX1/G7Zi+ppnf3VpeDQr9XGxjzUy+Jgm6P/rJNLS/jqvbQOelxeP6aTUdXs8/+le3v26TUGl0n9V38fnJiDKYGVd/A02XUSk9se8jDPgyMAZ8sRjwJezqtavwf7gO9gTtNd15/PLg3zU7cVehu0w3pZLzLufqN9L+CaWr+P2ch09s3OQME5/2c7jZMEmZtqtuh/jju5qu8/gJtTvET3M1PVdcjZdYt0po2mk5LWcSLC6ZtwjNn24pcZonvh49Dl1f6hYbbCbGubereTgvU1KXL6HhkjIupSPyw7hBwCe3F0SUmG9+Gh8T7CnNNRgyZpjVRammFzlH40pi6a76Oae5HFcSnW5UXA8jEkpX2s/RJCSx/vHTXXUnNL6rdOfuhNodXI3rarj4XI3nzNU0Epp2Wk7LWVg0GgbUx5Y/NmPn6u3o2lmCvctJCPaUY/oJzcM53dUwrsZNaLj4XI1LlMYY8BElQuvs9R3e3+qy0/p7GgSa13NQBpX0u2LKQKKvI0fOXKh5Xx1UrFoF9teb8LcmUgz4KJNw3EInr9GcPC3SbdvsUem2e+/13ubvq++9Lv93PR6b9NwoV+lsMnyjObdadzFMAj1TjCvJroZjwybZTcbHOnyCdfhSvi3Scx2+RYsX4tDOA3jtvTftlaSTac++PahYpyKyZcsm0zmEIuWKmPQr/11ByWolceq/U/htym9o26qtSSciIjeklzlfYFC/AXji+adRpVJle/odwIc2UogBXyx3DPj+CgzEJ6PGoHLFSnC81DU5gg8HY8LPE/Fwo4fR8P4GGDTc/gLdIf0GmycBJ0/7Ga2at7J/a5WIiNySvmdS36t4MPggRo4ZZb6Cc6cw4EshBnyx3DHg03U5dvyYebFr3M80pUyF8vZPa+3Zu8f8JSKizEEzDfQLOIULF7ZS7gwGfCnEgC+WOwZ8aY37CxER3Ul8LQsRERERJYgBH6UZ59w+IiIiSlupuc4y4KM0o0+zEhER0a2Rmuss6/AJ1slK+bZwvtto2LAhihcvjsjISCvFvUyfPt38feqpp8xfIiKi28Xb2xtHjhzB6tWrrZTkXbMZ8AkGfGkT8BEREdHtk5xrNot0iYiIiNwcc/gEc/i4LZKC24iIiDIq5vARERERuTkGfERERERujgEfERERkZtjwEdERETk5hjwEREREbk5BnxEREREbo4BHxEREZGbY8BHRERE5OYY8BERERG5OQZ8RERERG6OAR8RERGRm2PAR0REROTmGPARERERuTkGfERERERujgEfERERkZtjwEdERETk5hjwEREREbk5BnxEREREbo4BXyYVHByMRo0aYePGjVZKLO3Xrl07/Pnnn1YKERERZWQM+DIpDeo0oNPA7urVq1aq3auvvoo5c+a4DAaJiIgo48lUAR9ztWI9+OCDqFGjBk6dOoWRI0daqTCB3pIlS3DXXXehZ8+eVmrmxP2FiIjcRaYL+JirFWvChAnm76hRo8xf1atXL/N3xIgRyJYtm2nPrLi/EBGRu8hUAR9zteLSbfHCCy/ECWY0yHGkZ3bcX4iIyF142ITVnils374d/v7+JvfKEeiUKFHCBDqa45XZAh0NZkqWLBkn6Nu2bZsJdIj7CxERuYdM99AGc7Xi0lyqQYMGWV0w24DBXizuL0RE5A4yXQ6fYq5WXLoddHuEhITg0KFDJgikWNxfiIgoo3MZ8PXt2zdOnSUiIiIiSt+05MnxQGZ8LgM+Dw8Pq42IiIiIMoqECm4TDfiWBx81f93VumVL8d+xo3isS1crhShh3F+IiCi9eqTEveYvA74ERFy7Bp+sWa0uosRxfyEiovToZgFfpv+0Gi/elBzcX4iIKCPK9AEfERERkbtjwEdERETk5hjwEREREbk5BnxEREREbi5VT+m+1rI59u36x+oiIkp/ylWugq8WLra6ko/nOSJKj+Kf227pa1l04raTEVYXEVH641HEJ1WvmOJ5jojSo/jnNr6WhYiIiCiTY8BHRERE5OYY8BERERG5OQZ8RERERG6OAR8RERGRm2PAl6EswctFfMyTOXGa3kus/pYV3a1+3ZG8l1HETv/lFVZSSiVrGeKtV7z1WdzbqV+y14mI7rhDX6C+8zGuTesvEGT1vuPM8t3ic0uS5sFzId06DPgyiKDxD8gB3gbjre44fm7jXgf/nv1OF4Ig7NtjtRJRhmOClPvfxnqrO0bg2ygrgUuqby5TS29OXS1fWkrpPHgupDTEgC8jkJNF2UEb7O2d5pl3gjma/UPq2dPxPVrEz+nLgO6vLesTOBMLD1kJcpLbHWilE1GGojeqLX62t3ebEnvesq0fg/vtyRj/aTrK6UtHeC6ktMaAL90Lwmeffm9v1WBvdDN7u6VMt1VY1ElaXPS7wQ3FKg/gs5iTSXwy39ZOw7oIJuMWL0iTBkU0VVq3lwvBBux2LNeh/dBvHFSpUNneHY895zN2GeqPd1qCmPXV9XQuKrHWO872cJFDetPtFbuN6o9fEnd7WU383IuYbeYGwTlR4oKwcL79RvX+IbvxbWPTalfyDUzSm9XaY7B//hsoYyUbNz3unKuexDtP3XAcxysi1cbp2DPHY0fr/Ko3za76O48b5xyXtOW42TwSwnMhpTUGfOndocX4Ve7qgHoY2911QNd8tNwx3yzYc1mksAE973ddpDK+YyX0NPO1aLFxvBOh4849hhbRpDboK1MWVeTPP0H2qQQtnynL3BVtm5vOOHQZYnI+LesHVYp7ojN0PZ2Lw+3rHXd7yInYedmTub3WD2rjtL26opsG4WL8YueT2RLMceR2NL/J70WU0Tmdu558JE5IZ+jNqi1+sJfa81Sc41gDGxfVYOKdyxKSnHNc4suRQjwXUhpjwJfeHfo33oGWEnLic9xhOhUJm5xBMb6jizs6vfOONxx+HhFzNzjMHKwShK63DxNTtBz4L/bb21KoDCrVlpPGfvvpZv9+OYnVroiypstJzDJ0xSJrOR3FROsHfXLj+ljrHVsELuKnxSx7CraX07awnRyHb7tbRVY/z4sddsU8+4lWtm1v59wOIneU7HNXGp2nHMex43hzdZ6y6saZm+UpXe1pjnOJ3jwn9xyXyHIkOI+b4rmQ0hYDvoxK77riZZkn+OCG84nPKZew+eh56GbavseceHdq3XrF3nk3dxywcldnihdKvoF15mBehR6wZ/XHv7tMuTIoV0H+mBOyVUm5Qtm4uQDCfrerrCISbWLuQl2sj3UXWaaMozgkdlvEpllSsL3QqS96lLTaVcnmeFJO1jrsMOsue/Fi+4nz/tbNb1gfokwvteep5o6gylKyYsx5y+Ri6Xlqf197IBI/ZzG+ZJ7jEl2OFOO5kNIWA770zumkFVOXI8Uqo5zzgejEUWxgVw+V4hyw9qKFWE71VW7I6k+9smXlLtNUVrYqKZdN7SnBaX1itmdSJHV7uVrGMmjZ2n63vH7+YtlijiIM18VbRG4nWceas6Qfd4mSoK2/I7fNwbzRQM5bNy3SvbXnuKTiuZDSEgO+9C7m7iheHYjG46ws83hZ84nahX0JBI1VyjgfePGCS6uycIwVn8TU0XA8eZf0Zbi5Mo9YlZWXW5WU4yxbPE5FKc5NnAriKZbU7eVamW597XfBesIe7yjCaI+WCZw4idxKzI3iBvy63EWgZkopXJVKpO64c2aKU+V8cMP5yVE9JSG3+ByXVDwXUlpiwJfulUGPXlYRgcvKxksw+mbFqY3bWNnvG9BzXOz4i3s7Ku92Rdt4JwXnuhmLxznucO3DBQXtMl2x48U+jeeyjklyWReK8YN0vjcum7KfCEXg2xjtKFKIKeZOoGg7qVKwvVxrhrYmh0GmM8hehOFc9EPk3pqhtxUk6QMEcSr461Ofpm6YFkNax2uaHXd2sU+tPoCFj6yyB0BOr4NJzC0/xyUVz4WUhhjwZQSNx8XeXTqKJGKa2Ceu7h/yFlw8wCViT7zO48e+H2uci/Fi64PEPKnWqY0ZLraeh2MYpyfUXFVoTjZ7ZWUjoZOrU3HN+I7WtrAqFye8HZIqJdvLtbj1eZJ3wSLK6GJeGyVijlNtnIpJY4+ntDvuVEyukgYZVh2+mPm6zF2yzmdyU33rznGx80gangsp7TDgyyDMKwxOOirKxmM9PbWuW8L3S2b8G+5u65mnqVxl+XebEnde+h6tmCfLnANQZYoSEqnEm2xWZWXlopKygxbXxDwRZ9HlTGw7JFVyt1eCGr+FsY4TthUwE2UmpljVVc6aVQTpfDyl2XFnNMO3J3fHHn8OOl/nhzbkfBbnPKIPSaT1Oc7VPKzWxPFcSGnHwyas9hgeHh7m7/Lgo+ZvQh4pca8JNIgoIbHvAtO6QMm/aFFqaY7Ezc5lieF5jigt8FyY1uKf2/RcpVyEdQZz+IhuhZg6NFaRe22+b4qIMiGeC9MNBnxEt0KcVx50xaKbvfeLiMgd8VyYbrBIl4jcGot0icgdsUiXiIiIiOJgwEdERETk5hjwEREREbk5BnxEREREbi5VD208Vq0KwkIvWl1EROlPLr/cmL0zztegk4XnOSJKj+Kf22720EaqAj4iIiIiuvP4lC4RERFRJseAj4iIiMjNMeAjIiIicnMM+IiIiIjcXKIPbRARERFRxpGshzbq1q1rtRERERFRRlCiRAmr7UYuc/iIiIiIyH2wDh8RERGRm2PAR0REROTmGPARERERuTkGfERERERuLsGHNvz9/bF9+3ari4iIiIjSsxo1amDbtm1WV1wJBnz6Lj7blWiri4iIiIjSMw9fz+S9h4+IiIiI3AcDPiIiIiI3x4CPiIiIyM0x4CMiIiJycwz4iIiIiNwcAz4iIiIiN5fq17JUv88fO3futLqIiIiIKK1Vq1YNOza5fseeQ2KvZUl1wKcTPxy61eoiIiIiorRW3K/mTeMyvoePiIiIKBNjwEdERETk5hjwEREREbk5BnxEREREbo4BHxEREZGbY8BHRElwFD8+XNM8JfbYuKNWWqyVPez9ij88FcFWWpo7MBWP+Q3HSqvTtbXoq8vhaHqstdLtYpbTNDebFhGR+2DAR0Tp37LhKO7/MbZYnUm264hTAHoUh3ZZrUREmQwDPiJyS7UCqgGbl2HFASsBh7F/MxC4aYfVTUSUeTDgI6JbxxTDOhejvoAfYwIwh3jFsNo4FcWaYtj2s6yuWXghXv+ElH+sCWphJ/Y75nfgCPbKn4JHh9q74wke90KcZYhTdB2zHrr8zstrrU+c9XRRVHzT7eBcZL42pt256bvMGtQSUzydhG1BRMSAj4huDZfFsDsxxN85eNHg6U1MtbpiTHgz9YFMmWIoL3/2BtkDt+Cly2RZHjft8Wnw9ECfuJ+I3NLnURf1FXX5nZfXvj5x11OCUue6jEnaDrG29HkTQzZbHbK8HTrb26YudN4ea7Fsgr2tQ8sG9hYiokQw4COiZNFAKH7u0wtW8BFLAjlHrlznz83nF7WZ6Ahe2lu5YMtWWcFTNQzaZh9m1chqJsVR/67RZ5I+0xGoPY6JOq3PkhLkFEfZAFnevYdN16G9EtAFlDTtcRyYii/M8lvT1mbbO6glKVv6/HRjbp21PjHLqeKnbT6EQ6YlidshjthtcTi0H0a8aV8WTFgVO6xjuwW8g5ebmBQiokQx4COitOccyL0ZG5w1+uxzdDBts7BMc7dKl7QHM46cMgkeH9jb1R7s/N4BJUy/lLoXJSvLHxM4Wg9sVC5m+jiz5/wpq7hYm5gcOWs5nThy1EqUKWv+Oq9jbJolqdvBWeeu6FLaalelG6KVBK467BdWjuPKhfYgstZjDVO5jYgos2DAR0TJUmvk3JicKkfjyLG6UVmUdA5enJii1tId8Eb8cbU4V4OuNKibVrK848EN+wMbtcoXt/qkVDWUdaxPTLCaFDfZDk5uXMZ70fgxe87hltlrJHh1FOdWQ6um95p0IqKbYcBHRLfQfhy64SENu/Jl7MGKKbKVoDFOEama8L2LBzySp0RT68GNpfYHNhzzdCngHayKF8hqMyJNikxvvh0SU6J7V3uOoAav4xzFuU3QOIEgkogoPgZ8RJT2mjxgFVnuxJDPY3PqVvZwPPDwOJpIIBX7ZOwLWNF0oj3IsurPpYnS9gc3pvbRIlr7POOzB4Vi88f41lG8qg9amOVK5cuZk7gdbq4BmpicUJlOH3txbod3U1vkTUSZCQM+IroFGuBlR46do4hWGsfDHR1m9kMj+RuTc+VUhy+m/pzLHKykv5bFzv7ghhFQEi4e2YhTrDy1vbUM1oMWtUY+Z5Yz5ZK2HZKiUUvnJ4yTGigSEdkx4COiW6JE94kucuvsT6DGFpM2wIjQuRjkCMoctHjV+aGNJv3i1hOM8wWNxFgPbqjKxRLMEdNi5fj1ELWu4uzuqa8jl7TtkARNnovdTp0fSGUgSkSZjYdNWO1xeHh4wHYl2upKmIevpymGISKiWyn2nYUdZqZV3UIiyii0dOBmcZnGZAmEdczhIyJK12LqE1r1/vjuPSJKAQZ8RETpWZzXvzyOial+PyERZUYs0iUiIiJK51ikS0RERESJYsBHRERE5OYY8BERERG5OQZ8RERERG4u1Q9t5LkrHy5evGh1EREREVFay507N0JOnbe6XEvsoY1UB3xEREREdOfxKV0iIiKiTIwBHxEREZGbY8BHRERE5OYY8BERERG5OQZ8RERERG6OAR8RERGRm2PAR0REROTmGPARERERuTkGfERERERujgEfERERkZtjwEdERETk5hjwEREREbk5BnxEREREbo4BHxEREZGbY8BHRERE5OYY8BERERG5OQZ8RERERG6OAR8RERGRm2PAR0REROTm0jDgO4DPGnnCo9HnCLJSYiXWL+WCvmyA+l8esLqIiIiIyJUMnMO3BKN7b7DaiYiIiCghLNIlIiIicnN3NODTIlkPX8+Y5obi2aWvxOnv4fsKFmv6gc9R37clxkvr+t7lYtOJiIiI6AZ3LOBb/LonyvYGxv4TDdsVaf75FJDgLSbo06Cu7XfoNsfqf2Ufxtb9Di20HmDpN7HuykJ0k8HuH71P+n2D5vaxiIiIiCietA/4NvZC2Ti5ctqUQ8+NVn8lwdywHzRYm4Qepa00CeImja6H9b2fx2ca8wXtxnq8hLZN7b1lAPRYKYHfyjdRxkohIiIioptL+4Cv7qfYb3LknBvNnbP6KxPM1cOTzR3Rnl2Z5k/ifmzAbn2Ut0wlaf8OLSRgfHmpvT8RERERJV/6fWjDFNvaA8XxbWNzCxn8ERERESVP+gr4TM6fM6sY1ymXUIM/Bn1ERERESXdnAj5TXLsBvy6O+1Ru0P5/5P/1UMllJT0J/r7/VMYjIiIiouS4MwFf6TfR/0V9pYr1gIY68Dme1xcpv9jf/iCHeSVLg9j+Imjxr6bun+uAkIiIiIhcuWNFus2/jMb+0UDPKlb9vCq9AH3FypfN7AM0/SZuf2nsr3FZaz3Z2wy9zVO9fA8fERERUWI8bMJqj8PDw8PUnSMiIiKi9E8zxxII69LxU7pERERElCYY8BERERG5OQZ8RERERG6OAR8RERGRm2PAR0REROTmGPARERERubkEX8uSN29ehISEWF1ERERElJ7lyZMHFy5csLriSjDgIyIiIiL3wCJdIiIiIjfHgI+IiIjIzTHgIyIiInJzDPiIiIiI3BwDPiIiIiI3x4CPiIiIyK0B/wdoKFOTqlBZYgAAAABJRU5ErkJggg==" alt="memory regions"> |
| </div> |
| <div class="title">Figure 4. The named address spaces exposed in an OpenCL Platform. Global and Constant memories are shared between the one or more devices within a context, while local and private memories are associated with a single device. Each device may include an optional cache to support efficient access to their view of the global and constant address spaces.</div> |
| </div> |
| <div class="paragraph"> |
| <p>A programmer may use the features of the <a href="#memory-consistency-model">memory |
| consistency model</a> to manage safe access to global memory from multiple |
| work-items potentially running on one or more devices. |
| In addition, when using shared virtual memory (SVM), the memory consistency |
| model may also be used to ensure that host threads safely access memory |
| locations in the shared memory region.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_memory_objects"><a class="anchor" href="#_memory_objects"></a>3.3.2. Memory Objects</h4> |
| <div class="paragraph"> |
| <p>The contents of global memory are <em>memory objects</em>. |
| A memory object is a handle to a reference counted region of global memory. |
| Memory objects use the OpenCL type <em>cl_mem</em> and fall into three distinct |
| classes.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Buffer</strong>: A memory object stored as a block of contiguous memory and |
| used as a general purpose object to hold data used in an OpenCL program. |
| The types of the values within a buffer may be any of the built in types |
| (such as int, float), vector types, or user-defined structures. |
| The buffer can be manipulated through pointers much as one would with |
| any block of memory in C.</p> |
| </li> |
| <li> |
| <p><strong>Image</strong>: An image memory object holds one, two or three dimensional |
| images. |
| The formats are based on the standard image formats used in graphics |
| applications. |
| An image is an opaque data structure managed by functions defined in the |
| OpenCL API. |
| To optimize the manipulation of images stored in the texture memories |
| found in many GPUs, OpenCL kernels have traditionally been disallowed |
| from both reading and writing a single image. |
| In OpenCL 2.0, however, we have relaxed this restriction by providing |
| synchronization and fence operations that let programmers properly |
| synchronize their code to safely allow a kernel to read and write a |
| single image.</p> |
| </li> |
| <li> |
| <p><strong>Pipe</strong>: The <em>pipe</em> memory object conceptually is an ordered sequence of |
| data items. |
| A pipe has two endpoints: a write endpoint into which data items are |
| inserted, and a read endpoint from which data items are removed. |
| At any one time, only one kernel instance may write into a pipe, and |
| only one kernel instance may read from a pipe. |
| To support the producer consumer design pattern, one kernel instance |
| connects to the write endpoint (the producer) while another kernel |
| instance connects to the reading endpoint (the consumer). |
| Note: The <em>pipe</em> memory object is <a href="#unified-spec">missing before</a> |
| version 2.0.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Memory objects are allocated by host APIs. |
| The host program can provide the runtime with a pointer to a block of |
| continuous memory to hold the memory object when the object is created |
| (<a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>). |
| Alternatively, the physical memory can be managed by the OpenCL runtime and |
| not be directly accessible to the host program.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Allocation and access to memory objects within the different memory regions |
| varies between the host and work-items running on a device. |
| This is summarized in the <a href="#memory-regions-table">Memory Regions</a> table, |
| which describes whether the kernel or the host can allocate from a memory |
| region, the type of allocation (static at compile time vs. |
| dynamic at runtime) and the type of access allowed (i.e. whether the kernel |
| or the host can read and/or write to a memory region).</p> |
| </div> |
| <table id="memory-regions-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 1. Memory Regions</caption> |
| <colgroup> |
| <col style="width: 12.5%;"> |
| <col style="width: 12.5%;"> |
| <col style="width: 18.75%;"> |
| <col style="width: 18.75%;"> |
| <col style="width: 18.75%;"> |
| <col style="width: 18.75%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"></th> |
| <th class="tableblock halign-left valign-top"></th> |
| <th class="tableblock halign-left valign-top">Global</th> |
| <th class="tableblock halign-left valign-top">Constant</th> |
| <th class="tableblock halign-left valign-top">Local</th> |
| <th class="tableblock halign-left valign-top">Private</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top" rowspan="2"><p class="tableblock"><strong>Host</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Allocation</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dynamic</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dynamic</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dynamic</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Access</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Read/Write to Buffers and Images, but not Pipes</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Read/Write</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top" rowspan="2"><p class="tableblock"><strong>Kernel</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Allocation</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Static (program scope variables)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Static (program scope variables)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Static for parent kernel, |
| Dynamic for child kernels</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Static</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Access</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Read/Write</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Read-only</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Read/Write, |
| No access to child kernel memory</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Read/Write</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <a href="#memory-regions-table">Memory Regions</a> table shows the different |
| memory regions in OpenCL and how memory objects are allocated and accessed |
| by the host and by an executing instance of a kernel. |
| For kernels, we distinguish between the behavior of local memory |
| for a parent kernel and its child kernels.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Once allocated, a memory object is made available to kernel-instances |
| running on one or more devices. |
| In addition to <a href="#shared-virtual-memory">Shared Virtual Memory</a>, there are |
| three basic ways to manage the contents of buffers between the host and |
| devices.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Read/Write/Fill commands</strong>: The data associated with a memory object is |
| explicitly read and written between the host and global memory regions |
| using commands enqueued to an OpenCL command queue. |
| Note: Fill commands are <a href="#unified-spec">missing before</a> version 1.2.</p> |
| </li> |
| <li> |
| <p><strong>Map/Unmap commands</strong>: Data from the memory object is mapped into a |
| contiguous block of memory accessed through a host accessible pointer. |
| The host program enqueues a <em>map</em> command on block of a memory object |
| before it can be safely manipulated by the host program. |
| When the host program is finished working with the block of memory, the |
| host program enqueues an <em>unmap</em> command to allow a kernel-instance to |
| safely read and/or write the buffer.</p> |
| </li> |
| <li> |
| <p><strong>Copy commands:</strong> The data associated with a memory object is copied |
| between two buffers, each of which may reside either on the host or on |
| the device.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>With Read/Write/Map, the commands |
| can be blocking or non-blocking operations. |
| The OpenCL function call for a blocking memory transfer returns once the |
| command (memory transfer) has completed. At this point the associated memory |
| resources on the host can be safely reused, and following operations on the host are |
| guaranteed that the transfer has already completed. |
| For a non-blocking memory transfer, the OpenCL function call returns as soon |
| as the command is enqueued.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Memory objects are bound to a context and hence can appear in multiple |
| kernel-instances running on more than one physical device. |
| The OpenCL platform must support a large range of hardware platforms |
| including systems that do not support a single shared address space in |
| hardware; hence the ways memory objects can be shared between |
| kernel-instances is restricted. |
| The basic principle is that multiple read operations on memory objects from |
| multiple kernel-instances that overlap in time are allowed, but mixing |
| overlapping reads and writes into the same memory objects from different |
| kernel instances is only allowed when fine grained synchronization is used |
| with <a href="#shared-virtual-memory">Shared Virtual Memory</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When global memory is manipulated by multiple kernel-instances running on |
| multiple devices, the OpenCL runtime system must manage the association of |
| memory objects with a given device. |
| In most cases the OpenCL runtime will implicitly associate a memory object |
| with a device. |
| A kernel instance is naturally associated with the command queue to which |
| the kernel was submitted. |
| Since a command-queue can only access a single device, the queue uniquely |
| defines which device is involved with any given kernel-instance; hence |
| defining a clear association between memory objects, kernel-instances and |
| devices. |
| Programmers may anticipate these associations in their programs and |
| explicitly manage association of memory objects with devices in order to |
| improve performance.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="shared-virtual-memory"><a class="anchor" href="#shared-virtual-memory"></a>3.3.3. Shared Virtual Memory</h4> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Shared virtual memory is <a href="#unified-spec">missing before</a> |
| version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL extends the global memory region into the host memory region through |
| a shared virtual memory (SVM) mechanism. |
| There are three types of SVM in OpenCL</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Coarse-Grained buffer SVM</strong>: Sharing occurs at the granularity of |
| regions of OpenCL buffer memory objects. |
| Consistency is enforced at synchronization points and with map/unmap |
| commands to drive updates between the host and the device. |
| This form of SVM is similar to non-SVM use of memory; however, it lets |
| kernel-instances share pointer-based data structures (such as |
| linked-lists) with the host program. |
| Program scope global variables are treated as per-device coarse-grained |
| SVM for addressing and sharing purposes.</p> |
| </li> |
| <li> |
| <p><strong>Fine-Grained buffer SVM</strong>: Sharing occurs at the granularity of |
| individual loads/stores into bytes within OpenCL buffer memory objects. |
| Loads and stores may be cached. |
| This means consistency is guaranteed at synchronization points. |
| If the optional OpenCL atomics are supported, they can be used to |
| provide fine-grained control of memory consistency.</p> |
| </li> |
| <li> |
| <p><strong>Fine-Grained system SVM</strong>: Sharing occurs at the granularity of |
| individual loads/stores into bytes occurring anywhere within the host |
| memory. |
| Loads and stores may be cached so consistency is guaranteed at |
| synchronization points. |
| If the optional OpenCL atomics are supported, they can be used to |
| provide fine-grained control of memory consistency.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="svm-summary-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 2. A summary of shared virtual memory (SVM) options in OpenCL</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-center valign-top"></th> |
| <th class="tableblock halign-center valign-top">Granularity of sharing</th> |
| <th class="tableblock halign-center valign-top">Memory Allocation</th> |
| <th class="tableblock halign-center valign-top">Mechanisms to enforce Consistency</th> |
| <th class="tableblock halign-center valign-top">Explicit updates between host and device</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Non-SVM buffers</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">OpenCL Memory objects(buffer)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a><br> |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Host synchronization points on the same or between devices.</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">yes, through Map and Unmap commands.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Coarse-Grained buffer SVM</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">OpenCL Memory objects (buffer)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Host synchronization points between devices</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">yes, through Map and Unmap commands.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Fine-Grained buffer SVM</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Bytes within OpenCL Memory objects (buffer)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Synchronization points plus atomics (if supported)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">No</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Fine-Grained system SVM</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Bytes within Host memory (system)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Host memory allocation mechanisms (e.g. malloc)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Synchronization points plus atomics (if supported)</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">No</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Coarse-Grained buffer SVM is required in the core OpenCL specification. |
| The two finer grained approaches are optional features in OpenCL. |
| The various SVM mechanisms to access host memory from the work-items |
| associated with a kernel instance are <a href="#svm-summary-table">summarized |
| above</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_memory_consistency_model_for_opencl_1_x"><a class="anchor" href="#_memory_consistency_model_for_opencl_1_x"></a>3.3.4. Memory Consistency Model for OpenCL 1.x</h4> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| This memory consistency model is <a href="#unified-spec">deprecated |
| by</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 1.x uses a relaxed consistency memory model; i.e. the state of memory |
| visible to a work-item is not guaranteed to be consistent across the collection |
| of work-items at all times.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Within a work-item memory has load / store consistency. |
| Local memory is consistent across work-items in a single work-group at a |
| work-group barrier. |
| Global memory is consistent across work-items in a single work-group at a |
| work-group barrier, but there are no guarantees of memory consistency between |
| different work-groups executing a kernel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Memory consistency for memory objects shared between enqueued commands is |
| enforced at a synchronization point.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="memory-consistency-model"><a class="anchor" href="#memory-consistency-model"></a>3.3.5. Memory Consistency Model for OpenCL 2.x</h4> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| This memory consistency model is <a href="#unified-spec">missing |
| before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The OpenCL 2.x memory model tells programmers what they can expect from an |
| OpenCL 2.x implementation; which memory operations are guaranteed to happen in |
| which order and which memory values each read operation will return. |
| The memory model tells compiler writers which restrictions they must follow |
| when implementing compiler optimizations; which variables they can cache in |
| registers and when they can move reads or writes around a barrier or atomic |
| operation. |
| The memory model also tells hardware designers about limitations on hardware |
| optimizations; for example, when they must flush or invalidate hardware |
| caches.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The memory consistency model in OpenCL 2.x is based on the memory model from |
| the ISO C11 programming language. |
| To help make the presentation more precise and self-contained, we include |
| modified paragraphs taken verbatim from the ISO C11 international standard. |
| When a paragraph is taken or modified from the C11 standard, it is |
| identified as such along with its original location in the <a href="#iso-c11">C11 |
| standard</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For programmers, the most intuitive model is the <em>sequential consistency</em> |
| memory model. |
| Sequential consistency interleaves the steps executed by each of the units |
| of execution. |
| Each access to a memory location sees the last assignment to that location |
| in that interleaving. |
| While sequential consistency is relatively straightforward for a programmer |
| to reason about, implementing sequential consistency is expensive. |
| Therefore, OpenCL 2.x implements a relaxed memory consistency model; i.e. it is |
| possible to write programs where the loads from memory violate sequential |
| consistency. |
| Fortunately, if a program does not contain any races and if the program only |
| uses atomic operations that utilize the sequentially consistent memory order |
| (the default memory ordering for OpenCL 2.x), OpenCL programs appear to execute |
| with sequential consistency.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Programmers can to some degree control how the memory model is relaxed by |
| choosing the memory order for synchronization operations. |
| The precise semantics of synchronization and the memory orders are formally |
| defined in <a href="#memory-ordering-rules">Memory Ordering Rules</a>. |
| Here, we give a high level description of how these memory orders apply to |
| atomic operations on atomic objects shared between units of execution. |
| OpenCL 2.x memory_order choices are based on those from the ISO C11 standard |
| memory model. |
| They are specified in certain OpenCL functions through the following |
| enumeration constants:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>memory_order_relaxed</strong>: implies no order constraints. |
| This memory order can be used safely to increment counters that are |
| concurrently incremented, but it doesn’t guarantee anything about the |
| ordering with respect to operations to other memory locations. |
| It can also be used, for example, to do ticket allocation and by expert |
| programmers implementing lock-free algorithms.</p> |
| </li> |
| <li> |
| <p><strong>memory_order_acquire</strong>: A synchronization operation (fence or atomic) |
| that has acquire semantics "acquires" side-effects from a release |
| operation that synchronises with it: if an acquire synchronises with a |
| release, the acquiring unit of execution will see all side-effects |
| preceding that release (and possibly subsequent side-effects.) As part |
| of carefully-designed protocols, programmers can use an "acquire" to |
| safely observe the work of another unit of execution.</p> |
| </li> |
| <li> |
| <p><strong>memory_order_release</strong>: A synchronization operation (fence or atomic |
| operation) that has release semantics "releases" side effects to an |
| acquire operation that synchronises with it. |
| All side effects that precede the release are included in the release. |
| As part of carefully-designed protocols, programmers can use a "release" |
| to make changes made in one unit of execution visible to other units of |
| execution.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| In general, no acquire must <em>always</em> synchronise with any particular |
| release. |
| However, synchronisation can be forced by certain executions. |
| See the description of <a href="#memory-ordering-fence">Fence Operations</a> for |
| detailed rules for when synchronisation must occur. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>memory_order_acq_rel</strong>: A synchronization operation with acquire-release |
| semantics has the properties of both the acquire and release memory |
| orders. |
| It is typically used to order read-modify-write operations.</p> |
| </li> |
| <li> |
| <p><strong>memory_order_seq_cst</strong>: The loads and stores of each unit of execution |
| appear to execute in program (i.e., sequenced-before) order, and the |
| loads and stores from different units of execution appear to be simply |
| interleaved.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Regardless of which memory_order is specified, resolving constraints on |
| memory operations across a heterogeneous platform adds considerable overhead |
| to the execution of a program. |
| An OpenCL platform may be able to optimize certain operations that depend on |
| the features of the memory consistency model by restricting the scope of the |
| memory operations. |
| Distinct memory scopes are defined by the values of the memory_scope |
| enumeration constant:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>memory_scope_work_item</strong>: memory-ordering constraints only apply within |
| the work-item <sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>.</p> |
| </li> |
| <li> |
| <p><strong>memory_scope_sub_group</strong>: memory-ordering constraints only apply within |
| the sub-group.</p> |
| </li> |
| <li> |
| <p><strong>memory_scope_work_group</strong>: memory-ordering constraints only apply to |
| work-items executing within a single work-group.</p> |
| </li> |
| <li> |
| <p><strong>memory_scope_device:</strong> memory-ordering constraints only apply to |
| work-items executing on a single device</p> |
| </li> |
| <li> |
| <p><strong>memory_scope_all_svm_devices</strong>: memory-ordering constraints apply to |
| work-items executing across multiple devices and (when using SVM) the |
| host. |
| A release performed with <strong>memory_scope_all_svm_devices</strong> to a buffer that |
| does not have the <a href="#CL_MEM_SVM_ATOMICS"><code>CL_MEM_<wbr>SVM_<wbr>ATOMICS</code></a> flag set will commit to at least |
| <strong>memory_scope_device</strong> visibility, with full synchronization of the |
| buffer at a queue synchronization point (e.g. an OpenCL event).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>These memory scopes define a hierarchy of visibilities when analyzing the |
| ordering constraints of memory operations. |
| For example if a programmer knows that a sequence of memory operations will |
| only be associated with a collection of work-items from a single work-group |
| (and hence will run on a single device), the implementation is spared the |
| overhead of managing the memory orders across other devices within the same |
| context. |
| This can substantially reduce overhead in a program. |
| All memory scopes are valid when used on global memory or local memory. |
| For local memory, all visibility is constrained to within a given work-group |
| and scopes wider than <strong>memory_scope_work_group</strong> carry no additional meaning.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the following subsections (leading up to <a href="#opencl-framework">OpenCL |
| Framework</a>), we will explain the synchronization constructs and detailed |
| rules needed to use OpenCL’s 2.x relaxed memory models. |
| It is important to appreciate, however, that many programs do not benefit |
| from relaxed memory models. |
| Even expert programmers have a difficult time using atomics and fences to |
| write correct programs with relaxed memory models. |
| A large number of OpenCL programs can be written using a simplified memory |
| model. |
| This is accomplished by following these guidelines.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Write programs that manage safe sharing of global memory objects through |
| the synchronization points defined by the command queues.</p> |
| </li> |
| <li> |
| <p>Restrict low level synchronization inside work-groups to the work-group |
| functions such as barrier.</p> |
| </li> |
| <li> |
| <p>If you want sequential consistency behavior with system allocations or |
| fine-grain SVM buffers with atomics support, use only |
| <strong>memory_order_seq_cst</strong> operations with the scope |
| <strong>memory_scope_all_svm_devices</strong>.</p> |
| </li> |
| <li> |
| <p>If you want sequential consistency behavior when not using system |
| allocations or fine-grain SVM buffers with atomics support, use only |
| <strong>memory_order_seq_cst</strong> operations with the scope <strong>memory_scope_device</strong> |
| or <strong>memory_scope_all_svm_devices</strong>.</p> |
| </li> |
| <li> |
| <p>Ensure your program has no races.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If these guidelines are followed in your OpenCL programs, you can skip the |
| detailed rules behind the relaxed memory models and go directly to |
| <a href="#opencl-framework">OpenCL Framework</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_overview_of_atomic_and_fence_operations"><a class="anchor" href="#_overview_of_atomic_and_fence_operations"></a>3.3.6. Overview of atomic and fence operations</h4> |
| <div class="paragraph"> |
| <p>OpenCL 2.x has a number of <em>synchronization operations</em> that are used to define |
| memory order constraints in a program. |
| They play a special role in controlling how memory operations in one unit of |
| execution (such as work-items or, when using SVM a host thread) are made |
| visible to another. |
| There are two types of synchronization operations in OpenCL; <em>atomic |
| operations</em> and <em>fences</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Atomic operations are indivisible. |
| They either occur completely or not at all. |
| These operations are used to order memory operations between units of |
| execution and hence they are parameterized with the memory_order and |
| memory_scope parameters defined by the OpenCL memory consistency model. |
| The atomic operations for OpenCL kernel languages are similar to the |
| corresponding operations defined by the C11 standard.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OpenCL 2.x atomic operations apply to variables of an atomic type (a |
| subset of those in the C11 standard) including atomic versions of the int, |
| uint, long, ulong, float, double, half, intptr_t, uintptr_t, size_t, and |
| ptrdiff_t types. |
| However, support for some of these atomic types depends on support for the |
| corresponding regular types.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An atomic operation on one or more memory locations is either an acquire |
| operation, a release operation, or both an acquire and release operation. |
| An atomic operation without an associated memory location is a fence and can |
| be either an acquire fence, a release fence, or both an acquire and release |
| fence. |
| In addition, there are relaxed atomic operations, which do not have |
| synchronization properties, and atomic read-modify-write operations, which |
| have special characteristics. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 5, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>The orders <strong>memory_order_acquire</strong> (used for reads), <strong>memory_order_release</strong> |
| (used for writes), and <strong>memory_order_acq_rel</strong> (used for read-modify-write |
| operations) are used for simple communication between units of execution |
| using shared variables. |
| Informally, executing a <strong>memory_order_release</strong> on an atomic object A makes |
| all previous side effects visible to any unit of execution that later |
| executes a <strong>memory_order_acquire</strong> on A. |
| The orders <strong>memory_order_acquire</strong>, <strong>memory_order_release</strong>, and |
| <strong>memory_order_acq_rel</strong> do not provide sequential consistency for race-free |
| programs because they will not ensure that atomic stores followed by atomic |
| loads become visible to other threads in that order.</p> |
| </div> |
| <div id="atomic-fence-orders" class="paragraph"> |
| <p>The fence operation is atomic_work_item_fence, which includes a memory_order |
| argument as well as the memory_scope and cl_mem_fence_flags arguments. |
| Depending on the memory_order argument, this operation:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>has no effects, if <strong>memory_order_relaxed</strong>;</p> |
| </li> |
| <li> |
| <p>is an acquire fence, if <strong>memory_order_acquire</strong>;</p> |
| </li> |
| <li> |
| <p>is a release fence, if <strong>memory_order_release</strong>;</p> |
| </li> |
| <li> |
| <p>is both an acquire fence and a release fence, if <strong>memory_order_acq_rel</strong>;</p> |
| </li> |
| <li> |
| <p>is a sequentially-consistent fence with both acquire and release |
| semantics, if <strong>memory_order_seq_cst</strong>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If specified, the cl_mem_fence_flags argument must be <code>CLK_IMAGE_MEM_FENCE</code>, |
| <code>CLK_GLOBAL_MEM_FENCE</code>, <code>CLK_LOCAL_MEM_FENCE</code>, or <code>CLK_GLOBAL_MEM_FENCE | |
| CLK_LOCAL_MEM_FENCE</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>atomic_work_item_fence(CLK_IMAGE_MEM_FENCE, …​)</code> built-in function must be |
| used to make sure that sampler-less writes are visible to later reads by the |
| same work-item. |
| Without use of the atomic_work_item_fence function, write-read coherence on |
| image objects is not guaranteed: if a work-item reads from an image to which |
| it has previously written without an intervening atomic_work_item_fence, it |
| is not guaranteed that those previous writes are visible to the work-item.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The synchronization operations in OpenCL 2.x can be parameterized by a |
| memory_scope. |
| Memory scopes control the extent that an atomic operation or fence is |
| visible with respect to the memory model. |
| These memory scopes may be used when performing atomic operations and fences |
| on global memory and local memory. |
| When used on global memory visibility is bounded by the capabilities of that |
| memory. |
| When used on a fine-grained non-atomic SVM buffer, a coarse-grained SVM |
| buffer, or a non-SVM buffer, operations parameterized with |
| <strong>memory_scope_all_svm_devices</strong> will behave as if they were parameterized |
| with <strong>memory_scope_device</strong>. |
| When used on local memory, visibility is bounded by the work-group and, as a |
| result, memory_scope with wider visibility than <strong>memory_scope_work_group</strong> |
| will be reduced to <strong>memory_scope_work_group</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Two actions <strong>A</strong> and <strong>B</strong> are defined to have an inclusive scope if they have |
| the same scope <strong>P</strong> such that:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>P</strong> is <strong>memory_scope_sub_group</strong> and <strong>A</strong> and <strong>B</strong> are executed by |
| work-items within the same sub-group.</p> |
| </li> |
| <li> |
| <p><strong>P</strong> is <strong>memory_scope_work_group</strong> and <strong>A</strong> and <strong>B</strong> are executed by |
| work-items within the same work-group.</p> |
| </li> |
| <li> |
| <p><strong>P</strong> is <strong>memory_scope_device</strong> and <strong>A</strong> and <strong>B</strong> are executed by work-items |
| on the same device when <strong>A</strong> and <strong>B</strong> apply to an SVM allocation or <strong>A</strong> |
| and <strong>B</strong> are executed by work-items in the same kernel or one of its |
| children when <strong>A</strong> and <strong>B</strong> apply to a <code>cl_mem</code> buffer.</p> |
| </li> |
| <li> |
| <p><strong>P</strong> is <strong>memory_scope_all_svm_devices</strong> if <strong>A</strong> and <strong>B</strong> are executed by |
| host threads or by work-items on one or more devices that can share SVM |
| memory with each other and the host process.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="memory-ordering-rules"><a class="anchor" href="#memory-ordering-rules"></a>3.3.7. Memory Ordering Rules</h4> |
| <div class="paragraph"> |
| <p>Fundamentally, the issue in a memory model is to understand the orderings in |
| time of modifications to objects in memory. |
| Modifying an object or calling a function that modifies an object are side |
| effects, i.e. changes in the state of the execution environment. |
| Evaluation of an expression in general includes both value computations and |
| initiation of side effects. |
| Value computation for an lvalue expression includes determining the identity |
| of the designated object. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.3, paragraph 2, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>We assume that the OpenCL kernel language and host programming languages |
| have a sequenced-before relation between the evaluations executed by a |
| single unit of execution. |
| This sequenced-before relation is an asymmetric, transitive, pair-wise |
| relation between those evaluations, which induces a partial order among |
| them. |
| Given any two evaluations <strong>A</strong> and <strong>B</strong>, if <strong>A</strong> is sequenced-before <strong>B</strong>, then |
| the execution of <strong>A</strong> shall precede the execution of <strong>B</strong>. |
| (Conversely, if <strong>A</strong> is sequenced-before <strong>B</strong>, then <strong>B</strong> is sequenced-after |
| <strong>A</strong>.) If <strong>A</strong> is not sequenced-before or sequenced-after <strong>B</strong>, then <strong>A</strong> and |
| <strong>B</strong> are unsequenced. |
| Evaluations <strong>A</strong> and <strong>B</strong> are indeterminately sequenced when <strong>A</strong> is either |
| sequenced-before or sequenced-after <strong>B</strong>, but it is unspecified which. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.3, paragraph 3, modified.]</a></p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Sequenced-before is a partial order of the operations executed by a |
| single unit of execution (e.g. a host thread or work-item). |
| It generally corresponds to the source program order of those operations, and |
| is partial because of the undefined argument evaluation order of the OpenCL C |
| kernel language. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>In an OpenCL kernel language, the value of an object visible to a work-item |
| W at a particular point is the initial value of the object, a value stored |
| in the object by W, or a value stored in the object by another work-item or |
| host thread, according to the rules below. |
| Depending on details of the host programming language, the value of an |
| object visible to a host thread may also be the value stored in that object |
| by another work-item or host thread. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 2, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>Two expression evaluations conflict if one of them modifies a memory |
| location and the other one reads or modifies the same memory location. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 4.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>All modifications to a particular atomic object <strong>M</strong> occur in some particular |
| total order, called the modification order of <strong>M</strong>. |
| If <strong>A</strong> and <strong>B</strong> are modifications of an atomic object <strong>M</strong>, and <strong>A</strong> |
| happens-before <strong>B</strong>, then <strong>A</strong> shall precede <strong>B</strong> in the modification order of |
| <strong>M</strong>, which is defined below. |
| Note that the modification order of an atomic object <strong>M</strong> is independent of |
| whether <strong>M</strong> is in local or global memory. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 7, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>A release sequence begins with a release operation <strong>A</strong> on an atomic object |
| <strong>M</strong> and is the maximal contiguous sub-sequence of side effects in the |
| modification order of <strong>M</strong>, where the first operation is <strong>A</strong> and every |
| subsequent operation either is performed by the same work-item or host |
| thread that performed the release or is an atomic read-modify-write |
| operation. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 10, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL’s local and global memories are disjoint. |
| Kernels may access both kinds of memory while host threads may only access |
| global memory. |
| Furthermore, the <em>flags</em> argument of OpenCL’s work_group_barrier function |
| specifies which memory operations the function will make visible: these |
| memory operations can be, for example, just the ones to local memory, or the |
| ones to global memory, or both. |
| Since the visibility of memory operations can be specified for local memory |
| separately from global memory, we define two related but independent |
| relations, <em>global-synchronizes-with</em> and <em>local-synchronizes-with</em>. |
| Certain operations on global memory may global-synchronize-with other |
| operations performed by another work-item or host thread. |
| An example is a release atomic operation in one work- item that |
| global-synchronizes-with an acquire atomic operation in a second work-item. |
| Similarly, certain atomic operations on local objects in kernels can |
| local-synchronize- with other atomic operations on those local objects. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 11, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>We define two separate happens-before relations: global-happens-before and |
| local-happens-before.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A global memory action <strong>A</strong> global-happens-before a global memory action <strong>B</strong> |
| if</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>A</strong> is sequenced before <strong>B</strong>, or</p> |
| </li> |
| <li> |
| <p><strong>A</strong> global-synchronizes-with <strong>B</strong>, or</p> |
| </li> |
| <li> |
| <p>For some global memory action <strong>C</strong>, <strong>A</strong> global-happens-before <strong>C</strong> and <strong>C</strong> |
| global-happens-before <strong>B</strong>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A local memory action <strong>A</strong> local-happens-before a local memory action <strong>B</strong> if</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>A</strong> is sequenced before <strong>B</strong>, or</p> |
| </li> |
| <li> |
| <p><strong>A</strong> local-synchronizes-with <strong>B</strong>, or</p> |
| </li> |
| <li> |
| <p>For some local memory action <strong>C</strong>, <strong>A</strong> local-happens-before <strong>C</strong> and <strong>C</strong> |
| local-happens-before <strong>B</strong>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>An OpenCL 2.x implementation shall ensure that no program execution |
| demonstrates a cycle in either the local-happens-before relation or the |
| global-happens-before relation.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| The global- and local-happens-before relations are critical to |
| defining what values are read and when data races occur. |
| The global-happens-before relation, for example, defines what global memory |
| operations definitely happen before what other global memory operations. |
| If an operation <strong>A</strong> global-happens-before operation <strong>B</strong> then <strong>A</strong> must occur |
| before <strong>B</strong>; in particular, any write done by <strong>A</strong> will be visible to <strong>B</strong>. |
| The local-happens-before relation has similar properties for local memory. |
| Programmers can use the local- and global-happens-before relations to reason |
| about the order of program actions. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A visible side effect <strong>A</strong> on a global object <strong>M</strong> with respect to a value |
| computation <strong>B</strong> of <strong>M</strong> satisfies the conditions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>A</strong> global-happens-before <strong>B</strong>, and</p> |
| </li> |
| <li> |
| <p>there is no other side effect <strong>X</strong> to <strong>M</strong> such that <strong>A</strong> |
| global-happens-before <strong>X</strong> and <strong>X</strong> global-happens-before <strong>B</strong>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>We define visible side effects for local objects <strong>M</strong> similarly. |
| The value of a non-atomic scalar object <strong>M</strong>, as determined by evaluation |
| <strong>B</strong>, shall be the value stored by the visible side effect <strong>A</strong>. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 19, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>The execution of a program contains a data race if it contains two |
| conflicting actions <strong>A</strong> and <strong>B</strong> in different units of execution, and</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>(1) at least one of <strong>A</strong> or <strong>B</strong> is not atomic, or <strong>A</strong> and <strong>B</strong> do not have |
| inclusive memory scope, and</p> |
| </li> |
| <li> |
| <p>(2) the actions are global actions unordered by the |
| global-happens-before relation or are local actions unordered by the |
| local-happens-before relation.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Any such data race results in undefined behavior. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 25, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>We also define the visible sequence of side effects on local and global |
| atomic objects. |
| The remaining paragraphs of this subsection define this sequence for a |
| global atomic object <strong>M</strong>; the visible sequence of side effects for a local |
| atomic object is defined similarly by using the local-happens-before |
| relation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The visible sequence of side effects on a global atomic object <strong>M</strong>, with |
| respect to a value computation <strong>B</strong> of <strong>M</strong>, is a maximal contiguous |
| sub-sequence of side effects in the modification order of <strong>M</strong>, where the |
| first side effect is visible with respect to <strong>B</strong>, and for every side effect, |
| it is not the case that <strong>B</strong> global-happens-before it. |
| The value of <strong>M</strong>, as determined by evaluation <strong>B</strong>, shall be the value stored |
| by some operation in the visible sequence of <strong>M</strong> with respect to <strong>B</strong>. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 22, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>If an operation <strong>A</strong> that modifies an atomic object <strong>M</strong> global-happens before |
| an operation <strong>B</strong> that modifies <strong>M</strong>, then <strong>A</strong> shall be earlier than <strong>B</strong> in |
| the modification order of <strong>M</strong>. |
| This requirement is known as write-write coherence.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a value computation <strong>A</strong> of an atomic object <strong>M</strong> global-happens-before a |
| value computation <strong>B</strong> of <strong>M</strong>, and <strong>A</strong> takes its value from a side effect <strong>X</strong> |
| on <strong>M</strong>, then the value computed by <strong>B</strong> shall either equal the value stored |
| by <strong>X</strong>, or be the value stored by a side effect <strong>Y</strong> on <strong>M</strong>, where <strong>Y</strong> |
| follows <strong>X</strong> in the modification order of <strong>M</strong>. |
| This requirement is known as read-read coherence. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 22, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>If a value computation <strong>A</strong> of an atomic object <strong>M</strong> global-happens-before an |
| operation <strong>B</strong> on <strong>M</strong>, then <strong>A</strong> shall take its value from a side effect <strong>X</strong> |
| on <strong>M</strong>, where <strong>X</strong> precedes <strong>B</strong> in the modification order of <strong>M</strong>. |
| This requirement is known as read-write coherence.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a side effect <strong>X</strong> on an atomic object <strong>M</strong> global-happens-before a value |
| computation <strong>B</strong> of <strong>M</strong>, then the evaluation <strong>B</strong> shall take its value from |
| <strong>X</strong> or from a side effect <strong>Y</strong> that follows <strong>X</strong> in the modification order of |
| <strong>M</strong>. |
| This requirement is known as write-read coherence.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_atomic_operations"><a class="anchor" href="#_atomic_operations"></a>3.3.7.1. Atomic Operations</h5> |
| <div class="paragraph"> |
| <p>This and following sections describe how different program actions in kernel |
| C code and the host program contribute to the local- and |
| global-happens-before relations. |
| This section discusses ordering rules for OpenCL 2.x atomic operations.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#device-side-enqueue">Device-side enqueue</a> defines the enumerated type |
| memory_order.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For <strong>memory_order_relaxed</strong>, no operation orders memory.</p> |
| </li> |
| <li> |
| <p>For <strong>memory_order_release</strong>, <strong>memory_order_acq_rel</strong>, and |
| <strong>memory_order_seq_cst</strong>, a store operation performs a release operation |
| on the affected memory location.</p> |
| </li> |
| <li> |
| <p>For <strong>memory_order_acquire</strong>, <strong>memory_order_acq_rel</strong>, and |
| <strong>memory_order_seq_cst</strong>, a load operation performs an acquire operation |
| on the affected memory location. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraphs 2-4, modified.]</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Certain built-in functions synchronize with other built-in functions |
| performed by another unit of execution. |
| This is true for pairs of release and acquire operations under specific |
| circumstances. |
| An atomic operation <strong>A</strong> that performs a release operation on a global object |
| <strong>M</strong> global-synchronizes-with an atomic operation <strong>B</strong> that performs an |
| acquire operation on <strong>M</strong> and reads a value written by any side effect in the |
| release sequence headed by <strong>A</strong>. |
| A similar rule holds for atomic operations on objects in local memory: an |
| atomic operation <strong>A</strong> that performs a release operation on a local object <strong>M</strong> |
| local-synchronizes-with an atomic operation <strong>B</strong> that performs an acquire |
| operation on <strong>M</strong> and reads a value written by any side effect in the release |
| sequence headed by <strong>A</strong>. |
| <a href="#iso-c11">[C11 standard, Section 5.1.2.4, paragraph 11, modified.]</a></p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Atomic operations specifying <strong>memory_order_relaxed</strong> are relaxed only |
| with respect to memory ordering. |
| Implementations must still guarantee that any given atomic access to a |
| particular atomic object be indivisible with respect to all other atomic |
| accesses to that object. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>There shall exist a single total order <strong>S</strong> for all <strong>memory_order_seq_cst</strong> |
| operations that is consistent with the modification orders for all affected |
| locations, as well as the appropriate global-happens-before and |
| local-happens-before orders for those locations, such that each |
| <strong>memory_order_seq_cst</strong> operation <strong>B</strong> that loads a value from an atomic object |
| <strong>M</strong> in global or local memory observes one of the following values:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the result of the last modification <strong>A</strong> of <strong>M</strong> that precedes <strong>B</strong> in <strong>S</strong>, |
| if it exists, or</p> |
| </li> |
| <li> |
| <p>if <strong>A</strong> exists, the result of some modification of <strong>M</strong> in the visible |
| sequence of side effects with respect to <strong>B</strong> that is not |
| <strong>memory_order_seq_cst</strong> and that does not happen before <strong>A</strong>, or</p> |
| </li> |
| <li> |
| <p>if <strong>A</strong> does not exist, the result of some modification of <strong>M</strong> in the |
| visible sequence of side effects with respect to <strong>B</strong> that is not |
| <strong>memory_order_seq_cst</strong>. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraph 6, modified.]</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Let X and Y be two <strong>memory_order_seq_cst</strong> operations. |
| If X local-synchronizes-with or global-synchronizes-with Y then X both |
| local-synchronizes-with Y and global-synchronizes-with Y.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the total order <strong>S</strong> exists, the following rules hold:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For an atomic operation <strong>B</strong> that reads the value of an atomic object |
| <strong>M</strong>, if there is a <strong>memory_order_seq_cst</strong> fence <strong>X</strong> sequenced-before |
| <strong>B</strong>, then <strong>B</strong> observes either the last <strong>memory_order_seq_cst</strong> |
| modification of <strong>M</strong> preceding <strong>X</strong> in the total order <strong>S</strong> or a later |
| modification of <strong>M</strong> in its modification order. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraph 9.]</a></p> |
| </li> |
| <li> |
| <p>For atomic operations <strong>A</strong> and <strong>B</strong> on an atomic object <strong>M</strong>, where <strong>A</strong> |
| modifies <strong>M</strong> and <strong>B</strong> takes its value, if there is a |
| <strong>memory_order_seq_cst</strong> fence <strong>X</strong> such that <strong>A</strong> is sequenced-before <strong>X</strong> |
| and <strong>B</strong> follows <strong>X</strong> in <strong>S</strong>, then <strong>B</strong> observes either the effects of <strong>A</strong> |
| or a later modification of <strong>M</strong> in its modification order. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraph 10.]</a></p> |
| </li> |
| <li> |
| <p>For atomic operations <strong>A</strong> and <strong>B</strong> on an atomic object <strong>M</strong>, where <strong>A</strong> |
| modifies <strong>M</strong> and <strong>B</strong> takes its value, if there are |
| <strong>memory_order_seq_cst</strong> fences <strong>X</strong> and <strong>Y</strong> such that <strong>A</strong> is |
| sequenced-before <strong>X</strong>, <strong>Y</strong> is sequenced-before <strong>B</strong>, and <strong>X</strong> precedes <strong>Y</strong> |
| in <strong>S</strong>, then <strong>B</strong> observes either the effects of <strong>A</strong> or a later |
| modification of <strong>M</strong> in its modification order. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraph 11.]</a></p> |
| </li> |
| <li> |
| <p>For atomic operations <strong>A</strong> and <strong>B</strong> on an atomic object <strong>M</strong>, if there are |
| <strong>memory_order_seq_cst</strong> fences <strong>X</strong> and <strong>Y</strong> such that <strong>A</strong> is |
| sequenced-before <strong>X</strong>, <strong>Y</strong> is sequenced-before <strong>B</strong>, and <strong>X</strong> precedes <strong>Y</strong> |
| in <strong>S</strong>, then <strong>B</strong> occurs later than <strong>A</strong> in the modification order of <strong>M</strong>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <strong>memory_order_seq_cst</strong> ensures sequential consistency only for a |
| program that is (1) free of data races, and (2) exclusively uses |
| <strong>memory_order_seq_cst</strong> synchronization operations. |
| Any use of weaker ordering will invalidate this guarantee unless extreme |
| care is used. |
| In particular, <strong>memory_order_seq_cst</strong> fences ensure a total order only for |
| the fences themselves. |
| Fences cannot, in general, be used to restore sequential consistency for |
| atomic operations with weaker ordering specifications. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Atomic read-modify-write operations should always read the last value (in |
| the modification order) stored before the write associated with the |
| read-modify-write operation. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraph 12.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="underline">Implementations should ensure that no "out-of-thin-air" values |
| are computed that circularly depend on their own computation.</span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Note: Under the rules described above, and independent to the previously |
| footnoted C++ issue, it is known that <em>x == y == 42</em> is a valid final state |
| in the following problematic example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">global atomic_int x = ATOMIC_VAR_INIT(<span class="integer">0</span>); |
| local atomic_int y = ATOMIC_VAR_INIT(<span class="integer">0</span>); |
| |
| <span class="label">unit_of_execution_1:</span> |
| ... [execution not reading or writing x or y, leading up to:] |
| <span class="predefined-type">int</span> t = atomic_load_explicit(&y, memory_order_acquire); |
| atomic_store_explicit(&x, t, memory_order_release); |
| |
| <span class="label">unit_of_execution_2:</span> |
| ... [execution not reading or writing x or y, leading up to:] |
| <span class="predefined-type">int</span> t = atomic_load_explicit(&x, memory_order_acquire); |
| atomic_store_explicit(&y, t, memory_order_release);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This is not useful behavior and implementations should not exploit this |
| phenomenon. |
| It should be expected that in the future this may be disallowed by |
| appropriate updates to the memory model description by the OpenCL committee.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Implementations should make atomic stores visible to atomic loads within a |
| reasonable amount of time. |
| <a href="#iso-c11">[C11 standard, Section 7.17.3, paragraph 16.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>As long as the following conditions are met, a host program sharing SVM memory |
| with a kernel executing on one or more OpenCL 2.x devices may use atomic and |
| synchronization operations to ensure that its assignments, and those of the |
| kernel, are visible to each other:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Either fine-grained buffer or fine-grained system SVM must be used to |
| share memory. |
| While coarse-grained buffer SVM allocations may support atomic |
| operations, visibility on these allocations is not guaranteed except at |
| map and unmap operations.</p> |
| </li> |
| <li> |
| <p>The optional OpenCL 2.x SVM atomic-controlled visibility specified by |
| provision of the <a href="#CL_MEM_SVM_ATOMICS"><code>CL_MEM_<wbr>SVM_<wbr>ATOMICS</code></a> flag must be supported by the device |
| and the flag provided to the SVM buffer on allocation.</p> |
| </li> |
| <li> |
| <p>The host atomic and synchronization operations must be compatible with |
| those of an OpenCL kernel language. |
| This requires that the size and representation of the data types that |
| the host atomic operations act on be consistent with the OpenCL kernel |
| language atomic types.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>If these conditions are met, the host operations will apply at |
| all_svm_devices scope.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="memory-ordering-fence"><a class="anchor" href="#memory-ordering-fence"></a>3.3.7.2. Fence Operations</h5> |
| <div class="paragraph"> |
| <p>This section describes how the OpenCL 2.x fence operations contribute to the |
| local- and global-happens-before relations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Earlier, we introduced synchronization primitives called fences. |
| Fences can utilize the acquire memory_order, release memory_order, or both. |
| A fence with acquire semantics is called an acquire fence; a fence with |
| release semantics is called a release fence. The <a href="#atomic-fence-orders">overview of atomic and fence operations</a> section describes the memory orders |
| that result in acquire and release fences.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A global release fence <strong>A</strong> global-synchronizes-with a global acquire fence |
| <strong>B</strong> if there exist atomic operations <strong>X</strong> and <strong>Y</strong>, both operating on some |
| global atomic object <strong>M</strong>, such that <strong>A</strong> is sequenced-before <strong>X</strong>, <strong>X</strong> |
| modifies <strong>M</strong>, <strong>Y</strong> is sequenced-before <strong>B</strong>, <strong>Y</strong> reads the value written by |
| <strong>X</strong> or a value written by any side effect in the hypothetical release |
| sequence <strong>X</strong> would head if it were a release operation, and that the scopes |
| of <strong>A</strong>, <strong>B</strong> are inclusive. |
| <a href="#iso-c11">[C11 standard, Section 7.17.4, paragraph 2, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>A global release fence <strong>A</strong> global-synchronizes-with an atomic operation <strong>B</strong> |
| that performs an acquire operation on a global atomic object <strong>M</strong> if there |
| exists an atomic operation <strong>X</strong> such that <strong>A</strong> is sequenced-before <strong>X</strong>, <strong>X</strong> |
| modifies <strong>M</strong>, <strong>B</strong> reads the value written by <strong>X</strong> or a value written by any |
| side effect in the hypothetical release sequence <strong>X</strong> would head if it were a |
| release operation, and the scopes of <strong>A</strong> and <strong>B</strong> are inclusive. |
| <a href="#iso-c11">[C11 standard, Section 7.17.4, paragraph 3, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>An atomic operation <strong>A</strong> that is a release operation on a global atomic |
| object <strong>M</strong> global-synchronizes-with a global acquire fence <strong>B</strong> if there |
| exists some atomic operation <strong>X</strong> on <strong>M</strong> such that <strong>X</strong> is sequenced-before |
| <strong>B</strong> and reads the value written by <strong>A</strong> or a value written by any side effect |
| in the release sequence headed by <strong>A</strong>, and the scopes of <strong>A</strong> and <strong>B</strong> are |
| inclusive. |
| <a href="#iso-c11">[C11 standard, Section 7.17.4, paragraph 4, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>A local release fence <strong>A</strong> local-synchronizes-with a local acquire fence <strong>B</strong> |
| if there exist atomic operations <strong>X</strong> and <strong>Y</strong>, both operating on some local |
| atomic object <strong>M</strong>, such that <strong>A</strong> is sequenced-before <strong>X</strong>, <strong>X</strong> modifies <strong>M</strong>, |
| <strong>Y</strong> is sequenced-before <strong>B</strong>, and <strong>Y</strong> reads the value written by <strong>X</strong> or a |
| value written by any side effect in the hypothetical release sequence <strong>X</strong> |
| would head if it were a release operation, and the scopes of <strong>A</strong> and <strong>B</strong> are |
| inclusive. |
| <a href="#iso-c11">[C11 standard, Section 7.17.4, paragraph 2, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>A local release fence <strong>A</strong> local-synchronizes-with an atomic operation <strong>B</strong> |
| that performs an acquire operation on a local atomic object <strong>M</strong> if there |
| exists an atomic operation <strong>X</strong> such that <strong>A</strong> is sequenced-before <strong>X</strong>, <strong>X</strong> |
| modifies <strong>M</strong>, and <strong>B</strong> reads the value written by <strong>X</strong> or a value written by |
| any side effect in the hypothetical release sequence <strong>X</strong> would head if it |
| were a release operation, and the scopes of <strong>A</strong> and <strong>B</strong> are inclusive. |
| <a href="#iso-c11">[C11 standard, Section 7.17.4, paragraph 3, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>An atomic operation <strong>A</strong> that is a release operation on a local atomic object |
| <strong>M</strong> local-synchronizes-with a local acquire fence <strong>B</strong> if there exists some |
| atomic operation <strong>X</strong> on <strong>M</strong> such that <strong>X</strong> is sequenced-before <strong>B</strong> and reads |
| the value written by <strong>A</strong> or a value written by any side effect in the |
| release sequence headed by <strong>A</strong>, and the scopes of <strong>A</strong> and <strong>B</strong> are inclusive. |
| <a href="#iso-c11">[C11 standard, Section 7.17.4, paragraph 4, modified.]</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>Let <strong>X</strong> and <strong>Y</strong> be two work-item fences that each have both the |
| <code>CLK_GLOBAL_MEM_FENCE</code> and <code>CLK_LOCAL_MEM_FENCE</code> flags set. |
| <strong>X</strong> global-synchronizes-with <strong>Y</strong> and <strong>X</strong> local synchronizes with <strong>Y</strong> if the |
| conditions required for <strong>X</strong> to global-synchronize with <strong>Y</strong> are met, the |
| conditions required for <strong>X</strong> to local-synchronize-with <strong>Y</strong> are met, or both |
| sets of conditions are met.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_work_group_functions"><a class="anchor" href="#_work_group_functions"></a>3.3.7.3. Work-group Functions</h5> |
| <div class="paragraph"> |
| <p>The OpenCL kernel execution model includes collective operations across the |
| work-items within a single work-group. |
| These are called work-group functions, and include functions such as |
| barriers, scans, reductions, and broadcasts. |
| We will first discuss the work-group barrier function. |
| Other work-group functions are discussed afterwards.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The barrier function provides a mechanism for a kernel to synchronize the |
| work-items within a single work-group: informally, each work-item of the |
| work-group must execute the barrier before any are allowed to proceed. |
| It also orders memory operations to a specified combination of one or more |
| address spaces such as local memory or global memory, in a similar manner to |
| a fence.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To precisely specify the memory ordering semantics for barrier, we need to |
| distinguish between a dynamic and a static instance of the call to a |
| barrier. |
| A call to a barrier can appear in a loop, for example, and each execution of |
| the same static barrier call results in a new dynamic instance of the |
| barrier that will independently synchronize a work-groups work-items.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A work-item executing a dynamic instance of a barrier results in two |
| operations, both fences, that are called the entry and exit fences. |
| These fences obey all the rules for fences specified elsewhere in this |
| chapter as well as the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The entry fence is a release fence with the same flags and scope as |
| requested for the barrier.</p> |
| </li> |
| <li> |
| <p>The exit fence is an acquire fence with the same flags and scope as |
| requested for the barrier.</p> |
| </li> |
| <li> |
| <p>For each work-item the entry fence is sequenced before the exit fence.</p> |
| </li> |
| <li> |
| <p>If the flags have <code>CLK_GLOBAL_MEM_FENCE</code> set then for each work-item the |
| entry fence global-synchronizes-with the exit fence of all other |
| work-items in the same work-group.</p> |
| </li> |
| <li> |
| <p>If the flags have <code>CLK_LOCAL_MEM_FENCE</code> set then for each work-item the |
| entry fence local-synchronizes-with the exit fence of all other |
| work-items in the same work-group.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Other work-group functions include such functions as scans, reductions, |
| and broadcasts, and are described in the kernel language and IL specifications. |
| The use of these work-group functions implies sequenced-before relationships |
| between statements within the execution of a single work-item in order to |
| satisfy data dependencies. |
| For example, a work-item that provides a value to a work-group function must |
| behave as if it generates that value before beginning execution of that |
| work-group function. |
| Furthermore, the programmer must ensure that all work-items in a work-group |
| must execute the same work-group function call site, or dynamic work-group |
| function instance.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_sub_group_functions"><a class="anchor" href="#_sub_group_functions"></a>3.3.7.4. Sub-group Functions</h5> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Sub-group functions are <a href="#unified-spec">missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The OpenCL kernel execution model includes collective operations across the |
| work-items within a single sub-group. |
| These are called sub-group functions. |
| We will first discuss the sub-group barrier. |
| Other sub-group functions are discussed afterwards.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The barrier function provides a mechanism for a kernel to synchronize the |
| work-items within a single sub-group: informally, each work-item of the |
| sub-group must execute the barrier before any are allowed to proceed. |
| It also orders memory operations to a specified combination of one or more |
| address spaces such as local memory or global memory, in a similar manner to |
| a fence.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To precisely specify the memory ordering semantics for barrier, we need to |
| distinguish between a dynamic and a static instance of the call to a |
| barrier. |
| A call to a barrier can appear in a loop, for example, and each execution of |
| the same static barrier call results in a new dynamic instance of the |
| barrier that will independently synchronize a sub-groups work-items.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A work-item executing a dynamic instance of a barrier results in two |
| operations, both fences, that are called the entry and exit fences. |
| These fences obey all the rules for fences specified elsewhere in this |
| chapter as well as the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The entry fence is a release fence with the same flags and scope as |
| requested for the barrier.</p> |
| </li> |
| <li> |
| <p>The exit fence is an acquire fence with the same flags and scope as |
| requested for the barrier.</p> |
| </li> |
| <li> |
| <p>For each work-item the entry fence is sequenced before the exit fence.</p> |
| </li> |
| <li> |
| <p>If the flags have <code>CLK_GLOBAL_MEM_FENCE</code> set then for each work-item the |
| entry fence global-synchronizes-with the exit fence of all other |
| work-items in the same sub-group.</p> |
| </li> |
| <li> |
| <p>If the flags have <code>CLK_LOCAL_MEM_FENCE</code> set then for each work-item the |
| entry fence local-synchronizes-with the exit fence of all other |
| work-items in the same sub-group.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Other sub-group functions include such functions as scans, reductions, |
| and broadcasts, and are described in the kernel languages and IL specifications. |
| The use of these sub-group functions implies sequenced-before relationships |
| between statements within the execution of a single work-item in order to |
| satisfy data dependencies. |
| For example, a work-item that provides a value to a sub-group function must |
| behave as if it generates that value before beginning execution of that |
| sub-group function. |
| Furthermore, the programmer must ensure that all work-items in a sub-group |
| must execute the same sub-group function call site, or dynamic sub-group |
| function instance.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_host_side_and_device_side_commands"><a class="anchor" href="#_host_side_and_device_side_commands"></a>3.3.7.5. Host-side and Device-side Commands</h5> |
| <div class="paragraph"> |
| <p>This section describes how the OpenCL API functions associated with |
| command-queues contribute to happens-before relations. |
| There are two types of command queues and associated API functions in OpenCL |
| 2.x; <em>host command-queues</em> and <em>device command-queues</em>. |
| The interaction of these command queues with the memory model are for the |
| most part equivalent. |
| In a few cases, the rules only applies to the host command-queue. |
| We will indicate these special cases by specifically denoting the host |
| command-queue in the memory ordering rule. |
| SVM memory consistency in such instances is implied only with respect to |
| synchronizing host commands.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Memory ordering rules in this section apply to all memory objects (buffers, |
| images and pipes) as well as to SVM allocations where no earlier, and more |
| fine-grained, rules apply.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the remainder of this section, we assume that each command <strong>C</strong> enqueued |
| onto a command-queue has an associated event object <strong>E</strong> that signals its |
| execution status, regardless of whether <strong>E</strong> was returned to the unit of |
| execution that enqueued <strong>C</strong>. |
| We also distinguish between the API function call that enqueues a command |
| <strong>C</strong> and creates an event <strong>E</strong>, the execution of <strong>C</strong>, and the completion of |
| <strong>C</strong>(which marks the event <strong>E</strong> as complete).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The ordering and synchronization rules for API commands are defined as |
| following:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>If an API function call <strong>X</strong> enqueues a command <strong>C</strong>, then <strong>X</strong> |
| global-synchronizes-with <strong>C</strong>. |
| For example, a host API function to enqueue a kernel |
| global-synchronizes-with the start of that kernel-instances execution, |
| so that memory updates sequenced-before the enqueue kernel function call |
| will global-happen-before any kernel reads or writes to those same |
| memory locations. |
| For a device-side enqueue, global memory updates sequenced before <strong>X</strong> |
| happens-before <strong>C</strong> reads or writes to those memory locations only in the |
| case of fine-grained SVM.</p> |
| </li> |
| <li> |
| <p>If <strong>E</strong> is an event upon which a command <strong>C</strong> waits, then <strong>E</strong> |
| global-synchronizes-with <strong>C</strong>. |
| In particular, if <strong>C</strong> waits on an event <strong>E</strong> that is tracking the |
| execution status of the command <strong>C1</strong>, then memory operations done by |
| <strong>C1</strong> will global-happen-before memory operations done by <strong>C</strong>. |
| As an example, assume we have an OpenCL program using coarse-grain SVM |
| sharing that enqueues a kernel to a host command-queue to manipulate the |
| contents of a region of a buffer that the host thread then accesses |
| after the kernel completes. |
| To do this, the host thread can call <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> to enqueue a |
| blocking-mode map command to map that buffer region, specifying that the |
| map command must wait on an event signaling the kernels completion. |
| When <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> returns, any memory operations performed by |
| the kernel to that buffer region will global- happen-before subsequent |
| memory operations made by the host thread.</p> |
| </li> |
| <li> |
| <p>If a command <strong>C</strong> has an event <strong>E</strong> that signals its completion, then <strong>C</strong> |
| global- synchronizes-with <strong>E</strong>.</p> |
| </li> |
| <li> |
| <p>For a command <strong>C</strong> enqueued to a host-side command queue, if <strong>C</strong> has an |
| event <strong>E</strong> that signals its completion, then <strong>E</strong> global-synchronizes-with |
| an API call <strong>X</strong> that waits on <strong>E</strong>. |
| For example, if a host thread or kernel-instance calls the |
| wait-for-events function on <strong>E</strong> (e.g. the <a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a> function |
| called from a host thread), then <strong>E</strong> global-synchronizes-with that |
| wait-for-events function call.</p> |
| </li> |
| <li> |
| <p>If commands <strong>C</strong> and <strong>C1</strong> are enqueued in that sequence onto an in-order |
| command-queue, then the event (including the event implied between <strong>C</strong> |
| and <strong>C1</strong> due to the in-order queue) signaling <strong>C</strong>'s completion |
| global-synchronizes-with <strong>C1</strong>. |
| Note that in OpenCL 2.x, only a host command-queue can be configured as |
| an in-order queue.</p> |
| </li> |
| <li> |
| <p>If an API call enqueues a marker command <strong>C</strong> with an empty list of |
| events upon which <strong>C</strong> should wait, then the events of all commands |
| enqueued prior to <strong>C</strong> in the command-queue global-synchronize-with <strong>C</strong>.</p> |
| </li> |
| <li> |
| <p>If a host API call enqueues a command-queue barrier command <strong>C</strong> with an |
| empty list of events on which <strong>C</strong> should wait, then the events of all |
| commands enqueued prior to <strong>C</strong> in the command-queue |
| global-synchronize-with <strong>C</strong>. |
| In addition, the event signaling the completion of <strong>C</strong> |
| global-synchronizes-with all commands enqueued after <strong>C</strong> in the |
| command-queue.</p> |
| </li> |
| <li> |
| <p>If a host thread executes a <a href="#clFinish"><strong>clFinish</strong></a> call <strong>X</strong>, then the events of all |
| commands enqueued prior to <strong>X</strong> in the command-queue |
| global-synchronizes-with <strong>X</strong>.</p> |
| </li> |
| <li> |
| <p>The start of a kernel-instance <strong>K</strong> global-synchronizes-with all |
| operations in the work-items of <strong>K</strong>. |
| Note that this includes the execution of any atomic operations by the |
| work-items in a program using fine-grain SVM.</p> |
| </li> |
| <li> |
| <p>All operations of all work-items of a kernel-instance <strong>K</strong> |
| global-synchronizes-with the event signaling the completion of <strong>K</strong>. |
| Note that this also includes the execution of any atomic operations by |
| the work-items in a program using fine-grain SVM.</p> |
| </li> |
| <li> |
| <p>If a callback procedure <strong>P</strong> is registered on an event <strong>E</strong>, then <strong>E</strong> |
| global-synchronizes-with all operations of <strong>P</strong>. |
| Note that callback procedures are only defined for commands within host |
| command-queues.</p> |
| </li> |
| <li> |
| <p>If <strong>C</strong> is a command that waits for an event <strong>E</strong>'s completion, and API |
| function call <strong>X</strong> sets the status of a user event <strong>E</strong>'s status to |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> (for example, from a host thread using a |
| <a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a> function), then <strong>X</strong> global-synchronizes-with <strong>C</strong>.</p> |
| </li> |
| <li> |
| <p>If a device enqueues a command <strong>C</strong> with the |
| <code>CLK_ENQUEUE_FLAGS_WAIT_KERNEL</code> flag, then the end state of the parent |
| kernel instance global-synchronizes with <strong>C</strong>.</p> |
| </li> |
| <li> |
| <p>If a work-group enqueues a command <strong>C</strong> with the |
| <code>CLK_ENQUEUE_FLAGS_WAIT_WORK_GROUP</code> flag, then the end state of the |
| work-group global-synchronizes with <strong>C</strong>.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>When using an out-of-order command queue, a wait on an event or a marker or |
| command-queue barrier command can be used to ensure the correct ordering of |
| dependent commands. |
| In those cases, the wait for the event or the marker or barrier command will |
| provide the necessary global-synchronizes-with relation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this situation:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>access to shared locations or disjoint locations in a single <code>cl_mem</code> |
| object when using atomic operations from different kernel instances |
| enqueued from the host such that one or more of the atomic operations is |
| a write is implementation-defined and correct behavior is not guaranteed |
| except at synchronization points.</p> |
| </li> |
| <li> |
| <p>access to shared locations or disjoint locations in a single <code>cl_mem</code> |
| object when using atomic operations from different kernel instances |
| consisting of a parent kernel and any number of child kernels enqueued |
| by that kernel is guaranteed under the memory ordering rules described |
| earlier in this section.</p> |
| </li> |
| <li> |
| <p>access to shared locations or disjoint locations in a single program |
| scope global variable, coarse-grained SVM allocation or fine-grained SVM |
| allocation when using atomic operations from different kernel instances |
| enqueued from the host to a single device is guaranteed under the memory |
| ordering rules described earlier in this section.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If fine-grain SVM is used but without support for the OpenCL 2.x atomic |
| operations, then the host and devices can concurrently read the same memory |
| locations and can concurrently update non-overlapping memory regions, but |
| attempts to update the same memory locations are undefined. |
| Memory consistency is guaranteed at the OpenCL synchronization points |
| without the need for calls to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and |
| <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>. |
| For fine-grained SVM buffers it is guaranteed that at synchronization points |
| only values written by the kernel will be updated. |
| No writes to fine-grained SVM buffers can be introduced that were not in the |
| original program.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the remainder of this section, we discuss a few points regarding the |
| ordering rules for commands with a host command queue.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| In an OpenCL 1.x implementation a synchronization point is a |
| kernel-instance or host program location where the contents of memory |
| visible to different work-items or command-queue commands are the same. |
| It also says that waiting on an event and a command-queue barrier are |
| synchronization points between commands in command-queues. |
| Four of the rules listed above (2, 4, 7, and 8) cover these OpenCL |
| synchronization points. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A map operation (<a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) performed on a |
| non-SVM buffer or a coarse-grained SVM buffer is allowed to overwrite the |
| entire target region with the latest runtime view of the data as seen by the |
| command with which the map operation synchronizes, whether the values were |
| written by the executing kernels or not. |
| Any values that were changed within this region by another kernel or host |
| thread while the kernel synchronizing with the map operation was executing |
| may be overwritten by the map operation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Access to non-SVM <code>cl_mem</code> buffers and coarse-grained SVM allocations is |
| ordered at synchronization points between host commands. |
| In the presence of an out-of-order command queue or a set of command queues |
| mapped to the same device, multiple kernel instances may execute |
| concurrently on the same device.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="opencl-framework"><a class="anchor" href="#opencl-framework"></a>3.4. The OpenCL Framework</h3> |
| <div class="paragraph"> |
| <p>The OpenCL framework allows applications to use a host and one or more |
| OpenCL devices as a single heterogeneous parallel computer system. |
| The framework contains the following components:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>OpenCL Platform layer</strong>: The platform layer allows the host program to |
| discover OpenCL devices and their capabilities and to create contexts.</p> |
| </li> |
| <li> |
| <p><strong>OpenCL Runtime</strong>: The runtime allows the host program to manipulate |
| contexts once they have been created.</p> |
| </li> |
| <li> |
| <p><strong>OpenCL Compiler</strong>: The OpenCL compiler creates program executables that |
| contain OpenCL kernels. |
| The OpenCL compiler may build program executables from OpenCL C source |
| strings, the SPIR-V intermediate language, or device-specific program |
| binary objects, depending on the capabilities of a device. |
| Other kernel languages or intermediate languages may be supported by |
| some implementations.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="_mixed_version_support"><a class="anchor" href="#_mixed_version_support"></a>3.4.1. Mixed Version Support</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Mixed version support <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL supports devices with different capabilities under a single platform. |
| This includes devices which conform to different versions of the OpenCL |
| specification. |
| There are three version identifiers to consider for an OpenCL system: the |
| platform version, the version of a device, and the version(s) of the kernel |
| language or IL supported on a device.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The platform version indicates the version of the OpenCL runtime that is |
| supported. |
| This includes all of the APIs that the host can use to interact with |
| resources exposed by the OpenCL runtime; including contexts, memory objects, |
| devices, and command queues.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The device version is an indication of the device’s capabilities separate |
| from the runtime and compiler as represented by the device info returned by |
| <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>. |
| Examples of attributes associated with the device version are resource |
| limits (e.g., minimum size of local memory per compute unit) and extended |
| functionality (e.g., list of supported KHR extensions). |
| The version returned corresponds to the highest version of the OpenCL |
| specification for which the device is conformant, but is not higher than the |
| platform version.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The language version for a device represents the OpenCL programming language |
| features a developer can assume are supported on a given device. |
| The version reported is the highest version of the language supported.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_backwards_compatibility"><a class="anchor" href="#_backwards_compatibility"></a>3.4.2. Backwards Compatibility</h4> |
| <div class="paragraph"> |
| <p>Backwards compatibility is an important goal for the OpenCL standard. |
| Backwards compatibility is expected such that a device will consume earlier |
| versions of the OpenCL C programming languages and the SPIR-V intermediate language with the following |
| minimum requirements:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>An OpenCL 1.x device must support at least one 1.x version of the OpenCL C programming language.</p> |
| </li> |
| <li> |
| <p>An OpenCL 2.0 device must support all the requirements of an OpenCL 1.2 device in addition to the OpenCL C 2.0 programming language. |
| If multiple language versions are supported, the compiler defaults to using the OpenCL C 1.2 language version. |
| To utilize the OpenCL 2.0 Kernel programming language, a programmer must specifically pass the appropriate compiler build option (<code>-cl-std=CL2.0</code>). |
| The language version must not be higher than the platform version, but may exceed the <a href="#opencl-c-version">device version</a>.</p> |
| </li> |
| <li> |
| <p>An OpenCL 2.1 device must support all the requirements of an OpenCL 2.0 device in addition to the SPIR-V intermediate language at version 1.0 or above. |
| Intermediate language versioning is encoded as part of the binary object and no flags are required to be passed to the compiler.</p> |
| </li> |
| <li> |
| <p>An OpenCL 2.2 device must support all the requirements of an OpenCL 2.0 device in addition to the SPIR-V intermediate language at version 1.2 or above. |
| Intermediate language versioning is encoded as a part of the binary object and no flags are required to be passed to the compiler.</p> |
| </li> |
| <li> |
| <p>OpenCL 3.0 is designed to enable any OpenCL implementation supporting OpenCL 1.2 or newer to easily support and transition to OpenCL 3.0, by making many features in OpenCL 2.0, 2.1, or 2.2 optional. |
| This means that OpenCL 3.0 is backwards compatible with OpenCL 1.2, but is not necessarily backwards compatible with OpenCL 2.0, 2.1, or 2.2.</p> |
| <div class="paragraph"> |
| <p>An OpenCL 3.0 platform must implement all OpenCL 3.0 APIs, but some APIs may return an error code unconditionally when a feature is not supported by any devices in the platform. |
| Whenever a feature is optional, it will be paired with a query to determine whether the feature is supported. |
| The queries will enable correctly written applications to selectively use all optional features without generating any OpenCL errors, if desired.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 also adds a new version of the OpenCL C programming language, which makes many features in OpenCL C 2.0 optional. |
| The new version of OpenCL C is backwards compatible with OpenCL C 1.2, but is not backwards compatible with OpenCL C 2.0. |
| The new version of OpenCL C must be explicitly requested via the <code>-cl-std=</code> build option, otherwise a program will continue to be compiled using the highest OpenCL C 1.x language version supported for the device.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Whenever an OpenCL C feature is optional in the new version of the OpenCL C programming language, it will be paired with a feature macro, such as <code>__opencl_c_feature_name</code>, and a corresponding API query. |
| If a feature macro is defined then the feature is supported by the OpenCL C compiler, otherwise the optional feature is not supported.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In order to allow future versions of OpenCL to support new types of |
| devices, minor releases of OpenCL may add new profiles where some |
| features that are currently required for all OpenCL devices become |
| optional. |
| All features that are required for an OpenCL profile will also be |
| required for that profile in subsequent minor releases of OpenCL, |
| thereby guaranteeing backwards compatibility for applications |
| targeting specific profiles. |
| It is therefore strongly recommended that applications |
| <a href="#CL_DEVICE_PROFILE">query the profile</a> supported by the OpenCL device |
| they are running on in order to remain robust to future changes.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_versioning"><a class="anchor" href="#_versioning"></a>3.4.3. Versioning</h4> |
| <div class="paragraph"> |
| <p>The OpenCL specification is regularly updated with bug fixes and clarifications. |
| Occasionally new functionality is added to the core and extensions. In order to |
| indicate to developers how and when these changes are made to the specification, |
| and to provide a way to identify each set of changes, the OpenCL API, C language, |
| intermediate languages and extensions maintain a version number. Built-in kernels |
| are also versioned.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_versions"><a class="anchor" href="#_versions"></a>3.4.3.1. Versions</h5> |
| <div class="paragraph"> |
| <p>A version number comprises three logical fields:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <em>major</em> version indicates a significant change. Backwards compatibility may |
| break across major versions.</p> |
| </li> |
| <li> |
| <p>The <em>minor</em> version indicates the addition of new functionality with backwards |
| compatibility for any existing profiles.</p> |
| </li> |
| <li> |
| <p>The <em>patch</em> version indicates bug fixes, clarifications and general improvements.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Version numbers are represented using the <code>cl_version</code> type that is an alias for |
| a 32-bit integer. The fields are packed as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <em>major</em> version is a 10-bit integer packed into bits 31-22.</p> |
| </li> |
| <li> |
| <p>The <em>minor</em> version is a 10-bit integer packed into bits 21-12.</p> |
| </li> |
| <li> |
| <p>The <em>patch</em> version is a 12-bit integer packed into bits 11-0.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This enables versions to be ordered using standard C/C++ operators.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A number of convenience macros are provided by the OpenCL Headers to make |
| working with version numbers easier.</p> |
| </div> |
| <div class="paragraph"> |
| <p><code>CL_VERSION_MAJOR</code> extracts the <em>major</em> version from a packed <code>cl_version</code>.<br> |
| <code>CL_VERSION_MINOR</code> extracts the <em>minor</em> version from a packed <code>cl_version</code>.<br> |
| <code>CL_VERSION_PATCH</code> extracts the <em>patch</em> version from a packed <code>cl_version</code>.<br> |
| <code>CL_MAKE_VERSION</code> returns a packed <code>cl_version</code> from a <em>major</em>, <em>minor</em> and |
| <em>patch</em> version.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These are defined as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="keyword">typedef</span> cl_uint cl_version; |
| |
| <span class="preprocessor">#define</span> CL_VERSION_MAJOR_BITS (<span class="integer">10</span>) |
| <span class="preprocessor">#define</span> CL_VERSION_MINOR_BITS (<span class="integer">10</span>) |
| <span class="preprocessor">#define</span> CL_VERSION_PATCH_BITS (<span class="integer">12</span>) |
| |
| <span class="preprocessor">#define</span> CL_VERSION_MAJOR_MASK ((<span class="integer">1</span> << CL_VERSION_MAJOR_BITS) - <span class="integer">1</span>) |
| <span class="preprocessor">#define</span> CL_VERSION_MINOR_MASK ((<span class="integer">1</span> << CL_VERSION_MINOR_BITS) - <span class="integer">1</span>) |
| <span class="preprocessor">#define</span> CL_VERSION_PATCH_MASK ((<span class="integer">1</span> << CL_VERSION_PATCH_BITS) - <span class="integer">1</span>) |
| |
| <span class="preprocessor">#define</span> CL_VERSION_MAJOR(version) \ |
| ((version) >> (CL_VERSION_MINOR_BITS + CL_VERSION_PATCH_BITS)) |
| |
| <span class="preprocessor">#define</span> CL_VERSION_MINOR(version) \ |
| (((version) >> CL_VERSION_PATCH_BITS) & CL_VERSION_MINOR_MASK) |
| |
| <span class="preprocessor">#define</span> CL_VERSION_PATCH(version) ((version) & CL_VERSION_PATCH_MASK) |
| |
| <span class="preprocessor">#define</span> CL_MAKE_VERSION(major, minor, patch) \ |
| ((((major)& CL_VERSION_MAJOR_MASK) << \ |
| (CL_VERSION_MINOR_BITS + CL_VERSION_PATCH_BITS)) | \ |
| (((minor)& CL_VERSION_MINOR_MASK) << \ |
| CL_VERSION_PATCH_BITS) | \ |
| ((patch) & CL_VERSION_PATCH_MASK))</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_version_name_pairing"><a class="anchor" href="#_version_name_pairing"></a>3.4.3.2. Version name pairing</h5> |
| <div class="paragraph"> |
| <p>It is sometimes necessary to associate a version to an entity it applies to |
| (e.g. extension or built-in kernel). This is done using a dedicated |
| <a href="#cl_name_version"><code>cl_name_<wbr>version</code></a> structure, defined as follows:</p> |
| </div> |
| <div id="cl_name_version" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_name_version { |
| cl_version version; |
| <span class="predefined-type">char</span> name[CL_NAME_VERSION_MAX_NAME_SIZE]; |
| } cl_name_version;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>name</code> field is an array of <code>CL_NAME_VERSION_MAX_NAME_SIZE</code> bytes used as |
| storage for a NUL-terminated string whose maximum length is therefore |
| <code>CL_NAME_VERSION_MAX_NAME_SIZE - 1</code>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="opencl-platform-layer"><a class="anchor" href="#opencl-platform-layer"></a>4. The OpenCL Platform Layer</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This section describes the OpenCL platform layer which implements |
| platform-specific features that allow applications to query OpenCL devices, |
| device configuration information, and to create OpenCL contexts using one or |
| more devices.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_querying_platform_info"><a class="anchor" href="#_querying_platform_info"></a>4.1. Querying Platform Info</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The list of platforms available can be obtained with the function:</p> |
| </div> |
| <div id="clGetPlatformIDs" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetPlatformIDs( |
| cl_uint num_entries, |
| cl_platform_id* platforms, |
| cl_uint* num_platforms);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>num_entries</em> is the number of <code>cl_platform_<wbr>id</code> entries that can be added to |
| <em>platforms</em>. |
| If <em>platforms</em> is not <code>NULL</code>, the <em>num_entries</em> must be greater than zero.</p> |
| </li> |
| <li> |
| <p><em>platforms</em> returns a list of OpenCL platforms found. |
| The <code>cl_platform_<wbr>id</code> values returned in <em>platforms</em> can be used to identify a |
| specific OpenCL platform. |
| If <em>platforms</em> is <code>NULL</code>, this argument is ignored. |
| The number of OpenCL platforms returned is the minimum of the value |
| specified by <em>num_entries</em> or the number of OpenCL platforms available.</p> |
| </li> |
| <li> |
| <p><em>num_platforms</em> returns the number of OpenCL platforms available. |
| If <em>num_platforms</em> is <code>NULL</code>, this argument is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetPlatformIDs"><strong>clGetPlatformIDs</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_entries</em> is equal to zero and <em>platforms</em> is |
| not <code>NULL</code> or if both <em>num_platforms</em> and <em>platforms</em> are <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Specific information about an OpenCL platform can be obtained with |
| the function:</p> |
| </div> |
| <div id="clGetPlatformInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetPlatformInfo( |
| cl_platform_id platform, |
| cl_platform_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>platform</em> refers to the platform ID returned by <a href="#clGetPlatformIDs"><strong>clGetPlatformIDs</strong></a> or can |
| be <code>NULL</code>. |
| If <em>platform</em> is <code>NULL</code>, the behavior is implementation-defined.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> is an enumeration constant that identifies the platform |
| information being queried. |
| It can be one of the following values as specified in the |
| <a href="#platform-queries-table">Platform Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory location where appropriate values for a |
| given <em>param_name</em>, as specified in the <a href="#platform-queries-table">Platform |
| Queries</a> table, will be returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> specifies the size in bytes of memory pointed to by |
| <em>param_value</em>. |
| This size in bytes must be ≥ size of return type specified in the |
| <a href="#platform-queries-table">Platform Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The information that can be queried using <a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> is specified |
| in the <a href="#platform-queries-table">Platform Queries</a> table.</p> |
| </div> |
| <table id="platform-queries-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 3. List of supported param_names by <a href="#clGetPlatformInfo">clGetPlatformInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Platform Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_PROFILE"></a><a href="#CL_PLATFORM_PROFILE"><code>CL_PLATFORM_<wbr>PROFILE</code></a> <sup class="footnote">[<a id="_footnoteref_2" class="footnote" href="#_footnotedef_2" title="View footnote.">2</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[] <sup class="footnote">[<a id="_footnoteref_3" class="footnote" href="#_footnotedef_3" title="View footnote.">3</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL profile string. |
| Returns the profile name supported by the implementation. |
| The profile name returned can be one of the following strings:</p> |
| <p class="tableblock"> FULL_PROFILE - if the implementation supports the OpenCL |
| specification (functionality defined as part of the core |
| specification and does not require any extensions to be supported).</p> |
| <p class="tableblock"> EMBEDDED_PROFILE - if the implementation supports the OpenCL |
| embedded profile. |
| The embedded profile is defined to be a subset for each version of |
| OpenCL. |
| The embedded profile for OpenCL is described in |
| <a href="#opencl-embedded-profile">OpenCL Embedded Profile</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_VERSION"></a><a href="#CL_PLATFORM_VERSION"><code>CL_PLATFORM_<wbr>VERSION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL version string. |
| Returns the OpenCL version supported by the implementation. |
| This version string has the following format:</p> |
| <p class="tableblock"> <em>OpenCL<space><major_version.minor_version><space><platform-specific |
| information></em></p> |
| <p class="tableblock"> The <em>major_version.minor_version</em> value returned will be one of 1.0, |
| 1.1, 1.2, 2.0, 2.1, 2.2 or 3.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_NUMERIC_VERSION"></a><a href="#CL_PLATFORM_NUMERIC_VERSION"><code>CL_PLATFORM_<wbr>NUMERIC_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_version</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the detailed (major, minor, patch) version supported by the |
| platform. The major and minor version numbers returned must match |
| those returned via <a href="#CL_PLATFORM_VERSION"><code>CL_PLATFORM_<wbr>VERSION</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_NAME"></a><a href="#CL_PLATFORM_NAME"><code>CL_PLATFORM_<wbr>NAME</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Platform name string.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_VENDOR"></a><a href="#CL_PLATFORM_VENDOR"><code>CL_PLATFORM_<wbr>VENDOR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Platform vendor string.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_EXTENSIONS"></a><a href="#CL_PLATFORM_EXTENSIONS"><code>CL_PLATFORM_<wbr>EXTENSIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns a space separated list of extension names (the extension |
| names themselves do not contain any spaces) supported by the |
| platform. |
| Each extension that is supported by all devices associated with this |
| platform must be reported here.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_EXTENSIONS_WITH_VERSION"></a><a href="#CL_PLATFORM_EXTENSIONS_WITH_VERSION"><code>CL_PLATFORM_<wbr>EXTENSIONS_<wbr>WITH_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_name_version"><code>cl_name_<wbr>version</code></a>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of description (name and version) structures that lists |
| all the extensions supported by the platform. The same extension name |
| must not be reported more than once. The list of extensions reported |
| must match the list reported via <a href="#CL_PLATFORM_EXTENSIONS"><code>CL_PLATFORM_<wbr>EXTENSIONS</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_HOST_TIMER_RESOLUTION"></a><a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_PLATFORM_<wbr>HOST_<wbr>TIMER_<wbr>RESOLUTION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the resolution of the host timer in nanoseconds as used by |
| <a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a>.</p> |
| <p class="tableblock"> Support for device and host timer synchronization is required for |
| platforms supporting OpenCL 2.1 or 2.2. |
| This value must be 0 for devices that do not support device and |
| host timer synchronization.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following |
| errors <sup class="footnote">[<a id="_footnoteref_4" class="footnote" href="#_footnotedef_4" title="View footnote.">4</a>]</sup>.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PLATFORM"><code>CL_INVALID_<wbr>PLATFORM</code></a> if <em>platform</em> is not a valid platform.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not one of the supported values or |
| if size in bytes specified by <em>param_value_size</em> is < size of return |
| type as specified in the <a href="#platform-queries-table">OpenCL Platform |
| Queries</a> table, and <em>param_value</em> is not a <code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="platform-querying-devices"><a class="anchor" href="#platform-querying-devices"></a>4.2. Querying Devices</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The list of devices available on a platform can be obtained using the |
| function <sup class="footnote">[<a id="_footnoteref_5" class="footnote" href="#_footnotedef_5" title="View footnote.">5</a>]</sup>:</p> |
| </div> |
| <div id="clGetDeviceIDs" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetDeviceIDs( |
| cl_platform_id platform, |
| cl_device_type device_type, |
| cl_uint num_entries, |
| cl_device_id* devices, |
| cl_uint* num_devices);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>platform</em> refers to the platform ID returned by <a href="#clGetPlatformIDs"><strong>clGetPlatformIDs</strong></a> or can |
| be <code>NULL</code>. |
| If <em>platform</em> is <code>NULL</code>, the behavior is implementation-defined.</p> |
| </li> |
| <li> |
| <p><em>device_type</em> is a bitfield that identifies the type of OpenCL device. |
| The <em>device_type</em> can be used to query specific OpenCL devices or all OpenCL |
| devices available. |
| The valid values for <em>device_type</em> are specified in the |
| <a href="#device-types-table">Device Types</a> table.</p> |
| </li> |
| <li> |
| <p><em>num_entries</em> is the number of <code>cl_device_<wbr>id</code> entries that can be added to |
| <em>devices</em>. |
| If <em>devices</em> is not <code>NULL</code>, the <em>num_entries</em> must be greater than zero.</p> |
| </li> |
| <li> |
| <p><em>devices</em> returns a list of OpenCL devices found. |
| The <code>cl_device_<wbr>id</code> values returned in <em>devices</em> can be used to identify a |
| specific OpenCL device. |
| If <em>devices</em> is <code>NULL</code>, this argument is ignored. |
| The number of OpenCL devices returned is the minimum of the value specified |
| by <em>num_entries</em> or the number of OpenCL devices whose type matches |
| <em>device_type</em>.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> returns the number of OpenCL devices available that match |
| <em>device_type</em>. |
| If <em>num_devices</em> is <code>NULL</code>, this argument is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="device-types-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 4. List of supported device_types by <a href="#clGetDeviceIDs">clGetDeviceIDs</a></caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Device Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_CPU"></a><a href="#CL_DEVICE_TYPE_CPU"><code>CL_DEVICE_<wbr>TYPE_<wbr>CPU</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">An OpenCL device similar to a traditional CPU (Central Processing Unit). |
| The host processor that executes OpenCL host code may also be considered |
| a CPU OpenCL device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_GPU"></a><a href="#CL_DEVICE_TYPE_GPU"><code>CL_DEVICE_<wbr>TYPE_<wbr>GPU</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">An OpenCL device similar to a GPU (Graphics Processing Unit). |
| Many systems include a dedicated processor for graphics or rendering |
| that may be considered a GPU OpenCL device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_ACCELERATOR"></a><a href="#CL_DEVICE_TYPE_ACCELERATOR"><code>CL_DEVICE_<wbr>TYPE_<wbr>ACCELERATOR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dedicated devices that may accelerate OpenCL programs, such as FPGAs |
| (Field Programmable Gate Arrays), DSPs (Digital Signal Processors), or |
| AI (Artificial Intelligence) processors.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_CUSTOM"></a><a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specialized devices that implement some of the OpenCL runtime APIs but |
| do not support all required OpenCL functionality.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_DEFAULT"></a><a href="#CL_DEVICE_TYPE_DEFAULT"><code>CL_DEVICE_<wbr>TYPE_<wbr>DEFAULT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The default OpenCL device in the platform. |
| The default OpenCL device must not be a <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a> device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_ALL"></a><a href="#CL_DEVICE_TYPE_ALL"><code>CL_DEVICE_<wbr>TYPE_<wbr>ALL</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">All OpenCL devices available in the platform, except for |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a> devices.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The device type is purely informational and has no semantic meaning.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Some devices may be more than one type. |
| For example, a <a href="#CL_DEVICE_TYPE_CPU"><code>CL_DEVICE_<wbr>TYPE_<wbr>CPU</code></a> device may also be a |
| <a href="#CL_DEVICE_TYPE_GPU"><code>CL_DEVICE_<wbr>TYPE_<wbr>GPU</code></a> device, or a <a href="#CL_DEVICE_TYPE_ACCELERATOR"><code>CL_DEVICE_<wbr>TYPE_<wbr>ACCELERATOR</code></a> device |
| may also be some other, more descriptive device type. |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a> devices must not be combined with any other |
| device types.</p> |
| </div> |
| <div class="paragraph"> |
| <p>One device in the platform should be a <a href="#CL_DEVICE_TYPE_DEFAULT"><code>CL_DEVICE_<wbr>TYPE_<wbr>DEFAULT</code></a> device. |
| The default device should also be a more specific device type, such |
| as <a href="#CL_DEVICE_TYPE_CPU"><code>CL_DEVICE_<wbr>TYPE_<wbr>CPU</code></a> or <a href="#CL_DEVICE_TYPE_GPU"><code>CL_DEVICE_<wbr>TYPE_<wbr>GPU</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PLATFORM"><code>CL_INVALID_<wbr>PLATFORM</code></a> if <em>platform</em> is not a valid platform.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE_TYPE"><code>CL_INVALID_<wbr>DEVICE_<wbr>TYPE</code></a> if <em>device_type</em> is not a valid value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_entries</em> is equal to zero and <em>devices</em> is not |
| <code>NULL</code> or if both <em>num_devices</em> and <em>devices</em> are <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_NOT_FOUND"><code>CL_DEVICE_<wbr>NOT_<wbr>FOUND</code></a> if no OpenCL devices that matched <em>device_type</em> were |
| found.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The application can query specific capabilities of the OpenCL device(s) |
| returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>. |
| This can be used by the application to determine which device(s) to use.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To get specific information about an OpenCL device, call the function:</p> |
| </div> |
| <div id="clGetDeviceInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetDeviceInfo( |
| cl_device_id device, |
| cl_device_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>device</em> may be a device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> or a sub-device |
| created by <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>. |
| If <em>device</em> is a sub-device, the specific information for the sub-device |
| will be returned. |
| The information that can be queried using <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> is specified in |
| the <a href="#device-queries-table">Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> is an enumeration constant that identifies the device |
| information being queried. |
| It can be one of the following values as specified in the |
| <a href="#device-queries-table">Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory location where appropriate values for a |
| given <em>param_name</em>, as specified in the <a href="#device-queries-table">Device |
| Queries</a> table, will be returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> specifies the size in bytes of memory pointed to by |
| <em>param_value</em>. |
| This size in bytes must be ≥ size of return type specified in the |
| <a href="#device-queries-table">Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The device queries described in the <a href="#device-queries-table">Device Queries</a> |
| table should return the same information for a root-level device i.e. a |
| device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> and any sub-devices created from this |
| device except for the following queries:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_DEVICE_GLOBAL_MEM_CACHE_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>MEM_<wbr>CACHE_<wbr>SIZE</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_BUILT_IN_KERNELS"><code>CL_DEVICE_<wbr>BUILT_<wbr>IN_<wbr>KERNELS</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_PARENT_DEVICE"><code>CL_DEVICE_<wbr>PARENT_<wbr>DEVICE</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_PARTITION_TYPE"><code>CL_DEVICE_<wbr>PARTITION_<wbr>TYPE</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_REFERENCE_COUNT"><code>CL_DEVICE_<wbr>REFERENCE_<wbr>COUNT</code></a></p> |
| </li> |
| </ul> |
| </div> |
| <table id="device-queries-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 5. List of supported param_names by <a href="#clGetDeviceInfo">clGetDeviceInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Device Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE"></a><a href="#CL_DEVICE_TYPE"><code>CL_DEVICE_<wbr>TYPE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The type or types of the OpenCL device.</p> |
| <p class="tableblock"> Please see the <a href="#device-types-table">Device Types</a> table |
| for supported device types and device type combinations.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_VENDOR_ID"></a><a href="#CL_DEVICE_VENDOR_ID"><code>CL_DEVICE_<wbr>VENDOR_<wbr>ID</code></a> <sup class="footnote">[<a id="_footnoteref_6" class="footnote" href="#_footnotedef_6" title="View footnote.">6</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A unique device vendor identifier.</p> |
| <p class="tableblock"> If the vendor has a PCI vendor ID, the low 16 bits must contain that PCI |
| vendor ID, and the remaining bits must be set to zero. Otherwise, the |
| value returned must be a valid Khronos vendor ID represented by type |
| <code>cl_khronos_<wbr>vendor_<wbr>id</code>. Khronos vendor IDs are allocated starting at |
| 0x10000, to distinguish them from the PCI vendor ID namespace.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_COMPUTE_UNITS"></a><a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_DEVICE_<wbr>MAX_<wbr>COMPUTE_<wbr>UNITS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The number of parallel compute units on the OpenCL device. |
| A work-group executes on a single compute unit. |
| The minimum value is 1.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"></a><a href="#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>DIMENSIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum dimensions that specify the global and local work-item IDs |
| used by the data parallel execution model. (Refer to |
| <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>). |
| The minimum value is 3 for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WORK_ITEM_SIZES"></a><a href="#CL_DEVICE_MAX_WORK_ITEM_SIZES"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>SIZES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of work-items that can be specified in each dimension |
| of the work-group to <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>.</p> |
| <p class="tableblock"> Returns <em>n</em> <code>size_t</code> entries, where <em>n</em> is the value returned by the |
| query for <a href="#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>DIMENSIONS</code></a>.</p> |
| <p class="tableblock"> The minimum value is (1, 1, 1) for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WORK_GROUP_SIZE"></a><a href="#CL_DEVICE_MAX_WORK_GROUP_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of work-items in a work-group that a device is |
| capable of executing on a single compute unit, for any given |
| kernel-instance running on the device. (Refer also to |
| <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> and <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> ). |
| The minimum value is 1. |
| The returned value is an upper limit and will not necessarily |
| maximize performance. |
| This maximum may be larger than supported by a specific kernel |
| (refer to the <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> query of <a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a>).</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>CHAR</code></a> <br> |
| <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>SHORT</code></a> <br> |
| <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>INT</code></a> <br> |
| <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>LONG</code></a> <br> |
| <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>FLOAT</code></a> <br> |
| <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>DOUBLE</code></a><br> |
| <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>HALF</code></a></p> |
| <p class="tableblock"> <a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>HALF</code></a> is <a href="#unified-spec">missing before</a> |
| version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Preferred native vector width size for built-in scalar types that |
| can be put into vectors. |
| The vector width is defined as the number of scalar elements that |
| can be stored in the vector.</p> |
| <p class="tableblock"> If double precision is not supported, |
| <a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>DOUBLE</code></a> must return 0.</p> |
| <p class="tableblock"> If the <strong>cl_khr_fp16</strong> extension is not supported, |
| <a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>VECTOR_<wbr>WIDTH_<wbr>HALF</code></a> must return 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>CHAR</code></a> <br> |
| <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>SHORT</code></a> <br> |
| <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_INT"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_INT"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>INT</code></a> <br> |
| <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>LONG</code></a> <br> |
| <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>FLOAT</code></a> <br> |
| <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>DOUBLE</code></a><br> |
| <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>HALF</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the native ISA vector width. |
| The vector width is defined as the number of scalar elements that |
| can be stored in the vector.</p> |
| <p class="tableblock"> If double precision is not supported, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>DOUBLE</code></a> must return 0.</p> |
| <p class="tableblock"> If the <strong>cl_khr_fp16</strong> extension is not supported, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>HALF</code></a> must return 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_CLOCK_FREQUENCY"></a><a href="#CL_DEVICE_MAX_CLOCK_FREQUENCY"><code>CL_DEVICE_<wbr>MAX_<wbr>CLOCK_<wbr>FREQUENCY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Clock frequency of the device in MHz. |
| The meaning of this value is implementation-defined. |
| For devices with multiple clock domains, the clock frequency for any |
| of the clock domains may be returned. |
| For devices that dynamically change frequency for power or thermal |
| reasons, the returned clock frequency may be any valid frequency. |
| Note: This definition is <a href="#unified-spec">missing before</a> version 2.2.</p> |
| <p class="tableblock"> Maximum configured clock frequency of the device in MHz. |
| Note: This definition is <a href="#unified-spec">deprecated by</a> version 2.2.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ADDRESS_BITS"></a><a href="#CL_DEVICE_ADDRESS_BITS"><code>CL_DEVICE_<wbr>ADDRESS_<wbr>BITS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The default compute device address space size of the global address |
| space specified as an unsigned integer value in bits. |
| Currently supported values are 32 or 64 bits.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_MEM_ALLOC_SIZE"></a><a href="#CL_DEVICE_MAX_MEM_ALLOC_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>MEM_<wbr>ALLOC_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max size of memory object allocation in bytes. |
| The minimum value is max(min(1024 × 1024 × 1024, 1/4<sup>th</sup> |
| of <a href="#CL_DEVICE_GLOBAL_MEM_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>MEM_<wbr>SIZE</code></a>), 32 × 1024 × 1024) for |
| devices that are not of type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_SUPPORT"></a><a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if images are supported by the OpenCL device and <a href="#CL_FALSE"><code>CL_FALSE</code></a> |
| otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_READ_IMAGE_ARGS"></a><a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a> <sup class="footnote">[<a id="_footnoteref_7" class="footnote" href="#_footnotedef_7" title="View footnote.">7</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the |
| read_only qualifier. |
| The minimum value is 128 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the |
| value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WRITE_IMAGE_ARGS"></a><a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the |
| write_only qualifier. |
| The minimum value is 64 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the |
| value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"></a><a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the |
| write_only or read_write qualifier.</p> |
| <p class="tableblock"> Support for read-write image arguments is required for an OpenCL 2.0, 2.1, |
| or 2.2 device if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>.</p> |
| <p class="tableblock"> The minimum value is 64 if the device supports read-write images arguments, |
| and must be 0 for devices that do not support read-write images.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IL_VERSION"></a><a href="#CL_DEVICE_IL_VERSION"><code>CL_DEVICE_<wbr>IL_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_il_program</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The intermediate languages that can be supported by |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> for this device. |
| Returns a space-separated list of IL version strings of the form |
| <IL_Prefix>_<Major_Version>.<Minor_Version>.</p> |
| <p class="tableblock"> For an OpenCL 2.1 or 2.2 device, SPIR-V is a required IL prefix.</p> |
| <p class="tableblock"> If the device does not support intermediate language programs, the |
| value must be <code>""</code> (an empty string).</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ILS_WITH_VERSION"></a><a href="#CL_DEVICE_ILS_WITH_VERSION"><code>CL_DEVICE_<wbr>ILS_<wbr>WITH_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0. |
| Also see extension <strong>cl_khr_il_program</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_name_version"><code>cl_name_<wbr>version</code></a>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of descriptions (name and version) for all supported |
| intermediate languages. Intermediate languages with the same name may be |
| reported more than once but each name and major/minor version |
| combination may only be reported once. The list of intermediate |
| languages reported must match the list reported via |
| <a href="#CL_DEVICE_IL_VERSION"><code>CL_DEVICE_<wbr>IL_<wbr>VERSION</code></a>.</p> |
| <p class="tableblock"> For an OpenCL 2.1 or 2.2 device, at least one version of SPIR-V must |
| be reported.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE2D_MAX_WIDTH"></a><a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max width of 2D image or 1D image not created from a buffer object |
| in pixels.</p> |
| <p class="tableblock"> The minimum value is 16384 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE2D_MAX_HEIGHT"></a><a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>HEIGHT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max height of 2D image in pixels.</p> |
| <p class="tableblock"> The minimum value is 16384 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE3D_MAX_WIDTH"></a><a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max width of 3D image in pixels.</p> |
| <p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE3D_MAX_HEIGHT"></a><a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max height of 3D image in pixels.</p> |
| <p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE3D_MAX_DEPTH"></a><a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max depth of 3D image in pixels.</p> |
| <p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"></a><a href="#CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"><code>CL_DEVICE_<wbr>IMAGE_<wbr>MAX_<wbr>BUFFER_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of pixels for a 1D image created from a buffer object.</p> |
| <p class="tableblock"> The minimum value is 65536 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"></a><a href="#CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"><code>CL_DEVICE_<wbr>IMAGE_<wbr>MAX_<wbr>ARRAY_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of images in a 1D or 2D image array.</p> |
| <p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_SAMPLERS"></a><a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_DEVICE_<wbr>MAX_<wbr>SAMPLERS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of samplers that can be used in a kernel.</p> |
| <p class="tableblock"> The minimum value is 16 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_PITCH_ALIGNMENT"></a><a href="#CL_DEVICE_IMAGE_PITCH_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>PITCH_<wbr>ALIGNMENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The row pitch alignment size in pixels for 2D images created from a |
| buffer. |
| The value returned must be a power of 2.</p> |
| <p class="tableblock"> Support for 2D images created from a buffer is required for an OpenCL 2.0, 2.1, |
| or 2.2 device if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>.</p> |
| <p class="tableblock"> This value must be 0 for devices that do not support 2D images created from a buffer.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"></a><a href="#CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>BASE_<wbr>ADDRESS_<wbr>ALIGNMENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This query specifies the minimum alignment in pixels of the host_ptr |
| specified to <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> when a 2D image |
| is created from a buffer which was created using <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>. |
| The value returned must be a power of 2.</p> |
| <p class="tableblock"> Support for 2D images created from a buffer is required for an OpenCL 2.0, 2.1, |
| or 2.2 device if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>.</p> |
| <p class="tableblock"> This value must be 0 for devices that do not support 2D images created from a buffer.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_PIPE_ARGS"></a><a href="#CL_DEVICE_MAX_PIPE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>PIPE_<wbr>ARGS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of pipe objects that can be passed as arguments |
| to a kernel. |
| The minimum value is 16 for devices supporting pipes, and must be |
| 0 for devices that do not support pipes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS"></a><a href="#CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS"><code>CL_DEVICE_<wbr>PIPE_<wbr>MAX_<wbr>ACTIVE_<wbr>RESERVATIONS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of reservations that can be active for a pipe per |
| work-item in a kernel. |
| A work-group reservation is counted as one reservation per |
| work-item. |
| The minimum value is 1 for devices supporting pipes, and must be |
| 0 for devices that do not support pipes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PIPE_MAX_PACKET_SIZE"></a><a href="#CL_DEVICE_PIPE_MAX_PACKET_SIZE"><code>CL_DEVICE_<wbr>PIPE_<wbr>MAX_<wbr>PACKET_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum size of pipe packet in bytes.</p> |
| <p class="tableblock"> Support for pipes is required for an OpenCL 2.0, 2.1, or 2.2 device. |
| The minimum value is 1024 bytes if the device supports pipes, and must be |
| 0 for devices that do not support pipes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_PARAMETER_SIZE"></a><a href="#CL_DEVICE_MAX_PARAMETER_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>PARAMETER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max size in bytes of all arguments that can be passed to a kernel.</p> |
| <p class="tableblock"> The minimum value is 1024 for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>. |
| For this minimum value, only a maximum of 128 arguments can be |
| passed to a kernel</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MEM_BASE_ADDR_ALIGN"></a><a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Alignment requirement (in bits) for sub-buffer offsets. |
| The minimum value is the size (in bits) of the largest OpenCL |
| built-in data type supported by the device (long16 in FULL profile, |
| long16 or int16 in EMBEDDED profile) for devices that are not of |
| type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE"></a><a href="#CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE"><code>CL_DEVICE_<wbr>MIN_<wbr>DATA_<wbr>TYPE_<wbr>ALIGN_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Deprecated by</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The minimum value is the size (in bytes) of the largest OpenCL data |
| type supported by the device (<code>long16</code> in FULL profile, <code>long16</code> or |
| <code>int16</code> in EMBEDDED profile).</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_SINGLE_FP_CONFIG"></a><a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_DEVICE_<wbr>SINGLE_<wbr>FP_<wbr>CONFIG</code></a> <sup class="footnote" id="_footnote_native-rounding-modes">[<a id="_footnoteref_8" class="footnote" href="#_footnotedef_8" title="View footnote.">8</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>fp_<wbr>config</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes single precision floating-point capability of the device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_FP_DENORM"></a><a href="#CL_FP_DENORM"><code>CL_FP_<wbr>DENORM</code></a> - denorms are supported<br> |
| <a id="CL_FP_INF_NAN"></a><a href="#CL_FP_INF_NAN"><code>CL_FP_<wbr>INF_<wbr>NAN</code></a> - INF and quiet NaNs are supported<br> |
| <a id="CL_FP_ROUND_TO_NEAREST"></a><a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a>-- round to nearest even rounding mode |
| supported<br> |
| <a id="CL_FP_ROUND_TO_ZERO"></a><a href="#CL_FP_ROUND_TO_ZERO"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>ZERO</code></a> - round to zero rounding mode supported<br> |
| <a id="CL_FP_ROUND_TO_INF"></a><a href="#CL_FP_ROUND_TO_INF"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>INF</code></a> - round to positive and negative infinity |
| rounding modes supported<br> |
| <a id="CL_FP_FMA"></a><a href="#CL_FP_FMA"><code>CL_FP_<wbr>FMA</code></a> - IEEE754-2008 fused multiply-add is supported<br> |
| <a id="CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"></a><a href="#CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"><code>CL_FP_<wbr>CORRECTLY_<wbr>ROUNDED_<wbr>DIVIDE_<wbr>SQRT</code></a> - divide and sqrt are correctly |
| rounded as defined by the IEEE754 specification<br> |
| <a id="CL_FP_SOFT_FLOAT"></a><a href="#CL_FP_SOFT_FLOAT"><code>CL_FP_<wbr>SOFT_<wbr>FLOAT</code></a> - Basic floating-point operations (such as |
| addition, subtraction, multiplication) are implemented in software</p> |
| <p class="tableblock"> For the full profile, the mandated minimum floating-point capability |
| for devices that are not of type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a> is:</p> |
| <p class="tableblock"> <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a> |<br> |
| <a href="#CL_FP_INF_NAN"><code>CL_FP_<wbr>INF_<wbr>NAN</code></a>.</p> |
| <p class="tableblock"> For the embedded profile, see the |
| <a href="#embedded-profile-single-fp-config-requirements">dedicated table</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_DOUBLE_FP_CONFIG"></a><a href="#CL_DEVICE_DOUBLE_FP_CONFIG"><code>CL_DEVICE_<wbr>DOUBLE_<wbr>FP_<wbr>CONFIG</code></a> <sup class="footnoteref">[<a class="footnote" href="#_footnotedef_8" title="View footnote.">8</a>]</sup></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>fp_<wbr>config</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes double precision floating-point capability of the OpenCL |
| device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a href="#CL_FP_DENORM"><code>CL_FP_<wbr>DENORM</code></a> - denorms are supported<br> |
| <a href="#CL_FP_INF_NAN"><code>CL_FP_<wbr>INF_<wbr>NAN</code></a> - INF and NaNs are supported<br> |
| <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a> - round to nearest even rounding mode |
| supported<br> |
| <a href="#CL_FP_ROUND_TO_ZERO"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>ZERO</code></a> - round to zero rounding mode supported<br> |
| <a href="#CL_FP_ROUND_TO_INF"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>INF</code></a> - round to positive and negative infinity |
| rounding modes supported<br> |
| <a href="#CL_FP_FMA"><code>CL_FP_<wbr>FMA</code></a> - IEEE754-2008 fused multiply-add is supported<br> |
| <a href="#CL_FP_SOFT_FLOAT"><code>CL_FP_<wbr>SOFT_<wbr>FLOAT</code></a> - Basic floating-point operations (such as |
| addition, subtraction, multiplication) are implemented in software</p> |
| <p class="tableblock"> Double precision is an optional feature so the mandated minimum |
| double precision floating-point capability is 0.</p> |
| <p class="tableblock"> If double precision is supported by the device, then the minimum |
| double precision floating-point capability is:</p> |
| <p class="tableblock"> <a href="#CL_FP_FMA"><code>CL_FP_<wbr>FMA</code></a> |<br> |
| <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a> |<br> |
| <a href="#CL_FP_INF_NAN"><code>CL_FP_<wbr>INF_<wbr>NAN</code></a> |<br> |
| <a href="#CL_FP_DENORM"><code>CL_FP_<wbr>DENORM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_CACHE_TYPE"></a><a href="#CL_DEVICE_GLOBAL_MEM_CACHE_TYPE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>MEM_<wbr>CACHE_<wbr>TYPE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>mem_<wbr>cache_<wbr>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Type of global memory cache supported. |
| Valid values are: <a href="#CL_NONE"><code>CL_NONE</code></a>, <a id="CL_READ_ONLY_CACHE"></a><a href="#CL_READ_ONLY_CACHE"><code>CL_READ_<wbr>ONLY_<wbr>CACHE</code></a>, and |
| <a id="CL_READ_WRITE_CACHE"></a><a href="#CL_READ_WRITE_CACHE"><code>CL_READ_<wbr>WRITE_<wbr>CACHE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE"></a><a href="#CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>MEM_<wbr>CACHELINE_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Size of global memory cache line in bytes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_CACHE_SIZE"></a><a href="#CL_DEVICE_GLOBAL_MEM_CACHE_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>MEM_<wbr>CACHE_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Size of global memory cache in bytes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_SIZE"></a><a href="#CL_DEVICE_GLOBAL_MEM_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>MEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Size of global device memory in bytes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE"></a><a href="#CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>CONSTANT_<wbr>BUFFER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max size in bytes of a constant buffer allocation. |
| The minimum value is 64 KB for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_CONSTANT_ARGS"></a><a href="#CL_DEVICE_MAX_CONSTANT_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>CONSTANT_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of arguments declared with the <code>__constant</code> qualifier |
| in a kernel. |
| The minimum value is 8 for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE"></a><a href="#CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>GLOBAL_<wbr>VARIABLE_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of bytes of storage that may be allocated for any |
| single variable in program scope or inside a function in an OpenCL |
| kernel language declared in the global address space.</p> |
| <p class="tableblock"> Support for program scope global variables is required for an OpenCL 2.0, |
| 2.1, or 2.2 device. |
| The minimum value is 64 KB if the device supports program scope global |
| variables, and must be 0 for devices that do not support program scope |
| global variables.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE"></a><a href="#CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>VARIABLE_<wbr>PREFERRED_<wbr>TOTAL_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum preferred total size, in bytes, of all program variables in |
| the global address space. |
| This is a performance hint. |
| An implementation may place such variables in storage with optimized |
| device access. |
| This query returns the capacity of such storage. |
| The minimum value is 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LOCAL_MEM_TYPE"></a><a href="#CL_DEVICE_LOCAL_MEM_TYPE"><code>CL_DEVICE_<wbr>LOCAL_<wbr>MEM_<wbr>TYPE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>local_<wbr>mem_<wbr>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Type of local memory supported. |
| This can be set to <a id="CL_LOCAL"></a><a href="#CL_LOCAL"><code>CL_LOCAL</code></a> implying dedicated local memory storage |
| such as SRAM , or <a id="CL_GLOBAL"></a><a href="#CL_GLOBAL"><code>CL_GLOBAL</code></a>.</p> |
| <p class="tableblock"> For custom devices, <a href="#CL_NONE"><code>CL_NONE</code></a> can also be returned indicating no local |
| memory support.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LOCAL_MEM_SIZE"></a><a href="#CL_DEVICE_LOCAL_MEM_SIZE"><code>CL_DEVICE_<wbr>LOCAL_<wbr>MEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Size of local memory region in bytes. |
| The minimum value is 32 KB for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ERROR_CORRECTION_SUPPORT"></a><a href="#CL_DEVICE_ERROR_CORRECTION_SUPPORT"><code>CL_DEVICE_<wbr>ERROR_<wbr>CORRECTION_<wbr>SUPPORT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device implements error correction for all |
| accesses to compute device memory (global and constant). |
| Is <a href="#CL_FALSE"><code>CL_FALSE</code></a> if the device does not implement such error correction.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_HOST_UNIFIED_MEMORY"></a><a href="#CL_DEVICE_HOST_UNIFIED_MEMORY"><code>CL_DEVICE_<wbr>HOST_<wbr>UNIFIED_<wbr>MEMORY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1 and <a href="#unified-spec">deprecated by</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device and the host have a unified memory subsystem |
| and is <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PROFILING_TIMER_RESOLUTION"></a><a href="#CL_DEVICE_PROFILING_TIMER_RESOLUTION"><code>CL_DEVICE_<wbr>PROFILING_<wbr>TIMER_<wbr>RESOLUTION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the resolution of device timer. |
| This is measured in nanoseconds. |
| Refer to <a href="#profiling-operations">Profiling Operations</a> for details.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ENDIAN_LITTLE"></a><a href="#CL_DEVICE_ENDIAN_LITTLE"><code>CL_DEVICE_<wbr>ENDIAN_<wbr>LITTLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the OpenCL device is a little endian device and |
| <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_AVAILABLE"></a><a href="#CL_DEVICE_AVAILABLE"><code>CL_DEVICE_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device is available and <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise. |
| A device is considered to be available if the device can be expected |
| to successfully execute commands enqueued to the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_COMPILER_AVAILABLE"></a><a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_FALSE"><code>CL_FALSE</code></a> if the implementation does not have a compiler available |
| to compile the program source.</p> |
| <p class="tableblock"> Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the compiler is available. |
| This can be <a href="#CL_FALSE"><code>CL_FALSE</code></a> for the embedded platform profile only.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LINKER_AVAILABLE"></a><a href="#CL_DEVICE_LINKER_AVAILABLE"><code>CL_DEVICE_<wbr>LINKER_<wbr>AVAILABLE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_FALSE"><code>CL_FALSE</code></a> if the implementation does not have a linker available. |
| Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the linker is available.</p> |
| <p class="tableblock"> This can be <a href="#CL_FALSE"><code>CL_FALSE</code></a> for the embedded platform profile only.</p> |
| <p class="tableblock"> This must be <a href="#CL_TRUE"><code>CL_TRUE</code></a> if <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_EXECUTION_CAPABILITIES"></a><a href="#CL_DEVICE_EXECUTION_CAPABILITIES"><code>CL_DEVICE_<wbr>EXECUTION_<wbr>CAPABILITIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>exec_<wbr>capabilities</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the execution capabilities of the device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_EXEC_KERNEL"></a><a href="#CL_EXEC_KERNEL"><code>CL_EXEC_<wbr>KERNEL</code></a> - The OpenCL device can execute OpenCL kernels.<br> |
| <a id="CL_EXEC_NATIVE_KERNEL"></a><a href="#CL_EXEC_NATIVE_KERNEL"><code>CL_EXEC_<wbr>NATIVE_<wbr>KERNEL</code></a> - The OpenCL device can execute native |
| kernels.</p> |
| <p class="tableblock"> The mandated minimum capability is: <a href="#CL_EXEC_KERNEL"><code>CL_EXEC_<wbr>KERNEL</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_PROPERTIES"></a><a href="#CL_DEVICE_QUEUE_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Deprecated by</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue_<wbr>properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">See description of <a href="#CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>HOST_<wbr>PROPERTIES</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"></a><a href="#CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>HOST_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue_<wbr>properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the on host command-queue properties supported by the |
| device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a><br> |
| <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a></p> |
| <p class="tableblock"> These properties are described in the <a href="#queue-properties-table">Queue Properties</a> table.</p> |
| <p class="tableblock"> The mandated minimum capability is: <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES"></a><a href="#CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue_<wbr>properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the on device command-queue properties supported by the |
| device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a><br> |
| <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a></p> |
| <p class="tableblock"> These properties are described in the <a href="#queue-properties-table">Queue Properties</a> table.</p> |
| <p class="tableblock"> Support for on-device queues is required for an OpenCL 2.0, 2.1, or 2.2 device. |
| When on-device queues are supported, the mandated minimum capability is:</p> |
| <p class="tableblock"> <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> |<br> |
| <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a>.</p> |
| <p class="tableblock"> Must be 0 for devices that do not support on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"></a><a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>PREFERRED_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The preferred size of the device queue, in bytes. |
| Applications should use this size for the device queue to ensure |
| good performance.</p> |
| <p class="tableblock"> The minimum value is 16 KB for devices supporting on-device queues, |
| and must be 0 for devices that do not support on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"></a><a href="#CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>MAX_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum size of the device queue in bytes.</p> |
| <p class="tableblock"> The minimum value is 256 KB for the full profile and 64 KB for the |
| embedded profile for devices supporting on-device queues, |
| and must be 0 for devices that do not support on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_ON_DEVICE_QUEUES"></a><a href="#CL_DEVICE_MAX_ON_DEVICE_QUEUES"><code>CL_DEVICE_<wbr>MAX_<wbr>ON_<wbr>DEVICE_<wbr>QUEUES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of device queues that can be created for this |
| device in a single context.</p> |
| <p class="tableblock"> The minimum value is 1 for devices supporting on-device queues, |
| and must be 0 for devices that do not support on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_ON_DEVICE_EVENTS"></a><a href="#CL_DEVICE_MAX_ON_DEVICE_EVENTS"><code>CL_DEVICE_<wbr>MAX_<wbr>ON_<wbr>DEVICE_<wbr>EVENTS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of events in use by a device queue. |
| These refer to events returned by the <code>enqueue_</code> built-in functions |
| to a device queue or user events returned by the <code>create_user_event</code> |
| built-in function that have not been released.</p> |
| <p class="tableblock"> The minimum value is 1024 for devices supporting on-device queues, |
| and must be 0 for devices that do not support on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_BUILT_IN_KERNELS"></a><a href="#CL_DEVICE_BUILT_IN_KERNELS"><code>CL_DEVICE_<wbr>BUILT_<wbr>IN_<wbr>KERNELS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A semi-colon separated list of built-in kernels supported by the |
| device. |
| An empty string is returned if no built-in kernels are supported by |
| the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION"></a><a href="#CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION"><code>CL_DEVICE_<wbr>BUILT_<wbr>IN_<wbr>KERNELS_<wbr>WITH_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_name_version"><code>cl_name_<wbr>version</code></a>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of descriptions for the built-in kernels supported by |
| the device. Each built-in kernel may only be reported once. The list of |
| reported kernels must match the list returned via |
| <a href="#CL_DEVICE_BUILT_IN_KERNELS"><code>CL_DEVICE_<wbr>BUILT_<wbr>IN_<wbr>KERNELS</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PLATFORM"></a><a href="#CL_DEVICE_PLATFORM"><code>CL_DEVICE_<wbr>PLATFORM</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_platform_<wbr>id</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The platform associated with this device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NAME"></a><a href="#CL_DEVICE_NAME"><code>CL_DEVICE_<wbr>NAME</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Device name string.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_VENDOR"></a><a href="#CL_DEVICE_VENDOR"><code>CL_DEVICE_<wbr>VENDOR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Vendor name string.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DRIVER_VERSION"></a><a href="#CL_DRIVER_VERSION"><code>CL_DRIVER_<wbr>VERSION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL software driver version string. |
| Follows a vendor-specific format.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PROFILE"></a><a href="#CL_DEVICE_PROFILE"><code>CL_DEVICE_<wbr>PROFILE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL profile string. |
| Returns the profile name supported by the device. |
| The profile name returned can be one of the following strings:</p> |
| <p class="tableblock"> FULL_PROFILE - if the device supports the OpenCL specification |
| (functionality defined as part of the core specification and does |
| not require any extensions to be supported).</p> |
| <p class="tableblock"> EMBEDDED_PROFILE - if the device supports the OpenCL embedded |
| profile.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_VERSION"></a><a href="#CL_DEVICE_VERSION"><code>CL_DEVICE_<wbr>VERSION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL version string. |
| Returns the OpenCL version supported by the device. This version |
| string has the following format:</p> |
| <p class="tableblock"> <em>OpenCL<space><major_version.minor_version><space><vendor-specific |
| information></em></p> |
| <p class="tableblock"> The major_version.minor_version value returned will be one of 1.0, |
| 1.1, 1.2, 2.0, 2.1, 2.2, or 3.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NUMERIC_VERSION"></a><a href="#CL_DEVICE_NUMERIC_VERSION"><code>CL_DEVICE_<wbr>NUMERIC_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_version</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the detailed (major, minor, patch) version supported by the |
| device. The major and minor version numbers returned must match |
| those returned via <a href="#CL_DEVICE_VERSION"><code>CL_DEVICE_<wbr>VERSION</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_OPENCL_C_VERSION"></a><a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1 and <a href="#unified-spec">deprecated by</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the highest fully backwards compatible OpenCL C version |
| supported by the compiler for the device. |
| For devices supporting compilation from OpenCL C source, this will |
| return a version string with the following format:</p> |
| <p class="tableblock"> <em>OpenCL<space>C<space><major_version.minor_version><space><vendor-specific |
| information></em></p> |
| <p class="tableblock"> For devices that support compilation from OpenCL C source:</p> |
| <p class="tableblock"> Because OpenCL 3.0 is backwards compatible with OpenCL C 1.2, |
| an OpenCL 3.0 device must support at least OpenCL C 1.2. |
| An OpenCL 3.0 device may return an OpenCL C version newer |
| than OpenCL C 1.2 if and only if all optional OpenCL C |
| features are supported by the device for the newer version.</p> |
| <p class="tableblock"> Support for OpenCL C 2.0 is required for an OpenCL 2.0, OpenCL 2.1, |
| or OpenCL 2.2 device.</p> |
| <p class="tableblock"> Support for OpenCL C 1.2 is required for an OpenCL 1.2 device.</p> |
| <p class="tableblock"> Support for OpenCL C 1.1 is required for an OpenCL 1.1 device.</p> |
| <p class="tableblock"> Support for either OpenCL C 1.0 or OpenCL C 1.1 is required for |
| an OpenCL 1.0 device.</p> |
| <p class="tableblock"> For devices that do not support compilation from OpenCL C source, |
| such as when <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>, this |
| query may return an empty string.</p> |
| <p class="tableblock"> This query has been superseded by the <a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a> |
| query, which returns a set of OpenCL C versions supported by a |
| device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_OPENCL_C_ALL_VERSIONS"></a><a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_name_version"><code>cl_name_<wbr>version</code></a>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of name, version descriptions listing all the versions |
| of OpenCL C supported by the compiler for the device. |
| In each returned description structure, the name field is required to be |
| "OpenCL C". The list may include both newer non-backwards compatible |
| OpenCL C versions, such as OpenCL C 3.0, and older OpenCL C versions |
| with mandatory backwards compatibility. |
| The version returned by <a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a> is required to be |
| present in the list.</p> |
| <p class="tableblock"> For devices that support compilation from OpenCL C source:</p> |
| <p class="tableblock"> Because OpenCL 3.0 is backwards compatible with OpenCL C 1.2, |
| and OpenCL C 1.2 is backwards compatible with OpenCL C 1.1 and |
| OpenCL C 1.0, support for at least OpenCL C 3.0, OpenCL C 1.2, |
| OpenCL C 1.1, and OpenCL C 1.0 is required for an OpenCL 3.0 device.</p> |
| <p class="tableblock"> Support for OpenCL C 2.0, OpenCL C 1.2, OpenCL C 1.1, and OpenCL C |
| 1.0 is required for an OpenCL 2.0, OpenCL 2.1, or OpenCL 2.2 device.</p> |
| <p class="tableblock"> Support for OpenCL C 1.2, OpenCL C 1.1, and OpenCL C 1.0 is required |
| for an OpenCL 1.2 device.</p> |
| <p class="tableblock"> Support for OpenCL C 1.1 and OpenCL C 1.0 is required for an |
| OpenCL 1.1 device.</p> |
| <p class="tableblock"> Support for at least OpenCL C 1.0 is required for an OpenCL 1.0 device.</p> |
| <p class="tableblock"> For devices that do not support compilation from OpenCL C source, |
| this query may return an empty array.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_OPENCL_C_FEATURES"></a><a href="#CL_DEVICE_OPENCL_C_FEATURES"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>FEATURES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_name_version"><code>cl_name_<wbr>version</code></a>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of optional OpenCL C features supported by the |
| compiler for the device alongside the OpenCL C version that introduced |
| the feature macro. |
| For example, if a compiler supports an OpenCL C 3.0 feature, the |
| returned name will be the full name of the OpenCL C feature macro, and |
| the returned version will be 3.0.0.</p> |
| <p class="tableblock"> For devices that do not support compilation from OpenCL C source, |
| this query may return an empty array.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_EXTENSIONS"></a><a href="#CL_DEVICE_EXTENSIONS"><code>CL_DEVICE_<wbr>EXTENSIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns a space separated list of extension names (the extension |
| names themselves do not contain any spaces) supported by the device. |
| The list of extension names may include Khronos approved extension |
| names and vendor specified extension names.</p> |
| <p class="tableblock"> The following Khronos extension names must be returned by |
| all devices that support OpenCL 1.1:</p> |
| <p class="tableblock"> <strong>cl_khr_byte_addressable_store</strong><br> |
| <strong>cl_khr_global_int32_base_atomics</strong><br> |
| <strong>cl_khr_global_int32_extended_atomics</strong><br> |
| <strong>cl_khr_local_int32_base_atomics</strong><br> |
| <strong>cl_khr_local_int32_extended_atomics</strong></p> |
| <p class="tableblock"> Additionally, the following Khronos extension names must be returned |
| by all devices that support OpenCL 1.2 when and only when the optional |
| feature is supported:</p> |
| <p class="tableblock"> <strong>cl_khr_fp64</strong></p> |
| <p class="tableblock"> Additionally, the following Khronos extension names must be returned |
| by all devices that support OpenCL 2.0, OpenCL 2.1, or OpenCL 2.2. |
| For devices that support OpenCL 3.0, these extension names must |
| be returned when and only when the optional feature is supported:</p> |
| <p class="tableblock"> <strong>cl_khr_3d_image_writes</strong><br> |
| <strong>cl_khr_depth_images</strong><br> |
| <strong>cl_khr_image2d_from_buffer</strong></p> |
| <p class="tableblock"> Please refer to the OpenCL Extension Specification or vendor |
| provided documentation for a detailed description of these extensions.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_EXTENSIONS_WITH_VERSION"></a><a href="#CL_DEVICE_EXTENSIONS_WITH_VERSION"><code>CL_DEVICE_<wbr>EXTENSIONS_<wbr>WITH_<wbr>VERSION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_name_version"><code>cl_name_<wbr>version</code></a>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array of description (name and version) structures. The same |
| extension name must not be reported more than once. The list of |
| extensions reported must match the list reported via |
| <a href="#CL_DEVICE_EXTENSIONS"><code>CL_DEVICE_<wbr>EXTENSIONS</code></a>.</p> |
| <p class="tableblock"> See <a id="CL_DEVICE_EXTENSIONS"></a><a href="#CL_DEVICE_EXTENSIONS"><code>CL_DEVICE_<wbr>EXTENSIONS</code></a> for a list of extensions that are |
| required to be reported for a given OpenCL version.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PRINTF_BUFFER_SIZE"></a><a href="#CL_DEVICE_PRINTF_BUFFER_SIZE"><code>CL_DEVICE_<wbr>PRINTF_<wbr>BUFFER_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum size in bytes of the internal buffer that holds the output |
| of printf calls from a kernel. |
| The minimum value for the FULL profile is 1 MB.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_INTEROP_USER_SYNC"></a><a href="#CL_DEVICE_PREFERRED_INTEROP_USER_SYNC"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>INTEROP_<wbr>USER_<wbr>SYNC</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the devices preference is for the user to be |
| responsible for synchronization, when sharing memory objects between |
| OpenCL and other APIs such as DirectX, <a href="#CL_FALSE"><code>CL_FALSE</code></a> if the device / |
| implementation has a performant path for performing synchronization |
| of memory object shared between OpenCL and other APIs such as |
| DirectX.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARENT_DEVICE"></a><a href="#CL_DEVICE_PARENT_DEVICE"><code>CL_DEVICE_<wbr>PARENT_<wbr>DEVICE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>id</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the <code>cl_device_<wbr>id</code> of the parent device to which this |
| sub-device belongs. |
| If <em>device</em> is a root-level device, a <code>NULL</code> value is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_MAX_SUB_DEVICES"></a><a href="#CL_DEVICE_PARTITION_MAX_SUB_DEVICES"><code>CL_DEVICE_<wbr>PARTITION_<wbr>MAX_<wbr>SUB_<wbr>DEVICES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the maximum number of sub-devices that can be created when a |
| device is partitioned.</p> |
| <p class="tableblock"> The value returned cannot exceed <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_DEVICE_<wbr>MAX_<wbr>COMPUTE_<wbr>UNITS</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_PROPERTIES"></a><a href="#CL_DEVICE_PARTITION_PROPERTIES"><code>CL_DEVICE_<wbr>PARTITION_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>partition_<wbr>property</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the list of partition types supported by <em>device</em>. |
| This is an array of <code>cl_device_<wbr>partition_<wbr>property</code> values drawn from |
| the following list:</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_PARTITION_EQUALLY"><code>CL_DEVICE_<wbr>PARTITION_<wbr>EQUALLY</code></a><br> |
| <a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>COUNTS</code></a><br> |
| <a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>AFFINITY_<wbr>DOMAIN</code></a></p> |
| <p class="tableblock"> If the device cannot be partitioned (i.e. there is no partitioning |
| scheme supported by the device that will return at least two |
| subdevices), a value of 0 will be returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_AFFINITY_DOMAIN"></a><a href="#CL_DEVICE_PARTITION_AFFINITY_DOMAIN"><code>CL_DEVICE_<wbr>PARTITION_<wbr>AFFINITY_<wbr>DOMAIN</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>affinity_<wbr>domain</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the list of supported affinity domains for partitioning the |
| device using <a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>AFFINITY_<wbr>DOMAIN</code></a>. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_DEVICE_AFFINITY_DOMAIN_NUMA"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_NUMA"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>NUMA</code></a><br> |
| <a id="CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L4_<wbr>CACHE</code></a><br> |
| <a id="CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L3_<wbr>CACHE</code></a><br> |
| <a id="CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L2_<wbr>CACHE</code></a><br> |
| <a id="CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L1_<wbr>CACHE</code></a><br> |
| <a id="CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>NEXT_<wbr>PARTITIONABLE</code></a></p> |
| <p class="tableblock"> If the device does not support any affinity domains, a value of 0 |
| will be returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_TYPE"></a><a href="#CL_DEVICE_PARTITION_TYPE"><code>CL_DEVICE_<wbr>PARTITION_<wbr>TYPE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>partition_<wbr>property</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the properties argument specified in <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> if |
| device is a sub-device. |
| In the case where the properties argument to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> is |
| <a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>AFFINITY_<wbr>DOMAIN</code></a>, |
| <a href="#CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>NEXT_<wbr>PARTITIONABLE</code></a>, the affinity domain |
| used to perform the partition will be returned. |
| This can be one of the following values:</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_NUMA"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>NUMA</code></a><br> |
| <a href="#CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L4_<wbr>CACHE</code></a><br> |
| <a href="#CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L3_<wbr>CACHE</code></a><br> |
| <a href="#CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L2_<wbr>CACHE</code></a><br> |
| <a href="#CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L1_<wbr>CACHE</code></a></p> |
| <p class="tableblock"> Otherwise the implementation may either return a |
| <em>param_value_size_ret</em> of 0 i.e. there is no partition type |
| associated with device or can return a property value of 0 (where 0 |
| is used to terminate the partition property list) in the memory that |
| <em>param_value</em> points to.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_REFERENCE_COUNT"></a><a href="#CL_DEVICE_REFERENCE_COUNT"><code>CL_DEVICE_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_9" class="footnote" href="#_footnotedef_9" title="View footnote.">9</a>]</sup></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the <em>device</em> reference count. |
| If the device is a root-level device, a reference count of one is |
| returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_SVM_CAPABILITIES"></a><a href="#CL_DEVICE_SVM_CAPABILITIES"><code>CL_DEVICE_<wbr>SVM_<wbr>CAPABILITIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>svm_<wbr>capabilities</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the various shared virtual memory (SVM) memory |
| allocation types the device supports. |
| This is a bit-field that describes a combination of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_DEVICE_SVM_COARSE_GRAIN_BUFFER"></a><a href="#CL_DEVICE_SVM_COARSE_GRAIN_BUFFER"><code>CL_DEVICE_<wbr>SVM_<wbr>COARSE_<wbr>GRAIN_<wbr>BUFFER</code></a> - Support for coarse-grain buffer |
| sharing using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>. |
| Memory consistency is guaranteed at synchronization points and the |
| host must use calls to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and |
| <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.<br> |
| <a id="CL_DEVICE_SVM_FINE_GRAIN_BUFFER"></a><a href="#CL_DEVICE_SVM_FINE_GRAIN_BUFFER"><code>CL_DEVICE_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a> - Support for fine-grain buffer |
| sharing using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>. |
| Memory consistency is guaranteed at synchronization points without |
| need for <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.<br> |
| <a id="CL_DEVICE_SVM_FINE_GRAIN_SYSTEM"></a><a href="#CL_DEVICE_SVM_FINE_GRAIN_SYSTEM"><code>CL_DEVICE_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a> - Support for sharing the host’s |
| entire virtual memory including memory allocated using <strong>malloc</strong>. |
| Memory consistency is guaranteed at synchronization points.<br> |
| <a id="CL_DEVICE_SVM_ATOMICS"></a><a href="#CL_DEVICE_SVM_ATOMICS"><code>CL_DEVICE_<wbr>SVM_<wbr>ATOMICS</code></a> - Support for the OpenCL 2.0 atomic |
| operations that provide memory consistency across the host and all |
| OpenCL devices supporting fine-grain SVM allocations.</p> |
| <p class="tableblock"> The mandated minimum capability for an OpenCL 2.0, 2.1, or 2.2 device is |
| <a href="#CL_DEVICE_SVM_COARSE_GRAIN_BUFFER"><code>CL_DEVICE_<wbr>SVM_<wbr>COARSE_<wbr>GRAIN_<wbr>BUFFER</code></a>.</p> |
| <p class="tableblock"> For other device versions there is no mandated minimum capability.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_PLATFORM_ATOMIC_ALIGNMENT"></a><a href="#CL_DEVICE_PREFERRED_PLATFORM_ATOMIC_ALIGNMENT"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>PLATFORM_<wbr>ATOMIC_<wbr>ALIGNMENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value representing the preferred alignment in bytes for |
| OpenCL 2.0 fine-grained SVM atomic types. |
| This query can return 0 which indicates that the preferred alignment |
| is aligned to the natural size of the type.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_GLOBAL_ATOMIC_ALIGNMENT"></a><a href="#CL_DEVICE_PREFERRED_GLOBAL_ATOMIC_ALIGNMENT"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>GLOBAL_<wbr>ATOMIC_<wbr>ALIGNMENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value representing the preferred alignment in bytes for |
| OpenCL 2.0 atomic types to global memory. |
| This query can return 0 which indicates that the preferred alignment |
| is aligned to the natural size of the type.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_LOCAL_ATOMIC_ALIGNMENT"></a><a href="#CL_DEVICE_PREFERRED_LOCAL_ATOMIC_ALIGNMENT"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>LOCAL_<wbr>ATOMIC_<wbr>ALIGNMENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value representing the preferred alignment in bytes for |
| OpenCL 2.0 atomic types to local memory. |
| This query can return 0 which indicates that the preferred alignment |
| is aligned to the natural size of the type.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_NUM_SUB_GROUPS"></a><a href="#CL_DEVICE_MAX_NUM_SUB_GROUPS"><code>CL_DEVICE_<wbr>MAX_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of sub-groups in a work-group that a device is |
| capable of executing on a single compute unit, for any given |
| kernel-instance running on the device.</p> |
| <p class="tableblock"> The minimum value is 1 if the device supports subgroups, and must be |
| 0 for devices that do not support subgroups. |
| Support for subgroups is required for an OpenCL 2.1 or 2.2 device.</p> |
| <p class="tableblock"> (Refer also to <a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a>.)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"></a><a href="#CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"><code>CL_DEVICE_<wbr>SUB_<wbr>GROUP_<wbr>INDEPENDENT_<wbr>FORWARD_<wbr>PROGRESS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if this device supports independent forward progress of |
| sub-groups, <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise.</p> |
| <p class="tableblock"> This query must return <a href="#CL_TRUE"><code>CL_TRUE</code></a> for devices that support the |
| <strong>cl_khr_subgroups</strong> extension, and must return <a href="#CL_FALSE"><code>CL_FALSE</code></a> for |
| devices that do not support subgroups.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES"></a><a href="#CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>MEMORY_<wbr>CAPABILITIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>atomic_<wbr>capabilities</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the various memory orders and scopes that the device supports for atomic memory operations. |
| This is a bit-field that describes a combination of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_DEVICE_ATOMIC_ORDER_RELAXED"></a><a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> - Support for the <strong>relaxed</strong> memory order.<br> |
| <a id="CL_DEVICE_ATOMIC_ORDER_ACQ_REL"></a><a href="#CL_DEVICE_ATOMIC_ORDER_ACQ_REL"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>ACQ_<wbr>REL</code></a> - Support for the <strong>acquire</strong>, <strong>release</strong>, and <strong>acquire-release</strong> memory orders.<br> |
| <a id="CL_DEVICE_ATOMIC_ORDER_SEQ_CST"></a><a href="#CL_DEVICE_ATOMIC_ORDER_SEQ_CST"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>SEQ_<wbr>CST</code></a> - Support for the <strong>sequentially consistent</strong> memory order.</p> |
| <p class="tableblock"> Because atomic memory orders are hierarchical, a device that supports a strong memory order must also support all weaker memory orders.</p> |
| <p class="tableblock"> <a id="CL_DEVICE_ATOMIC_SCOPE_WORK_ITEM"></a><a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_ITEM"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>ITEM</code></a> <sup class="footnote">[<a id="_footnoteref_10" class="footnote" href="#_footnotedef_10" title="View footnote.">10</a>]</sup> - Support for memory ordering constraints that apply to a single work-item.<br> |
| <a id="CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"></a><a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a> - Support for memory ordering constraints that apply to all work-items in a work-group.<br> |
| <a id="CL_DEVICE_ATOMIC_SCOPE_DEVICE"></a><a href="#CL_DEVICE_ATOMIC_SCOPE_DEVICE"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>DEVICE</code></a> - Support for memory ordering constraints that apply to all work-items executing on the device.<br> |
| <a id="CL_DEVICE_ATOMIC_SCOPE_ALL_DEVICES"></a><a href="#CL_DEVICE_ATOMIC_SCOPE_ALL_DEVICES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>ALL_<wbr>DEVICES</code></a> - Support for memory ordering constraints that apply to all work-items executing across all devices that can share SVM memory with each other and the host process.</p> |
| <p class="tableblock"> Because atomic scopes are hierarchical, a device that supports a wide scope must also support all narrower scopes, except for the work-item scope, which is a special case.</p> |
| <p class="tableblock"> The mandated minimum capability is:</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ATOMIC_FENCE_CAPABILITIES"></a><a href="#CL_DEVICE_ATOMIC_FENCE_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>FENCE_<wbr>CAPABILITIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>atomic_<wbr>capabilities</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes the various memory orders and scopes that the device supports for atomic fence operations. |
| This is a bit-field that has the same set of possible values as described for <a href="#CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>MEMORY_<wbr>CAPABILITIES</code></a>.</p> |
| <p class="tableblock"> The mandated minimum capability is:</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_ORDER_ACQ_REL"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>ACQ_<wbr>REL</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NON_UNIFORM_WORK_GROUP_SUPPORT"></a><a href="#CL_DEVICE_NON_UNIFORM_WORK_GROUP_SUPPORT"><code>CL_DEVICE_<wbr>NON_<wbr>UNIFORM_<wbr>WORK_<wbr>GROUP_<wbr>SUPPORT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device supports non-uniform work-groups, and <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_WORK_GROUP_COLLECTIVE_FUNCTIONS_SUPPORT"></a><a href="#CL_DEVICE_WORK_GROUP_COLLECTIVE_FUNCTIONS_SUPPORT"><code>CL_DEVICE_<wbr>WORK_<wbr>GROUP_<wbr>COLLECTIVE_<wbr>FUNCTIONS_<wbr>SUPPORT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device supports work-group collective functions e.g. <code>work_group_broadcast</code>, <code>work_group_reduce</code>, and <code>work_group_scan</code>, and <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT"></a><a href="#CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT"><code>CL_DEVICE_<wbr>GENERIC_<wbr>ADDRESS_<wbr>SPACE_<wbr>SUPPORT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device supports the generic address space and its associated built-in functions, and <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_DEVICE_ENQUEUE_CAPABILITIES"></a><a href="#CL_DEVICE_DEVICE_ENQUEUE_CAPABILITIES"><code>CL_DEVICE_<wbr>DEVICE_<wbr>ENQUEUE_<wbr>CAPABILITIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>device_<wbr>enqueue_<wbr>capabilities</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes device-side enqueue capabilities of the device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_DEVICE_QUEUE_SUPPORTED"></a><a href="#CL_DEVICE_QUEUE_SUPPORTED"><code>CL_DEVICE_<wbr>QUEUE_<wbr>SUPPORTED</code></a> - Device supports device-side enqueue and on-device queues.<br> |
| <a id="CL_DEVICE_QUEUE_REPLACEABLE_DEFAULT"></a><a href="#CL_DEVICE_QUEUE_REPLACEABLE_DEFAULT"><code>CL_DEVICE_<wbr>QUEUE_<wbr>REPLACEABLE_<wbr>DEFAULT</code></a> - Device supports a replaceable default on-device queue.</p> |
| <p class="tableblock"> If <a href="#CL_DEVICE_QUEUE_REPLACEABLE_DEFAULT"><code>CL_DEVICE_<wbr>QUEUE_<wbr>REPLACEABLE_<wbr>DEFAULT</code></a> is set, <a href="#CL_DEVICE_QUEUE_SUPPORTED"><code>CL_DEVICE_<wbr>QUEUE_<wbr>SUPPORTED</code></a> must also be set.</p> |
| <p class="tableblock"> Devices that set <a href="#CL_DEVICE_QUEUE_SUPPORTED"><code>CL_DEVICE_<wbr>QUEUE_<wbr>SUPPORTED</code></a> for <a href="#CL_DEVICE_DEVICE_ENQUEUE_CAPABILITIES"><code>CL_DEVICE_<wbr>DEVICE_<wbr>ENQUEUE_<wbr>CAPABILITIES</code></a> must also return <a href="#CL_TRUE"><code>CL_TRUE</code></a> for <a href="#CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT"><code>CL_DEVICE_<wbr>GENERIC_<wbr>ADDRESS_<wbr>SPACE_<wbr>SUPPORT</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PIPE_SUPPORT"></a><a href="#CL_DEVICE_PIPE_SUPPORT"><code>CL_DEVICE_<wbr>PIPE_<wbr>SUPPORT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the device supports pipes, and <a href="#CL_FALSE"><code>CL_FALSE</code></a> otherwise.</p> |
| <p class="tableblock"> Devices that return <a href="#CL_TRUE"><code>CL_TRUE</code></a> for <a href="#CL_DEVICE_PIPE_SUPPORT"><code>CL_DEVICE_<wbr>PIPE_<wbr>SUPPORT</code></a> must also return <a href="#CL_TRUE"><code>CL_TRUE</code></a> for <a href="#CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT"><code>CL_DEVICE_<wbr>GENERIC_<wbr>ADDRESS_<wbr>SPACE_<wbr>SUPPORT</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"></a><a href="#CL_DEVICE_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>WORK_<wbr>GROUP_<wbr>SIZE_<wbr>MULTIPLE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the preferred multiple of work-group size for the given device. |
| This is a performance hint intended as a guide when specifying the local work size argument to <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>.</p> |
| <p class="tableblock"> (Refer also to <a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a> where <a href="#CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"><code>CL_KERNEL_<wbr>PREFERRED_<wbr>WORK_<wbr>GROUP_<wbr>SIZE_<wbr>MULTIPLE</code></a> |
| can return a different value to <a href="#CL_DEVICE_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>WORK_<wbr>GROUP_<wbr>SIZE_<wbr>MULTIPLE</code></a> which may be more optimal.)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LATEST_CONFORMANCE_VERSION_PASSED"></a><a href="#CL_DEVICE_LATEST_CONFORMANCE_VERSION_PASSED"><code>CL_DEVICE_<wbr>LATEST_<wbr>CONFORMANCE_<wbr>VERSION_<wbr>PASSED</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the latest version of the conformance test suite that this device |
| has fully passed in accordance with the official conformance process.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not one of the supported values or |
| if size in bytes specified by <em>param_value_size</em> is < size of return |
| type as specified in the <a href="#device-queries-table">Device Queries</a> table |
| and <em>param_value</em> is not a <code>NULL</code> value or if <em>param_name</em> is a value |
| that is available as an extension and the corresponding extension is not |
| supported by the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To query device and host timestamps, call the function:</p> |
| </div> |
| <div id="clGetDeviceAndHostTimer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetDeviceAndHostTimer( |
| cl_device_id device, |
| cl_ulong* device_timestamp, |
| cl_ulong* host_timestamp);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>device</em> is a device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>device_timestamp</em> will be updated with the value of the device timer in |
| nanoseconds. |
| The resolution of the timer is the same as the device profiling timer |
| returned by <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> and the <a href="#CL_DEVICE_PROFILING_TIMER_RESOLUTION"><code>CL_DEVICE_<wbr>PROFILING_<wbr>TIMER_<wbr>RESOLUTION</code></a> |
| query.</p> |
| </li> |
| <li> |
| <p><em>host_timestamp</em> will be updated with the value of the host timer in |
| nanoseconds at the closest possible point in time to that at which |
| <em>device_timer</em> was returned. |
| The resolution of the timer may be queried via <a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> and the |
| flag <a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_PLATFORM_<wbr>HOST_<wbr>TIMER_<wbr>RESOLUTION</code></a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> returns a reasonably synchronized pair of |
| timestamps from the device timer and the host timer as seen by <em>device</em>. |
| Implementations may need to execute this query with a high latency in order |
| to provide reasonable synchronization of the timestamps. |
| The host timestamp and device timestamp returned by this function and |
| <a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> each have an implementation defined timebase. |
| The timestamps will always be in their respective timebases regardless of |
| which query function is used. |
| The timestamp returned from <a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> for an event on a |
| device and a device timestamp queried from the same device will always be in |
| the same timebase.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> will return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> with a time value in |
| <em>host_timestamp</em> if provided. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the platform associated with <em>device</em> does not |
| support device and host timer synchronization.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>host_timestamp</em> or <em>device_timestamp</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To query the host clock, call the function:</p> |
| </div> |
| <div id="clGetHostTimer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetHostTimer( |
| cl_device_id device, |
| cl_ulong* host_timestamp);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>device</em> is a device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>host_timestamp</em> will be updated with the value of the current timer in |
| nanoseconds. |
| The resolution of the timer may be queried via <a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> and the |
| flag <a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_PLATFORM_<wbr>HOST_<wbr>TIMER_<wbr>RESOLUTION</code></a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> returns the current value of the host clock as seen by |
| <em>device</em>. |
| This value is in the same timebase as the <em>host_timestamp</em> returned from |
| <a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a>. |
| The implementation will return with as low a latency as possible to allow a |
| correlation with a subsequent application sampled time. |
| The host timestamp and device timestamp returned by this function and |
| <a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> each have an implementation defined timebase. |
| The timestamps will always be in their respective timebases regardless of |
| which query function is used. |
| The timestamp returned from <a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> for an event on a |
| device and a device timestamp queried from the same device will always be in |
| the same timebase.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> will return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> with a time value in |
| <em>host_timestamp</em> if provided. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the platform associated with <em>device</em> does not |
| support device and host timer synchronization.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>host_timestamp</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_partitioning_a_device"><a class="anchor" href="#_partitioning_a_device"></a>4.3. Partitioning a Device</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Partitioning devices is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create sub-devices partitioning an OpenCL device, call the function:</p> |
| </div> |
| <div id="clCreateSubDevices" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clCreateSubDevices( |
| cl_device_id in_device, |
| <span class="directive">const</span> cl_device_partition_property* properties, |
| cl_uint num_devices, |
| cl_device_id* out_devices, |
| cl_uint* num_devices_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>in_device</em> is the device to be partitioned.</p> |
| </li> |
| <li> |
| <p><em>properties</em> specifies how <em>in_device</em> is to be partitioned, described by a |
| partition name and its corresponding value. |
| Each partition name is immediately followed by the corresponding desired |
| value. |
| The list is terminated with 0. |
| The list of supported partitioning schemes is described in the |
| <a href="#subdevice-partition-table">Subdevice Partition</a> table. |
| Only one of the listed partitioning schemes can be specified in |
| <em>properties</em>.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the size of memory pointed to by <em>out_devices</em> specified as |
| the number of <code>cl_device_<wbr>id</code> entries.</p> |
| </li> |
| <li> |
| <p><em>out_devices</em> is the buffer where the OpenCL sub-devices will be returned. |
| If <em>out_devices</em> is <code>NULL</code>, this argument is ignored. |
| If <em>out_devices</em> is not <code>NULL</code>, <em>num_devices</em> must be greater than or equal |
| to the number of sub-devices that <em>device</em> may be partitioned into according |
| to the partitioning scheme specified in <em>properties</em>.</p> |
| </li> |
| <li> |
| <p><em>num_devices_ret</em> returns the number of sub-devices that <em>device</em> may be |
| partitioned into according to the partitioning scheme specified in |
| <em>properties</em>. |
| If <em>num_devices_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> creates an array of sub-devices that each reference a |
| non-intersecting set of compute units within <em>in_device</em>, according to the |
| partition scheme given by <em>properties</em>. |
| The output sub-devices may be used in every way that the root (or parent) |
| device can be used, including creating contexts, building programs, further |
| calls to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> and creating command-queues. |
| When a command-queue is created against a sub-device, the commands enqueued |
| on the queue are executed only on the sub-device.</p> |
| </div> |
| <table id="subdevice-partition-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 6. List of supported partition schemes by <a href="#clCreateSubDevices">clCreateSubDevices</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Partition Property</th> |
| <th class="tableblock halign-left valign-top">Partition Value</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_EQUALLY"></a><a href="#CL_DEVICE_PARTITION_EQUALLY"><code>CL_DEVICE_<wbr>PARTITION_<wbr>EQUALLY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Split the aggregate device into as many smaller aggregate devices as |
| can be created, each containing <em>n</em> compute units. |
| The value <em>n</em> is passed as the value accompanying this property. |
| If <em>n</em> does not divide evenly into |
| <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_DEVICE_<wbr>MAX_<wbr>COMPUTE_<wbr>UNITS</code></a>, then the remaining compute |
| units are not used.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_BY_COUNTS"></a><a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>COUNTS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This property is followed by a list of compute unit counts |
| terminated with 0 or <a id="CL_DEVICE_PARTITION_BY_COUNTS_LIST_END"></a><a href="#CL_DEVICE_PARTITION_BY_COUNTS_LIST_END"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>COUNTS_<wbr>LIST_<wbr>END</code></a>. |
| For each non-zero count <em>m</em> in the list, a sub-device is created |
| with <em>m</em> compute units in it.</p> |
| <p class="tableblock"> The number of non-zero count entries in the list may not exceed |
| <a href="#CL_DEVICE_PARTITION_MAX_SUB_DEVICES"><code>CL_DEVICE_<wbr>PARTITION_<wbr>MAX_<wbr>SUB_<wbr>DEVICES</code></a>.</p> |
| <p class="tableblock"> The total number of compute units specified may not exceed |
| <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_DEVICE_<wbr>MAX_<wbr>COMPUTE_<wbr>UNITS</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"></a><a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>AFFINITY_<wbr>DOMAIN</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>affinity_<wbr>domain</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Split the device into smaller aggregate devices containing one or |
| more compute units that all share part of a cache hierarchy. |
| The value accompanying this property may be drawn from the following |
| list:</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_NUMA"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>NUMA</code></a> - Split the device into sub-devices |
| comprised of compute units that share a NUMA node.</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L4_<wbr>CACHE</code></a> - Split the device into |
| sub-devices comprised of compute units that share a level 4 data |
| cache.</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L3_<wbr>CACHE</code></a> - Split the device into |
| sub-devices comprised of compute units that share a level 3 data |
| cache.</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L2_<wbr>CACHE</code></a> - Split the device into |
| sub-devices comprised of compute units that share a level 2 data |
| cache.</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>L1_<wbr>CACHE</code></a> - Split the device into |
| sub-devices comprised of compute units that share a level 1 data |
| cache.</p> |
| <p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"><code>CL_DEVICE_<wbr>AFFINITY_<wbr>DOMAIN_<wbr>NEXT_<wbr>PARTITIONABLE</code></a> - Split the device |
| along the next partitionable affinity domain. |
| The implementation shall find the first level along which the device |
| or sub-device may be further subdivided in the order NUMA, L4, L3, |
| L2, L1, and partition the device into sub-devices comprised of |
| compute units that share memory subsystems at this level.</p> |
| <p class="tableblock"> The user may determine what happened by calling |
| <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>(<a href="#CL_DEVICE_PARTITION_TYPE"><code>CL_DEVICE_<wbr>PARTITION_<wbr>TYPE</code></a>) on the sub-devices.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the partition is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>in_device</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>properties</em> are not valid or if |
| values specified in <em>properties</em> are valid but not supported by the |
| device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>out_devices</em> is not <code>NULL</code> and <em>num_devices</em> is |
| less than the number of sub-devices created by the partition scheme.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_PARTITION_FAILED"><code>CL_DEVICE_<wbr>PARTITION_<wbr>FAILED</code></a> if the partition name is supported by the |
| implementation but in_device could not be further partitioned.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE_PARTITION_COUNT"><code>CL_INVALID_<wbr>DEVICE_<wbr>PARTITION_<wbr>COUNT</code></a> if the partition name specified in |
| <em>properties</em> is <a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>COUNTS</code></a> and the number of |
| sub-devices requested exceeds <a href="#CL_DEVICE_PARTITION_MAX_SUB_DEVICES"><code>CL_DEVICE_<wbr>PARTITION_<wbr>MAX_<wbr>SUB_<wbr>DEVICES</code></a> or the |
| total number of compute units requested exceeds |
| <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_DEVICE_<wbr>MAX_<wbr>COMPUTE_<wbr>UNITS</code></a> for <em>in_device</em>, or the number of |
| compute units requested for one or more sub-devices is less than zero or |
| the number of sub-devices requested exceeds |
| <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_DEVICE_<wbr>MAX_<wbr>COMPUTE_<wbr>UNITS</code></a> for <em>in_device</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A few examples that describe how to specify partition properties in |
| <em>properties</em> argument to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> are given below:</p> |
| </div> |
| <div class="paragraph"> |
| <p>To partition a device containing 16 compute units into two sub-devices, each |
| containing 8 compute units, pass the following in <em>properties</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">{ CL_DEVICE_PARTITION_EQUALLY, <span class="integer">8</span>, |
| <span class="integer">0</span> } <span class="comment">// 0 terminates the property list</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To partition a device with four compute units into two sub-devices with one |
| sub-device containing 3 compute units and the other sub-device 1 compute |
| unit, pass the following in properties argument:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">{ CL_DEVICE_PARTITION_BY_COUNTS, |
| <span class="integer">3</span>, <span class="integer">1</span>, CL_DEVICE_PARTITION_BY_COUNTS_LIST_END, |
| <span class="integer">0</span> } <span class="comment">// 0 terminates the property list</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To split a device along the outermost cache line (if any), pass the |
| following in properties argument:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">{ CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN, |
| CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE, |
| <span class="integer">0</span> } <span class="comment">// 0 terminates the property list</span></code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a device, call the function:</p> |
| </div> |
| <div id="clRetainDevice" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainDevice( |
| cl_device_id device);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clRetainDevice"><strong>clRetainDevice</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>device</em> is the OpenCL device to retain.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainDevice"><strong>clRetainDevice</strong></a> increments the <em>device</em> reference count if <em>device</em> is a |
| valid sub-device created by a call to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>. |
| If <em>device</em> is a root level device i.e. a <code>cl_device_<wbr>id</code> returned by |
| <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>, the <em>device</em> reference count remains unchanged.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainDevice"><strong>clRetainDevice</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed successfully |
| or the device is a root-level device. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a device, call the function:</p> |
| </div> |
| <div id="clReleaseDevice" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseDevice( |
| cl_device_id device);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clReleaseDevice"><strong>clReleaseDevice</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>device</em> is the OpenCL device to retain.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseDevice"><strong>clReleaseDevice</strong></a> decrements the <em>device</em> reference count if device is a |
| valid sub-device created by a call to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>. |
| If <em>device</em> is a root level device i.e. a <code>cl_device_<wbr>id</code> returned by |
| <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>, the <em>device</em> reference count remains unchanged.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseDevice"><strong>clReleaseDevice</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>After the <em>device</em> reference count becomes zero and all the objects attached |
| to <em>device</em> (such as command-queues) are released, the <em>device</em> object is |
| deleted. |
| Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainDevice"><strong>clRetainDevice</strong></a> causes undefined behavior.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_contexts"><a class="anchor" href="#_contexts"></a>4.4. Contexts</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create an OpenCL context, call the function:</p> |
| </div> |
| <div id="clCreateContext" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_context clCreateContext( |
| <span class="directive">const</span> cl_context_properties* properties, |
| cl_uint num_devices, |
| <span class="directive">const</span> cl_device_id* devices, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(<span class="directive">const</span> <span class="predefined-type">char</span>* errinfo, <span class="directive">const</span> <span class="directive">void</span>* private_info, size_t cb, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>properties</em> specifies a list of context property names and their |
| corresponding values. |
| Each property name is immediately followed by the corresponding desired |
| value. |
| The list is terminated with 0. |
| The list of supported properties is described in the |
| <a href="#context-properties-table">Context Properties</a> table. |
| <em>properties</em> can be <code>NULL</code> in which case the platform that is selected is |
| implementation-defined.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the number of devices specified in the <em>devices</em> argument.</p> |
| </li> |
| <li> |
| <p><em>devices</em> is a pointer to a list of unique devices returned by |
| <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> or sub-devices created by <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> for a |
| platform. <sup class="footnote">[<a id="_footnoteref_11" class="footnote" href="#_footnotedef_11" title="View footnote.">11</a>]</sup></p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is a callback function that can be registered by the |
| application. |
| This callback function will be used by the OpenCL implementation to report |
| information on errors during context creation as well as errors that occur |
| at runtime in this context. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the applications responsibility to ensure that the callback function |
| is thread-safe. |
| If <em>pfn_notify</em> is <code>NULL</code>, no callback function is registered.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is |
| called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The parameters to the callback function <em>pfn_notify</em> are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>errinfo</em> is a pointer to an error string.</p> |
| </li> |
| <li> |
| <p><em>private_info</em> and <em>cb</em> represent a pointer to binary data that is |
| returned by the OpenCL implementation that can be used to log additional |
| information helpful in debugging the error.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> is a pointer to user supplied data.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Contexts are used by the OpenCL runtime for managing objects such as |
| command-queues, memory, program and kernel objects and for executing kernels |
| on one or more devices specified in the context.</p> |
| </div> |
| <table id="context-properties-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 7. List of supported context creation properties by <a href="#clCreateContext">clCreateContext</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Context Property</th> |
| <th class="tableblock halign-left valign-top">Property Value</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_PLATFORM"></a><a href="#CL_CONTEXT_PLATFORM"><code>CL_CONTEXT_<wbr>PLATFORM</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_platform_<wbr>id</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the platform to use.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_INTEROP_USER_SYNC"></a><a href="#CL_CONTEXT_INTEROP_USER_SYNC"><code>CL_CONTEXT_<wbr>INTEROP_<wbr>USER_<wbr>SYNC</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether the user is responsible for synchronization |
| between OpenCL and other APIs. |
| Please refer to the specific sections in the OpenCL Extension |
| Specification that describe sharing with other APIs for restrictions |
| on using this flag.</p> |
| <p class="tableblock"> If <a href="#CL_CONTEXT_INTEROP_USER_SYNC"><code>CL_CONTEXT_<wbr>INTEROP_<wbr>USER_<wbr>SYNC</code></a> is not specified, a default of |
| <a href="#CL_FALSE"><code>CL_FALSE</code></a> is assumed.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| There are a number of cases where error notifications need to be |
| delivered due to an error that occurs outside a context. |
| Such notifications may not be delivered through the <em>pfn_notify</em> callback. |
| Where these notifications go is implementation-defined. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateContext"><strong>clCreateContext</strong></a> returns a valid non-zero context and <em>errcode_ret</em> is set |
| to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the context is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PLATFORM"><code>CL_INVALID_<wbr>PLATFORM</code></a> if <em>properties</em> is <code>NULL</code> and no platform could be |
| selected or if platform value specified in <em>properties</em> is not a valid |
| platform.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROPERTY"><code>CL_INVALID_<wbr>PROPERTY</code></a> if context property name in <em>properties</em> is not a |
| supported property name, if the value specified for a supported property |
| name is not valid, or if the same property name is specified more than |
| once. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>devices</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_devices</em> is equal to zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if any device in <em>devices</em> is not a valid device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_NOT_AVAILABLE"><code>CL_DEVICE_<wbr>NOT_<wbr>AVAILABLE</code></a> if a device in <em>devices</em> is currently not |
| available even though the device was returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>It is possible that a device(s) becomes unavailable after a context and |
| command-queues that use this device(s) have been created and commands have |
| been queued to command-queues. |
| In this case the behavior of OpenCL API calls that use this context (and |
| command-queues) are considered to be implementation-defined. |
| The user callback function, if specified, when the context is created can be |
| used to record appropriate information in the <em>errinfo</em>, <em>private_info</em> |
| arguments passed to the callback function when the device becomes |
| unavailable.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create an OpenCL context from a specific device |
| type <sup class="footnote">[<a id="_footnoteref_12" class="footnote" href="#_footnotedef_12" title="View footnote.">12</a>]</sup>, call the function:</p> |
| </div> |
| <div id="clCreateContextFromType" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_context clCreateContextFromType( |
| <span class="directive">const</span> cl_context_properties* properties, |
| cl_device_type device_type, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(<span class="directive">const</span> <span class="predefined-type">char</span>* errinfo, <span class="directive">const</span> <span class="directive">void</span>* private_info, size_t cb, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>properties</em> specifies a list of context property names and their |
| corresponding values. |
| Each property name is immediately followed by the corresponding desired |
| value. |
| The list of supported properties is described in the |
| <a href="#context-properties-table">Context Properties</a> table. |
| <em>properties</em> can also be <code>NULL</code> in which case the platform that is selected |
| is implementation-defined.</p> |
| </li> |
| <li> |
| <p><em>device_type</em> is a bit-field that identifies the type of device and is |
| described in the <a href="#device-types-table">Device Types</a> table.</p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> and <em>user_data</em> are described in <a href="#clCreateContext"><strong>clCreateContext</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Only devices that are returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> for <em>device_type</em> are |
| used to create the context. |
| The context does not reference any sub-devices that may have been created |
| from these devices.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> returns a valid non-zero context and <em>errcode_ret</em> |
| is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the context is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PLATFORM"><code>CL_INVALID_<wbr>PLATFORM</code></a> if <em>properties</em> is <code>NULL</code> and no platform could be |
| selected or if platform value specified in <em>properties</em> is not a valid |
| platform.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROPERTY"><code>CL_INVALID_<wbr>PROPERTY</code></a> if context property name in <em>properties</em> is not a |
| supported property name, if the value specified for a supported property |
| name is not valid, or if the same property name is specified more than |
| once. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE_TYPE"><code>CL_INVALID_<wbr>DEVICE_<wbr>TYPE</code></a> if <em>device_type</em> is not a valid value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_NOT_AVAILABLE"><code>CL_DEVICE_<wbr>NOT_<wbr>AVAILABLE</code></a> if no devices that match <em>device_type</em> and |
| property values specified in <em>properties</em> are currently available.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_NOT_FOUND"><code>CL_DEVICE_<wbr>NOT_<wbr>FOUND</code></a> if no devices that match <em>device_type</em> and property |
| values specified in <em>properties</em> were found.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a context, call the function:</p> |
| </div> |
| <div id="clRetainContext" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainContext( |
| cl_context context);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> specifies the OpenCL context to retain.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainContext"><strong>clRetainContext</strong></a> increments the <em>context</em> reference count.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateContext"><strong>clCreateContext</strong></a> and <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> perform an implicit retain. |
| This is very helpful for 3<sup>rd</sup> party libraries, which typically get a |
| context passed to them by the application. |
| However, it is possible that the application may delete the context without |
| informing the library. |
| Allowing functions to attach to (i.e. retain) and release a context solves |
| the problem of a context being used by a library no longer being valid.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainContext"><strong>clRetainContext</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a context, call the function:</p> |
| </div> |
| <div id="clReleaseContext" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseContext( |
| cl_context context);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> specifies the OpenCL context to release.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseContext"><strong>clReleaseContext</strong></a> decrements the <em>context</em> reference count. |
| After the reference count becomes zero and all the objects attached to |
| <em>context</em> (such as memory objects, command-queues) are released, the |
| <em>context</em> is deleted. |
| Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainContext"><strong>clRetainContext</strong></a> causes undefined behavior.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseContext"><strong>clReleaseContext</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To query information about a context, call the function:</p> |
| </div> |
| <div id="clGetContextInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetContextInfo( |
| cl_context context, |
| cl_context_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> specifies the OpenCL context being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> is an enumeration constant that specifies the information to |
| query.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> specifies the size in bytes of memory pointed to by |
| <em>param_value</em>. |
| This size must be greater than or equal to the size of return type as |
| described in the <a href="#context-info-table">Context Attributes</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The list of supported <em>param_name</em> values and the information returned in |
| <em>param_value</em> by <a href="#clGetContextInfo"><strong>clGetContextInfo</strong></a> is described in the |
| <a href="#context-info-table">Context Attributes</a> table.</p> |
| </div> |
| <table id="context-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 8. List of supported param_names by <a href="#clGetContextInfo">clGetContextInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Context Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_REFERENCE_COUNT"></a><a href="#CL_CONTEXT_REFERENCE_COUNT"><code>CL_CONTEXT_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_13" class="footnote" href="#_footnotedef_13" title="View footnote.">13</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the <em>context</em> reference count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_NUM_DEVICES"></a><a href="#CL_CONTEXT_NUM_DEVICES"><code>CL_CONTEXT_<wbr>NUM_<wbr>DEVICES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the number of devices in <em>context</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_DEVICES"></a><a href="#CL_CONTEXT_DEVICES"><code>CL_CONTEXT_<wbr>DEVICES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>id</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the list of devices and sub-devices in <em>context</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_PROPERTIES"></a><a href="#CL_CONTEXT_PROPERTIES"><code>CL_CONTEXT_<wbr>PROPERTIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context_<wbr>properties</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in <a href="#clCreateContext"><strong>clCreateContext</strong></a> or |
| <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a>.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreateContext"><strong>clCreateContext</strong></a> or |
| <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> used to create <em>context</em> was not <code>NULL</code>, |
| the implementation must return the values specified in the |
| properties argument in the same order and without including |
| additional properties.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreateContext"><strong>clCreateContext</strong></a> or |
| <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> used to create <em>context</em> was <code>NULL</code>, the |
| implementation must return <em>param_value_size_ret</em> equal to 0, |
| indicating that there are no properties to be returned.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetContextInfo"><strong>clGetContextInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not one of the supported values or |
| if size in bytes specified by <em>param_value_size</em> is < size of return |
| type as specified in the <a href="#context-info-table">Context Attributes</a> |
| table and <em>param_value</em> is not a <code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To register a callback function with a context that is called when |
| the context is destroyed, call the function</p> |
| </div> |
| <div id="clSetContextDestructorCallback" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetContextDestructorCallback( |
| cl_context context, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_context context, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetContextDestructorCallback"><strong>clSetContextDestructorCallback</strong></a> is <a href="#unified-spec">missing before</a> version 3.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> specifies the OpenCL context to register the callback to.</p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is the callback function to register. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the application’s responsibility to ensure that the callback function |
| is thread-safe. |
| The parameters to this callback function are:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is the OpenCL context being deleted. |
| When the callback function is called by the implementation, this context |
| is no longer valid. |
| <em>context</em> is only provided for reference purposes.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> is a pointer to user-supplied data.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is |
| called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Each call to <a href="#clSetContextDestructorCallback"><strong>clSetContextDestructorCallback</strong></a> registers the specified |
| callback function on a destructor callback stack associated with <em>context</em>. |
| The registered callback functions are called in the reverse order in |
| which they were registered. |
| If a context callback function was specified when <em>context</em> was created, |
| it will not be called after any context destructor callback is called. |
| Therefore, the context destructor callback provides a mechanism for an |
| application to safely re-use or free any <em>user_data</em> specified for the |
| context callback function when <em>context</em> was created.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetContextDestructorCallback"><strong>clSetContextDestructorCallback</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is |
| executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="opencl-runtime"><a class="anchor" href="#opencl-runtime"></a>5. The OpenCL Runtime</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>In this section we describe the API calls that manage OpenCL objects such as |
| command-queues, memory objects, program objects, kernel objects for kernel |
| functions in a program and calls that allow you to enqueue commands to a |
| command-queue such as executing a kernel, reading, or writing a memory |
| object.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_command_queues"><a class="anchor" href="#_command_queues"></a>5.1. Command Queues</h3> |
| <div class="paragraph"> |
| <p>OpenCL objects such as memory, program and kernel objects are created using |
| a context. |
| Operations on these objects are performed using a command-queue. |
| The command-queue can be used to queue a set of operations (referred to as |
| commands) in order. |
| Having multiple command-queues allows applications to queue multiple |
| independent commands without requiring synchronization. |
| Note that this should work as long as these objects are not being shared. |
| Sharing of objects across multiple command-queues will require the |
| application to perform appropriate synchronization. |
| This is described in <a href="#shared-opencl-objects">Shared OpenCL Objects</a></p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a host or device command-queue on a specific device, call the |
| function</p> |
| </div> |
| <div id="clCreateCommandQueueWithProperties" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_command_queue clCreateCommandQueueWithProperties( |
| cl_context context, |
| cl_device_id device, |
| <span class="directive">const</span> cl_queue_properties* properties, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| Also see extension <strong>cl_khr_create_command_queue</strong>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>device</em> must be a device or sub-device associated with <em>context</em>. |
| It can either be in the list of devices and sub-devices specified when |
| <em>context</em> is created using <a href="#clCreateContext"><strong>clCreateContext</strong></a> or be a root device with the |
| same device type as specified when <em>context</em> is created using |
| <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>properties</em> specifies a list of properties for the command-queue and their |
| corresponding values. |
| Each property name is immediately followed by the corresponding desired |
| value. |
| The list is terminated with 0. |
| The list of supported properties is described in the |
| <a href="#queue-properties-table">table below</a>. |
| If a supported property and its value is not specified in <em>properties</em>, its |
| default value will be used. |
| <em>properties</em> can be <code>NULL</code> in which case the default values for supported |
| command-queue properties will be used.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="queue-properties-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 9. List of supported queue creation properties by <a href="#clCreateCommandQueueWithProperties">clCreateCommandQueueWithProperties</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Queue Property</th> |
| <th class="tableblock halign-left valign-top">Property Value</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_PROPERTIES"></a><a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue_<wbr>properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a bitfield and can be set to a combination of the following |
| values:</p> |
| <p class="tableblock"> <a id="CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"></a><a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> - Determines whether the |
| commands queued in the command-queue are executed in-order or |
| out-of-order. |
| If set, the commands in the command-queue are executed out-of-order. |
| Otherwise, commands are executed in-order.</p> |
| <p class="tableblock"> <a id="CL_QUEUE_PROFILING_ENABLE"></a><a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a> - Enable or disable profiling of commands |
| in the command-queue. |
| If set, the profiling of commands is enabled. |
| Otherwise profiling of commands is disabled.</p> |
| <p class="tableblock"> <a id="CL_QUEUE_ON_DEVICE"></a><a href="#CL_QUEUE_ON_DEVICE"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE</code></a> - Indicates that this is a device queue. |
| If <a href="#CL_QUEUE_ON_DEVICE"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE</code></a> is set, |
| <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> |
| <sup class="footnote">[<a id="_footnoteref_14" class="footnote" href="#_footnotedef_14" title="View footnote.">14</a>]</sup> |
| must also be set. |
| <a href="#unified-spec">Missing before</a> version 2.0.</p> |
| <p class="tableblock"> <a id="CL_QUEUE_ON_DEVICE_DEFAULT"></a><a href="#CL_QUEUE_ON_DEVICE_DEFAULT"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>DEFAULT</code></a> |
| <sup class="footnote">[<a id="_footnoteref_15" class="footnote" href="#_footnotedef_15" title="View footnote.">15</a>]</sup> - |
| indicates that this is the default device queue. |
| This can only be used with <a href="#CL_QUEUE_ON_DEVICE"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE</code></a>. |
| <a href="#unified-spec">Missing before</a> version 2.0.</p> |
| <p class="tableblock"> If <a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a> is not specified an in-order host command |
| queue is created for the specified device</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_SIZE"></a><a href="#CL_QUEUE_SIZE"><code>CL_QUEUE_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the size of the device queue in bytes.</p> |
| <p class="tableblock"> This can only be specified if <a href="#CL_QUEUE_ON_DEVICE"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE</code></a> is set in |
| <a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a>. |
| This must be a value ≤ <a href="#CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>MAX_<wbr>SIZE</code></a>.</p> |
| <p class="tableblock"> For best performance, this should be ≤ |
| <a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>PREFERRED_<wbr>SIZE</code></a>.</p> |
| <p class="tableblock"> If <a href="#CL_QUEUE_SIZE"><code>CL_QUEUE_<wbr>SIZE</code></a> is not specified, the device queue is created with |
| <a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>PREFERRED_<wbr>SIZE</code></a> as the size of the queue.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> returns a valid non-zero command-queue |
| and <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the command-queue is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device or is not associated |
| with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>properties</em> are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_QUEUE_PROPERTIES"><code>CL_INVALID_<wbr>QUEUE_<wbr>PROPERTIES</code></a> if values specified in <em>properties</em> are |
| valid but are not supported by the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a host command-queue on a specific device, call the function</p> |
| </div> |
| <div id="clCreateCommandQueue" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_command_queue clCreateCommandQueue( |
| cl_context context, |
| cl_device_id device, |
| cl_command_queue_properties properties, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a> is <a href="#unified-spec">deprecated by</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>device</em> must be a device or sub-device associated with <em>context</em>. |
| It can either be in the list of devices and sub-devices specified when |
| <em>context</em> is created using <a href="#clCreateContext"><strong>clCreateContext</strong></a> or be a root device with the |
| same device type as specified when <em>context</em> is created using |
| <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>properties</em> specifies a list of properties for the command-queue. |
| This is a bit-field and the supported properties are described in the |
| <a href="#legacy-queue-properties-table">table</a> below. |
| Only command-queue properties specified in this table can be used, |
| otherwise the value specified in <em>properties</em> is considered to be not |
| valid. |
| <em>properties</em> can be 0 in which case the default values for supported |
| command-queue properties will be used.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="legacy-queue-properties-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 10. List of supported <code>cl_command_queue_property</code> values by <a href="#clCreateCommandQueue">clCreateCommandQueue</a></caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Command-Queue Properties</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Determines whether the commands queued in the command-queue are executed |
| in-order or out-of-order. |
| If set, the commands in the command-queue are executed out-of-order. |
| Otherwise, commands are executed in-order.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Enable or disable profiling of commands in the command-queue. |
| If set, the profiling of commands is enabled. |
| Otherwise profiling of commands is disabled.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a> returns a valid non-zero command-queue and <em>errcode_ret</em> |
| is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the command-queue is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device or is not associated |
| with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>properties</em> are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_QUEUE_PROPERTIES"><code>CL_INVALID_<wbr>QUEUE_<wbr>PROPERTIES</code></a> if values specified in <em>properties</em> are |
| valid but are not supported by the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To replace the default command queue on a device, call the function</p> |
| </div> |
| <div id="clSetDefaultDeviceCommandQueue" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetDefaultDeviceCommandQueue( |
| cl_context context, |
| cl_device_id device, |
| cl_command_queue command_queue);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is the OpenCL context used to create <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><em>device</em> is a valid OpenCL device associated with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><em>command_queue</em> specifies a command queue object which replaces the |
| default device command queue</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a> may be used to replace a default device |
| command queue created with <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> and the |
| <a href="#CL_QUEUE_ON_DEVICE_DEFAULT"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>DEFAULT</code></a> flag.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is |
| executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not a valid device or is not associated |
| with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>device</em> does not support a replaceable default on-device queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid command-queue |
| for <em>device</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a command queue, call the function</p> |
| </div> |
| <div id="clRetainCommandQueue" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainCommandQueue( |
| cl_command_queue command_queue);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> specifies the command-queue to be retained.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>command_queue</em> reference count is incremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> and <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a> perform an |
| implicit retain. |
| This is very helpful for 3<sup>rd</sup> party libraries, which typically get a |
| command-queue passed to them by the application. |
| However, it is possible that the application may delete the command-queue |
| without informing the library. |
| Allowing functions to attach to (i.e. retain) and release a command-queue |
| solves the problem of a command-queue being used by a library no longer |
| being valid.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainCommandQueue"><strong>clRetainCommandQueue</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a command queue, call the function</p> |
| </div> |
| <div id="clReleaseCommandQueue" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseCommandQueue( |
| cl_command_queue command_queue);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> specifies the command-queue to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>command_queue</em> reference count is decremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After the <em>command_queue</em> reference count becomes zero and all commands |
| queued to <em>command_queue</em> have finished (eg. |
| kernel-instances, memory object updates etc.), the command-queue is deleted.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a> performs an implicit flush to issue any previously |
| queued OpenCL commands in <em>command_queue</em>. |
| Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainCommandQueue"><strong>clRetainCommandQueue</strong></a> causes undefined behavior.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To query information about a command-queue, call the function</p> |
| </div> |
| <div id="clGetCommandQueueInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetCommandQueueInfo( |
| cl_command_queue command_queue, |
| cl_command_queue_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> specifies the command-queue being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#command-queue-param-table">Command Queue Parameter</a> table. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The list of supported <em>param_name</em> values and the information returned in |
| <em>param_value</em> by <a href="#clGetCommandQueueInfo"><strong>clGetCommandQueueInfo</strong></a> is described in the |
| <a href="#command-queue-param-table">Command Queue Parameter</a> table.</p> |
| </div> |
| <table id="command-queue-param-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 11. List of supported param_names by <a href="#clGetCommandQueueInfo">clGetCommandQueueInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Queue Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_CONTEXT"></a><a href="#CL_QUEUE_CONTEXT"><code>CL_QUEUE_<wbr>CONTEXT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the context specified when the command-queue is created.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_DEVICE"></a><a href="#CL_QUEUE_DEVICE"><code>CL_QUEUE_<wbr>DEVICE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>id</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the device specified when the command-queue is created.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_REFERENCE_COUNT"></a><a href="#CL_QUEUE_REFERENCE_COUNT"><code>CL_QUEUE_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_16" class="footnote" href="#_footnotedef_16" title="View footnote.">16</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the command-queue reference count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_PROPERTIES"></a><a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue_<wbr>properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the currently specified properties for the command-queue. |
| These properties are specified by the value associated with the |
| <a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a> passed in <em>properties</em> argument in |
| <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a>, or the value of the <em>properties</em> |
| argument in <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_PROPERTIES_ARRAY"></a><a href="#CL_QUEUE_PROPERTIES_ARRAY"><code>CL_QUEUE_<wbr>PROPERTIES_<wbr>ARRAY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_queue_<wbr>properties</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in |
| <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a>.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in |
| <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> used to create <em>command_queue</em> |
| was not <code>NULL</code>, the implementation must return the values specified in |
| the properties argument in the same order and without including |
| additional properties.</p> |
| <p class="tableblock"> If <em>command_queue</em> was created using <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a>, or if the |
| <em>properties</em> argument specified in clCreateCommandQueueWithProperties} |
| was <code>NULL</code>, the implementation must return <em>param_value_size_ret</em> |
| equal to 0, indicating that there are no properties to be returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_SIZE"></a><a href="#CL_QUEUE_SIZE"><code>CL_QUEUE_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the size of the device command-queue. |
| To be considered valid for this query, <em>command_queue</em> must be a |
| device command-queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_DEVICE_DEFAULT"></a><a href="#CL_QUEUE_DEVICE_DEFAULT"><code>CL_QUEUE_<wbr>DEVICE_<wbr>DEFAULT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the current default command queue for the underlying device.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetCommandQueueInfo"><strong>clGetCommandQueueInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid |
| command-queue, or if <em>command_queue</em> is not a valid command-queue |
| for <em>param_name</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not one of the supported values or |
| if size in bytes specified by <em>param_value_size</em> is < size of return |
| type as specified in the <a href="#command-queue-param-table">Command Queue |
| Parameter</a> table, and <em>param_value</em> is not a <code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enable or disable the properties of a command-queue, call the function</p> |
| </div> |
| <div id="clSetCommandQueueProperty" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetCommandQueueProperty( |
| cl_command_queue command_queue, |
| cl_command_queue_properties properties, |
| cl_bool enable, |
| cl_command_queue_properties* old_properties);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetCommandQueueProperty"><strong>clSetCommandQueueProperty</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> specifies the command-queue being modified.</p> |
| </li> |
| <li> |
| <p><em>properties</em> specifies the new list of properties for the command-queue. |
| This is a bit-field and the supported properties are described in the |
| <a href="#legacy-queue-properties-table">Command-Queue Properties table</a> for |
| <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a>. |
| Only command-queue properties specified in this table can be used, |
| otherwise the value specified in <em>properties</em> is considered to be not |
| valid.</p> |
| </li> |
| <li> |
| <p><em>enable</em> determines whether the values specified by <em>properties</em> are |
| enabled (if <em>enable</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>) or disabled (if <em>enable</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>) |
| for the command-queue.</p> |
| </li> |
| <li> |
| <p><em>old_properties</em> returns the command-queue properties before they were |
| changed by <a href="#clSetCommandQueueProperty"><strong>clSetCommandQueueProperty</strong></a>. If <em>old_properties</em> is <code>NULL</code>, it |
| is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Changing the <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> command-queue property |
| will cause the OpenCL implementation to block until all previously queued |
| commands in <em>command_queue</em> have completed. This can be an expensive operation |
| and therefore changes to this property should only be done when absolutely |
| necessary.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetCommandQueueProperty"><strong>clSetCommandQueueProperty</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>properties</em> are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_QUEUE_PROPERTIES"><code>CL_INVALID_<wbr>QUEUE_<wbr>PROPERTIES</code></a> if values specified in <em>properties</em> are |
| valid but are not supported by the device.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_buffer_objects"><a class="anchor" href="#_buffer_objects"></a>5.2. Buffer Objects</h3> |
| <div class="paragraph"> |
| <p>A <em>buffer</em> object stores a one-dimensional collection of elements. |
| Elements of a <em>buffer</em> object can be a scalar data type (such as an int, |
| float), vector data type, or a user-defined structure.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_buffer_objects"><a class="anchor" href="#_creating_buffer_objects"></a>5.2.1. Creating Buffer Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>A <strong>buffer object</strong> may be created using the function</p> |
| </div> |
| <div id="clCreateBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateBuffer( |
| cl_context context, |
| cl_mem_flags flags, |
| size_t size, |
| <span class="directive">void</span>* host_ptr, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A <strong>buffer object</strong> may also be created with additional properties using the function</p> |
| </div> |
| <div id="clCreateBufferWithProperties" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateBufferWithProperties( |
| cl_context context, |
| <span class="directive">const</span> cl_mem_properties* properties, |
| cl_mem_flags flags, |
| size_t size, |
| <span class="directive">void</span>* host_ptr, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> is <a href="#unified-spec">missing before</a> version 3.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context used to create the buffer object.</p> |
| </li> |
| <li> |
| <p><em>properties</em> is an optional list of properties for the buffer object and their corresponding values. |
| The list is terminated with the special property <code>0</code>. |
| If no properties are required, <em>properties</em> may be <code>NULL</code>. |
| OpenCL 3.0 does not define any optional properties for buffers.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information about the image memory object being created and is described in |
| the <a href="#memory-flags-table">supported memory flag values</a> table.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of the buffer memory object to be allocated.</p> |
| </li> |
| <li> |
| <p><em>host_ptr</em> is a pointer to the buffer data that may already be allocated |
| by the application. |
| The size of the buffer that <em>host_ptr</em> points to must be greater than or equal to <em>size</em> |
| bytes.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> may return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The alignment requirements for data stored in buffer objects are described |
| in <a href="#alignment-app-data-types">Alignment of Application Data Types</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> is called with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> set in its <em>flags</em> argument, the contents of the |
| memory pointed to by <em>host_ptr</em> at the time of the <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> call |
| define the initial contents of the buffer object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> is called with a |
| pointer returned by <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> as its <em>host_ptr</em> argument, and |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> is set in its <em>flags</em> argument, <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> will succeed and return a valid non-zero |
| buffer object as long as the <em>size</em> argument is no larger than the |
| <em>size</em> argument passed in the original <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> call. |
| The new buffer object returned has the shared memory as the underlying |
| storage. |
| Locations in the buffers underlying shared memory can be operated on using |
| atomic operations to the devices level of support as defined in the memory |
| model.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> and <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> returns a valid non-zero |
| buffer object and <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the buffer object |
| is created successfully. |
| Otherwise, they return a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROPERTY"><code>CL_INVALID_<wbr>PROPERTY</code></a> if a property name in <em>properties</em> is not a |
| supported property name, if the value specified for a supported property |
| name is not valid, or if the same property name is specified more than |
| once.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>flags</em> are not valid as defined |
| in the <a href="#memory-flags-table">Memory Flags</a> table.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_BUFFER_SIZE"><code>CL_INVALID_<wbr>BUFFER_<wbr>SIZE</code></a> if <em>size</em> is 0 or if <em>size</em> is greater than |
| <a href="#CL_DEVICE_MAX_MEM_ALLOC_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>MEM_<wbr>ALLOC_<wbr>SIZE</code></a> for all devices in <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_HOST_PTR"><code>CL_INVALID_<wbr>HOST_<wbr>PTR</code></a> if <em>host_ptr</em> is <code>NULL</code> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or |
| <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> |
| but <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> are not set in <em>flags</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="memory-flags-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 12. List of supported memory flag values</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Memory Flags</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_READ_WRITE"></a><a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the memory object will be read |
| and written by a kernel. |
| This is the default.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_WRITE_ONLY"></a><a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the memory object will be |
| written but not read by a kernel.</p> |
| <p class="tableblock"> Reading from a buffer or image object created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> |
| inside a kernel is undefined.</p> |
| <p class="tableblock"> <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> and <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> are mutually exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_READ_ONLY"></a><a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the memory object is a |
| readonly memory object when used inside a kernel.</p> |
| <p class="tableblock"> Writing to a buffer or image object created with <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> inside |
| a kernel is undefined.</p> |
| <p class="tableblock"> <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> and <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> are mutually |
| exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_USE_HOST_PTR"></a><a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag is valid only if host_ptr is not <code>NULL</code>. |
| If specified, it indicates that the application wants the OpenCL |
| implementation to use memory referenced by host_ptr as the storage bits |
| for the memory object.</p> |
| <p class="tableblock"> The contents of the memory pointed to by host_ptr at the time of the |
| <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>, <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, <a href="#clCreateImage"><strong>clCreateImage</strong></a>, |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> |
| call define the initial contents of the memory object.</p> |
| <p class="tableblock"> OpenCL implementations are allowed to cache the contents pointed |
| to by host_ptr in device memory. |
| This cached copy can be used when kernels are executed on a device.</p> |
| <p class="tableblock"> The result of OpenCL commands that operate on multiple buffer objects |
| created with the same host_ptr or from overlapping host or SVM regions |
| is considered to be undefined.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_ALLOC_HOST_PTR"></a><a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the application wants the OpenCL implementation |
| to allocate memory from host accessible memory.</p> |
| <p class="tableblock"> <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> are mutually exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_COPY_HOST_PTR"></a><a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag is valid only if host_ptr is not <code>NULL</code>. |
| If specified, it indicates that the application wants the OpenCL |
| implementation to allocate memory for the memory object and copy the |
| data from memory referenced by host_ptr. |
| The implementation will copy the memory immediately and host_ptr is |
| available for reuse by the application when the <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>, |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, |
| <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> operation returns.</p> |
| <p class="tableblock"> <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> are mutually exclusive.</p> |
| <p class="tableblock"> <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> can be used with <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a> to |
| initialize the contents of the <code>cl_mem</code> object allocated using |
| host-accessible (e.g. PCIe) memory.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_WRITE_ONLY"></a><a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the host will only write to the memory object |
| (using OpenCL APIs that enqueue a write or a map for write). |
| This can be used to optimize write access from the host (e.g. enable |
| write-combined allocations for memory objects for devices that |
| communicate with the host over a system bus such as PCIe).</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_READ_ONLY"></a><a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the host will only read |
| the memory object (using OpenCL APIs that enqueue a read or a map for |
| read).</p> |
| <p class="tableblock"> <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> and <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> are mutually exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_NO_ACCESS"></a><a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the host will not read or |
| write the memory object.</p> |
| <p class="tableblock"> <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> and |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> are mutually exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_KERNEL_READ_AND_WRITE"></a><a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag is only used by <a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> to query image |
| formats that may be both read from and written to by the same kernel |
| instance. |
| To create a memory object that may be read from and written to use |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a new buffer object (referred to as a sub-buffer object) from an |
| existing buffer object, call the function</p> |
| </div> |
| <div id="clCreateSubBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateSubBuffer( |
| cl_mem buffer, |
| cl_mem_flags flags, |
| cl_buffer_create_type buffer_create_type, |
| <span class="directive">const</span> <span class="directive">void</span>* buffer_create_info, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>buffer</em> must be a valid buffer object and cannot be a sub-buffer object.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information about the sub-buffer memory object being created and is |
| described in the <a href="#memory-flags-table">Memory Flags</a> table. |
| If the <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>, <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a>, or <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> values are |
| not specified in <em>flags</em>, they are inherited from the corresponding memory |
| access qualifiers associated with <em>buffer</em>. |
| The <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a>, and <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> |
| values cannot be specified in <em>flags</em> but are inherited from the |
| corresponding memory access qualifiers associated with <em>buffer</em>. |
| If <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> is specified in the memory access qualifier values |
| associated with <em>buffer</em> it does not imply any additional copies when the |
| sub-buffer is created from <em>buffer</em>. |
| If the <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a>, <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a>, or |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> values are not specified in <em>flags</em>, they are |
| inherited from the corresponding memory access qualifiers associated with |
| <em>buffer</em>.</p> |
| </li> |
| <li> |
| <p><em>buffer_create_type</em> and <em>buffer_create_info</em> describe the type of buffer |
| object to be created. |
| The list of supported values for <em>buffer_create_type</em> and corresponding |
| descriptor that <em>buffer_create_info</em> points to is described in the |
| <a href="#subbuffer-create-info-table">SubBuffer Attributes</a> table.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="subbuffer-create-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 13. List of supported buffer creation types by <a href="#clCreateSubBuffer">clCreateSubBuffer</a></caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Buffer Creation Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_BUFFER_CREATE_TYPE_REGION"></a><a href="#CL_BUFFER_CREATE_TYPE_REGION"><code>CL_BUFFER_<wbr>CREATE_<wbr>TYPE_<wbr>REGION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Create a buffer object that represents a specific region in <em>buffer</em>.</p> |
| <p class="tableblock"> <em>buffer_create_info</em> is a pointer to a <a href="#cl_buffer_region"><code>cl_buffer_<wbr>region</code></a> structure |
| specifying a region of the buffer.</p> |
| <p class="tableblock"> If <em>buffer</em> is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, the <em>host_ptr</em> |
| associated with the buffer object returned is <em>host_ptr + origin</em>.</p> |
| <p class="tableblock"> The buffer object returned references the data store allocated for |
| buffer and points to the region specified by <em>buffer_create_info</em> in |
| this data store.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>buffer</em> is not a valid buffer object or is a |
| sub-buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>buffer</em> was created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> and |
| <em>flags</em> specifies <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> or <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a>, or if <em>buffer</em> |
| was created with <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> and <em>flags</em> specifies |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a>, or if <em>flags</em> specifies |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>buffer</em> was created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> and |
| <em>flags</em> specify <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a>, or if <em>buffer</em> was created with |
| <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> and <em>flags</em> specify <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a>, or if |
| <em>buffer</em> was created with <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> and <em>flags</em> specify |
| <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the value specified in <em>buffer_create_type</em> is not |
| valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if value(s) specified in <em>buffer_create_info</em> (for a |
| given <em>buffer_create_type</em>) is not valid or if <em>buffer_create_info</em> is |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for sub-buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the region specified by the <a href="#cl_buffer_region"><code>cl_buffer_<wbr>region</code></a> |
| structure passed in <em>buffer_create_info</em> is out of bounds in <em>buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_BUFFER_SIZE"><code>CL_INVALID_<wbr>BUFFER_<wbr>SIZE</code></a> if the <em>size</em> field of the <a href="#cl_buffer_region"><code>cl_buffer_<wbr>region</code></a> |
| structure passed in <em>buffer_create_info</em> is 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if there are no devices in <em>context</em> |
| associated with <em>buffer</em> for which the <em>origin</em> field of the |
| <a href="#cl_buffer_region"><code>cl_buffer_<wbr>region</code></a> structure passed in <em>buffer_create_info</em> is |
| aligned to the <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Concurrent reading from, writing to and copying between both a buffer object |
| and its sub-buffer object(s) is undefined. |
| Concurrent reading from, writing to and copying between overlapping |
| sub-buffer objects created with the same buffer object is undefined. |
| Only reading from both a buffer object and its sub-buffer objects or reading |
| from multiple overlapping sub-buffer objects is defined.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The <a href="#cl_buffer_region"><code>cl_buffer_<wbr>region</code></a> structure specifies a region of a buffer object:</p> |
| </div> |
| <div id="cl_buffer_region" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_buffer_region { |
| size_t origin; |
| size_t size; |
| } cl_buffer_region;</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>origin</em> is the offset in bytes of the region.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of the region.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Constraints on the values of <em>origin</em> and <em>size</em> are specified for the |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> function to which this structure is passed.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_reading_writing_and_copying_buffer_objects"><a class="anchor" href="#_reading_writing_and_copying_buffer_objects"></a>5.2.2. Reading, Writing and Copying Buffer Objects</h4> |
| <div class="paragraph"> |
| <p>The following functions enqueue commands to read from a buffer object to |
| host memory or write to a buffer object from host memory.</p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To read from a buffer object to host memory or to write to a buffer object from |
| host memory call one of the functions</p> |
| </div> |
| <div id="clEnqueueReadBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueReadBuffer( |
| cl_command_queue command_queue, |
| cl_mem buffer, |
| cl_bool blocking_read, |
| size_t offset, |
| size_t size, |
| <span class="directive">void</span>* ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div id="clEnqueueWriteBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWriteBuffer( |
| cl_command_queue command_queue, |
| cl_mem buffer, |
| cl_bool blocking_write, |
| size_t offset, |
| size_t size, |
| <span class="directive">const</span> <span class="directive">void</span>* ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue in which the read / write |
| command will be queued. |
| <em>command_queue</em> and <em>buffer</em> must be created with the same OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>buffer</em> refers to a valid buffer object.</p> |
| </li> |
| <li> |
| <p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write |
| operations are <em>blocking</em> or <em>non-blocking</em> (see below).</p> |
| </li> |
| <li> |
| <p><em>offset</em> is the offset in bytes in the buffer object to read from or write |
| to.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of data being read or written.</p> |
| </li> |
| <li> |
| <p><em>ptr</em> is the pointer to buffer in host memory where data is to be read into |
| or to be written from.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this read / write command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_read</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a> i.e. the read command is blocking, |
| <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> does not return until the buffer data has been read |
| and copied into memory pointed to by <em>ptr</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_read</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. the read command is non-blocking, |
| <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> queues a non-blocking read command and returns. |
| The contents of the buffer that <em>ptr</em> points to cannot be used until the |
| read command has completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the read command. |
| When the read command has completed, the contents of the buffer that <em>ptr</em> |
| points to can be used by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_write</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the write command is blocking and does not |
| return until the command is complete, including transfer of the data. |
| The memory pointed to by <em>ptr</em> can be reused by the application after the |
| <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> call returns.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_write</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>, the OpenCL implementation will use <em>ptr</em> to |
| perform a non-blocking write. |
| As the write is non-blocking the implementation can return immediately. |
| The memory pointed to by <em>ptr</em> cannot be reused by the application after the |
| call returns. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the write command. |
| When the write command has completed, the memory pointed to by <em>ptr</em> can |
| then be reused by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> and <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the |
| function is executed successfully. |
| Otherwise, they return one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| <em>buffer</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the region being read or written specified by |
| (<em>offset</em>, <em>size</em>) is out of bounds or if <em>ptr</em> is a <code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and |
| <em>offset</em> specified when the sub-buffer object is created is not aligned |
| to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated with |
| <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the read and write |
| operations are blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> is called on <em>buffer</em> |
| which has been created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> or |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> is called on <em>buffer</em> |
| which has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The following functions enqueue commands to read a 2D or 3D rectangular |
| region from a buffer object to host memory or write a 2D or 3D rectangular |
| region to a buffer object from host memory.</p> |
| </div> |
| <div id="clEnqueueReadBufferRect" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueReadBufferRect( |
| cl_command_queue command_queue, |
| cl_mem buffer, |
| cl_bool blocking_read, |
| <span class="directive">const</span> size_t* buffer_origin, |
| <span class="directive">const</span> size_t* host_origin, |
| <span class="directive">const</span> size_t* region, |
| size_t buffer_row_pitch, |
| size_t buffer_slice_pitch, |
| size_t host_row_pitch, |
| size_t host_slice_pitch, |
| <span class="directive">void</span>* ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div id="clEnqueueWriteBufferRect" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWriteBufferRect( |
| cl_command_queue command_queue, |
| cl_mem buffer, |
| cl_bool blocking_write, |
| <span class="directive">const</span> size_t* buffer_origin, |
| <span class="directive">const</span> size_t* host_origin, |
| <span class="directive">const</span> size_t* region, |
| size_t buffer_row_pitch, |
| size_t buffer_slice_pitch, |
| size_t host_row_pitch, |
| size_t host_slice_pitch, |
| <span class="directive">const</span> <span class="directive">void</span>* ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers is a valid host command-queue in which the read / |
| write command will be queued. |
| <em>command_queue</em> and <em>buffer</em> must be created with the same OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>buffer</em> refers to a valid buffer object.</p> |
| </li> |
| <li> |
| <p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write |
| operations are <em>blocking</em> or <em>non-blocking</em> (see below).</p> |
| </li> |
| <li> |
| <p><em>buffer_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region |
| associated with <em>buffer</em>. |
| For a 2D rectangle region, the <em>z</em> value given by <em>buffer_origin</em>[2] should |
| be 0. |
| The offset in bytes is computed as <em>buffer_origin</em>[2] × |
| <em>buffer_slice_pitch</em> + <em>buffer_origin</em>[1] × <em>buffer_row_pitch</em> + |
| <em>buffer_origin</em>[0].</p> |
| </li> |
| <li> |
| <p><em>host_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region |
| pointed to by <em>ptr</em>. |
| For a 2D rectangle region, the <em>z</em> value given by <em>host_origin</em>[2] should be |
| 0. |
| The offset in bytes is computed as <em>host_origin</em>[2] × |
| <em>host_slice_pitch</em> + <em>host_origin</em>[1] × <em>host_row_pitch</em> + |
| <em>host_origin</em>[0].</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em> in bytes, <em>height</em> in rows, <em>depth</em> in slices) |
| of the 2D or 3D rectangle being read or written. |
| For a 2D rectangle copy, the <em>depth</em> value given by <em>region</em>[2] should be 1. |
| The values in region cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>buffer_row_pitch</em> is the length of each row in bytes to be used for the |
| memory region associated with <em>buffer</em>. |
| If <em>buffer_row_pitch</em> is 0, <em>buffer_row_pitch</em> is computed as <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><em>buffer_slice_pitch</em> is the length of each 2D slice in bytes to be used for |
| the memory region associated with <em>buffer</em>. |
| If <em>buffer_slice_pitch</em> is 0, <em>buffer_slice_pitch</em> is computed as |
| <em>region</em>[1] × <em>buffer_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><em>host_row_pitch</em> is the length of each row in bytes to be used for the |
| memory region pointed to by <em>ptr</em>. |
| If <em>host_row_pitch</em> is 0, <em>host_row_pitch</em> is computed as <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><em>host_slice_pitch</em> is the length of each 2D slice in bytes to be used for |
| the memory region pointed to by <em>ptr</em>. |
| If <em>host_slice_pitch</em> is 0, <em>host_slice_pitch</em> is computed as <em>region</em>[1] |
| × <em>host_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><em>ptr</em> is the pointer to buffer in host memory where data is to be read into |
| or to be written from.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this read / write command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_read</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a> i.e. the read command is blocking, |
| <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> does not return until the buffer data has been |
| read and copied into memory pointed to by <em>ptr</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_read</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. the read command is non-blocking, |
| <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> queues a non-blocking read command and returns. |
| The contents of the buffer that <em>ptr</em> points to cannot be used until the |
| read command has completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the read command. |
| When the read command has completed, the contents of the buffer that <em>ptr</em> |
| points to can be used by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_write</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the write command is blocking and does not |
| return until the command is complete, including transfer of the data. |
| The memory pointed to by <em>ptr</em> can be reused by the application after the |
| <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> call returns.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_write</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>, the OpenCL implementation will use <em>ptr</em> to |
| perform a non-blocking write. |
| As the write is non-blocking the implementation can return immediately. |
| The memory pointed to by <em>ptr</em> cannot be reused by the application after the |
| call returns. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the write command. |
| When the write command has completed, the memory pointed to by <em>ptr</em> can |
| then be reused by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> and <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> |
| if the function is executed successfully. |
| Otherwise, they return one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| <em>buffer</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>buffer_origin</em>, <em>host_origin</em>, or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the region being read or written specified by |
| (<em>buffer_origin</em>, <em>region</em>, <em>buffer_row_pitch</em>, <em>buffer_slice_pitch</em>) is |
| out of bounds.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if any <em>region</em> array element is 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>buffer_row_pitch</em> is not 0 and is less than |
| <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>host_row_pitch</em> is not 0 and is less than |
| <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>buffer_slice_pitch</em> is not 0 and is less than |
| <em>region</em>[1] × <em>buffer_row_pitch</em> and not a multiple of |
| <em>buffer_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>host_slice_pitch</em> is not 0 and is less than |
| <em>region</em>[1] × <em>host_row_pitch</em> and not a multiple of |
| <em>host_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>ptr</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and |
| <em>offset</em> specified when the sub-buffer object is created is not aligned |
| to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated with |
| <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the read and write |
| operations are blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> is called on <em>buffer</em> |
| which has been created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> or |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> is called on <em>buffer</em> |
| which has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Calling <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> to read a region of the buffer object with the |
| <em>ptr</em> argument value set to <em>host_ptr</em> + <em>offset</em>, where <em>host_ptr</em> is a |
| pointer to the memory region specified when the buffer object being read is |
| created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, must meet the following requirements in |
| order to avoid undefined behavior:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All commands that use this buffer object or a memory object (buffer or |
| image) created from this buffer object have finished execution before |
| the read command begins execution.</p> |
| </li> |
| <li> |
| <p>The buffer object or memory objects created from this buffer object are |
| not mapped.</p> |
| </li> |
| <li> |
| <p>The buffer object or memory objects created from this buffer object are |
| not used by any command-queue until the read command has finished |
| execution.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Calling <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> to read a region of the buffer object with |
| the <em>ptr</em> argument value set to <em>host_ptr</em> and <em>host_origin</em>, |
| <em>buffer_origin</em> values are the same, where <em>host_ptr</em> is a pointer to the |
| memory region specified when the buffer object being read is created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, must meet the same requirements given above for |
| <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Calling <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> to update the latest bits in a region of the |
| buffer object with the <em>ptr</em> argument value set to <em>host_ptr</em> + <em>offset</em>, |
| where <em>host_ptr</em> is a pointer to the memory region specified when the buffer |
| object being written is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, must meet the |
| following requirements in order to avoid undefined behavior:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The host memory region given by (<em>host_ptr</em> + <em>offset</em>, <em>cb</em>) contains |
| the latest bits when the enqueued write command begins execution.</p> |
| </li> |
| <li> |
| <p>The buffer object or memory objects created from this buffer object are |
| not mapped.</p> |
| </li> |
| <li> |
| <p>The buffer object or memory objects created from this buffer object are |
| not used by any command-queue until the write command has finished |
| execution.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Calling <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> to update the latest bits in a region of |
| the buffer object with the <em>ptr</em> argument value set to <em>host_ptr</em> and |
| <em>host_origin</em>, <em>buffer_origin</em> values are the same, where <em>host_ptr</em> is a |
| pointer to the memory region specified when the buffer object being written |
| is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, must meet the following requirements in |
| order to avoid undefined behavior:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The host memory region given by (<em>buffer_origin region</em>) contains the |
| latest bits when the enqueued write command begins execution.</p> |
| </li> |
| <li> |
| <p>The buffer object or memory objects created from this buffer object are |
| not mapped.</p> |
| </li> |
| <li> |
| <p>The buffer object or memory objects created from this buffer object are |
| not used by any command-queue until the write command has finished |
| execution.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to copy a buffer object identified by <em>src_buffer</em> to |
| another buffer object identified by <em>dst_buffer</em>, call the function</p> |
| </div> |
| <div id="clEnqueueCopyBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyBuffer( |
| cl_command_queue command_queue, |
| cl_mem src_buffer, |
| cl_mem dst_buffer, |
| size_t src_offset, |
| size_t dst_offset, |
| size_t size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to a host command-queue in which the copy command |
| will be queued. |
| The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and |
| <em>dst_buffer</em> must be the same.</p> |
| </li> |
| <li> |
| <p><em>src_offset</em> refers to the offset where to begin copying data from |
| <em>src_buffer</em>.</p> |
| </li> |
| <li> |
| <p><em>dst_offset</em> refers to the offset where to begin copying data into |
| <em>dst_buffer</em>.</p> |
| </li> |
| <li> |
| <p><em>size</em> refers to the size in bytes to copy.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this copy command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueCopyBuffer"><strong>clEnqueueCopyBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em>, |
| <em>src_buffer</em> and <em>dst_buffer</em> are not the same or if the context |
| associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not |
| the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are not valid |
| buffer objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_offset</em>, <em>dst_offset</em>, <em>size</em>, <em>src_offset</em> |
| + <em>size</em> or <em>dst_offset</em> + <em>size</em> require accessing elements |
| outside the <em>src_buffer</em> and <em>dst_buffer</em> buffer objects respectively.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>src_buffer</em> is a sub-buffer object |
| and <em>offset</em> specified when the sub-buffer object is created is not |
| aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated |
| with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>dst_buffer</em> is a sub-buffer object |
| and <em>offset</em> specified when the sub-buffer object is created is not |
| aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated |
| with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_MEM_<wbr>COPY_<wbr>OVERLAP</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer |
| or sub-buffer object and the source and destination regions overlap or |
| if <em>src_buffer</em> and <em>dst_buffer</em> are different sub-buffers of the same |
| associated buffer object and they overlap. |
| The regions overlap if <em>src_offset</em> ≤ <em>dst_offset</em> ≤ |
| <em>src_offset</em> + <em>size</em> - 1 or if <em>dst_offset</em> ≤ <em>src_offset</em> ≤ |
| <em>dst_offset</em> + <em>size</em> - 1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>src_buffer</em> or <em>dst_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to copy a 2D or 3D rectangular region from the buffer |
| object identified by <em>src_buffer</em> to a 2D or 3D region in the buffer object |
| identified by <em>dst_buffer</em>, call the function</p> |
| </div> |
| <div id="clEnqueueCopyBufferRect" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyBufferRect( |
| cl_command_queue command_queue, |
| cl_mem src_buffer, |
| cl_mem dst_buffer, |
| <span class="directive">const</span> size_t* src_origin, |
| <span class="directive">const</span> size_t* dst_origin, |
| <span class="directive">const</span> size_t* region, |
| size_t src_row_pitch, |
| size_t src_slice_pitch, |
| size_t dst_row_pitch, |
| size_t dst_slice_pitch, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueCopyBufferRect"><strong>clEnqueueCopyBufferRect</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the copy command |
| will be queued. |
| The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and |
| <em>dst_buffer</em> must be the same.</p> |
| </li> |
| <li> |
| <p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region |
| associated with <em>src_buffer</em>. |
| For a 2D rectangle region, the <em>z</em> value given by <em>src_origin</em>[2] should be |
| 0. |
| The offset in bytes is computed as <em>src_origin</em>[2] × <em>src_slice_pitch</em> |
| + <em>src_origin</em>[1] × <em>src_row_pitch</em> + <em>src_origin</em>[0].</p> |
| </li> |
| <li> |
| <p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region |
| associated with <em>dst_buffer</em>. |
| For a 2D rectangle region, the <em>z</em> value given by <em>dst_origin</em>[2] should be |
| 0. |
| The offset in bytes is computed as <em>dst_origin</em>[2] × <em>dst_slice_pitch</em> |
| + <em>dst_origin</em>[1] × <em>dst_row_pitch</em> + <em>dst_origin</em>[0].</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em> in bytes, <em>height</em> in rows, <em>depth</em> in slices) |
| of the 2D or 3D rectangle being copied. |
| For a 2D rectangle, the <em>depth</em> value given by <em>region</em>[2] should be 1. |
| The values in region cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>src_row_pitch</em> is the length of each row in bytes to be used for the memory |
| region associated with <em>src_buffer</em>. |
| If <em>src_row_pitch</em> is 0, <em>src_row_pitch</em> is computed as <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><em>src_slice_pitch</em> is the length of each 2D slice in bytes to be used for the |
| memory region associated with <em>src_buffer</em>. |
| If <em>src_slice_pitch</em> is 0, <em>src_slice_pitch</em> is computed as <em>region</em>[1] |
| × <em>src_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><em>dst_row_pitch</em> is the length of each row in bytes to be used for the memory |
| region associated with <em>dst_buffer</em>. |
| If <em>dst_row_pitch</em> is 0, <em>dst_row_pitch</em> is computed as <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><em>dst_slice_pitch</em> is the length of each 2D slice in bytes to be used for the |
| memory region associated with <em>dst_buffer</em>. |
| If <em>dst_slice_pitch</em> is 0, <em>dst_slice_pitch</em> is computed as <em>region</em>[1] |
| × <em>dst_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this copy command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Copying begins at the source offset and destination offset which are |
| computed as described below in the description for <em>src_origin</em> and |
| <em>dst_origin</em>. |
| Each byte of the region’s width is copied from the source offset to the |
| destination offset. |
| After copying each width, the source and destination offsets are incremented |
| by their respective source and destination row pitches. |
| After copying each 2D rectangle, the source and destination offsets are |
| incremented by their respective source and destination slice pitches.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>If <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer object, <em>src_row_pitch</em> |
| must equal <em>dst_row_pitch</em> and <em>src_slice_pitch</em> must equal |
| <em>dst_slice_pitch</em>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueCopyBufferRect"><strong>clEnqueueCopyBufferRect</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em>, |
| <em>src_buffer</em> and <em>dst_buffer</em> are not the same or if the context |
| associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not |
| the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are not valid |
| buffer objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_origin</em>, <em>dst_origin</em>, or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if (<em>src_origin</em>, <em>region</em>, <em>src_row_pitch</em>, |
| <em>src_slice_pitch</em>) or (<em>dst_origin</em>, <em>region</em>, <em>dst_row_pitch</em>, |
| <em>dst_slice_pitch</em>) require accessing elements outside the <em>src_buffer</em> |
| and <em>dst_buffer</em> buffer objects respectively.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if any <em>region</em> array element is 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_row_pitch</em> is not 0 and is less than |
| <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>dst_row_pitch</em> is not 0 and is less than |
| <em>region</em>[0].</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_slice_pitch</em> is not 0 and is less than |
| <em>region</em>[1] × <em>src_row_pitch</em> or if <em>src_slice_pitch</em> is not 0 and |
| is not a multiple of <em>src_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>dst_slice_pitch</em> is not 0 and is less than |
| <em>region</em>[1] × <em>dst_row_pitch</em> or if <em>dst_slice_pitch</em> is not 0 and |
| is not a multiple of <em>dst_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer |
| object and <em>src_slice_pitch</em> is not equal to <em>dst_slice_pitch</em> and |
| <em>src_row_pitch</em> is not equal to <em>dst_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_MEM_<wbr>COPY_<wbr>OVERLAP</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer |
| or sub-buffer object and the source and destination regions overlap or |
| if <em>src_buffer</em> and <em>dst_buffer</em> are different sub-buffers of the same |
| associated buffer object and they overlap. |
| Refer to <a href="#check-copy-overlap">Checking for Memory Copy Overlap</a> for |
| details on how to determine if source and destination regions overlap.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>src_buffer</em> is a sub-buffer object |
| and <em>offset</em> specified when the sub-buffer object is created is not |
| aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated |
| with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>dst_buffer</em> is a sub-buffer object |
| and <em>offset</em> specified when the sub-buffer object is created is not |
| aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated |
| with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>src_buffer</em> or <em>dst_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filling_buffer_objects"><a class="anchor" href="#_filling_buffer_objects"></a>5.2.3. Filling Buffer Objects</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Filling buffer objects is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to fill a buffer object with a pattern of a given |
| pattern size, call the function</p> |
| </div> |
| <div id="clEnqueueFillBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueFillBuffer( |
| cl_command_queue command_queue, |
| cl_mem buffer, |
| <span class="directive">const</span> <span class="directive">void</span>* pattern, |
| size_t pattern_size, |
| size_t offset, |
| size_t size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the fill command |
| will be queued. |
| The OpenCL context associated with <em>command_queue</em> and <em>buffer</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>buffer</em> is a valid buffer object.</p> |
| </li> |
| <li> |
| <p><em>pattern</em> is a pointer to the data pattern of size <em>pattern_size</em> in bytes. |
| <em>pattern</em> will be used to fill a region in <em>buffer</em> starting at <em>offset</em> and |
| is <em>size</em> bytes in size. |
| The data pattern must be a scalar or vector integer or floating-point data |
| type supported by OpenCL as described in <a href="#scalar-data-types">Shared |
| Application Scalar Data Types</a> and <a href="#vector-data-types">Supported |
| Application Vector Data Types</a>. |
| For example, if <em>buffer</em> is to be filled with a pattern of <code>float4</code> values, |
| then <em>pattern</em> will be a pointer to a <code>cl_float4</code> value and <em>pattern_size</em> |
| will be <code>sizeof(cl_float4)</code>. |
| The maximum value of <em>pattern_size</em> is the size of the largest integer or |
| floating-point vector data type supported by the OpenCL device. |
| The memory associated with <em>pattern</em> can be reused or freed after the |
| function returns.</p> |
| </li> |
| <li> |
| <p><em>offset</em> is the location in bytes of the region being filled in <em>buffer</em> and |
| must be a multiple of <em>pattern_size</em>.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of region being filled in <em>buffer</em> and must be a |
| multiple of <em>pattern_size</em>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The usage information which indicates whether the memory object can be read |
| or written by a kernel and/or the host and is given by the <code>cl_mem_<wbr>flags</code> |
| argument value specified when <em>buffer</em> is created is ignored by |
| <a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| <em>buffer</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>offset</em> or <em>offset</em> + <em>size</em> require accessing |
| elements outside the <em>buffer</em> buffer object respectively.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pattern</em> is <code>NULL</code> or if <em>pattern_size</em> is 0 or if |
| <em>pattern_size</em> is not one of { 1, 2, 4, 8, 16, 32, 64, 128 }.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>offset</em> and <em>size</em> are not a multiple of |
| <em>pattern_size</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and |
| offset specified when the sub-buffer object is created is not aligned to |
| <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_mapping_buffer_objects"><a class="anchor" href="#_mapping_buffer_objects"></a>5.2.4. Mapping Buffer Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to map a region of the buffer object given by <em>buffer</em> |
| into the host address space and returns a pointer to this mapped region, |
| call the function</p> |
| </div> |
| <div id="clEnqueueMapBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span>* clEnqueueMapBuffer( |
| cl_command_queue command_queue, |
| cl_mem buffer, |
| cl_bool blocking_map, |
| cl_map_flags map_flags, |
| size_t offset, |
| size_t size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>blocking_map</em> indicates if the map operation is <em>blocking</em> or |
| <em>non-blocking</em>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_map</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> does not return until the |
| specified region in <em>buffer</em> is mapped into the host address space and the |
| application can access the contents of the mapped region using the pointer |
| returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_map</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. map operation is non-blocking, the |
| pointer to the mapped region returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> cannot be used |
| until the map command has completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the map command. |
| When the map command is completed, the application can access the contents |
| of the mapped region using the pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>map_flags</em> is a bit-field and is described in the |
| <a href="#memory-map-flags-table">Memory Map Flags</a> table.</p> |
| </li> |
| <li> |
| <p><em>buffer</em> is a valid buffer object. |
| The OpenCL context associated with <em>command_queue</em> and <em>buffer</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>offset</em> and <em>size</em> are the offset in bytes and the size of the region in |
| the buffer object that is being mapped.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> will return a pointer to the mapped region. |
| The <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>NULL</code> pointer is returned otherwise with one of the following error |
| values returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and |
| <em>buffer</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if region being mapped given by (<em>offset</em>, <em>size</em>) is |
| out of bounds or if <em>size</em> is 0 or if values specified in <em>map_flags</em> |
| are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and |
| <em>offset</em> specified when the sub-buffer object is created is not aligned |
| to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for the device associated with |
| <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MAP_FAILURE"><code>CL_MAP_<wbr>FAILURE</code></a> if there is a failure to map the requested region into |
| the host address space. |
| This error cannot occur for buffer objects created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the map operation is |
| blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>buffer</em> has been created with |
| <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> and <a href="#CL_MAP_READ"><code>CL_MAP_<wbr>READ</code></a> is set |
| in <em>map_flags</em> or if <em>buffer</em> has been created with |
| <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> and <a href="#CL_MAP_WRITE"><code>CL_MAP_<wbr>WRITE</code></a> or |
| <a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_MAP_<wbr>WRITE_<wbr>INVALIDATE_<wbr>REGION</code></a> is set in <em>map_flags</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if mapping would lead to overlapping regions being |
| mapped for writing.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The pointer returned maps a region starting at <em>offset</em> and is at least |
| <em>size</em> bytes in size. |
| The result of a memory access outside this region is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the buffer object is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> set in <em>mem_flags</em>, |
| the following will be true:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <em>host_ptr</em> specified in <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> |
| will contain the latest bits in the region being mapped when the |
| <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> command has completed.</p> |
| </li> |
| <li> |
| <p>The pointer value returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> will be derived from |
| the <em>host_ptr</em> specified when the buffer object is created.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Mapped buffer objects are unmapped using <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>. |
| This is described in <a href="#unmapping-mapped-memory">Unmapping Mapped Memory |
| Objects</a>.</p> |
| </div> |
| <table id="memory-map-flags-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 14. List of supported map flag values</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Map Flags</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_READ"></a><a href="#CL_MAP_READ"><code>CL_MAP_<wbr>READ</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the region being mapped in the memory object is |
| being mapped for reading.</p> |
| <p class="tableblock"> The pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) is |
| guaranteed to contain the latest bits in the region being mapped when |
| the <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) command has completed.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_WRITE"></a><a href="#CL_MAP_WRITE"><code>CL_MAP_<wbr>WRITE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the region being mapped in the memory object is |
| being mapped for writing.</p> |
| <p class="tableblock"> The pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) is |
| guaranteed to contain the latest bits in the region being mapped when |
| the <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) command has completed</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_WRITE_INVALIDATE_REGION"></a><a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_MAP_<wbr>WRITE_<wbr>INVALIDATE_<wbr>REGION</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the region being mapped in the memory object is |
| being mapped for writing.</p> |
| <p class="tableblock"> The contents of the region being mapped are to be discarded. |
| This is typically the case when the region being mapped is overwritten |
| by the host. |
| This flag allows the implementation to no longer guarantee that the |
| pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) contains |
| the latest bits in the region being mapped which can be a significant |
| performance enhancement.</p> |
| <p class="tableblock"> <a href="#CL_MAP_READ"><code>CL_MAP_<wbr>READ</code></a> or <a href="#CL_MAP_WRITE"><code>CL_MAP_<wbr>WRITE</code></a> and <a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_MAP_<wbr>WRITE_<wbr>INVALIDATE_<wbr>REGION</code></a> are |
| mutually exclusive.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_image_objects"><a class="anchor" href="#_image_objects"></a>5.3. Image Objects</h3> |
| <div class="paragraph"> |
| <p>An <em>image</em> object is used to store a one-, two- or three-dimensional |
| texture, frame-buffer or image. |
| The elements of an image object are selected from a list of predefined image |
| formats. |
| The minimum number of elements in a memory object is one.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_image_objects"><a class="anchor" href="#_creating_image_objects"></a>5.3.1. Creating Image Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>An <strong>image object</strong> may be created using the function</p> |
| </div> |
| <div id="clCreateImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateImage( |
| cl_context context, |
| cl_mem_flags flags, |
| <span class="directive">const</span> cl_image_format* image_format, |
| <span class="directive">const</span> cl_image_desc* image_desc, |
| <span class="directive">void</span>* host_ptr, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>An <strong>image object</strong> may also be created with additional properties using the function</p> |
| </div> |
| <div id="clCreateImageWithProperties" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateImageWithProperties( |
| cl_context context, |
| <span class="directive">const</span> cl_mem_properties* properties, |
| cl_mem_flags flags, |
| <span class="directive">const</span> cl_image_format* image_format, |
| <span class="directive">const</span> cl_image_desc* image_desc, |
| <span class="directive">void</span>* host_ptr, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> is <a href="#unified-spec">missing before</a> version 3.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context used to create the image object.</p> |
| </li> |
| <li> |
| <p><em>properties</em> is an optional list of properties for the image object and their corresponding values. |
| The list is terminated with the special property <code>0</code>. |
| If no properties are required, <em>properties</em> may be <code>NULL</code>. |
| OpenCL 3.0 does not define any optional properties for images.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information about the image memory object being created and is described in |
| the <a href="#memory-flags-table">supported memory flag values</a> table.</p> |
| </li> |
| <li> |
| <p><em>image_format</em> is a pointer to a structure that describes format properties |
| of the image to be allocated. |
| A 1D image buffer or 2D image can be created from a buffer by specifying a |
| buffer object in the <em>image_desc</em>→<em>mem_object</em>. |
| A 2D image can be created from another 2D image object by specifying an |
| image object in the <em>image_desc</em>→<em>mem_object</em>. |
| Refer to the <a href="#image-format-descriptor">Image Format Descriptor</a> section |
| for a detailed description of the image format descriptor.</p> |
| </li> |
| <li> |
| <p><em>image_desc</em> is a pointer to a structure that describes type and dimensions |
| of the image to be allocated. |
| Refer to the <a href="#image-descriptor">Image Descriptor</a> section for a detailed |
| description of the image descriptor.</p> |
| </li> |
| <li> |
| <p><em>host_ptr</em> is a pointer to the image data that may already be allocated by |
| the application. |
| Refer to the <a href="#host-ptr-buffer-size-table">table below</a> for a description |
| of how large the buffer that <em>host_ptr</em> points to must be.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The alignment requirements for data stored in image objects are described |
| in <a href="#alignment-app-data-types">Alignment of Application Data Types</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For all image types except <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>BUFFER</code></a>, if the value |
| specified for <em>flags</em> is 0, the default is used which is <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>BUFFER</code></a> image type, or an image created from |
| another memory object (image or buffer), if the <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>, |
| <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> values are not specified in <em>flags</em>, |
| they are inherited from the corresponding memory access qualifiers associated |
| with <em>mem_object</em>. |
| The <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a> and <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> |
| values cannot be specified in <em>flags</em> but are inherited from the |
| corresponding memory access qualifiers associated with <em>mem_object</em>. |
| If <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> is specified in the memory access qualifier values |
| associated with <em>mem_object</em> it does not imply any additional copies when |
| the image is created from <em>mem_object</em>. |
| If the <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a>, <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> values are not specified in <em>flags</em>, they are |
| inherited from the corresponding memory access qualifiers associated with |
| <em>mem_object</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a 3D image or 2D image array, the image data specified by <em>host_ptr</em> is |
| stored as a linear sequence of adjacent 2D image slices or 2D images |
| respectively. |
| Each 2D image is a linear sequence of adjacent scanlines. |
| Each scanline is a linear sequence of image elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a 2D image, the image data specified by <em>host_ptr</em> is stored as a linear |
| sequence of adjacent scanlines. |
| Each scanline is a linear sequence of image elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a 1D image array, the image data specified by <em>host_ptr</em> is stored as a |
| linear sequence of adjacent 1D images. |
| Each 1D image is stored as a single scanline which is a linear sequence of |
| adjacent elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For 1D image or 1D image buffer, the image data specified by <em>host_ptr</em> is |
| stored as a single scanline which is a linear sequence of adjacent elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Image elements are stored according to their image format as described in the |
| <a href="#image-format-descriptor">Image Format Descriptor</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateImage"><strong>clCreateImage</strong></a> and <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> returns a valid non-zero |
| image object and <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the image object |
| is created successfully. |
| Otherwise, they return a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROPERTY"><code>CL_INVALID_<wbr>PROPERTY</code></a> if a property name in <em>properties</em> is not a |
| supported property name, if the value specified for a supported property |
| name is not valid, or if the same property name is specified more than |
| once.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>flags</em> are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>FORMAT_<wbr>DESCRIPTOR</code></a> if values specified in <em>image_format</em> |
| are not valid or if <em>image_format</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>FORMAT_<wbr>DESCRIPTOR</code></a> if a 2D image is created from a |
| buffer and the row pitch and base address alignment does not follow the |
| rules described for creating a 2D image from a buffer.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>FORMAT_<wbr>DESCRIPTOR</code></a> if a 2D image is created from a 2D |
| image object and the rules described above are not followed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>DESCRIPTOR</code></a> if values specified in <em>image_desc</em> are not |
| valid or if <em>image_desc</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions specified in <em>image_desc</em> |
| exceed the maximum image dimensions described in the |
| <a href="#device-queries-table">Device Queries</a> table for all devices |
| in <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_HOST_PTR"><code>CL_INVALID_<wbr>HOST_<wbr>PTR</code></a> if <em>host_ptr</em> is <code>NULL</code> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or |
| <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> |
| but <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> are not set in <em>flags</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if an image is being created from another memory object |
| (buffer or image) under one of the following circumstances: 1) |
| <em>mem_object</em> was created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> and <em>flags</em> specifies |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> or <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a>, 2) <em>mem_object</em> was created with |
| <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> and <em>flags</em> specifies <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> or |
| <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a>, 3) <em>flags</em> specifies <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or |
| <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if an image is being created from another memory object |
| (buffer or image) and <em>mem_object</em> was created with |
| <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> and <em>flags</em> specifies <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a>, or |
| if <em>mem_object</em> was created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> and <em>flags</em> |
| specifies <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a>, or if <em>mem_object</em> was created with |
| <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> and_flags_ specifies <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or |
| <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if there are no devices in <em>context</em> that |
| support <em>image_format</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if there are no devices in <em>context</em> that support |
| images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="host-ptr-buffer-size-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 15. Required <em>host_ptr</em> buffer sizes for images</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Image Type</th> |
| <th class="tableblock halign-left valign-top">Size of buffer that <em>host_ptr</em> points to</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE1D"></a><a href="#CL_MEM_OBJECT_IMAGE1D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_row_pitch</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE1D_BUFFER"></a><a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>BUFFER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_row_pitch</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE2D"></a><a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_row_pitch × image_height</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE3D"></a><a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE3D</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_slice_pitch × image_depth</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE1D_ARRAY"></a><a href="#CL_MEM_OBJECT_IMAGE1D_ARRAY"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>ARRAY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_slice_pitch × image_array_size</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE2D_ARRAY"></a><a href="#CL_MEM_OBJECT_IMAGE2D_ARRAY"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D_<wbr>ARRAY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_slice_pitch × image_array_size</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>A <strong>2D image</strong> object can be created using the following function</p> |
| </div> |
| <div id="clCreateImage2D" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateImage2D( |
| cl_context context, |
| cl_mem_flags flags, |
| <span class="directive">const</span> cl_image_format* image_format, |
| size_t image_width, |
| size_t image_height, |
| size_t image_row_pitch, |
| <span class="directive">void</span>* host_ptr, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context on which the image object is to be |
| created.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information about the image memory object being created and is described in |
| the <a href="#memory-flags-table">supported memory flag values</a> table. |
| If the value specified for <em>flags</em> is 0, the default is used which is |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>.</p> |
| </li> |
| <li> |
| <p><em>image_format</em> is a pointer to a structure that describes format properties |
| of the image to be allocated. |
| Refer to the <a href="#image-format-descriptor">Image Format Descriptor</a> section |
| for a detailed description of the image format descriptor.</p> |
| </li> |
| <li> |
| <p><em>image_width</em> and <em>image_height</em> are the width and height of the image in |
| pixels. |
| These must be values greater than or equal to 1.</p> |
| </li> |
| <li> |
| <p><em>image_row_pitch</em> is the scan-line pitch in bytes. |
| This must be 0 if <em>host_ptr</em> is <code>NULL</code> and can be either 0 or ≥ |
| <em>image_width</em> × size of element in bytes if <em>host_ptr</em> is not <code>NULL</code>. |
| If <em>host_ptr</em> is not <code>NULL</code> and <em>image_row_pitch</em> is 0, <em>image_row_pitch</em> |
| is calculated as <em>image_width</em> × size of element in bytes. |
| If <em>image_row_pitch</em> is not 0, it must be a multiple of the image element |
| size in bytes.</p> |
| </li> |
| <li> |
| <p><em>host_ptr</em> is a pointer to the image data that may already be allocated by |
| the application. |
| Refer to the <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a> entry in the |
| <a href="#host-ptr-buffer-size-table">required <em>host_ptr</em> buffer size table</a> for a |
| description of how large the buffer that <em>host_ptr</em> points to must be. |
| The image data specified by <em>host_ptr</em> is stored as a linear sequence of |
| adjacent scanlines. |
| Each scanline is a linear sequence of image elements. |
| Image elements are stored according to their image format as described in |
| the <a href="#image-format-descriptor">Image Format Descriptor</a> section.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a> returns a valid non-zero image object created and the |
| <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the image object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>flags</em> are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>FORMAT_<wbr>DESCRIPTOR</code></a> if values specified in <em>image_format</em> |
| are not valid or if <em>image_format</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if <em>image_width</em> or <em>image_height</em> are 0 or if they |
| exceed the maximum values specified in <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a> or |
| <a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>HEIGHT</code></a> respectively for all devices in <em>context</em> or |
| if values specified by <em>image_row_pitch</em> do not follow rules described in the |
| argument description above.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_HOST_PTR"><code>CL_INVALID_<wbr>HOST_<wbr>PTR</code></a> if <em>host_ptr</em> is <code>NULL</code> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or |
| <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> |
| but <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> are not set in <em>flags</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if there are no devices in <em>context</em> that |
| support <em>image_format</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if there are no devices in <em>context</em> that support |
| images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>A <strong>3D image</strong> object can be created using the following function</p> |
| </div> |
| <div id="clCreateImage3D" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateImage3D( |
| cl_context context, |
| cl_mem_flags flags, |
| <span class="directive">const</span> cl_image_format* image_format, |
| size_t image_width, |
| size_t image_height, |
| size_t image_depth, |
| size_t image_row_pitch, |
| size_t image_slice_pitch, |
| <span class="directive">void</span>* host_ptr, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context on which the image object is to be |
| created.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information about the image memory object being created and is described in |
| the <a href="#memory-flags-table">supported memory flag values</a> table. |
| If the value specified for <em>flags</em> is 0, the default is used which is |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>.</p> |
| </li> |
| <li> |
| <p><em>image_format</em> is a pointer to a structure that describes format properties |
| of the image to be allocated. |
| Refer to the <a href="#image-format-descriptor">Image Format Descriptor</a> section |
| for a detailed description of the image format descriptor.</p> |
| </li> |
| <li> |
| <p><em>image_width</em> and <em>image_height</em> are the width and height of the image in |
| pixels. |
| These must be values greater than or equal to 1.</p> |
| </li> |
| <li> |
| <p><em>image_depth</em> is the depth of the image in pixels. For <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>, |
| this must be a value > 1.</p> |
| </li> |
| <li> |
| <p><em>image_row_pitch</em> is the scan-line pitch in bytes. |
| This must be 0 if <em>host_ptr</em> is <code>NULL</code> and can be either 0 or ≥ |
| <em>image_width</em> × size of element in bytes if <em>host_ptr</em> is not <code>NULL</code>. |
| If <em>host_ptr</em> is not <code>NULL</code> and <em>image_row_pitch</em> is 0, <em>image_row_pitch</em> |
| is calculated as <em>image_width</em> × size of element in bytes. |
| If <em>image_row_pitch</em> is not 0, it must be a multiple of the image element |
| size in bytes.</p> |
| </li> |
| <li> |
| <p><em>image_slice_pitch</em> is the size in bytes of each 2D slice in the 3D image. |
| This be be 0 if <em>host_ptr</em> is <code>NULL</code> and can be 0 or ≥ |
| <em>image_row_pitch</em> × <em>image_height</em> if <em>host_ptr</em> is not <code>NULL</code>. |
| If <em>host_ptr</em> is not <code>NULL</code> and <em>image_slice_pitch</em> is 0, |
| <em>image_slice_pitch</em> is calculated as <em>image_row_pitch</em> × |
| <em>image_height</em>. |
| If <em>image_slice_pitch</em> is not 0, it must be a multiple of the |
| <em>image_row_pitch</em>.</p> |
| </li> |
| <li> |
| <p><em>host_ptr</em> is a pointer to the image data that may already be allocated by |
| the application. |
| Refer to the <a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE3D</code></a> entry in the |
| <a href="#host-ptr-buffer-size-table">required <em>host_ptr</em> buffer size table</a> for a |
| description of how large the buffer that <em>host_ptr</em> points to must be. |
| The image data specified by <em>host_ptr</em> is stored as a linear sequence of |
| adjacent 2D slices. |
| Each scanline is a linear sequence of image elements. |
| Image elements are stored according to their image format as described in |
| the <a href="#image-format-descriptor">Image Format Descriptor</a> section.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> returns a valid non-zero image object created and the |
| <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the image object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>flags</em> are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>FORMAT_<wbr>DESCRIPTOR</code></a> if values specified in <em>image_format</em> |
| are not valid or if <em>image_format</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if <em>image_width</em> or <em>image_height</em> are 0 or if |
| <em>image_depth</em> ≤ 1, or if they exceed the maximum values specified in |
| <a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a> or |
| <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a> respectively for all devices in <em>context</em>, or |
| if values specified by <em>image_row_pitch</em> and <em>image_slice_pitch</em> do not |
| follow rules described in the argument description above.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_HOST_PTR"><code>CL_INVALID_<wbr>HOST_<wbr>PTR</code></a> if <em>host_ptr</em> is <code>NULL</code> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or |
| <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> |
| but <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_MEM_<wbr>COPY_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> are not set in <em>flags</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if there are no devices in <em>context</em> that |
| support <em>image_format</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if there are no devices in <em>context</em> that support |
| images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="image-format-descriptor"><a class="anchor" href="#image-format-descriptor"></a>5.3.1.1. Image Format Descriptor</h5> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The <a href="#cl_image_format"><code>cl_image_<wbr>format</code></a> image format descriptor structure describes an image |
| format, and is defined as:</p> |
| </div> |
| <div id="cl_image_format" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_image_format { |
| cl_channel_order image_channel_order; |
| cl_channel_type image_channel_data_type; |
| } cl_image_format;</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>image_channel_order</code> specifies the number of channels and the channel |
| layout i.e. the memory layout in which channels are stored in the image. |
| Valid values are described in the <a href="#image-channel-order-table">Image Channel |
| Order</a> table.</p> |
| </li> |
| <li> |
| <p><code>image_channel_data_type</code> describes the size of the channel data type. |
| The list of supported values is described in the |
| <a href="#image-channel-data-types-table">Image Channel Data Types</a> table. |
| The number of bits per element determined by the <code>image_channel_data_type</code> |
| and <code>image_channel_order</code> must be a power of two.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="image-channel-order-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 16. List of supported Image Channel Order Values</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Image Channel Order</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_R"></a><a href="#CL_R"><code>CL_R</code></a>, <a id="CL_A"></a><a href="#CL_A"><code>CL_A</code></a>,</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Single channel image formats where the single channel represents a <code>RED</code> or <code>ALPHA</code> component.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEPTH"></a><a href="#CL_DEPTH"><code>CL_DEPTH</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A single channel image format where the single channel represents a <code>DEPTH</code> component.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_LUMINANCE"></a><a href="#CL_LUMINANCE"><code>CL_LUMINANCE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A single channel image format where the single channel represents a <code>LUMINANCE</code> value. |
| The <code>LUMINANCE</code> value is replicated into the <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INTENSITY"></a><a href="#CL_INTENSITY"><code>CL_INTENSITY</code></a>,</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A single channel image format where the single channel represents an <code>INTENSITY</code> value. |
| The <code>INTENSITY</code> value is replicated into the <code>RED</code>, <code>GREEN</code>, <code>BLUE</code>, and <code>ALPHA</code> components.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RG"></a><a href="#CL_RG"><code>CL_RG</code></a>, <a id="CL_RA"></a><a href="#CL_RA"><code>CL_RA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Two channel image formats. |
| The first channel always represents a <code>RED</code> component. |
| The second channel represents a <code>GREEN</code> component or an <code>ALPHA</code> component.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_Rx"></a><a href="#CL_Rx"><code>CL_Rx</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A two channel image format, where the first channel represents a <code>RED</code> component and the second channel is ignored.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGB"></a><a href="#CL_RGB"><code>CL_RGB</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A three channel image format, where the three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGx"></a><a href="#CL_RGx"><code>CL_RGx</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A three channel image format, where the first two channels represent <code>RED</code> and <code>GREEN</code> components and the third channel is ignored.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGBA"></a><a href="#CL_RGBA"><code>CL_RGBA</code></a>, <a id="CL_ARGB"></a><a href="#CL_ARGB"><code>CL_ARGB</code></a>, <a id="CL_BGRA"></a><a href="#CL_BGRA"><code>CL_BGRA</code></a>, <a id="CL_ABGR"></a><a href="#CL_ABGR"><code>CL_ABGR</code></a></p> |
| <p class="tableblock"> <a href="#CL_ABGR"><code>CL_ABGR</code></a> is <a href="#unified-spec">missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Four channel image formats, where the four channels represent <code>RED</code>, <code>GREEN</code>, <code>BLUE</code>, and <code>ALPHA</code> components.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGBx"></a><a href="#CL_RGBx"><code>CL_RGBx</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A four channel image format, where the first three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components and the fourth channel is ignored.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_sRGB"></a><a href="#CL_sRGB"><code>CL_sRGB</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A three channel image format, where the three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components in the sRGB color space.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_sRGBA"></a><a href="#CL_sRGBA"><code>CL_sRGBA</code></a>, <a id="CL_sBGRA"></a><a href="#CL_sBGRA"><code>CL_sBGRA</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Four channel image formats, where the first three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components in the sRGB color space. |
| The fourth channel represents an <code>ALPHA</code> component.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_sRGBx"></a><a href="#CL_sRGBx"><code>CL_sRGBx</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A four channel image format, where the three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components in the sRGB color space. |
| The fourth channel is ignored.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <table id="image-channel-data-types-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 17. List of supported Image Channel Data Types</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Image Channel Data Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SNORM_INT8"></a><a href="#CL_SNORM_INT8"><code>CL_SNORM_<wbr>INT8</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized signed 8-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SNORM_INT16"></a><a href="#CL_SNORM_INT16"><code>CL_SNORM_<wbr>INT16</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized signed 16-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT8"></a><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized unsigned 8-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT16"></a><a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized unsigned 16-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_SHORT_565"></a><a href="#CL_UNORM_SHORT_565"><code>CL_UNORM_<wbr>SHORT_<wbr>565</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized 5-6-5 3-channel RGB image. |
| The channel order must be <a href="#CL_RGB"><code>CL_RGB</code></a> or <a href="#CL_RGBx"><code>CL_RGBx</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_SHORT_555"></a><a href="#CL_UNORM_SHORT_555"><code>CL_UNORM_<wbr>SHORT_<wbr>555</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized x-5-5-5 4-channel xRGB image. |
| The channel order must be <a href="#CL_RGB"><code>CL_RGB</code></a> or <a href="#CL_RGBx"><code>CL_RGBx</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT_101010"></a><a href="#CL_UNORM_INT_101010"><code>CL_UNORM_<wbr>INT_<wbr>101010</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized x-10-10-10 4-channel xRGB image. |
| The channel order must be <a href="#CL_RGB"><code>CL_RGB</code></a> or <a href="#CL_RGBx"><code>CL_RGBx</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT_101010_2"></a><a href="#CL_UNORM_INT_101010_2"><code>CL_UNORM_<wbr>INT_<wbr>101010_<wbr>2</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized 10-10-10-2 four-channel RGBA image. |
| The channel order must be <a href="#CL_RGBA"><code>CL_RGBA</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SIGNED_INT8"></a><a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized signed 8-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SIGNED_INT16"></a><a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized signed 16-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SIGNED_INT32"></a><a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized signed 32-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNSIGNED_INT8"></a><a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized unsigned 8-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNSIGNED_INT16"></a><a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized unsigned 16-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNSIGNED_INT32"></a><a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized unsigned 32-bit integer value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_HALF_FLOAT"></a><a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a 16-bit half-float value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLOAT"></a><a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a single precision floating-point value</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>For example, to specify a normalized unsigned 8-bit / channel RGBA image, |
| <code>image_channel_order</code> = <a href="#CL_RGBA"><code>CL_RGBA</code></a>, and <code>image_channel_data_type</code> = |
| <a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a>. |
| The memory layout of this image format is described below:</p> |
| </div> |
| <table class="tableblock frame-all grid-all" style="width: 60%;"> |
| <colgroup> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">R</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">G</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">…​</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>with the corresponding byte offsets</p> |
| </div> |
| <table class="tableblock frame-all grid-all" style="width: 60%;"> |
| <colgroup> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">…​</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Similar, if <code>image_channel_order</code> = <a href="#CL_RGBA"><code>CL_RGBA</code></a> and <code>image_channel_data_type</code> = |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a>, the memory layout of this image format is described below:</p> |
| </div> |
| <table class="tableblock frame-all grid-all" style="width: 60%;"> |
| <colgroup> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">R</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">G</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">…​</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>with the corresponding byte offsets</p> |
| </div> |
| <table class="tableblock frame-all grid-all" style="width: 60%;"> |
| <colgroup> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 10%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">…​</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><code>image_channel_data_type</code> values of <a href="#CL_UNORM_SHORT_565"><code>CL_UNORM_<wbr>SHORT_<wbr>565</code></a>, <a href="#CL_UNORM_SHORT_555"><code>CL_UNORM_<wbr>SHORT_<wbr>555</code></a>, |
| <a href="#CL_UNORM_INT_101010"><code>CL_UNORM_<wbr>INT_<wbr>101010</code></a>, and <a href="#CL_UNORM_INT_101010_2"><code>CL_UNORM_<wbr>INT_<wbr>101010_<wbr>2</code></a> are special cases of packed |
| image formats where the channels of each element are packed into a single |
| unsigned short or unsigned int. |
| For these special packed image formats, the channels are normally packed |
| with the first channel in the most significant bits of the bitfield, and |
| successive channels occupying progressively less significant locations. |
| For <a href="#CL_UNORM_SHORT_565"><code>CL_UNORM_<wbr>SHORT_<wbr>565</code></a>, R is in bits 15:11, G is in bits 10:5 and B is in |
| bits 4:0. |
| For <a href="#CL_UNORM_SHORT_555"><code>CL_UNORM_<wbr>SHORT_<wbr>555</code></a>, bit 15 is undefined, R is in bits 14:10, G in bits |
| 9:5 and B in bits 4:0. |
| For <a href="#CL_UNORM_INT_101010"><code>CL_UNORM_<wbr>INT_<wbr>101010</code></a>, bits 31:30 are undefined, R is in bits 29:20, G in |
| bits 19:10 and B in bits 9:0. |
| For <a href="#CL_UNORM_INT_101010_2"><code>CL_UNORM_<wbr>INT_<wbr>101010_<wbr>2</code></a>, R is in bits 31:22, G in bits 21:12, B in bits |
| 11:2 and A in bits 1:0.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL implementations must maintain the minimum precision specified by the |
| number of bits in <code>image_channel_data_type</code>. |
| If the image format specified by <code>image_channel_order</code>, and |
| <code>image_channel_data_type</code> cannot be supported by the OpenCL implementation, |
| then the call to <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, |
| <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> will return a <code>NULL</code> memory object.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="image-descriptor"><a class="anchor" href="#image-descriptor"></a>5.3.1.2. Image Descriptor</h5> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The <a href="#cl_image_desc"><code>cl_image_<wbr>desc</code></a> image descriptor structure describes the image type |
| and dimensions of an image or image array when creating an image using |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a> or <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, and is defined as:</p> |
| </div> |
| <div id="cl_image_desc" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_image_desc { |
| cl_mem_object_type image_type; |
| size_t image_width; |
| size_t image_height; |
| size_t image_depth; |
| size_t image_array_size; |
| size_t image_row_pitch; |
| size_t image_slice_pitch; |
| cl_uint num_mip_levels; |
| cl_uint num_samples; |
| <span class="keyword">union</span> { |
| cl_mem buffer; |
| cl_mem mem_object; |
| }; |
| } cl_image_desc;</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>image_type</code> describes the image type and must be either |
| <a href="#CL_MEM_OBJECT_IMAGE1D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D</code></a>, <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>BUFFER</code></a>, |
| <a href="#CL_MEM_OBJECT_IMAGE1D_ARRAY"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>ARRAY</code></a>, <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a>, |
| <a href="#CL_MEM_OBJECT_IMAGE2D_ARRAY"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D_<wbr>ARRAY</code></a>, or <a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE3D</code></a>.</p> |
| </li> |
| <li> |
| <p><code>image_width</code> is the width of the image in pixels. |
| For a 2D image and image array, the image width must be a value ≥ 1 and |
| ≤ <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a>. |
| For a 3D image, the image width must be a value ≥ 1 and ≤ |
| <a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a>. |
| For a 1D image buffer, the image width must be a value ≥ 1 and ≤ |
| <a href="#CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"><code>CL_DEVICE_<wbr>IMAGE_<wbr>MAX_<wbr>BUFFER_<wbr>SIZE</code></a>. |
| For a 1D image and 1D image array, the image width must be a value ≥ 1 |
| and ≤ <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a>.</p> |
| </li> |
| <li> |
| <p><code>image_height</code> is the height of the image in pixels. |
| This is only used if the image is a 2D or 3D image, or a 2D image array. |
| For a 2D image or image array, the image height must be a value ≥ 1 and |
| ≤ <a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>HEIGHT</code></a>. |
| For a 3D image, the image height must be a value ≥ 1 and ≤ |
| <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a>.</p> |
| </li> |
| <li> |
| <p><code>image_depth</code> is the depth of the image in pixels. |
| This is only used if the image is a 3D image and must be a value ≥ 1 and |
| ≤ <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a>.</p> |
| </li> |
| <li> |
| <p><code>image_array_size</code> <sup class="footnote">[<a id="_footnoteref_17" class="footnote" href="#_footnotedef_17" title="View footnote.">17</a>]</sup> is the number of |
| images in the image array. |
| This is only used if the image is a 1D or 2D image array. |
| The values for <code>image_array_size</code>, if specified, must be a value ≥ 1 and |
| ≤ <a href="#CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"><code>CL_DEVICE_<wbr>IMAGE_<wbr>MAX_<wbr>ARRAY_<wbr>SIZE</code></a>.</p> |
| </li> |
| <li> |
| <p><code>image_row_pitch</code> is the scan-line pitch in bytes. |
| This must be 0 if <em>host_ptr</em> is <code>NULL</code> and can be either 0 or ≥ |
| <code>image_width</code> × size of element in bytes if <em>host_ptr</em> is not <code>NULL</code>. |
| If <em>host_ptr</em> is not <code>NULL</code> and <code>image_row_pitch</code> = 0, <code>image_row_pitch</code> is |
| calculated as <code>image_width</code> × size of element in bytes. |
| If <code>image_row_pitch</code> is not 0, it must be a multiple of the image element |
| size in bytes. |
| For a 2D image created from a buffer, the pitch specified (or computed if |
| pitch specified is 0) must be a multiple of the maximum of the |
| <a href="#CL_DEVICE_IMAGE_PITCH_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>PITCH_<wbr>ALIGNMENT</code></a> value for all devices in the context |
| associated with the buffer specified by <code>mem_object</code> that support images.</p> |
| </li> |
| <li> |
| <p><code>image_slice_pitch</code> is the size in bytes of each 2D slice in the 3D image or |
| the size in bytes of each image in a 1D or 2D image array. |
| This must be 0 if <em>host_ptr</em> is <code>NULL</code>. |
| If <em>host_ptr</em> is not <code>NULL</code>, <code>image_slice_pitch</code> can be either 0 or ≥ |
| <code>image_row_pitch</code> × <code>image_height</code> for a 2D image array or 3D image |
| and can be either 0 or ≥ <code>image_row_pitch</code> for a 1D image array. |
| If <em>host_ptr</em> is not <code>NULL</code> and <code>image_slice_pitch</code> = 0, <code>image_slice_pitch</code> |
| is calculated as <code>image_row_pitch</code> × <code>image_height</code> for a 2D image |
| array or 3D image and <code>image_row_pitch</code> for a 1D image array. |
| If <code>image_slice_pitch</code> is not 0, it must be a multiple of the |
| <code>image_row_pitch</code>.</p> |
| </li> |
| <li> |
| <p><code>num_mip_levels</code> and <code>num_samples</code> must be 0.</p> |
| </li> |
| <li> |
| <p><code>mem_object</code> may refer to a valid buffer or image memory object. |
| <code>mem_object</code> can be a buffer memory object if <code>image_type</code> is |
| <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>BUFFER</code></a> or |
| <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a> <sup class="footnote">[<a id="_footnoteref_18" class="footnote" href="#_footnotedef_18" title="View footnote.">18</a>]</sup>. |
| <code>mem_object</code> can be an image object if <code>image_type</code> is |
| <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a> <sup class="footnote">[<a id="_footnoteref_19" class="footnote" href="#_footnotedef_19" title="View footnote.">19</a>]</sup>. |
| Otherwise it must be <code>NULL</code>. |
| The image pixels are taken from the memory objects data store. |
| When the contents of the specified memory objects data store are modified, |
| those changes are reflected in the contents of the image object and |
| vice-versa at corresponding synchronization points.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For a 1D image buffer created from a buffer object, the <code>image_width</code> × |
| size of element in bytes must be ≤ size of the buffer object. |
| The image data in the buffer object is stored as a single scanline which is |
| a linear sequence of adjacent elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a 2D image created from a buffer object, the <code>image_row_pitch</code> × |
| <code>image_height</code> must be ≤ size of the buffer object specified by |
| <code>mem_object</code>. |
| The image data in the buffer object is stored as a linear sequence of |
| adjacent scanlines. |
| Each scanline is a linear sequence of image elements padded to |
| <code>image_row_pitch</code> bytes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For an image object created from another image object, the values specified |
| in the image descriptor except for <code>mem_object</code> must match the image |
| descriptor information associated with <code>mem_object</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Image elements are stored according to their image format as described in |
| <a href="#image-format-descriptor">Image Format Descriptor</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the buffer object specified by <code>mem_object</code> was created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, the <em>host_ptr</em> specified to <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> must be aligned to the maximum of the |
| <a href="#CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>BASE_<wbr>ADDRESS_<wbr>ALIGNMENT</code></a> value for all devices in the |
| context associated with the buffer specified by <code>mem_object</code> that |
| support images.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Creating a 2D image object from another 2D image object creates a new |
| 2D image object that shares the image data store with <code>mem_object</code> but views |
| the pixels in the image with a different image channel order. |
| Restrictions are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All of the values specified in <em>image_desc</em> must match the image descriptor |
| information associated with <code>mem_object</code>, except for <code>mem_object</code>.</p> |
| </li> |
| <li> |
| <p>The image channel data type specified in <em>image_format</em> must match the |
| image channel data type associated with <code>mem_object</code>.</p> |
| </li> |
| <li> |
| <p>The image channel order specified in <em>image_format</em> must be compatible |
| with the image channel order associated with <code>mem_object</code>. |
| Compatible image channel orders |
| <sup class="footnote">[<a id="_footnoteref_20" class="footnote" href="#_footnotedef_20" title="View footnote.">20</a>]</sup> are:</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Image Channel Order in <em>image_format</em>:</th> |
| <th class="tableblock halign-left valign-top">Image Channel Order associated with <code>mem_object</code>:</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sBGRA"><code>CL_sBGRA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_BGRA</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_BGRA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sBGRA"><code>CL_sBGRA</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBA"><code>CL_sRGBA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_RGBA</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_RGBA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBA"><code>CL_sRGBA</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGB"><code>CL_sRGB</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGB"><code>CL_RGB</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGB"><code>CL_RGB</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGB"><code>CL_sRGB</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBx"><code>CL_sRGBx</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBx"><code>CL_RGBx</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBx"><code>CL_RGBx</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBx"><code>CL_sRGBx</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEPTH"><code>CL_DEPTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_R"><code>CL_R</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Concurrent reading from, writing to and copying between both a buffer object |
| and 1D image buffer or 2D image object associated with the buffer object is |
| undefined. |
| Only reading from both a buffer object and 1D image buffer or 2D image |
| object associated with the buffer object is defined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Writing to an image created from a buffer and then reading from this buffer |
| in a kernel even if appropriate synchronization operations (such as a |
| barrier) are performed between the writes and reads is undefined. |
| Similarly, writing to the buffer and reading from the image created from |
| this buffer with appropriate synchronization between the writes and reads is |
| undefined.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_querying_list_of_supported_image_formats"><a class="anchor" href="#_querying_list_of_supported_image_formats"></a>5.3.2. Querying List of Supported Image Formats</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To get the list of image formats supported by an OpenCL implementation for a |
| specified context, image type, and allocation information, call the function</p> |
| </div> |
| <div id="clGetSupportedImageFormats" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetSupportedImageFormats( |
| cl_context context, |
| cl_mem_flags flags, |
| cl_mem_object_type image_type, |
| cl_uint num_entries, |
| cl_image_format* image_formats, |
| cl_uint* num_image_formats);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context on which the image object(s) will be |
| created.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify usage |
| information about the image formats being queried and is described in |
| the <a href="#memory-flags-table">Memory Flags</a> table. |
| <em>flags</em> may be <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> to query image formats that may be read |
| from and written to by different kernel instances when correctly ordered by |
| event dependencies, or <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> to query image formats that may |
| be read from by a kernel, or <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> to query image formats that |
| may be written to by a kernel, or <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a> to query |
| image formats that may be both read from and written to by the same kernel |
| instance. |
| Please see <a href="#image-format-mapping">Image Format Mapping</a> for clarification.</p> |
| </li> |
| <li> |
| <p><em>image_type</em> describes the image type and must be either |
| <a href="#CL_MEM_OBJECT_IMAGE1D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D</code></a>, <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>BUFFER</code></a>, <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a>, |
| <a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE3D</code></a>, <a href="#CL_MEM_OBJECT_IMAGE1D_ARRAY"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE1D_<wbr>ARRAY</code></a>, or |
| <a href="#CL_MEM_OBJECT_IMAGE2D_ARRAY"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D_<wbr>ARRAY</code></a>.</p> |
| </li> |
| <li> |
| <p><em>num_entries</em> specifies the number of entries that can be returned in the |
| memory location given by <em>image_formats</em>.</p> |
| </li> |
| <li> |
| <p><em>image_formats</em> is a pointer to a memory location where the list of |
| supported image formats are returned. |
| Each entry describes a <a href="#cl_image_format"><code>cl_image_<wbr>format</code></a> structure supported by the OpenCL |
| implementation. |
| If <em>image_formats</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>num_image_formats</em> is the actual number of supported image formats for a |
| specific <em>context</em> and values specified by <em>flags</em>. |
| If <em>num_image_formats</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> returns a union of image formats supported by |
| all devices in the context.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>flags</em> or <em>image_type</em> are not valid, or if |
| <em>num_entries</em> is 0 and <em>image_formats</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the <a href="#device-queries-table">Device |
| Queries</a> table is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the values assigned to |
| <a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a>, <a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a> |
| <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>HEIGHT</code></a> |
| <a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a> |
| <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a>, and <a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_DEVICE_<wbr>MAX_<wbr>SAMPLERS</code></a> by the implementation |
| must be greater than or equal to the minimum values specified in the |
| <a href="#device-queries-table">Device Queries</a> table.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="minimum-list-of-supported-image-formats"><a class="anchor" href="#minimum-list-of-supported-image-formats"></a>5.3.2.1. Minimum List of Supported Image Formats</h5> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The tables below describe the required minimum lists of supported image |
| formats. |
| To query all image formats supported by an implementation, call the function <a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For full profile devices supporting OpenCL 2.0, 2.1, or 2.2, the minimum |
| list of supported image formats for either reading or writing in a kernel |
| is:</p> |
| </div> |
| <table id="min-supported-image-formats-2.0" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 18. Minimum list of supported image formats for reading or writing (OpenCL 2.0, 2.1, or 2.2)</caption> |
| <colgroup> |
| <col style="width: 34%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">num_channels</th> |
| <th class="tableblock halign-left valign-top">channel_order</th> |
| <th class="tableblock halign-left valign-top">channel_data_type</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_R"><code>CL_R</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SNORM_INT8"><code>CL_SNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_SNORM_INT16"><code>CL_SNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEPTH"><code>CL_DEPTH</code></a> <sup class="footnote">[<a id="_footnoteref_21" class="footnote" href="#_footnotedef_21" title="View footnote.">21</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RG"><code>CL_RG</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SNORM_INT8"><code>CL_SNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_SNORM_INT16"><code>CL_SNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_RGBA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SNORM_INT8"><code>CL_SNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_SNORM_INT16"><code>CL_SNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_BGRA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBA"><code>CL_sRGBA</code></a> <sup class="footnote">[<a id="_footnoteref_22" class="footnote" href="#_footnotedef_22" title="View footnote.">22</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>For full profile devices supporting other OpenCL versions, such as OpenCL 1.2 |
| or OpenCL 3.0, the minimum list of supported image formats for either reading |
| or writing in a kernel is:</p> |
| </div> |
| <table id="min-supported-image-formats" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 19. Minimum list of required image formats for reading or writing</caption> |
| <colgroup> |
| <col style="width: 34%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">num_channels</th> |
| <th class="tableblock halign-left valign-top">channel_order</th> |
| <th class="tableblock halign-left valign-top">channel_data_type</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_RGBA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_BGRA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>For full profile devices that support reading from and writing to the same |
| image object from the same kernel instance (see <a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a>), |
| the minimum list of supported image formats for reading and writing in |
| the same kernel instance is:</p> |
| </div> |
| <table id="min-supported-image-formats-read-write" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 20. Minimum list of required image formats for reading and writing</caption> |
| <colgroup> |
| <col style="width: 34%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">num_channels</th> |
| <th class="tableblock halign-left valign-top">channel_order</th> |
| <th class="tableblock halign-left valign-top">channel_data_type</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_R"><code>CL_R</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_RGBA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="image-format-mapping"><a class="anchor" href="#image-format-mapping"></a>5.3.2.2. Image format mapping to OpenCL kernel language image access qualifiers</h5> |
| <div class="paragraph"> |
| <p>Image arguments to kernels may have the <code>read_only</code>, <code>write_only</code> or |
| <code>read_write</code> qualifier. |
| Not all image formats supported by the device and platform are valid to be |
| passed to all of these access qualifiers. |
| For each access qualifier, only images whose format is in the list of |
| formats returned by <a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> with the given flag |
| arguments in the <a href="#image-format-mapping-table">Image Format Mapping</a> table |
| are permitted. |
| It is not valid to pass an image supporting writing as both a <code>read_only</code> |
| image and a <code>write_only</code> image parameter, or to a <code>read_write</code> image |
| parameter and any other image parameter.</p> |
| </div> |
| <table id="image-format-mapping-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 21. Mapping from format flags passed to <a href="#clGetSupportedImageFormats">clGetSupportedImageFormats</a> to OpenCL kernel language image access qualifiers</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Access Qualifier</th> |
| <th class="tableblock halign-left valign-top">Memory Flags</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>read_only</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a>,<br> |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>,<br> |
| <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>write_only</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a>,<br> |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>,<br> |
| <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>read_write</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_reading_writing_and_copying_image_objects"><a class="anchor" href="#_reading_writing_and_copying_image_objects"></a>5.3.3. Reading, Writing and Copying Image Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The following functions enqueue commands to read from an image or image |
| array object to host memory or write to an image or image array object from |
| host memory.</p> |
| </div> |
| <div id="clEnqueueReadImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueReadImage( |
| cl_command_queue command_queue, |
| cl_mem image, |
| cl_bool blocking_read, |
| <span class="directive">const</span> size_t* origin, |
| <span class="directive">const</span> size_t* region, |
| size_t row_pitch, |
| size_t slice_pitch, |
| <span class="directive">void</span>* ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div id="clEnqueueWriteImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWriteImage( |
| cl_command_queue command_queue, |
| cl_mem image, |
| cl_bool blocking_write, |
| <span class="directive">const</span> size_t* origin, |
| <span class="directive">const</span> size_t* region, |
| size_t input_row_pitch, |
| size_t input_slice_pitch, |
| <span class="directive">const</span> <span class="directive">void</span>* ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the read / write |
| command will be queued. |
| <em>command_queue</em> and <em>image</em> must be created with the same OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>image</em> refers to a valid image or image array object.</p> |
| </li> |
| <li> |
| <p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write |
| operations are <em>blocking</em> or <em>non-blocking</em>.</p> |
| </li> |
| <li> |
| <p><em>origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or 3D |
| image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>image</em> is a 2D image object, <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image or 1D image buffer object, <em>origin</em>[1] and |
| <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image array object, <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image array object, <em>origin</em>[1] describes the image index |
| in the 1D image array. |
| If <em>image</em> is a 2D image array object, <em>origin</em>[2] describes the image index |
| in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or |
| 3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the |
| number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D |
| rectangle and the number of images of a 1D image array. |
| If <em>image</em> is a 2D image object, <em>region</em>[2] must be 1. |
| If <em>image</em> is a 1D image or 1D image buffer object, <em>region</em>[1] and |
| <em>region</em>[2] must be 1. |
| If <em>image</em> is a 1D image array object, <em>region</em>[2] must be 1. |
| The values in <em>region</em> cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>row_pitch</em> in <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <em>input_row_pitch</em> in |
| <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> is the length of each row in bytes. |
| This value must be greater than or equal to the element size in bytes |
| × <em>width</em>. |
| If <em>row_pitch</em> (or <em>input_row_pitch</em>) is set to 0, the appropriate row pitch |
| is calculated based on the size of each element in bytes multiplied by |
| <em>width</em>.</p> |
| </li> |
| <li> |
| <p><em>slice_pitch</em> in <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <em>input_slice_pitch</em> in |
| <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> is the size in bytes of the 2D slice of the 3D region |
| of a 3D image or each image of a 1D or 2D image array being read or written |
| respectively. |
| This must be 0 if <em>image</em> is a 1D or 2D image. |
| Otherwise this value must be greater than or equal to <em>row_pitch</em> × |
| <em>height</em>. |
| If <em>slice_pitch</em> (or <em>input_slice_pitch</em>) is set to 0, the appropriate slice |
| pitch is calculated based on the <em>row_pitch</em> × <em>height</em>.</p> |
| </li> |
| <li> |
| <p><em>ptr</em> is the pointer to a buffer in host memory where image data is to be |
| read from or to be written to. |
| The alignment requirements for ptr are specified in |
| <a href="#alignment-app-data-types">Alignment of Application Data Types</a>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this read / write command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_read</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a> i.e. the read command is blocking, |
| <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> does not return until the buffer data has been read and |
| copied into memory pointed to by <em>ptr</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_read</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. the read command is non-blocking, |
| <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> queues a non-blocking read command and returns. |
| The contents of the buffer that <em>ptr</em> points to cannot be used until the |
| read command has completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the read command. |
| When the read command has completed, the contents of the buffer that <em>ptr</em> |
| points to can be used by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_write</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the write command is blocking and does not |
| return until the command is complete, including transfer of the data. |
| The memory pointed to by <em>ptr</em> can be reused by the application after the |
| <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> call returns.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_write</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>, the OpenCL implementation will use <em>ptr</em> to |
| perform a non-blocking write. |
| As the write is non-blocking the implementation can return immediately. |
| The memory pointed to by <em>ptr</em> cannot be reused by the application after the |
| call returns. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the write command. |
| When the write command has completed, the memory pointed to by <em>ptr</em> can |
| then be reused by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the |
| function is executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| <em>image</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>image</em> is not a valid image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>origin</em> or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the region being read or written specified by |
| <em>origin</em> and <em>region</em> is out of bounds.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values in <em>origin</em> and <em>region</em> do not follow rules |
| described in the argument description for <em>origin</em> and <em>region</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>image</em> is a 1D or 2D image and <em>slice_pitch</em> or |
| <em>input_slice_pitch</em> is not 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>ptr</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions (image width, height, |
| specified or compute row and/or slice pitch) for <em>image</em> are not |
| supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if image format (image channel order and |
| data type) for <em>image</em> are not supported by device associated with |
| <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>image</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> does |
| not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> is called on <em>image</em> which |
| has been created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> is called on <em>image</em> which |
| has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the read and write |
| operations are blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Calling <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> to read a region of the <em>image</em> with the <em>ptr</em> |
| argument value set to <em>host_ptr</em> + (<em>origin</em>[2] × <em>image slice pitch</em> |
| + <em>origin</em>[1] × <em>image row pitch</em> + <em>origin</em>[0] × <em>bytes |
| per pixel</em>), where <em>host_ptr</em> is a pointer to the memory region specified |
| when the <em>image</em> being read is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, must meet |
| the following requirements in order to avoid undefined behavior:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All commands that use this image object have finished execution before |
| the read command begins execution.</p> |
| </li> |
| <li> |
| <p>The <em>row_pitch</em> and <em>slice_pitch</em> argument values in |
| <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> must be set to the image row pitch and slice pitch.</p> |
| </li> |
| <li> |
| <p>The image object is not mapped.</p> |
| </li> |
| <li> |
| <p>The image object is not used by any command-queue until the read command |
| has finished execution.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Calling <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> to update the latest bits in a region of the |
| <em>image</em> with the <em>ptr</em> argument value set to <em>host_ptr</em> + (<em>origin</em>[2] |
| × <em>image slice pitch</em> + <em>origin</em>[1] × <em>image row pitch</em> + |
| <em>origin</em>[0] × <em>bytes per pixel</em>), where <em>host_ptr</em> is a pointer to the |
| memory region specified when the <em>image</em> being written is created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>, must meet the following requirements in order to avoid |
| undefined behavior:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The host memory region being written contains the latest bits when the |
| enqueued write command begins execution.</p> |
| </li> |
| <li> |
| <p>The <em>input_row_pitch</em> and <em>input_slice_pitch</em> argument values in |
| <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> must be set to the image row pitch and slice |
| pitch.</p> |
| </li> |
| <li> |
| <p>The image object is not mapped.</p> |
| </li> |
| <li> |
| <p>The image object is not used by any command-queue until the write |
| command has finished execution.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to copy image objects, call the function</p> |
| </div> |
| <div id="clEnqueueCopyImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyImage( |
| cl_command_queue command_queue, |
| cl_mem src_image, |
| cl_mem dst_image, |
| <span class="directive">const</span> size_t* src_origin, |
| <span class="directive">const</span> size_t* dst_origin, |
| <span class="directive">const</span> size_t* region, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>src_image</em> and <em>dst_image</em> can be 1D, 2D, 3D image or a 1D, 2D image array |
| objects. |
| It is possible to copy subregions between any combinations of source and |
| destination types, provided that the dimensions of the subregions are the |
| same e.g., one can copy a rectangular region from a 2D image to a slice of a |
| 3D image.</p> |
| </li> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the copy command |
| will be queued. |
| The OpenCL context associated with <em>command_queue</em>, <em>src_image</em> and |
| <em>dst_image</em> must be the same.</p> |
| </li> |
| <li> |
| <p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or |
| 3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>image</em> is a 2D image object, <em>src_origin</em>[2] must be 0. |
| If <em>src_image</em> is a 1D image object, <em>src_origin</em>[1] and <em>src_origin</em>[2] |
| must be 0. |
| If <em>src_image</em> is a 1D image array object, <em>src_origin</em>[2] must be 0. |
| If <em>src_image</em> is a 1D image array object, <em>src_origin</em>[1] describes the |
| image index in the 1D image array. |
| If <em>src_image</em> is a 2D image array object, <em>src_origin</em>[2] describes the |
| image index in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or |
| 3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>dst_image</em> is a 2D image object, <em>dst_origin</em>[2] must be 0. |
| If <em>dst_image</em> is a 1D image or 1D image buffer object, <em>dst_origin</em>[1] and |
| <em>dst_origin</em>[2] must be 0. |
| If <em>dst_image</em> is a 1D image array object, <em>dst_origin</em>[2] must be 0. |
| If <em>dst_image</em> is a 1D image array object, <em>dst_origin</em>[1] describes the |
| image index in the 1D image array. |
| If <em>dst_image</em> is a 2D image array object, <em>dst_origin</em>[2] describes the |
| image index in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or |
| 3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the |
| number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D |
| rectangle and the number of images of a 1D image array. |
| If <em>src_image</em> or <em>dst_image</em> is a 2D image object, <em>region</em>[2] must be 1. |
| If <em>src_image</em> or <em>dst_image</em> is a 1D image or 1D image buffer object, |
| <em>region</em>[1] and <em>region</em>[2] must be 1. |
| If <em>src_image</em> or <em>dst_image</em> is a 1D image array object, <em>region</em>[2] must |
| be 1. |
| The values in <em>region</em> cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this copy command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>It is currently a requirement that the <em>src_image</em> and <em>dst_image</em> image |
| memory objects for <a href="#clEnqueueCopyImage"><strong>clEnqueueCopyImage</strong></a> must have the exact same image |
| format (i.e. the <a href="#cl_image_format"><code>cl_image_<wbr>format</code></a> descriptor specified when <em>src_image</em> and |
| <em>dst_image</em> are created must match).</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueCopyImage"><strong>clEnqueueCopyImage</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em>, |
| <em>src_image</em> and <em>dst_image</em> are not the same or if the context |
| associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not |
| the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>src_image</em> and <em>dst_image</em> are not valid image |
| objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_MISMATCH"><code>CL_IMAGE_<wbr>FORMAT_<wbr>MISMATCH</code></a> if <em>src_image</em> and <em>dst_image</em> do not use the |
| same image format.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_origin</em>, <em>dst_origin</em>, or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the 2D or 3D rectangular region specified by |
| <em>src_origin</em> and <em>src_origin</em> + <em>region</em> refers to a region outside |
| <em>src_image</em>, or if the 2D or 3D rectangular region specified by |
| <em>dst_origin</em> and <em>dst_origin</em> + <em>region</em> refers to a region outside |
| <em>dst_image</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values in <em>src_origin</em>, <em>dst_origin</em> and <em>region</em> do |
| not follow rules described in the argument description for <em>src_origin</em>, |
| <em>dst_origin</em> and <em>region</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions (image width, height, |
| specified or compute row and/or slice pitch) for <em>src_image</em> or |
| <em>dst_image</em> are not supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if image format (image channel order and |
| data type) for <em>src_image</em> or <em>dst_image</em> are not supported by device |
| associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>src_image</em> or <em>dst_image</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> does |
| not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_MEM_<wbr>COPY_<wbr>OVERLAP</code></a> if <em>src_image</em> and <em>dst_image</em> are the same image |
| object and the source and destination regions overlap.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filling_image_objects"><a class="anchor" href="#_filling_image_objects"></a>5.3.4. Filling Image Objects</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Filling image objects is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to fill an image object with a specified color, call |
| the function</p> |
| </div> |
| <div id="clEnqueueFillImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueFillImage( |
| cl_command_queue command_queue, |
| cl_mem image, |
| <span class="directive">const</span> <span class="directive">void</span>* fill_color, |
| <span class="directive">const</span> size_t* origin, |
| <span class="directive">const</span> size_t* region, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the fill command |
| will be queued. |
| The OpenCL context associated with <em>command_queue</em> and <em>image</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>image</em> is a valid image object.</p> |
| </li> |
| <li> |
| <p><em>fill_color</em> is the color used to fill the image. |
| The fill color is a single floating point value if the channel order is |
| <a href="#CL_DEPTH"><code>CL_DEPTH</code></a>. |
| Otherwise, the fill color is a four component RGBA floating-point color |
| value if the <em>image</em> channel data type is not an unnormalized signed or |
| unsigned integer type, is a four component signed integer value if the |
| <em>image</em> channel data type is an unnormalized signed integer type and is a |
| four component unsigned integer value if the <em>image</em> channel data type is an |
| unnormalized unsigned integer type. |
| The fill color will be converted to the appropriate image channel format and |
| order associated with <em>image</em>.</p> |
| </li> |
| <li> |
| <p><em>origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or 3D |
| image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>image</em> is a 2D image object, <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image or 1D image buffer object, <em>origin</em>[1] and |
| <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image array object, <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image array object, <em>origin</em>[1] describes the image index |
| in the 1D image array. |
| If <em>image</em> is a 2D image array object, <em>origin</em>[2] describes the image index |
| in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or |
| 3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the |
| number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D |
| rectangle and the number of images of a 1D image array. |
| If <em>image</em> is a 2D image object, <em>region</em>[2] must be 1. |
| If <em>image</em> is a 1D image or 1D image buffer object, <em>region</em>[1] and |
| <em>region</em>[2] must be 1. |
| If <em>image</em> is a 1D image array object, <em>region</em>[2] must be 1. |
| The values in <em>region</em> cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The usage information which indicates whether the memory object can be read |
| or written by a kernel and/or the host and is given by the <code>cl_mem_<wbr>flags</code> |
| argument value specified when <em>image</em> is created is ignored by |
| <a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| <em>image</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>image</em> is not a valid image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>fill_color</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>origin</em> or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the region being filled as specified by <em>origin</em> and |
| <em>region</em> is out of bounds.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values in <em>origin</em> and <em>region</em> do not follow rules |
| described in the argument description for <em>origin</em> and <em>region</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions (image width, height, |
| specified or compute row and/or slice pitch) for <em>image</em> are not |
| supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if image format (image channel order and |
| data type) for <em>image</em> are not supported by device associated with |
| <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>image</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_copying_between_image_and_buffer_objects"><a class="anchor" href="#_copying_between_image_and_buffer_objects"></a>5.3.5. Copying between Image and Buffer Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to copy an image object to a buffer object, call the |
| function</p> |
| </div> |
| <div id="clEnqueueCopyImageToBuffer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyImageToBuffer( |
| cl_command_queue command_queue, |
| cl_mem src_image, |
| cl_mem dst_buffer, |
| <span class="directive">const</span> size_t* src_origin, |
| <span class="directive">const</span> size_t* region, |
| size_t dst_offset, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue. |
| The OpenCL context associated with <em>command_queue</em>, <em>src_image</em> and |
| <em>dst_buffer</em> must be the same.</p> |
| </li> |
| <li> |
| <p><em>src_image</em> is a valid image object.</p> |
| </li> |
| <li> |
| <p><em>dst_buffer</em> is a valid buffer object.</p> |
| </li> |
| <li> |
| <p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or |
| 3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>src_image</em> is a 2D image object, <em>src_origin</em>[2] must be 0. |
| If <em>src_image</em> is a 1D image or 1D image buffer object, <em>src_origin</em>[1] and |
| <em>src_origin</em>[2] must be 0. |
| If <em>src_image</em> is a 1D image array object, <em>src_origin</em>[2] must be 0. |
| If <em>src_image</em> is a 1D image array object, <em>src_origin</em>[1] describes the |
| image index in the 1D image array. |
| If <em>src_image</em> is a 2D image array object, <em>src_origin</em>[2] describes the |
| image index in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or |
| 3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the |
| number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D |
| rectangle and the number of images of a 1D image array. |
| If <em>src_image</em> is a 2D image object, <em>region</em>[2] must be 1. |
| If <em>src_image</em> is a 1D image or 1D image buffer object, <em>region</em>[1] and |
| <em>region</em>[2] must be 1. |
| If <em>src_image</em> is a 1D image array object, <em>region</em>[2] must be 1. |
| The values in <em>region</em> cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>dst_offset</em> refers to the offset where to begin copying data into |
| <em>dst_buffer</em>. |
| The size in bytes of the region to be copied referred to as <em>dst_cb</em> is |
| computed as <em>width</em> × <em>height</em> × <em>depth</em> × <em>bytes/image |
| element</em> if <em>src_image</em> is a 3D image object, is computed as <em>width</em> × |
| <em>height</em> × <em>bytes/image element</em> if <em>src_image</em> is a 2D image, is |
| computed as <em>width</em> × <em>height</em> × <em>arraysize</em> × |
| <em>bytes/image element</em> if <em>src_image</em> is a 2D image array object, is computed |
| as <em>width</em> × <em>bytes/image element</em> if <em>src_image</em> is a 1D image or 1D |
| image buffer object and is computed as <em>width</em> × <em>arraysize</em> × |
| <em>bytes/image element</em> if <em>src_image</em> is a 1D image array object.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this copy command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueCopyImageToBuffer"><strong>clEnqueueCopyImageToBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em>, |
| <em>src_image</em> and <em>dst_buffer</em> are not the same or if the context |
| associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not |
| the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>src_image</em> is not a valid image object or |
| <em>dst_buffer</em> is not a valid buffer object or if <em>src_image</em> is a 1D |
| image buffer object created from <em>dst_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>src_origin</em> or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the 1D, 2D or 3D rectangular region specified by |
| <em>src_origin</em> and <em>src_origin</em> + <em>region</em> refers to a region outside |
| <em>src_image</em>, or if the region specified by <em>dst_offset</em> and <em>dst_offset</em> |
| + <em>dst_cb</em> to a region outside <em>dst_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values in <em>src_origin</em> and <em>region</em> do not follow |
| rules described in the argument description for <em>src_origin</em> and |
| <em>region</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>dst_buffer</em> is a sub-buffer object |
| and <em>offset</em> specified when the sub-buffer object is created is not |
| aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated |
| with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions (image width, height, |
| specified or compute row and/or slice pitch) for <em>src_image</em> are not |
| supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if image format (image channel order and |
| data type) for <em>src_image</em> are not supported by device associated with |
| <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>src_image</em> or <em>dst_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> does |
| not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to copy a buffer object to an image object, call the |
| function</p> |
| </div> |
| <div id="clEnqueueCopyBufferToImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyBufferToImage( |
| cl_command_queue command_queue, |
| cl_mem src_buffer, |
| cl_mem dst_image, |
| size_t src_offset, |
| <span class="directive">const</span> size_t* dst_origin, |
| <span class="directive">const</span> size_t* region, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue. |
| The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and |
| <em>dst_image</em> must be the same.</p> |
| </li> |
| <li> |
| <p><em>src_buffer</em> is a valid buffer object.</p> |
| </li> |
| <li> |
| <p><em>dst_image</em> is a valid image object.</p> |
| </li> |
| <li> |
| <p><em>src_offset</em> refers to the offset where to begin copying data from |
| <em>src_buffer</em>.</p> |
| </li> |
| <li> |
| <p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or |
| 3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>dst_image</em> is a 2D image object, <em>dst_origin</em>[2] must be 0. |
| If <em>dst_image</em> is a 1D image or 1D image buffer object, <em>dst_origin</em>[1] and |
| <em>dst_origin</em>[2] must be 0. |
| If <em>dst_image</em> is a 1D image array object, <em>dst_origin</em>[2] must be 0. |
| If <em>dst_image</em> is a 1D image array object, <em>dst_origin</em>[1] describes the |
| image index in the 1D image array. |
| If <em>dst_image</em> is a 2D image array object, <em>dst_origin</em>[2] describes the |
| image index in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or |
| 3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the |
| number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D |
| rectangle and the number of images of a 1D image array. |
| If <em>dst_image</em> is a 2D image object, <em>region</em>[2] must be 1. |
| If <em>dst_image</em> is a 1D image or 1D image buffer object, <em>region</em>[1] and |
| <em>region</em>[2] must be 1. |
| If <em>dst_image</em> is a 1D image array object, <em>region</em>[2] must be 1. |
| The values in <em>region</em> cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this copy command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The size in bytes of the region to be copied from <em>src_buffer</em> referred to |
| as <em>src_cb</em> is computed as <em>width</em> × <em>height</em> × <em>depth</em> × |
| <em>bytes/image element</em> if <em>dst_image</em> is a 3D image object, is computed as |
| <em>width</em> × <em>height</em> × <em>bytes/image element</em> if <em>dst_image</em> is a |
| 2D image, is computed as <em>width</em> × <em>height</em> × <em>arraysize</em> |
| × <em>bytes/image element</em> if <em>dst_image</em> is a 2D image array object, is |
| computed as <em>width</em> × <em>bytes/image element</em> if <em>dst_image</em> is a 1D |
| image or 1D image buffer object and is computed as <em>width</em> × |
| <em>arraysize</em> × <em>bytes/image element</em> if <em>dst_image</em> is a 1D image array |
| object.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueCopyBufferToImage"><strong>clEnqueueCopyBufferToImage</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em>, |
| <em>src_buffer</em> and <em>dst_image</em> are not the same or if the context |
| associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not |
| the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>src_buffer</em> is not a valid buffer object or |
| <em>dst_image</em> is not a valid image object or if <em>dst_image</em> is a 1D image |
| buffer object created from <em>src_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>dst_origin</em> or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the 1D, 2D or 3D rectangular region specified by |
| <em>dst_origin</em> and <em>dst_origin</em> + <em>region</em> refer to a region outside |
| <em>dst_image</em>, or if the region specified by <em>src_offset</em> and <em>src_offset</em> |
| + <em>src_cb</em> refer to a region outside <em>src_buffer</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values in <em>dst_origin</em> and <em>region</em> do not follow |
| rules described in the argument description for <em>dst_origin</em> and |
| <em>region</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if <em>src_buffer</em> is a sub-buffer object |
| and <em>offset</em> specified when the sub-buffer object is created is not |
| aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated |
| with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions (image width, height, |
| specified or compute row and/or slice pitch) for <em>dst_image</em> are not |
| supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if image format (image channel order and |
| data type) for <em>dst_image</em> are not supported by device associated with |
| <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>src_buffer</em> or <em>dst_image</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> does |
| not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_mapping_image_objects"><a class="anchor" href="#_mapping_image_objects"></a>5.3.6. Mapping Image Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to map a region in the image object given by <em>image</em> |
| into the host address space and returns a pointer to this mapped region, |
| call the function</p> |
| </div> |
| <div id="clEnqueueMapImage" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span>* clEnqueueMapImage( |
| cl_command_queue command_queue, |
| cl_mem image, |
| cl_bool blocking_map, |
| cl_map_flags map_flags, |
| <span class="directive">const</span> size_t* origin, |
| <span class="directive">const</span> size_t* region, |
| size_t* image_row_pitch, |
| size_t* image_slice_pitch, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>image</em> is a valid image object. |
| The OpenCL context associated with <em>command_queue</em> and <em>image</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>blocking_map</em> indicates if the map operation is <em>blocking</em> or |
| <em>non-blocking</em>.</p> |
| </li> |
| <li> |
| <p><em>map_flags</em> is a bit-field and is described in the |
| <a href="#memory-map-flags-table">Memory Map Flags</a> table.</p> |
| </li> |
| <li> |
| <p><em>origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or 3D |
| image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or |
| the (<em>x</em>) offset and the image index in the 1D image array. |
| If <em>image</em> is a 2D image object, <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image or 1D image buffer object, <em>origin</em>[1] and |
| <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image array object, <em>origin</em>[2] must be 0. |
| If <em>image</em> is a 1D image array object, <em>origin</em>[1] describes the image index |
| in the 1D image array. |
| If <em>image</em> is a 2D image array object, <em>origin</em>[2] describes the image index |
| in the 2D image array.</p> |
| </li> |
| <li> |
| <p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or |
| 3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the |
| number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D |
| rectangle and the number of images of a 1D image array. |
| If <em>image</em> is a 2D image object, <em>region</em>[2] must be 1. |
| If <em>image</em> is a 1D image or 1D image buffer object, <em>region</em>[1] and |
| <em>region</em>[2] must be 1. |
| If <em>image</em> is a 1D image array object, <em>region</em>[2] must be 1. |
| The values in <em>region</em> cannot be 0.</p> |
| </li> |
| <li> |
| <p><em>image_row_pitch</em> returns the scan-line pitch in bytes for the mapped |
| region. |
| This must be a non-<code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><em>image_slice_pitch</em> returns the size in bytes of each 2D slice of a 3D image |
| or the size of each 1D or 2D image in a 1D or 2D image array for the mapped |
| region. |
| For a 1D and 2D image, zero is returned if this argument is not <code>NULL</code>. |
| For a 3D image, 1D and 2D image array, <em>image_slice_pitch</em> must be a |
| non-<code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> does not wait on |
| any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_map</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> does not return until the |
| specified region in <em>image</em> is mapped into the host address space and the |
| application can access the contents of the mapped region using the pointer |
| returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_map</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. map operation is non-blocking, the |
| pointer to the mapped region returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> cannot be used |
| until the map command has completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the map command. |
| When the map command is completed, the application can access the contents |
| of the mapped region using the pointer returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> will return a pointer to the mapped region. |
| The <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>NULL</code> pointer is returned otherwise with one of the following error |
| values returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and |
| <em>image</em> are not the same or if context associated with <em>command_queue</em> |
| and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>image</em> is not a valid image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>origin</em> or <em>region</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if region being mapped given by (<em>origin</em>, |
| <em>origin</em> + <em>region</em>) is out of bounds or if values specified in <em>map_flags</em> |
| are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values in <em>origin</em> and <em>region</em> do not follow rules |
| described in the argument description for <em>origin</em> and <em>region</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>image_row_pitch</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>image</em> is a 3D image, 1D or 2D image array object |
| and <em>image_slice_pitch</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if image dimensions (image width, height, |
| specified or compute row and/or slice pitch) for <em>image</em> are not |
| supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if image format (image channel order and |
| data type) for <em>image</em> are not supported by device associated with |
| <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MAP_FAILURE"><code>CL_MAP_<wbr>FAILURE</code></a> if there is a failure to map the requested region into |
| the host address space. |
| This error cannot occur for image objects created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_MEM_<wbr>ALLOC_<wbr>HOST_<wbr>PTR</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the map operation is |
| blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with <em>image</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> does |
| not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>image</em> has been created with |
| <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>WRITE_<wbr>ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> and <a href="#CL_MAP_READ"><code>CL_MAP_<wbr>READ</code></a> is set |
| in <em>map_flags</em> or if <em>image</em> has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_MEM_<wbr>HOST_<wbr>READ_<wbr>ONLY</code></a> |
| or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> and <a href="#CL_MAP_WRITE"><code>CL_MAP_<wbr>WRITE</code></a> or |
| <a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_MAP_<wbr>WRITE_<wbr>INVALIDATE_<wbr>REGION</code></a> is set in <em>map_flags</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if mapping would lead to overlapping regions being |
| mapped for writing.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The pointer returned maps a 1D, 2D or 3D region starting at <em>origin</em> and is |
| at least <em>region</em>[0] pixels in size for a 1D image, 1D image buffer or 1D |
| image array, (<em>image_row_pitch × region[1])</em> pixels in size for a 2D |
| image or 2D image array, and (<em>image_slice_pitch × region[2])</em> pixels |
| in size for a 3D image. |
| The result of a memory access outside this region is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the image object is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> set in <em>mem_flags</em>, |
| the following will be true:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <em>host_ptr</em> specified in <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, |
| <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> is guaranteed to contain the |
| latest bits in the region being mapped when the <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> command |
| has completed.</p> |
| </li> |
| <li> |
| <p>The pointer value returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> will be derived from |
| the <em>host_ptr</em> specified when the image object is created.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Mapped image objects are unmapped using <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>. |
| This is described in <a href="#unmapping-mapped-memory">Unmapping Mapped Memory |
| Objects</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="image-object-queries"><a class="anchor" href="#image-object-queries"></a>5.3.7. Image Object Queries</h4> |
| <div class="paragraph"> |
| <p>To get information that is common to all memory objects, use the |
| <a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a> function described in <a href="#memory-object-queries">Memory |
| Object Queries</a>.</p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To get information specific to an image object created with <a href="#clCreateImage"><strong>clCreateImage</strong></a>, |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> call |
| the function</p> |
| </div> |
| <div id="clGetImageInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetImageInfo( |
| cl_mem image, |
| cl_image_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>image</em> specifies the image object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetImageInfo"><strong>clGetImageInfo</strong></a> is described in the |
| <a href="#image-info-table">Image Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#image-info-table">Image Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="image-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 22. List of supported param_names by <a href="#clGetImageInfo">clGetImageInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Image Info</th> |
| <th class="tableblock halign-left valign-top">Return type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_FORMAT"></a><a href="#CL_IMAGE_FORMAT"><code>CL_IMAGE_<wbr>FORMAT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#cl_image_format"><code>cl_image_<wbr>format</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the image format descriptor specified when <em>image</em> is created |
| with <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, |
| <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a> or <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_ELEMENT_SIZE"></a><a href="#CL_IMAGE_ELEMENT_SIZE"><code>CL_IMAGE_<wbr>ELEMENT_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return size of each element of the image memory object given by |
| <em>image</em> in bytes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_ROW_PITCH"></a><a href="#CL_IMAGE_ROW_PITCH"><code>CL_IMAGE_<wbr>ROW_<wbr>PITCH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return calculated row pitch in bytes of a row of elements of the |
| image object given by <em>image</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_SLICE_PITCH"></a><a href="#CL_IMAGE_SLICE_PITCH"><code>CL_IMAGE_<wbr>SLICE_<wbr>PITCH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return calculated slice pitch in bytes of a 2D slice for the 3D |
| image object or size of each image in a 1D or 2D image array given |
| by <em>image</em>. |
| For a 1D image, 1D image buffer and 2D image object return 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_WIDTH"></a><a href="#CL_IMAGE_WIDTH"><code>CL_IMAGE_<wbr>WIDTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return width of the image in pixels.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_HEIGHT"></a><a href="#CL_IMAGE_HEIGHT"><code>CL_IMAGE_<wbr>HEIGHT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return height of the image in pixels. |
| For a 1D image, 1D image buffer and 1D image array object, height = |
| 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_DEPTH"></a><a href="#CL_IMAGE_DEPTH"><code>CL_IMAGE_<wbr>DEPTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return depth of the image in pixels. |
| For a 1D image, 1D image buffer, 2D image or 1D and 2D image array |
| object, depth = 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_ARRAY_SIZE"></a><a href="#CL_IMAGE_ARRAY_SIZE"><code>CL_IMAGE_<wbr>ARRAY_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return number of images in the image array. |
| If <em>image</em> is not an image array, 0 is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_BUFFER"></a><a href="#CL_IMAGE_BUFFER"><code>CL_IMAGE_<wbr>BUFFER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2 and <a href="#unified-spec">deprecated by</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_mem</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return buffer object associated with <em>image</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_NUM_MIP_LEVELS"></a><a href="#CL_IMAGE_NUM_MIP_LEVELS"><code>CL_IMAGE_<wbr>NUM_<wbr>MIP_<wbr>LEVELS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return <code>num_mip_levels</code> associated with <em>image</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_NUM_SAMPLES"></a><a href="#CL_IMAGE_NUM_SAMPLES"><code>CL_IMAGE_<wbr>NUM_<wbr>SAMPLES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return <code>num_samples</code> associated with <em>image</em>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetImageInfo"><strong>clGetImageInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#image-info-table">Image Object Queries</a> table and <em>param_value</em> is |
| not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>image</em> is a not a valid image object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_pipes"><a class="anchor" href="#_pipes"></a>5.4. Pipes</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Pipes are <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A <em>pipe</em> is a memory object that stores data organized as a FIFO. |
| Pipe objects can only be accessed using built-in functions that read from |
| and write to a pipe. |
| Pipe objects are not accessible from the host. |
| A pipe object encapsulates the following information:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Packet size in bytes</p> |
| </li> |
| <li> |
| <p>Maximum capacity in packets</p> |
| </li> |
| <li> |
| <p>Information about the number of packets currently in the pipe</p> |
| </li> |
| <li> |
| <p>Data packets</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_pipe_objects"><a class="anchor" href="#_creating_pipe_objects"></a>5.4.1. Creating Pipe Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a <strong>pipe object</strong>, call the function</p> |
| </div> |
| <div id="clCreatePipe" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreatePipe( |
| cl_context context, |
| cl_mem_flags flags, |
| cl_uint pipe_packet_size, |
| cl_uint pipe_max_packets, |
| <span class="directive">const</span> cl_pipe_properties* properties, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreatePipe"><strong>clCreatePipe</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context used to create the pipe object.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information such as the memory arena that should be used to allocate the |
| pipe object and how it will be used. |
| The <a href="#memory-flags">Memory Flags</a> table describes the possible values for |
| <em>flags</em>. |
| Only <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> and <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a> can be specified when |
| creating a pipe object. |
| If the value specified for <em>flags</em> is 0, the default is used which is |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> | <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_MEM_<wbr>HOST_<wbr>NO_<wbr>ACCESS</code></a>.</p> |
| </li> |
| <li> |
| <p><em>pipe_packet_size</em> is the size in bytes of a pipe packet.</p> |
| </li> |
| <li> |
| <p><em>pipe_max_packets</em> specifies the pipe capacity by specifying the maximum |
| number of packets the pipe can hold.</p> |
| </li> |
| <li> |
| <p><em>properties</em> specifies a list of properties for the pipe and their |
| corresponding values. |
| Each property name is immediately followed by the corresponding desired |
| value. |
| The list is terminated with 0. |
| Currently, in all OpenCL versions, <em>properties</em> must be <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreatePipe"><strong>clCreatePipe</strong></a> returns a valid non-zero pipe object and <em>errcode_ret</em> is set |
| to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the pipe object is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in <em>context</em> support pipes.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if values specified in <em>flags</em> are not as defined |
| above.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>properties</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PIPE_SIZE"><code>CL_INVALID_<wbr>PIPE_<wbr>SIZE</code></a> if <em>pipe_packet_size</em> is 0 or the |
| <em>pipe_packet_size</em> exceeds <a href="#CL_DEVICE_PIPE_MAX_PACKET_SIZE"><code>CL_DEVICE_<wbr>PIPE_<wbr>MAX_<wbr>PACKET_<wbr>SIZE</code></a> value |
| specified in the <a href="#device-queries-table">Device Queries</a> table for all |
| devices in <em>context</em> or if <em>pipe_max_packets</em> is 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for the pipe object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Pipes follow the same memory consistency model as defined for buffer and |
| image objects. |
| The pipe state i.e. contents of the pipe across kernel-instances (on the |
| same or different devices) is enforced at a synchronization point.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_pipe_object_queries"><a class="anchor" href="#_pipe_object_queries"></a>5.4.2. Pipe Object Queries</h4> |
| <div class="paragraph"> |
| <p>To get information that is common to all memory objects, use the |
| <a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a> function described in <a href="#memory-object-queries">Memory |
| Object Queries</a>.</p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To get information specific to a pipe object created with <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>, |
| call the function</p> |
| </div> |
| <div id="clGetPipeInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetPipeInfo( |
| cl_mem pipe, |
| cl_pipe_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clGetPipeInfo"><strong>clGetPipeInfo</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>pipe</em> specifies the pipe object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetPipeInfo"><strong>clGetPipeInfo</strong></a> is described in the <a href="#pipe-info-table">Pipe |
| Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#pipe-info-table">Pipe Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetPipeInfo"><strong>clGetPipeInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>pipe</em> is a not a valid pipe object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#pipe-info-table">Pipe Object Queries</a> table and <em>param_value</em> is |
| not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="pipe-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 23. List of supported param_names by <a href="#clGetPipeInfo">clGetPipeInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Pipe Info</th> |
| <th class="tableblock halign-left valign-top">Return type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PIPE_PACKET_SIZE"></a><a href="#CL_PIPE_PACKET_SIZE"><code>CL_PIPE_<wbr>PACKET_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return pipe packet size specified when <em>pipe</em> is created with |
| <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PIPE_MAX_PACKETS"></a><a href="#CL_PIPE_MAX_PACKETS"><code>CL_PIPE_<wbr>MAX_<wbr>PACKETS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return max. number of packets specified when <em>pipe</em> is created with |
| <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PIPE_PROPERTIES"></a><a href="#CL_PIPE_PROPERTIES"><code>CL_PIPE_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_pipe_<wbr>properties</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreatePipe"><strong>clCreatePipe</strong></a> used to |
| create <em>pipe</em> was not <code>NULL</code>, the implementation must return the |
| values specified in the properties argument in the same order and |
| without including additional properties.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreatePipe"><strong>clCreatePipe</strong></a> used to |
| create <em>pipe</em> was <code>NULL</code>, the implementation must return |
| <em>param_value_size_ret</em> equal to 0, indicating that there are no |
| properties to be returned.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_querying_unmapping_migrating_retaining_and_releasing_memory_objects"><a class="anchor" href="#_querying_unmapping_migrating_retaining_and_releasing_memory_objects"></a>5.5. Querying, Unmapping, Migrating, Retaining and Releasing Memory Objects</h3> |
| <div class="sect3"> |
| <h4 id="_retaining_and_releasing_memory_objects"><a class="anchor" href="#_retaining_and_releasing_memory_objects"></a>5.5.1. Retaining and Releasing Memory Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a memory object, call the function</p> |
| </div> |
| <div id="clRetainMemObject" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainMemObject( |
| cl_mem memobj);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>memobj</em> specifies the memory object to be retained.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>memobj</em> reference count is incremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainMemObject"><strong>clRetainMemObject</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>memobj</em> is not a valid memory object (buffer |
| or image object).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>, <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>, |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, |
| <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a> and <a href="#clCreatePipe"><strong>clCreatePipe</strong></a> perform an implicit retain.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a memory object, call the function</p> |
| </div> |
| <div id="clReleaseMemObject" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseMemObject( |
| cl_mem memobj);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>memobj</em> specifies the memory object to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>memobj</em> reference count is decremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseMemObject"><strong>clReleaseMemObject</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>memobj</em> is not a valid memory object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>After the <em>memobj</em> reference count becomes zero and commands queued for |
| execution on a command-queue(s) that use <em>memobj</em> have finished, the memory |
| object is deleted. |
| If <em>memobj</em> is a buffer object, <em>memobj</em> cannot be deleted until all |
| sub-buffer objects associated with <em>memobj</em> are deleted. |
| Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainMemObject"><strong>clRetainMemObject</strong></a> causes undefined behavior.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To register a callback function with a memory object that is called when |
| the memory object is destroyed, call the function</p> |
| </div> |
| <div id="clSetMemObjectDestructorCallback" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetMemObjectDestructorCallback( |
| cl_mem memobj, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_mem memobj, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetMemObjectDestructorCallback"><strong>clSetMemObjectDestructorCallback</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>memobj</em> specifies the memory object to register the callback to.</p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is the callback function to register. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the application’s responsibility to ensure that the callback function |
| is thread-safe. |
| The parameters to this callback function are:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>memobj</em> is the memory object being deleted. |
| When the callback function is called by the implementation, this memory |
| object is not longer valid. |
| <em>memobj</em> is only provided for reference purposes.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> is a pointer to user-supplied data.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is |
| called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Each call to <a href="#clSetMemObjectDestructorCallback"><strong>clSetMemObjectDestructorCallback</strong></a> registers the specified |
| callback function on a destructor callback stack associated with <em>memobj</em>. |
| The registered callback functions are called in the reverse order in |
| which they were registered. |
| The registered callback functions are called and then the memory object’s |
| resources are freed and the memory object is deleted. |
| Therefore, the memory object destructor callback provides a mechanism for |
| an application to safely re-use or free a <em>host_ptr</em> that was specified when |
| <em>memobj</em> was created and used as the storage bits for the memory object.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetMemObjectDestructorCallback"><strong>clSetMemObjectDestructorCallback</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is |
| executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>memobj</em> is not a valid memory object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>When the user callback function is called by the implementation, the |
| contents of the memory region pointed to by <em>host_ptr</em> (if the memory object |
| is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>) are undefined. |
| The callback function is typically used by the application to either free or |
| reuse the memory region pointed to by <em>host_ptr</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The behavior of calling expensive system routines, OpenCL API calls to |
| create contexts or command-queues, or blocking OpenCL operations from the |
| following list below, in a callback is undefined.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clFinish"><strong>clFinish</strong></a>,</p> |
| </li> |
| <li> |
| <p><a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a>,</p> |
| </li> |
| <li> |
| <p>blocking calls to <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a>, <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a>, |
| <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a>, <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a>,</p> |
| </li> |
| <li> |
| <p>blocking calls to <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a>,</p> |
| </li> |
| <li> |
| <p>blocking calls to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>,</p> |
| </li> |
| <li> |
| <p>blocking calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or |
| <a href="#clLinkProgram"><strong>clLinkProgram</strong></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If an application needs to wait for completion of a routine from the above |
| list in a callback, please use the non-blocking form of the function, and |
| assign a completion callback to it to do the remainder of your work. |
| Note that when a callback (or other code) enqueues commands to a |
| command-queue, the commands are not required to begin execution until the |
| queue is flushed. |
| In standard usage, blocking enqueue calls serve this role by implicitly |
| flushing the queue. |
| Since blocking calls are not permitted in callbacks, those callbacks that |
| enqueue commands on a command queue should either call <a href="#clFlush"><strong>clFlush</strong></a> on the |
| queue before returning or arrange for <a href="#clFlush"><strong>clFlush</strong></a> to be called later on |
| another thread.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The user callback function may not call OpenCL APIs with the memory object |
| for which the callback function is invoked and for such cases the behavior |
| of OpenCL APIs is considered to be undefined.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="unmapping-mapped-memory"><a class="anchor" href="#unmapping-mapped-memory"></a>5.5.2. Unmapping Mapped Memory Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to unmap a previously mapped region of a memory object, |
| call the function</p> |
| </div> |
| <div id="clEnqueueUnmapMemObject" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueUnmapMemObject( |
| cl_command_queue command_queue, |
| cl_mem memobj, |
| <span class="directive">void</span>* mapped_ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>memobj</em> is a valid memory (buffer or image) object. |
| The OpenCL context associated with <em>command_queue</em> and <em>memobj</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>mapped_ptr</em> is the host address returned by a previous call to |
| <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> for <em>memobj</em>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Reads or writes from the host using the pointer returned by |
| <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> are considered to be complete.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> increment the mapped count of |
| the memory object. |
| The initial mapped count value of the memory object is zero. |
| Multiple calls to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> on the same |
| memory object will increment this mapped count by appropriate number of |
| calls. |
| <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> decrements the mapped count of the memory object.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, and <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> act as synchronization points |
| for a region of the buffer object being mapped.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>memobj</em> is not a valid memory object or is a |
| pipe object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>mapped_ptr</em> is not a valid pointer returned by |
| <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> for <em>memobj</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or if <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and |
| <em>memobj</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="accessing-mapped-regions"><a class="anchor" href="#accessing-mapped-regions"></a>5.5.3. Accessing mapped regions of a memory object</h4> |
| <div class="paragraph"> |
| <p>This section describes the behavior of OpenCL commands that access mapped |
| regions of a memory object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The contents of the region of a memory object and associated memory objects |
| (sub-buffer objects or 1D image buffer objects that overlap this region) |
| mapped for writing (i.e. <a href="#CL_MAP_WRITE"><code>CL_MAP_<wbr>WRITE</code></a> or <a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_MAP_<wbr>WRITE_<wbr>INVALIDATE_<wbr>REGION</code></a> is |
| set in <em>map_flags</em> argument to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) |
| are considered to be undefined until this region is unmapped.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Multiple commands in command-queues can map a region or overlapping regions |
| of a memory object and associated memory objects (sub-buffer objects or 1D |
| image buffer objects that overlap this region) for reading (i.e. <em>map_flags</em> |
| = <a href="#CL_MAP_READ"><code>CL_MAP_<wbr>READ</code></a>). |
| The contents of the regions of a memory object mapped for reading can also |
| be read by kernels and other OpenCL commands (such as <a href="#clEnqueueCopyBuffer"><strong>clEnqueueCopyBuffer</strong></a>) |
| executing on a device(s).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Mapping (and unmapping) overlapped regions in a memory object and/or |
| associated memory objects (sub-buffer objects or 1D image buffer objects |
| that overlap this region) for writing is an error and will result in |
| <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> error returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, or |
| <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a memory object is currently mapped for writing, the application must |
| ensure that the memory object is unmapped before any enqueued kernels or |
| commands that read from or write to this memory object or any of its |
| associated memory objects (sub-buffer or 1D image buffer objects) or its |
| parent object (if the memory object is a sub-buffer or 1D image buffer |
| object) begin execution; otherwise the behavior is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a memory object is currently mapped for reading, the application must |
| ensure that the memory object is unmapped before any enqueued kernels or |
| commands that write to this memory object or any of its associated memory |
| objects (sub-buffer or 1D image buffer objects) or its parent object (if the |
| memory object is a sub-buffer or 1D image buffer object) begin execution; |
| otherwise the behavior is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A memory object is considered as mapped if there are one or more active |
| mappings for the memory object irrespective of whether the mapped regions |
| span the entire memory object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Accessing the contents of the memory region referred to by the mapped |
| pointer that has been unmapped is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The mapped pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> |
| can be used as the <em>ptr</em> argument value to <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a>, |
| <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a>, <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a>, |
| <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a>, <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a>, or |
| <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> provided the rules described above are adhered to.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_migrating_memory_objects"><a class="anchor" href="#_migrating_memory_objects"></a>5.5.4. Migrating Memory Objects</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Migrating memory objects is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>This section describes a mechanism for assigning which device an OpenCL |
| memory object resides. |
| A user may wish to have more explicit control over the location of their |
| memory objects on creation. |
| This could be used to:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ensure that an object is allocated on a specific device prior to usage.</p> |
| </li> |
| <li> |
| <p>Preemptively migrate an object from one device to another.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to indicate which device a set of memory objects should |
| be associated with, call the function</p> |
| </div> |
| <div id="clEnqueueMigrateMemObjects" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueMigrateMemObjects( |
| cl_command_queue command_queue, |
| cl_uint num_mem_objects, |
| <span class="directive">const</span> cl_mem* mem_objects, |
| cl_mem_migration_flags flags, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue. |
| The specified set of memory objects in <em>mem_objects</em> will be migrated to the |
| OpenCL device associated with <em>command_queue</em> or to the host if the |
| <a href="#CL_MIGRATE_MEM_OBJECT_HOST"><code>CL_MIGRATE_<wbr>MEM_<wbr>OBJECT_<wbr>HOST</code></a> has been specified.</p> |
| </li> |
| <li> |
| <p><em>num_mem_objects</em> is the number of memory objects specified in |
| <em>mem_objects</em>.</p> |
| </li> |
| <li> |
| <p><em>mem_objects</em> is a pointer to a list of memory objects.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify migration options. |
| The <a href="#migration-flags-table">Memory Migration Flags</a> describes the possible |
| values for flags.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="migration-flags-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 24. List of supported migration flags by <a href="#clEnqueueMigrateMemObjects">clEnqueueMigrateMemObjects</a></caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Memory Migration Flags</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MIGRATE_MEM_OBJECT_HOST"></a><a href="#CL_MIGRATE_MEM_OBJECT_HOST"><code>CL_MIGRATE_<wbr>MEM_<wbr>OBJECT_<wbr>HOST</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag indicates that the specified set of memory objects are to be |
| migrated to the host, regardless of the target command-queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED"></a><a href="#CL_MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED"><code>CL_MIGRATE_<wbr>MEM_<wbr>OBJECT_<wbr>CONTENT_<wbr>UNDEFINED</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag indicates that the contents of the set of memory objects are |
| undefined after migration. |
| The specified set of memory objects are migrated to the device |
| associated with <em>command_queue</em> without incurring the overhead of |
| migrating their contents.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Typically, memory objects are implicitly migrated to a device for which |
| enqueued commands, using the memory object, are targeted. |
| <a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a> allows this migration to be explicitly |
| performed ahead of the dependent commands. |
| This allows a user to preemptively change the association of a memory |
| object, through regular command queue scheduling, in order to prepare for |
| another upcoming command. |
| This also permits an application to overlap the placement of memory objects |
| with other unrelated operations before these memory objects are needed |
| potentially hiding transfer latencies. |
| Once the event, returned from <a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a>, has been marked |
| CL_COMPLETE the memory objects specified in <em>mem_objects</em> have been |
| successfully migrated to the device associated with <em>command_queue</em>. |
| The migrated memory object shall remain resident on the device until another |
| command is enqueued that either implicitly or explicitly migrates it away.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a> can also be used to direct the initial |
| placement of a memory object, after creation, possibly avoiding the initial |
| overhead of instantiating the object on the first enqueued command to use |
| it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The user is responsible for managing the event dependencies, associated with |
| this command, in order to avoid overlapping access to memory objects. |
| Improperly specified event dependencies passed to |
| <a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a> could result in undefined results.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a> return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| memory objects in <em>mem_objects</em> are not the same or if the context |
| associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not |
| the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if any of the memory objects in <em>mem_objects</em> is |
| not a valid memory object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_mem_objects</em> is zero or if <em>mem_objects</em> is |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>flags</em> is not 0 or is not any of the values |
| described in the table above.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for the specified set of memory objects in <em>mem_objects</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="memory-object-queries"><a class="anchor" href="#memory-object-queries"></a>5.5.5. Memory Object Queries</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To get information that is common to all memory objects (buffer and image |
| objects), call the function</p> |
| </div> |
| <div id="clGetMemObjectInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetMemObjectInfo( |
| cl_mem memobj, |
| cl_mem_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>memobj</em> specifies the memory object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a> is described in the |
| <a href="#mem-info-table">Memory Object Info</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#mem-info-table">Memory Object Info</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="mem-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 25. List of supported param_names by <a href="#clGetMemObjectInfo">clGetMemObjectInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Memory Object Info</th> |
| <th class="tableblock halign-left valign-top">Return type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_TYPE"></a><a href="#CL_MEM_TYPE"><code>CL_MEM_<wbr>TYPE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_mem_<wbr>object_<wbr>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns one of the following values:</p> |
| <p class="tableblock"> <a id="CL_MEM_OBJECT_BUFFER"></a><a href="#CL_MEM_OBJECT_BUFFER"><code>CL_MEM_<wbr>OBJECT_<wbr>BUFFER</code></a> if <em>memobj</em> is created with <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>, |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, or <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>.</p> |
| <p class="tableblock"> <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a> if <em>memobj</em> is created with <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>.</p> |
| <p class="tableblock"> <a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE3D</code></a> if <em>memobj</em> is created with <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>.</p> |
| <p class="tableblock"> The value of <em>image_desc</em>→<em>image_type</em> if <em>memobj</em> is created with |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a> or <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>.</p> |
| <p class="tableblock"> <a id="CL_MEM_OBJECT_PIPE"></a><a href="#CL_MEM_OBJECT_PIPE"><code>CL_MEM_<wbr>OBJECT_<wbr>PIPE</code></a> if <em>memobj</em> is created with <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_FLAGS"></a><a href="#CL_MEM_FLAGS"><code>CL_MEM_<wbr>FLAGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_mem_<wbr>flags</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the flags argument value specified when <em>memobj</em> is created |
| with <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>,<br> |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>,<br> |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>,<br> |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a>,<br> |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>,<br> |
| <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>,<br> |
| <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>, or<br> |
| <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>.</p> |
| <p class="tableblock"> If <em>memobj</em> is a sub-buffer the memory access qualifiers inherited |
| from parent buffer is also returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_SIZE"></a><a href="#CL_MEM_SIZE"><code>CL_MEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return actual size of the data store associated with <em>memobj</em> in |
| bytes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_PTR"></a><a href="#CL_MEM_HOST_PTR"><code>CL_MEM_<wbr>HOST_<wbr>PTR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>void</code>*</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">If <em>memobj</em> is created with <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>, <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or |
| <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>, and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> is specified in mem_flags, |
| return the host_ptr argument value specified when <em>memobj</em> is created.</p> |
| <p class="tableblock"> Otherwise, if <em>memobj</em> is created with <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>, and |
| <em>memobj</em> is created from a buffer that was created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> specified in mem_flags, return the host_ptr |
| passed to <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, plus |
| the origin value specified in buffer_create_info when <em>memobj</em> is |
| created.</p> |
| <p class="tableblock"> Otherwise, returns <code>NULL</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_MAP_COUNT"></a><a href="#CL_MEM_MAP_COUNT"><code>CL_MEM_<wbr>MAP_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_23" class="footnote" href="#_footnotedef_23" title="View footnote.">23</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Map count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_REFERENCE_COUNT"></a><a href="#CL_MEM_REFERENCE_COUNT"><code>CL_MEM_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_24" class="footnote" href="#_footnotedef_24" title="View footnote.">24</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return <em>memobj</em> reference count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_CONTEXT"></a><a href="#CL_MEM_CONTEXT"><code>CL_MEM_<wbr>CONTEXT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return context specified when memory object is created. |
| If <em>memobj</em> is created using <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>, the context |
| associated with the memory object specified as the <em>buffer</em> argument |
| to <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_ASSOCIATED_MEMOBJECT"></a><a href="#CL_MEM_ASSOCIATED_MEMOBJECT"><code>CL_MEM_<wbr>ASSOCIATED_<wbr>MEMOBJECT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_mem</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return memory object from which <em>memobj</em> is created.</p> |
| <p class="tableblock"> This returns the memory object specified as buffer argument to |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> if <em>memobj</em> is a subbuffer object created using |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>.</p> |
| <p class="tableblock"> This returns <em>image_desc</em>→<em>mem_object</em> if <em>memobj</em> |
| is an image object created using <a href="#clCreateImage"><strong>clCreateImage</strong></a> or |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>.</p> |
| <p class="tableblock"> Otherwise, returns <code>NULL</code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OFFSET"></a><a href="#CL_MEM_OFFSET"><code>CL_MEM_<wbr>OFFSET</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return offset if <em>memobj</em> is a sub-buffer object created using |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>.</p> |
| <p class="tableblock"> This return 0 if <em>memobj</em> is not a subbuffer object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_USES_SVM_POINTER"></a><a href="#CL_MEM_USES_SVM_POINTER"><code>CL_MEM_<wbr>USES_<wbr>SVM_<wbr>POINTER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return <a href="#CL_TRUE"><code>CL_TRUE</code></a> if <em>memobj</em> is a buffer object that was created with |
| <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> or is a sub-buffer object of a buffer object |
| that was created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> and the <em>host_ptr</em> |
| specified when the buffer object was created is a SVM pointer; |
| otherwise returns <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_PROPERTIES"></a><a href="#CL_MEM_PROPERTIES"><code>CL_MEM_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_mem_<wbr>properties</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> or <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> or <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> |
| used to create <em>memobj</em> was not <code>NULL</code>, the implementation must |
| return the values specified in the properties argument in the |
| same order and without including additional properties.</p> |
| <p class="tableblock"> If <em>memobj</em> was created using <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>, |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>, <a href="#clCreateImage"><strong>clCreateImage</strong></a>, <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, or |
| <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>, or if the <em>properties</em> argument specified |
| in <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> or |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> was <code>NULL</code>, the implementation |
| must return <em>param_value_size_ret</em> equal to 0, indicating that |
| there are no properties to be returned.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if <em>memobj</em> is a not a valid memory object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#mem-info-table">Memory Object Info</a> table and <em>param_value</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_shared_virtual_memory"><a class="anchor" href="#_shared_virtual_memory"></a>5.6. Shared Virtual Memory</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Shared virtual memory is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Shared virtual memory (a.k.a. SVM) allows the host and kernels executing on |
| devices to directly share complex, pointer-containing data structures such as |
| trees and linked lists. |
| It also eliminates the need to marshal data between the host and devices. |
| As a result, SVM substantially simplifies OpenCL programming and may improve |
| performance.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_svm_sharing_granularity_coarse_and_fine_grained_sharing"><a class="anchor" href="#_svm_sharing_granularity_coarse_and_fine_grained_sharing"></a>5.6.1. SVM sharing granularity: coarse- and fine- grained sharing</h4> |
| <div class="paragraph"> |
| <p>OpenCL maintains memory consistency in a coarse-grained fashion in regions |
| of buffers. |
| We call this coarse-grained sharing. |
| Many platforms such as those with integrated CPU-GPU processors and ones |
| using the SVM-related PCI-SIG IOMMU services can do better, and can support |
| sharing at a granularity smaller than a buffer. |
| We call this fine-grained sharing.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Coarse-grained sharing: Coarse-grain sharing may be used for memory and |
| virtual pointer sharing between multiple devices as well as between the |
| host and one or more devices. |
| The shared memory region is a memory buffer allocated using |
| <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>. |
| Memory consistency is guaranteed at synchronization points and the host |
| can use calls to <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> and <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> or create a |
| <code>cl_mem</code> buffer object using the SVM pointer and use OpenCL’s existing host |
| API functions <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> to |
| update regions of the buffer. |
| What coarse-grain buffer SVM adds to OpenCL’s earlier buffer support are |
| the ability to share virtual memory pointers and a guarantee that |
| concurrent access to the same memory allocation from multiple kernels on |
| a single device is valid. |
| The coarse-grain buffer SVM provides a memory consistency model similar |
| to the global memory consistency model described in <em>sections 3.3.1</em> and |
| <em>3.4.3</em> of the OpenCL 1.2 specification. |
| This memory consistency applies to the regions of buffers being shared |
| in a coarse-grained fashion. |
| It is enforced at the synchronization points between commands enqueued |
| to command queues in a single context with the additional consideration |
| that multiple kernels concurrently running on the same device may safely |
| share the data.</p> |
| </li> |
| <li> |
| <p>Fine-grained sharing: Shared virtual memory where memory consistency is |
| maintained at a granularity smaller than a buffer. |
| How fine-grained SVM is used depends on whether the device supports SVM |
| atomic operations.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If SVM atomic operations are supported, they provide memory consistency |
| for loads and stores by the host and kernels executing on devices |
| supporting SVM. |
| This means that the host and devices can concurrently read and update |
| the same memory. |
| The consistency provided by SVM atomics is in addition to the |
| consistency provided at synchronization points. |
| There is no need for explicit calls to <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> and |
| <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> or <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and |
| <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> on a <code>cl_mem</code> buffer object created using the |
| SVM pointer.</p> |
| </li> |
| <li> |
| <p>If SVM atomic operations are not supported, the host and devices can |
| concurrently read the same memory locations and can concurrently update |
| non-overlapping memory regions, but attempts to update the same memory |
| locations are undefined. |
| Memory consistency is guaranteed at synchronization points without the |
| need for explicit calls to <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> and <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> |
| or <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> on a <code>cl_mem</code> |
| buffer object created using the SVM pointer.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>There are two kinds of fine-grain sharing support. |
| Devices may support either fine-grain buffer sharing or fine-grain |
| system sharing.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Fine-grain buffer sharing provides fine-grain SVM only within buffers |
| and is an extension of coarse-grain sharing. |
| To support fine-grain buffer sharing in an OpenCL context, all devices |
| in the context must support <a href="#CL_DEVICE_SVM_FINE_GRAIN_BUFFER"><code>CL_DEVICE_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a>.</p> |
| </li> |
| <li> |
| <p>Fine-grain system sharing enables fine-grain sharing of the host’s |
| entire virtual memory, including memory regions allocated by the system |
| <strong>malloc</strong> API. |
| OpenCL buffer objects are unnecessary and programmers can pass pointers |
| allocated using <strong>malloc</strong> to OpenCL kernels.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>As an illustration of fine-grain SVM using SVM atomic operations to maintain |
| memory consistency, consider the following example. |
| The host and a set of devices can simultaneously access and update a shared |
| work-queue data structure holding work-items to be done. |
| The host can use atomic operations to insert new work-items into the queue |
| at the same time as the devices using similar atomic operations to remove |
| work-items for processing.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is the programmer’s responsibility to ensure that no host code or |
| executing kernels attempt to access a shared memory region after that memory |
| is freed. |
| We require the SVM implementation to work with either 32- or 64- bit host |
| applications subject to the following requirement: the address space size |
| must be the same for the host and all OpenCL devices in the context.</p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To allocate a shared virtual memory buffer (referred to as a SVM buffer) |
| that can be shared by the host and all devices in an OpenCL context that |
| support shared virtual memory, call the function</p> |
| </div> |
| <div id="clSVMAlloc" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span>* clSVMAlloc( |
| cl_context context, |
| cl_svm_mem_flags flags, |
| size_t size, |
| cl_uint alignment);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context used to create the SVM buffer.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify allocation and usage |
| information. |
| The <a href="#svm-flags-table">SVM Memory Flags</a> table describes the possible values |
| for <em>flags</em>.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of the SVM buffer to be allocated.</p> |
| </li> |
| <li> |
| <p><em>alignment</em> is the minimum alignment in bytes that is required for the newly |
| created buffers memory region. |
| It must be a power of two up to the largest data type supported by the |
| OpenCL device. |
| For the full profile, the largest data type is long16. |
| For the embedded profile, it is long16 if the device supports 64-bit |
| integers; otherwise it is int16. |
| If alignment is 0, a default alignment will be used that is equal to the |
| size of largest data type supported by the OpenCL implementation.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="svm-flags-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 26. List of supported SVM memory flag values</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">SVM Memory Flags</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the SVM buffer will be read and written by a |
| kernel. |
| This is the default.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the SVM buffer will be written but not read by |
| a kernel.</p> |
| <p class="tableblock"> Reading from a SVM buffer created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> inside a kernel |
| is undefined.</p> |
| <p class="tableblock"> <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> and <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> are mutually exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the SVM buffer object is a read-only memory |
| object when used inside a kernel.</p> |
| <p class="tableblock"> Writing to a SVM buffer created with <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> inside a kernel is |
| undefined.</p> |
| <p class="tableblock"> <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> and <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a> are mutually |
| exclusive.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_SVM_FINE_GRAIN_BUFFER"></a><a href="#CL_MEM_SVM_FINE_GRAIN_BUFFER"><code>CL_MEM_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This specifies that the application wants the OpenCL implementation to |
| do a fine-grained allocation.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_SVM_ATOMICS"></a><a href="#CL_MEM_SVM_ATOMICS"><code>CL_MEM_<wbr>SVM_<wbr>ATOMICS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag is valid only if <a href="#CL_MEM_SVM_FINE_GRAIN_BUFFER"><code>CL_MEM_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a> is specified in |
| flags. |
| It is used to indicate that SVM atomic operations can control visibility |
| of memory accesses in this SVM buffer.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>If <a href="#CL_MEM_SVM_FINE_GRAIN_BUFFER"><code>CL_MEM_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a> is not specified, the buffer can be created |
| as a coarse grained SVM allocation. |
| Similarly, if <a href="#CL_MEM_SVM_ATOMICS"><code>CL_MEM_<wbr>SVM_<wbr>ATOMICS</code></a> is not specified, the buffer can be created |
| without support for SVM atomic operations (refer to an OpenCL kernel |
| language specifications).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Calling <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> does not itself provide consistency for the shared |
| memory region. |
| When the host cannot use the SVM atomic operations, it must rely on OpenCL’s |
| guaranteed memory consistency at synchronization points.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For SVM to be used efficiently, the host and any devices sharing a buffer |
| containing virtual memory pointers should have the same endianness. |
| If the context passed to <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> has devices with mixed endianness and |
| the OpenCL implementation is unable to implement SVM because of that mixed |
| endianness, <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> will fail and return <code>NULL</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Although SVM is generally not supported for image objects, <a href="#clCreateImage"><strong>clCreateImage</strong></a> |
| and <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> |
| may create an image from a buffer (a 1D image from a buffer or a 2D image |
| from buffer) if the buffer specified in its image description parameter is a |
| SVM buffer. |
| Such images have a linear memory representation so their memory can be |
| shared using SVM. |
| However, fine grained sharing and atomics are not supported for image reads |
| and writes in a kernel.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> returns a valid non-<code>NULL</code> shared virtual memory address if the |
| SVM buffer is successfully allocated. |
| Otherwise, like <strong>malloc</strong>, it returns a <code>NULL</code> pointer value. |
| <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> will fail if</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is not a valid context, or no devices in <em>context</em> support SVM.</p> |
| </li> |
| <li> |
| <p><em>flags</em> does not contain <a href="#CL_MEM_SVM_FINE_GRAIN_BUFFER"><code>CL_MEM_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a> but does contain |
| <a href="#CL_MEM_SVM_ATOMICS"><code>CL_MEM_<wbr>SVM_<wbr>ATOMICS</code></a>.</p> |
| </li> |
| <li> |
| <p>Values specified in <em>flags</em> do not follow rules described for supported |
| values in the <a href="#svm-flags-table">SVM Memory Flags</a> table.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_SVM_FINE_GRAIN_BUFFER"><code>CL_MEM_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>BUFFER</code></a> or <a href="#CL_MEM_SVM_ATOMICS"><code>CL_MEM_<wbr>SVM_<wbr>ATOMICS</code></a> is specified in |
| <em>flags</em> and these are not supported by at least one device in <em>context</em>.</p> |
| </li> |
| <li> |
| <p>The values specified in <em>flags</em> are not valid, i.e. don’t match those |
| defined in the <a href="#svm-flags-table">SVM Memory Flags</a> table.</p> |
| </li> |
| <li> |
| <p><em>size</em> is 0 or > <a href="#CL_DEVICE_MAX_MEM_ALLOC_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>MEM_<wbr>ALLOC_<wbr>SIZE</code></a> value for any device in |
| <em>context</em>.</p> |
| </li> |
| <li> |
| <p><em>alignment</em> is not a power of two or the OpenCL implementation cannot |
| support the specified alignment for at least one device in <em>context</em>.</p> |
| </li> |
| <li> |
| <p>There was a failure to allocate resources.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To free a shared virtual memory buffer allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>, call |
| the function</p> |
| </div> |
| <div id="clSVMFree" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> clSVMFree( |
| cl_context context, |
| <span class="directive">void</span>* svm_pointer);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSVMFree"><strong>clSVMFree</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> is a valid OpenCL context used to create the SVM buffer. |
| If no devices in <em>context</em> support SVM, no action occurs.</p> |
| </li> |
| <li> |
| <p><em>svm_pointer</em> must be the value returned by a call to <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>. |
| If a <code>NULL</code> pointer is passed in <em>svm_pointer</em>, no action occurs.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note that <a href="#clSVMFree"><strong>clSVMFree</strong></a> does not wait for previously enqueued commands that |
| may be using <em>svm_pointer</em> to finish before freeing <em>svm_pointer</em>. |
| It is the responsibility of the application to make sure that enqueued |
| commands that use <em>svm_pointer</em> have finished before freeing <em>svm_pointer</em>. |
| This can be done by enqueuing a blocking operation such as <a href="#clFinish"><strong>clFinish</strong></a>, |
| <a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a>, <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> or by registering a callback with |
| the events associated with enqueued commands and when the last enqueued |
| command has finished freeing <em>svm_pointer</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The behavior of using <em>svm_pointer</em> after it has been freed is undefined. |
| In addition, if a buffer object is created using <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> with <em>svm_pointer</em>, the buffer object must |
| first be released before the <em>svm_pointer</em> is freed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> API can also be used to enqueue a callback to free |
| the shared virtual memory buffer allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> or a shared |
| system memory pointer.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to free the shared virtual memory allocated using |
| <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> or a shared system memory pointer, call the function</p> |
| </div> |
| <div id="clEnqueueSVMFree" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueSVMFree( |
| cl_command_queue command_queue, |
| cl_uint num_svm_pointers, |
| <span class="directive">void</span>* svm_pointers[], |
| <span class="directive">void</span> (CL_CALLBACK* pfn_free_func)(cl_command_queue queue, cl_uint num_svm_pointers, <span class="directive">void</span>* svm_pointers[], <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>svm_pointers</em> and <em>num_svm_pointers</em> specify shared virtual memory pointers |
| to be freed. |
| Each pointer in <em>svm_pointers</em> that was allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> must |
| have been allocated from the same context from which <em>command_queue</em> was |
| created. |
| The memory associated with <em>svm_pointers</em> can be reused or freed after the |
| function returns.</p> |
| </li> |
| <li> |
| <p><em>pfn_free_func</em> specifies the callback function to be called to free the SVM |
| pointers. |
| <em>pfn_free_func</em> takes four arguments: <em>queue</em> which is the command queue in |
| which <a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> was enqueued, the count and list of SVM pointers to |
| free and <em>user_data</em> which is a pointer to user specified data. |
| If <em>pfn_free_func</em> is <code>NULL</code>, all pointers specified in <em>svm_pointers</em> must |
| be allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> and the OpenCL implementation will free |
| these SVM pointers. |
| <em>pfn_free_func</em> must be a valid callback function if any SVM pointer to be |
| freed is a shared system memory pointer i.e. not allocated using |
| <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>. |
| If <em>pfn_free_func</em> is a valid callback function, the OpenCL implementation |
| will call <em>pfn_free_func</em> to free all the SVM pointers specified in |
| <em>svm_pointers</em>.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_free_func</em> |
| is called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before <a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then <a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> does not wait on any |
| event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command queue</em> does not support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_svm_pointers</em> is 0 and <em>svm_pointers</em> is |
| non-<code>NULL</code>, <em>or</em> if <em>svm_pointers</em> is <code>NULL</code> and <em>num_svm_pointers</em> is |
| not 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to do a memcpy operation, call the function</p> |
| </div> |
| <div id="clEnqueueSVMMemcpy" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueSVMMemcpy( |
| cl_command_queue command_queue, |
| cl_bool blocking_copy, |
| <span class="directive">void</span>* dst_ptr, |
| <span class="directive">const</span> <span class="directive">void</span>* src_ptr, |
| size_t size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the read / write |
| command will be queued. |
| If either <em>dst_ptr</em> or <em>src_ptr</em> is allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> then the |
| OpenCL context allocated against must match that of <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><em>blocking_copy</em> indicates if the copy operation is <em>blocking</em> or |
| <em>non-blocking</em>.</p> |
| </li> |
| <li> |
| <p>If <em>blocking_copy</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a> i.e. the copy command is blocking, |
| <a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a> does not return until the buffer data has been copied |
| into memory pointed to by <em>dst_ptr</em>.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of data being copied.</p> |
| </li> |
| <li> |
| <p><em>dst_ptr</em> is the pointer to a host or SVM memory allocation where data is |
| copied to.</p> |
| </li> |
| <li> |
| <p><em>src_ptr</em> is the pointer to a host or SVM memory allocation where data is |
| copied from.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this read / write command |
| and can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_copy</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. the copy command is non-blocking, |
| <a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a> queues a non-blocking copy command and returns. |
| The contents of the buffer that <em>dst_ptr</em> points to cannot be used until the |
| copy command has completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the read command. |
| When the copy command has completed, the contents of the buffer that |
| <em>dst_ptr</em> points to can be used by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the memory allocation(s) containing <em>dst_ptr</em> and/or <em>src_ptr</em> are |
| allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> and either is not allocated from the same |
| context from which <em>command_queue</em> was created the behavior is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command queue</em> does not support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the copy operation is |
| blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>dst_ptr</em> or <em>src_ptr</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_MEM_<wbr>COPY_<wbr>OVERLAP</code></a> if the values specified for <em>dst_ptr</em>, <em>src_ptr</em> and |
| <em>size</em> result in an overlapping copy.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to fill a region in memory with a pattern of a given |
| pattern size, call the function</p> |
| </div> |
| <div id="clEnqueueSVMMemFill" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueSVMMemFill( |
| cl_command_queue command_queue, |
| <span class="directive">void</span>* svm_ptr, |
| <span class="directive">const</span> <span class="directive">void</span>* pattern, |
| size_t pattern_size, |
| size_t size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueSVMMemFill"><strong>clEnqueueSVMMemFill</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> refers to the host command-queue in which the fill command |
| will be queued. |
| The OpenCL context associated with <em>command_queue</em> and SVM pointer referred |
| to by <em>svm_ptr</em> must be the same.</p> |
| </li> |
| <li> |
| <p><em>svm_ptr</em> is a pointer to a memory region that will be filled with |
| <em>pattern</em>. |
| It must be aligned to <em>pattern_size</em> bytes. |
| If <em>svm_ptr</em> is allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> then it must be allocated from |
| the same context from which <em>command_queue</em> was created. |
| Otherwise the behavior is undefined.</p> |
| </li> |
| <li> |
| <p><em>pattern</em> is a pointer to the data pattern of size <em>pattern_size</em> in bytes. |
| <em>pattern</em> will be used to fill a region in <em>buffer</em> starting at <em>svm_ptr</em> |
| and is <em>size</em> bytes in size. |
| The data pattern must be a scalar or vector integer or floating-point data |
| type supported by OpenCL as described in <a href="#scalar-data-types">Shared |
| Application Scalar Data Types</a> and <a href="#vector-data-types">Supported |
| Application Vector Data Types</a>. |
| For example, if region pointed to by <em>svm_ptr</em> is to be filled with a |
| pattern of float4 values, then <em>pattern</em> will be a pointer to a cl_float4 |
| value and <em>pattern_size</em> will be <code>sizeof(cl_float4)</code>. |
| The maximum value of <em>pattern_size</em> is the size of the largest integer or |
| floating-point vector data type supported by the OpenCL device. |
| The memory associated with <em>pattern</em> can be reused or freed after the |
| function returns.</p> |
| </li> |
| <li> |
| <p><em>size</em> is the size in bytes of region being filled starting with <em>svm_ptr</em> |
| and must be a multiple of <em>pattern_size</em>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMMemFill"><strong>clEnqueueSVMMemFill</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command queue</em> does not support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if the context associated with <em>command_queue</em> and |
| events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>svm_ptr</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>svm_ptr</em> is not aligned to <em>pattern_size</em> bytes.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pattern</em> is <code>NULL</code> or if <em>pattern_size</em> is 0 or if |
| <em>pattern_size</em> is not one of {1, 2, 4, 8, 16, 32, 64, 128}.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>size</em> is not a multiple of <em>pattern_size</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command that will allow the host to update a region of a SVM |
| buffer, call the function</p> |
| </div> |
| <div id="clEnqueueSVMMap" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueSVMMap( |
| cl_command_queue command_queue, |
| cl_bool blocking_map, |
| cl_map_flags flags, |
| <span class="directive">void</span>* svm_ptr, |
| size_t size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>blocking_map</em> indicates if the map operation is <em>blocking</em> or |
| <em>non-blocking</em>.</p> |
| </li> |
| <li> |
| <p><em>map_flags</em> is a bit-field and is described in the |
| <a href="#memory-map-flags-table">Memory Map Flags</a> table.</p> |
| </li> |
| <li> |
| <p><em>svm_ptr</em> and <em>size</em> are a pointer to a memory region and size in bytes that |
| will be updated by the host. |
| If <em>svm_ptr</em> is allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> then it must be allocated from |
| the same context from which <em>command_queue</em> was created. |
| Otherwise the behavior is undefined.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_map</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> does not return until the |
| application can access the contents of the SVM region specified by <em>svm_ptr</em> |
| and <em>size</em> on the host.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>blocking_map</em> is <a href="#CL_FALSE"><code>CL_FALSE</code></a> i.e. map operation is non-blocking, the region |
| specified by <em>svm_ptr</em> and <em>size</em> cannot be used until the map command has |
| completed. |
| The <em>event</em> argument returns an event object which can be used to query the |
| execution status of the map command. |
| When the map command is completed, the application can access the contents |
| of the region specified by <em>svm_ptr</em> and <em>size</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that since we are enqueuing a command with a SVM buffer, the region is |
| already mapped in the host address space.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command queue</em> does not support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>svm_ptr</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>size</em> is 0 or if values specified in <em>map_flags</em> |
| are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the map operation is |
| blocking and the execution status of any of the events in |
| <em>event_wait_list</em> is a negative integer value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to indicate that the host has completed updating the |
| region given by <em>svm_ptr</em> and which was specified in a previous call to |
| <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a>, call the function</p> |
| </div> |
| <div id="clEnqueueSVMUnmap" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueSVMUnmap( |
| cl_command_queue command_queue, |
| <span class="directive">void</span>* svm_ptr, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> must be a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>svm_ptr</em> is a pointer that was specified in a previous call to |
| <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a>. |
| If <em>svm_ptr</em> is allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> then it must be allocated from |
| the same context from which <em>command_queue</em> was created. |
| Otherwise the behavior is undefined.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> does not wait on any |
| event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> and <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> act as synchronization points for |
| the region of the SVM buffer specified in these calls.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command queue</em> does not support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>svm_ptr</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or if <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>If a coarse-grained SVM buffer is currently mapped for writing, the |
| application must ensure that the SVM buffer is unmapped before any enqueued |
| kernels or commands that read from or write to this SVM buffer or any of its |
| associated <code>cl_mem</code> buffer objects begin execution; otherwise the behavior is |
| undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a coarse-grained SVM buffer is currently mapped for reading, the |
| application must ensure that the SVM buffer is unmapped before any enqueued |
| kernels or commands that write to this memory object or any of its |
| associated <code>cl_mem</code> buffer objects begin execution; otherwise the behavior is |
| undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A SVM buffer is considered as mapped if there are one or more active |
| mappings for the SVM buffer irrespective of whether the mapped regions span |
| the entire SVM buffer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The above note does not apply to fine-grained SVM buffers (fine-grained |
| buffers allocated using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> or fine-grained system allocations).</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to indicate which device a set of ranges of SVM |
| allocations should be associated with, call the function</p> |
| </div> |
| <div id="clEnqueueSVMMigrateMem" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueSVMMigrateMem( |
| cl_command_queue command_queue, |
| cl_uint num_svm_pointers, |
| <span class="directive">const</span> <span class="directive">void</span>** svm_pointers, |
| <span class="directive">const</span> size_t* sizes, |
| cl_mem_migration_flags flags, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command queue. |
| The specified set of allocation ranges will be migrated to the OpenCL device |
| associated with <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><em>num_svm_pointers</em> is the number of pointers in the specified <em>svm_pointers</em> |
| array, and the number of sizes in the <em>sizes</em> array, if <em>sizes</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><em>svm_pointers</em> is a pointer to an array of pointers. |
| Each pointer in this array must be within an allocation produced by a call |
| to <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>sizes</em> is an array of sizes. |
| The pair <em>svm_pointers</em>[i] and <em>sizes</em>[i] together define the starting |
| address and number of bytes in a range to be migrated. |
| <em>sizes</em> may be <code>NULL</code> indicating that every allocation containing any |
| <em>svm_pointer</em>[i] is to be migrated. |
| Also, if <em>sizes</em>[i] is zero, then the entire allocation containing |
| <em>svm_pointer</em>[i] is migrated.</p> |
| </li> |
| <li> |
| <p><em>flags</em> is a bit-field that is used to specify migration options. |
| The <a href="#migration-flags-table">Memory Migration Flags</a> describes the possible |
| values for <em>flags</em>.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or queue a wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Once the event returned by <a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a> has become <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>, |
| the ranges specified by svm pointers and sizes have been successfully |
| migrated to the device associated with command queue.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The user is responsible for managing the event dependencies associated with |
| this command in order to avoid overlapping access to SVM allocations. |
| Improperly specified event dependencies passed to <a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a> |
| could result in undefined results.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command queue</em> does not support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_svm_pointers</em> is zero or <em>svm_pointers</em> is |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>sizes</em>[i] is non-zero range [<em>svm_pointers</em>[i], |
| <em>svm_pointers</em>[i]+<em>sizes</em>[i]) is not contained within an existing |
| <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> allocation.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or if <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_memory_consistency_for_svm_allocations"><a class="anchor" href="#_memory_consistency_for_svm_allocations"></a>5.6.2. Memory consistency for SVM allocations</h4> |
| <div class="paragraph"> |
| <p>To ensure memory consistency in SVM allocations, the program can rely on the |
| guaranteed memory consistency at synchronization points. |
| This consistency support already exists in OpenCL 1.x and can be used for |
| coarse-grained SVM allocations or for fine-grained buffer SVM allocations; |
| what SVM adds is the ability to share pointers between the host and all SVM |
| devices.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition, sub-buffers can also be used to ensure that each device gets a |
| consistent view of a SVM buffers memory when it is shared by multiple |
| devices. |
| For example, assume that two devices share a SVM pointer. |
| The host can create a <code>cl_mem</code> buffer object using <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or |
| <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a> with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> and <em>host_ptr</em> set |
| to the SVM pointer and then create two disjoint sub-buffers with starting |
| virtual addresses <em>sb1_ptr</em> and <em>sb2_ptr</em>. |
| These pointers (<em>sb1_ptr</em> and <em>sb2_ptr</em>) can be passed to kernels executing |
| on the two devices. |
| <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a> and the existing |
| <a href="#accessing-mapped-regions">access rules for memory objects</a> ensure |
| consistency for buffer regions (<em>sb1_ptr</em> and <em>sb2_ptr</em>) read and written by |
| these kernels.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the host and devices are able to use SVM atomic operations (i.e. |
| <a href="#CL_DEVICE_SVM_ATOMICS"><code>CL_DEVICE_<wbr>SVM_<wbr>ATOMICS</code></a> is set in <a href="#CL_DEVICE_SVM_CAPABILITIES"><code>CL_DEVICE_<wbr>SVM_<wbr>CAPABILITIES</code></a>), these atomic |
| operations can be used to provide memory consistency at a fine grain in a |
| shared memory region. |
| The effect of these operations is visible to the host and all devices with |
| which that memory is shared.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_sampler_objects"><a class="anchor" href="#_sampler_objects"></a>5.7. Sampler Objects</h3> |
| <div class="paragraph"> |
| <p>A sampler object describes how to sample an image when the image is read in |
| the kernel. |
| The built-in functions to read from an image in a kernel take a sampler as |
| an argument. |
| The sampler arguments to the image read function can be sampler objects |
| created using OpenCL functions and passed as argument values to the kernel |
| or can be samplers declared inside a kernel. |
| In this section we discuss how sampler objects are created using OpenCL |
| functions.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_sampler_objects"><a class="anchor" href="#_creating_sampler_objects"></a>5.7.1. Creating Sampler Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a sampler object, call the function</p> |
| </div> |
| <div id="clCreateSamplerWithProperties" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_sampler clCreateSamplerWithProperties( |
| cl_context context, |
| <span class="directive">const</span> cl_sampler_properties* sampler_properties, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>sampler_properties</em> specifies a list of sampler property names and their |
| corresponding values. |
| Each sampler property name is immediately followed by the corresponding |
| desired value. |
| The list is terminated with 0. |
| The list of supported properties is described in the |
| <a href="#sampler-properties-table">Sampler Properties</a> table. |
| If a supported property and its value is not specified in |
| <em>sampler_properties</em>, its default value will be used. |
| <em>sampler_properties</em> can be <code>NULL</code> in which case the default values for |
| supported sampler properties will be used.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="sampler-properties-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 27. List of supported sampler creation properties by <a href="#clCreateSamplerWithProperties">clCreateSamplerWithProperties</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Sampler Property</th> |
| <th class="tableblock halign-left valign-top">Property Value</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_NORMALIZED_COORDS"></a><a href="#CL_SAMPLER_NORMALIZED_COORDS"><code>CL_SAMPLER_<wbr>NORMALIZED_<wbr>COORDS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A boolean value that specifies whether the image coordinates |
| specified are normalized or not.</p> |
| <p class="tableblock"> The default value (i.e. the value used if this property is not |
| specified in sampler_properties) is <a href="#CL_TRUE"><code>CL_TRUE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_ADDRESSING_MODE"></a><a href="#CL_SAMPLER_ADDRESSING_MODE"><code>CL_SAMPLER_<wbr>ADDRESSING_<wbr>MODE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_addressing_<wbr>mode</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how out-of-range image coordinates are handled when |
| reading from an image. |
| Valid values are:</p> |
| <p class="tableblock"> <a id="CL_ADDRESS_NONE"></a><a href="#CL_ADDRESS_NONE"><code>CL_ADDRESS_<wbr>NONE</code></a> - Behavior is undefined for out-of-range |
| image coordinates.</p> |
| <p class="tableblock"> <a id="CL_ADDRESS_CLAMP_TO_EDGE"></a><a href="#CL_ADDRESS_CLAMP_TO_EDGE"><code>CL_ADDRESS_<wbr>CLAMP_<wbr>TO_<wbr>EDGE</code></a> - Out-of-range image coordinates |
| are clamped to the edge of the image.</p> |
| <p class="tableblock"> <a id="CL_ADDRESS_CLAMP"></a><a href="#CL_ADDRESS_CLAMP"><code>CL_ADDRESS_<wbr>CLAMP</code></a> - Out-of-range image coordinates are |
| assigned a border color value.</p> |
| <p class="tableblock"> <a id="CL_ADDRESS_REPEAT"></a><a href="#CL_ADDRESS_REPEAT"><code>CL_ADDRESS_<wbr>REPEAT</code></a> - Out-of-range image coordinates read |
| from the image as-if the image data were replicated in all dimensions.</p> |
| <p class="tableblock"> <a id="CL_ADDRESS_MIRRORED_REPEAT"></a><a href="#CL_ADDRESS_MIRRORED_REPEAT"><code>CL_ADDRESS_<wbr>MIRRORED_<wbr>REPEAT</code></a> - Out-of-range image coordinates |
| read from the image as-if the image data were replicated in all |
| dimensions, mirroring the image contents at the edge of each |
| replication.</p> |
| <p class="tableblock"> The default is <a href="#CL_ADDRESS_CLAMP"><code>CL_ADDRESS_<wbr>CLAMP</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_FILTER_MODE"></a><a href="#CL_SAMPLER_FILTER_MODE"><code>CL_SAMPLER_<wbr>FILTER_<wbr>MODE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_filter_<wbr>mode</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the type of filter that is applied when reading an |
| image. |
| Valid values are:</p> |
| <p class="tableblock"> <a id="CL_FILTER_NEAREST"></a><a href="#CL_FILTER_NEAREST"><code>CL_FILTER_<wbr>NEAREST</code></a> - Returns the image element nearest |
| to the image coordinate.</p> |
| <p class="tableblock"> <a id="CL_FILTER_LINEAR"></a><a href="#CL_FILTER_LINEAR"><code>CL_FILTER_<wbr>LINEAR</code></a> - Returns a weighted average of the |
| four image elements nearest to the image coordinate.</p> |
| <p class="tableblock"> The default value is <a href="#CL_FILTER_NEAREST"><code>CL_FILTER_<wbr>NEAREST</code></a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a> returns a valid non-zero sampler object and |
| <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the sampler object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the property name in <em>sampler_properties</em> is not a |
| supported property name, if the value specified for a supported property |
| name is not valid, or if the same property name is specified more than |
| once.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if images are not supported by any device |
| associated with <em>context</em> (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a sampler object, call the function</p> |
| </div> |
| <div id="clCreateSampler" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_sampler clCreateSampler( |
| cl_context context, |
| cl_bool normalized_coords, |
| cl_addressing_mode addressing_mode, |
| cl_filter_mode filter_mode, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateSampler"><strong>clCreateSampler</strong></a> is <a href="#unified-spec">deprecated by</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>normalized_coords</em> has the same interpretation as |
| <a href="#CL_SAMPLER_NORMALIZED_COORDS"><code>CL_SAMPLER_<wbr>NORMALIZED_<wbr>COORDS</code></a> in the <a href="#sampler-properties-table">sampler |
| creation properties table</a>.</p> |
| </li> |
| <li> |
| <p><em>addressing_mode</em> has the same interpretation as |
| <a href="#CL_SAMPLER_ADDRESSING_MODE"><code>CL_SAMPLER_<wbr>ADDRESSING_<wbr>MODE</code></a> in the <a href="#sampler-properties-table">sampler |
| creation properties table</a>.</p> |
| </li> |
| <li> |
| <p><em>filter_mode</em> has the same interpretation as |
| <a href="#CL_SAMPLER_FILTER_MODE"><code>CL_SAMPLER_<wbr>FILTER_<wbr>MODE</code></a> in the <a href="#sampler-properties-table">sampler |
| creation properties table</a>.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateSampler"><strong>clCreateSampler</strong></a> returns a valid non-zero sampler object and <em>errcode_ret</em> is |
| set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the sampler object is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>addressing_mode</em>, <em>filter_mode</em>, <em>normalized_coords</em> |
| or a combination of these arguements are not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if images are not supported by any device |
| associated with <em>context</em> (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_FALSE</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a sampler object, call the function</p> |
| </div> |
| <div id="clRetainSampler" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainSampler( |
| cl_sampler sampler);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>sampler</em> specifies the sampler to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>sampler</em> reference count is incremented. |
| <a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a> and <a href="#clCreateSampler"><strong>clCreateSampler</strong></a> perform an implicit |
| retain.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainSampler"><strong>clRetainSampler</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_SAMPLER"><code>CL_INVALID_<wbr>SAMPLER</code></a> if <em>sampler</em> is not a valid sampler object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a sampler object, call the function</p> |
| </div> |
| <div id="clReleaseSampler" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseSampler( |
| cl_sampler sampler);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>sampler</em> specifies the sampler to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>sampler</em> reference count is decremented. |
| The sampler object is deleted after the reference count becomes zero and |
| commands queued for execution on a command-queue(s) that use <em>sampler</em> have |
| finished.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseSampler"><strong>clReleaseSampler</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_SAMPLER"><code>CL_INVALID_<wbr>SAMPLER</code></a> if <em>sampler</em> is not a valid sampler object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainSampler"><strong>clRetainSampler</strong></a> causes undefined behavior.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_sampler_object_queries"><a class="anchor" href="#_sampler_object_queries"></a>5.7.2. Sampler Object Queries</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about a sampler object, call the function</p> |
| </div> |
| <div id="clGetSamplerInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetSamplerInfo( |
| cl_sampler sampler, |
| cl_sampler_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>sampler</em> specifies the sampler being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetSamplerInfo"><strong>clGetSamplerInfo</strong></a> is described in the |
| <a href="#sampler-info-table">Sampler Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#sampler-info-table">Sampler Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="sampler-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 28. List of supported param_names by <a href="#clGetSamplerInfo">clGetSamplerInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Sampler Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_REFERENCE_COUNT"></a><a href="#CL_SAMPLER_REFERENCE_COUNT"><code>CL_SAMPLER_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_25" class="footnote" href="#_footnotedef_25" title="View footnote.">25</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the <em>sampler</em> reference count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_CONTEXT"></a><a href="#CL_SAMPLER_CONTEXT"><code>CL_SAMPLER_<wbr>CONTEXT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the context specified when the sampler is created.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_NORMALIZED_COORDS"></a><a href="#CL_SAMPLER_NORMALIZED_COORDS"><code>CL_SAMPLER_<wbr>NORMALIZED_<wbr>COORDS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the normalized coords value associated with <em>sampler</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_ADDRESSING_MODE"></a><a href="#CL_SAMPLER_ADDRESSING_MODE"><code>CL_SAMPLER_<wbr>ADDRESSING_<wbr>MODE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_addressing_<wbr>mode</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the addressing mode value associated with <em>sampler</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_FILTER_MODE"></a><a href="#CL_SAMPLER_FILTER_MODE"><code>CL_SAMPLER_<wbr>FILTER_<wbr>MODE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_filter_<wbr>mode</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the filter mode value associated with <em>sampler</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SAMPLER_PROPERTIES"></a><a href="#CL_SAMPLER_PROPERTIES"><code>CL_SAMPLER_<wbr>PROPERTIES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_sampler_<wbr>properties</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in |
| <a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a>.</p> |
| <p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a> |
| used to create <em>sampler</em> was not <code>NULL</code>, the implementation must return |
| the values specified in the properties argument in the same order and |
| without including additional properties.</p> |
| <p class="tableblock"> If <em>sampler</em> was created using <a href="#clCreateSampler"><strong>clCreateSampler</strong></a>, or if the <em>properties</em> |
| argument specified in <a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a> was <code>NULL</code>, the |
| implementation must return <em>param_value_size_ret</em> equal to 0, |
| indicating that there are no properties to be returned.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetSamplerInfo"><strong>clGetSamplerInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#sampler-info-table">Sampler Object Queries</a> table and |
| <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_SAMPLER"><code>CL_INVALID_<wbr>SAMPLER</code></a> if <em>sampler</em> is a not a valid sampler object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_program_objects"><a class="anchor" href="#_program_objects"></a>5.8. Program Objects</h3> |
| <div class="paragraph"> |
| <p>An OpenCL program consists of a set of kernels that are identified as |
| functions declared with the <code>__kernel</code> qualifier in the program source. |
| OpenCL programs may also contain auxiliary functions and constant data that |
| can be used by kernel functions. |
| The program executable can be generated <em>online</em> or <em>offline</em> by the OpenCL |
| compiler for the appropriate target device(s).</p> |
| </div> |
| <div class="paragraph"> |
| <p>A program object encapsulates the following information:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>An associated context.</p> |
| </li> |
| <li> |
| <p>A program source or binary.</p> |
| </li> |
| <li> |
| <p>The latest successfully built program executable, library or compiled |
| binary, the list of devices for which the program executable, library or |
| compiled binary is built, the build options used and a build log.</p> |
| </li> |
| <li> |
| <p>The number of kernel objects currently attached.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_program_objects"><a class="anchor" href="#_creating_program_objects"></a>5.8.1. Creating Program Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To creates a program object for a context and load source code into that |
| object, call the function</p> |
| </div> |
| <div id="clCreateProgramWithSource" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_program clCreateProgramWithSource( |
| cl_context context, |
| cl_uint count, |
| <span class="directive">const</span> <span class="predefined-type">char</span>** strings, |
| <span class="directive">const</span> size_t* lengths, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>strings</em> is an array of <em>count</em> pointers to optionally null-terminated |
| character strings that make up the source code.</p> |
| </li> |
| <li> |
| <p><em>lengths</em> argument is an array with the number of chars in each string |
| (the string length). |
| If an element in <em>lengths</em> is zero, its accompanying string is |
| null-terminated. |
| If <em>lengths</em> is <code>NULL</code>, all strings in the <em>strings</em> argument are considered |
| null-terminated. |
| Any length value passed in that is greater than zero excludes the null |
| terminator in its count.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The source code specified by <em>strings</em> will be loaded into the program |
| object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The devices associated with the program object are the devices associated |
| with <em>context</em>. |
| The source code specified by <em>strings</em> is either an OpenCL C program source, |
| header or implementation-defined source for custom devices that support an |
| online compiler. |
| OpenCL C++ is not supported as an online-compiled kernel language through |
| this interface.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> returns a valid non-zero program object and |
| <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the program object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>count</em> is zero or if <em>strings</em> or any entry in |
| <em>strings</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a program object for a context and load code in an intermediate |
| language into that object, call the function</p> |
| </div> |
| <div id="clCreateProgramWithIL" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_program clCreateProgramWithIL( |
| cl_context context, |
| <span class="directive">const</span> <span class="directive">void</span>* il, |
| size_t length, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_il_program</strong>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>il</em> is a pointer to a <em>length</em>-byte block of memory containing SPIR-V or an |
| implementation-defined intermediate language.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The intermediate language pointed to by <em>il</em> and with length in bytes <em>length</em> |
| will be loaded into the program object. |
| The devices associated with the program object are the devices associated |
| with <em>context</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> returns a valid non-zero program object and |
| <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the program object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in <em>context</em> support intermediate |
| language programs.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>il</em> is <code>NULL</code> or if <em>length</em> is zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the <em>length</em>-byte memory pointed to by <em>il</em> does not |
| contain well-formed intermediate language input that can be consumed by |
| the OpenCL runtime.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a program object for a context and load binary bits into that |
| object, call the function</p> |
| </div> |
| <div id="clCreateProgramWithBinary" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_program clCreateProgramWithBinary( |
| cl_context context, |
| cl_uint num_devices, |
| <span class="directive">const</span> cl_device_id* device_list, |
| <span class="directive">const</span> size_t* lengths, |
| <span class="directive">const</span> <span class="predefined-type">unsigned</span> <span class="predefined-type">char</span>** binaries, |
| cl_int* binary_status, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>device_list</em> is a pointer to a list of devices that are in <em>context</em>. |
| <em>device_list</em> must be a non-<code>NULL</code> value. |
| The binaries are loaded for devices specified in this list.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the number of devices listed in <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><em>lengths</em> is an array of the size in bytes of the program binaries to be |
| loaded for devices specified by <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><em>binaries</em> is an array of pointers to program binaries to be loaded for |
| devices specified by <em>device_list</em>. |
| For each device given by <em>device_list</em>[i], the pointer to the program binary |
| for that device is given by <em>binaries</em>[i] and the length of this |
| corresponding binary is given by <em>lengths</em>[i]. |
| <em>lengths</em>[i] cannot be zero and <em>binaries</em>[i] cannot be a <code>NULL</code> pointer.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The devices associated with the program object will be the list of devices |
| specified by <em>device_list</em>. |
| The list of devices specified by <em>device_list</em> must be devices associated |
| with <em>context</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The program binaries specified by <em>binaries</em> will be loaded into the program |
| object. |
| They contain bits that describe one of the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>a program executable to be run on the device(s) associated with |
| <em>context</em>,</p> |
| </li> |
| <li> |
| <p>a compiled program for device(s) associated with <em>context</em>, or</p> |
| </li> |
| <li> |
| <p>a library of compiled programs for device(s) associated with <em>context</em>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The program binary can consist of either or both:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Device-specific code and/or,</p> |
| </li> |
| <li> |
| <p>Implementation-specific intermediate representation (IR) which will be |
| converted to the device-specific code.</p> |
| </li> |
| <li> |
| <p><em>binary_status</em> returns whether the program binary for each device specified |
| in <em>device_list</em> was loaded successfully or not. |
| It is an array of <em>num_devices</em> entries and returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> in |
| <em>binary_status</em>[i] if binary was successfully loaded for device specified by |
| <em>device_list</em>[i]; otherwise returns <a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>lengths</em>[i] is zero |
| or if <em>binaries</em>[i] is a <code>NULL</code> value or <a href="#CL_INVALID_BINARY"><code>CL_INVALID_<wbr>BINARY</code></a> in |
| <em>binary_status</em>[i] if program binary is not a valid binary for the specified |
| device. |
| If <em>binary_status</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL allows applications to create a program object using the program |
| source or binary and build appropriate program executables. |
| This can be very useful as it allows applications to load program source and |
| then compile and link to generate a program executable online on its first |
| instance for appropriate OpenCL devices in the system. |
| These executables can now be queried and cached by the application. |
| The cached executables can be read and loaded by the application, which can |
| help significantly reduce the application initialization time.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> returns a valid non-zero program object and |
| <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the program object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>device_list</em> is <code>NULL</code> or <em>num_devices</em> is zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if any device in <em>device_list</em> is not in |
| the list of devices associated with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>lengths</em> or <em>binaries</em> is <code>NULL</code> or if any entry |
| in <em>lengths</em>[i] is zero or <em>binaries</em>[i] is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_BINARY"><code>CL_INVALID_<wbr>BINARY</code></a> if an invalid program binary was encountered for any |
| device. |
| <em>binary_status</em> will return specific status for each device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a program object for a context and loads the information related |
| to the built-in kernels into that object, call the function</p> |
| </div> |
| <div id="clCreateProgramWithBuiltInKernels" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_program clCreateProgramWithBuiltInKernels( |
| cl_context context, |
| cl_uint num_devices, |
| <span class="directive">const</span> cl_device_id* device_list, |
| <span class="directive">const</span> <span class="predefined-type">char</span>* kernel_names, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateProgramWithBuiltInKernels"><strong>clCreateProgramWithBuiltInKernels</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the number of devices listed in <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><em>device_list</em> is a pointer to a list of devices that are in <em>context</em>. |
| <em>device_list</em> must be a non-<code>NULL</code> value. |
| The built-in kernels are loaded for devices specified in this list.</p> |
| </li> |
| <li> |
| <p><em>kernel_names</em> is a semi-colon separated list of built-in kernel names.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The devices associated with the program object will be the list of devices |
| specified by <em>device_list</em>. |
| The list of devices specified by <em>device_list</em> must be devices associated |
| with <em>context</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateProgramWithBuiltInKernels"><strong>clCreateProgramWithBuiltInKernels</strong></a> returns a valid non-zero program object |
| and <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the program object is created |
| successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>device_list</em> is <code>NULL</code> or <em>num_devices</em> is zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>kernel_names</em> is <code>NULL</code> or <em>kernel_names</em> contains |
| a kernel name that is not supported by any of the devices in |
| <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if any device in <em>device_list</em> is not in the list |
| of devices associated with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_retaining_and_releasing_program_objects"><a class="anchor" href="#_retaining_and_releasing_program_objects"></a>5.8.2. Retaining and Releasing Program Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a program object, call the function</p> |
| </div> |
| <div id="clRetainProgram" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainProgram( |
| cl_program program);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is the program object to be retained.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>program</em> reference count is incremented. |
| All APIs that create a program do an implicit retain.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainProgram"><strong>clRetainProgram</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a program object, call the function</p> |
| </div> |
| <div id="clReleaseProgram" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseProgram( |
| cl_program program);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is the program object to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>program</em> reference count is decremented. |
| The program object is deleted after all kernel objects associated with |
| <em>program</em> have been deleted and the <em>program</em> reference count becomes zero.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseProgram"><strong>clReleaseProgram</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainProgram"><strong>clRetainProgram</strong></a> causes undefined behavior.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To register a callback function with a program object that is called when |
| the program object is destroyed, call the function</p> |
| </div> |
| <div id="clSetProgramReleaseCallback" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetProgramReleaseCallback( |
| cl_program program, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_program program, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a> is <a href="#unified-spec">missing before</a> version 2.2 and <a href="#unified-spec">deprecated by</a> version 3.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> specifies the memory object to register the callback to.</p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is the callback function to register. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the application’s responsibility to ensure that the callback function |
| is thread safe. |
| The parameters to this callback function are:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is the program being deleted. |
| When the callback function is called by the implementation, this program |
| object is not longer valid. |
| <em>program</em> is only provided for reference purposes.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> is a pointer to user supplied data.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is |
| called. |
| user data can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Each call to <a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a> registers the specified |
| callback function on a callback stack associated with <em>program</em>. |
| The registered callback functions are called in the reverse order in |
| which they were registered. |
| The registered callback functions are called after destructors (if any) for |
| program scope global variables (if any) are called and before the program |
| object is deleted. |
| This provides a mechanism for an application to be notified when destructors |
| for program scope global variables are complete.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a> may unconditionally return an error if no |
| devices in the context associated with <em>program</em> support destructors for |
| program scope global variables. |
| Support for constructors and destructors for program scope global variables |
| is required only for OpenCL 2.2 devices.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in the context associated with |
| <em>program</em> support destructors for program scope global variables.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_setting_spir_v_specialization_constants"><a class="anchor" href="#_setting_spir_v_specialization_constants"></a>5.8.3. Setting SPIR-V specialization constants</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Specialization constants are <a href="#unified-spec">missing before</a> version |
| 2.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To set the value of a specialization constant, call the function</p> |
| </div> |
| <div id="clSetProgramSpecializationConstant" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetProgramSpecializationConstant( |
| cl_program program, |
| cl_uint spec_id, |
| size_t spec_size, |
| <span class="directive">const</span> <span class="directive">void</span>* spec_value);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetProgramSpecializationConstant"><strong>clSetProgramSpecializationConstant</strong></a> is <a href="#unified-spec">missing before</a> version 2.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> must be a valid OpenCL program created from an intermediate |
| language (e.g. SPIR-V).</p> |
| </li> |
| <li> |
| <p><em>spec_id</em> identifies the specialization constant whose value will be |
| set.</p> |
| </li> |
| <li> |
| <p><em>spec_size</em> specifies the size in bytes of the data pointed to by |
| <em>spec_value</em>. |
| This should be 1 for boolean constants. |
| For all other constant types this should match the size of the |
| specialization constant in the module.</p> |
| </li> |
| <li> |
| <p><em>spec_value</em> is a pointer to the memory location that contains the value of |
| the specialization constant. |
| The data pointed to by <em>spec_value</em> are copied and can be safely reused by |
| the application after <a href="#clSetProgramSpecializationConstant"><strong>clSetProgramSpecializationConstant</strong></a> returns. |
| This specialization value will be used by subsequent calls to |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> until another call to <a href="#clSetProgramSpecializationConstant"><strong>clSetProgramSpecializationConstant</strong></a> |
| changes it. |
| If a specialization constant is a boolean constant, <em>spec_value</em> should be a |
| pointer to a <code>cl_uchar</code> value. |
| A value of zero will set the specialization constant to false; any other |
| value will set it to true.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Calling this function multiple times for the same specialization constant |
| shall cause the last provided value to override any previously specified |
| value. |
| The values are used by a subsequent <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> call for the <em>program</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Application is not required to provide values for every specialization |
| constant contained in the module. If the value is not set by this API |
| call, default values will be used during the build.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetProgramSpecializationConstant"><strong>clSetProgramSpecializationConstant</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is |
| executed successfully.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object created |
| from an intermediate language (e.g. SPIR-V), or if the intermediate |
| language does not support specialization constants.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices associated with <em>program</em> support |
| intermediate language programs.</p> |
| </li> |
| <li> |
| <p><a href="#CL_COMPILER_NOT_AVAILABLE"><code>CL_COMPILER_<wbr>NOT_<wbr>AVAILABLE</code></a> if <em>program</em> is created with |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> and a compiler is not |
| available, i.e. <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is set to <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_SPEC_ID"><code>CL_INVALID_<wbr>SPEC_<wbr>ID</code></a> if <em>spec_id</em> is not a valid specialization constant |
| identifier.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>spec_size</em> does not match the size of the |
| specialization constant in the module, or if <em>spec_value</em> is |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_building_program_executables"><a class="anchor" href="#_building_program_executables"></a>5.8.4. Building Program Executables</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To build (compile & link) a program executable, call the function</p> |
| </div> |
| <div id="clBuildProgram" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clBuildProgram( |
| cl_program program, |
| cl_uint num_devices, |
| <span class="directive">const</span> cl_device_id* device_list, |
| <span class="directive">const</span> <span class="predefined-type">char</span>* options, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_program program, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is the program object.</p> |
| </li> |
| <li> |
| <p><em>device_list</em> is a pointer to a list of devices associated with <em>program</em>. |
| If <em>device_list</em> is a <code>NULL</code> value, the program executable is built for all |
| devices associated with <em>program</em> for which a source or binary has been |
| loaded. |
| If <em>device_list</em> is a non-<code>NULL</code> value, the program executable is built for |
| devices specified in this list for which a source or binary has been loaded.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the number of devices listed in <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><em>options</em> is a pointer to a null-terminated string of characters that |
| describes the build options to be used for building the program executable. |
| The list of supported options is described in <a href="#compiler-options">Compiler |
| Options</a>. |
| If the program was created using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> and <em>options</em> |
| is a <code>NULL</code> pointer, the program will be built as if <em>options</em> were the same |
| as when the program binary was originally built. |
| If the program was created using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> and <em>options</em> |
| string contains anything other than the same options in the same order |
| (whitespace ignored) as when the program binary was originally built, then |
| the behavior is implementation defined. |
| Otherwise, if <em>options</em> is a <code>NULL</code> pointer then it will have the same |
| result as the empty string.</p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is a function pointer to a notification routine. |
| The notification routine is a callback function that an application can |
| register and which will be called when the program executable has been built |
| (successfully or unsuccessfully). |
| If <em>pfn_notify</em> is not <code>NULL</code>, <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> does not need to wait for |
| the build to complete and can return immediately once the build operation |
| can begin. |
| Any state changes of the program object that result from calling |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> (e.g. build status or log) will be observable from this |
| callback function. |
| The build operation can begin if the context, program whose sources are |
| being compiled and linked, list of devices and build options specified are |
| all valid and appropriate host and device resources needed to perform the |
| build are available. |
| If <em>pfn_notify</em> is <code>NULL</code>, <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> does not return until the build |
| has completed. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the applications responsibility to ensure that the callback function |
| is thread-safe.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>user_data</em> will be passed as an argument when <em>pfn_notify</em> is called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The program executable is built from the program source or binary for all |
| the devices, or a specific device(s) in the OpenCL context associated with |
| <em>program</em>. |
| OpenCL allows program executables to be built using the source or the |
| binary. |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> must be called for <em>program</em> created using |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>, <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> or |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> to build the program executable for one or more |
| devices associated with <em>program</em>. |
| If <em>program</em> is created with <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>, then the program |
| binary must be an executable binary (not a compiled binary or library).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The executable binary can be queried using <a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a>(<em>program</em>, |
| <a href="#CL_PROGRAM_BINARIES"><code>CL_PROGRAM_<wbr>BINARIES</code></a>, …​) and can be specified to |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> to create a new program object.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clBuildProgram"><strong>clBuildProgram</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>device_list</em> is <code>NULL</code> and <em>num_devices</em> is greater |
| than zero, or if <em>device_list</em> is not <code>NULL</code> and <em>num_devices</em> is zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if any device in <em>device_list</em> is not in |
| the list of devices associated with <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_BINARY"><code>CL_INVALID_<wbr>BINARY</code></a> if <em>program</em> is created with |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> and devices listed in <em>device_list</em> do not |
| have a valid program binary loaded.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_BUILD_OPTIONS"><code>CL_INVALID_<wbr>BUILD_<wbr>OPTIONS</code></a> if the build options specified by <em>options</em> are |
| invalid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_COMPILER_NOT_AVAILABLE"><code>CL_COMPILER_<wbr>NOT_<wbr>AVAILABLE</code></a> if <em>program</em> is created with |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> or <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> and a compiler is |
| not available, i.e. <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is set to <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_BUILD_PROGRAM_FAILURE"><code>CL_BUILD_<wbr>PROGRAM_<wbr>FAILURE</code></a> if there is a failure to build the program |
| executable. |
| This error will be returned if <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> does not return until |
| the build has completed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the build of a program executable for any of the |
| devices listed in <em>device_list</em> by a previous call to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> |
| for <em>program</em> has not completed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if there are kernel objects attached to <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>program</em> was not created with |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>, <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> or |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_separate_compilation_and_linking_of_programs"><a class="anchor" href="#_separate_compilation_and_linking_of_programs"></a>5.8.5. Separate Compilation and Linking of Programs</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Separate compilation and linking are <a href="#unified-spec">missing before</a> |
| version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL programs are compiled and linked to support the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Separate compilation and link stages. |
| Program sources can be compiled to generate a compiled binary object and |
| linked in a separate stage with other compiled program objects to the |
| program executable.</p> |
| </li> |
| <li> |
| <p>Embedded headers. |
| In OpenCL 1.0 and 1.1, the I build option could be used to specify the |
| list of directories to be searched for headers files that are included |
| by a program source(s). |
| OpenCL 1.2 extends this by allowing the header sources to come from |
| program objects instead of just header files.</p> |
| </li> |
| <li> |
| <p>Libraries. |
| The linker can be used to link compiled objects and libraries into a |
| program executable or to create a library of compiled binaries.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To compile a program’s source for all the devices or a specific device(s) in |
| the OpenCL context associated with the program, call the function</p> |
| </div> |
| <div id="clCompileProgram" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clCompileProgram( |
| cl_program program, |
| cl_uint num_devices, |
| <span class="directive">const</span> cl_device_id* device_list, |
| <span class="directive">const</span> <span class="predefined-type">char</span>* options, |
| cl_uint num_input_headers, |
| <span class="directive">const</span> cl_program* input_headers, |
| <span class="directive">const</span> <span class="predefined-type">char</span>** header_include_names, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_program program, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is the program object that is the compilation target.</p> |
| </li> |
| <li> |
| <p><em>device_list</em> is a pointer to a list of devices associated with <em>program</em>. |
| If <em>device_list</em> is a <code>NULL</code> value, the compile is performed for all devices |
| associated with <em>program</em>. |
| If <em>device_list</em> is a non-<code>NULL</code> value, the compile is performed for devices |
| specified in this list.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the number of devices listed in <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><em>options</em> is a pointer to a null-terminated string of characters that |
| describes the compilation options to be used for building the program |
| executable. |
| If <em>options</em> is a <code>NULL</code> pointer then it will have the same result as the |
| empty string. |
| Certain options are ignored when program is created with IL. |
| The list of supported options is as described in <a href="#compiler-options">Compiler Options</a>.</p> |
| </li> |
| <li> |
| <p><em>num_input_headers</em> specifies the number of programs that describe headers |
| in the array referenced by <em>input_headers</em>.</p> |
| </li> |
| <li> |
| <p><em>input_headers</em> is an array of program embedded headers created with |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>header_include_names</em> is an array that has a one to one correspondence with |
| <em>input_headers</em>. |
| Each entry in <em>header_include_names</em> specifies the include name used by |
| source in <em>program</em> that comes from an embedded header. |
| The corresponding entry in <em>input_headers</em> identifies the program object |
| which contains the header source to be used. |
| The embedded headers are first searched before the headers in the list of |
| directories specified by the <code>-I</code> compile option (as described in |
| <a href="#preprocessor-options">Preprocessor options</a>). |
| If multiple entries in <em>header_include_names</em> refer to the same header name, |
| the first one encountered will be used.</p> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is a function pointer to a notification routine. |
| The notification routine is a callback function that an application can |
| register and which will be called when the program executable has been built |
| (successfully or unsuccessfully). |
| If <em>pfn_notify</em> is not <code>NULL</code>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> does not need to wait for |
| the compiler to complete and can return immediately once the compilation can |
| begin. |
| Any state changes of the program object that result from calling |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> (e.g. compile status or log) will be observable from this |
| callback function. |
| The compilation can begin if the context, program whose sources are being |
| compiled, list of devices, input headers, programs that describe input |
| headers and compiler options specified are all valid and appropriate host |
| and device resources needed to perform the compile are available. |
| If <em>pfn_notify</em> is <code>NULL</code>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> does not return until the |
| compiler has completed. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the applications responsibility to ensure that the callback function |
| is thread-safe.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>user_data</em> will be passed as an argument when <em>pfn_notify</em> is called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The pre-processor runs before the program sources are compiled. |
| The compiled binary is built for all devices associated with <em>program</em> or |
| the list of devices specified. |
| The compiled binary can be queried using <a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a>(<em>program</em>, |
| <a href="#CL_PROGRAM_BINARIES"><code>CL_PROGRAM_<wbr>BINARIES</code></a>, …​) and can be passed to <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> |
| to create a new program object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>program</em> was created using <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a>, then |
| <em>num_input_headers</em>, <em>input_headers</em>, and <em>header_include_names</em> are |
| ignored.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, consider the following program source:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#include</span> <span class="include"><foo.h></span> |
| <span class="preprocessor">#include</span> <span class="include"><mydir/myinc.h></span> |
| __kernel <span class="directive">void</span> |
| image_filter (<span class="predefined-type">int</span> n, <span class="predefined-type">int</span> m, |
| __constant <span class="predefined-type">float</span> *filter_weights, |
| __read_only image2d_t src_image, |
| __write_only image2d_t dst_image) |
| { |
| ... |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This kernel includes two headers foo.h and mydir/myinc.h. |
| The following describes how these headers can be passed as embedded headers |
| in program objects:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">cl_program foo_pg = clCreateProgramWithSource(context, |
| <span class="integer">1</span>, &foo_header_src, <span class="predefined-constant">NULL</span>, &err); |
| cl_program myinc_pg = clCreateProgramWithSource(context, |
| <span class="integer">1</span>, &myinc_header_src, <span class="predefined-constant">NULL</span>, &err); |
| |
| <span class="comment">// lets assume the program source described above is given</span> |
| <span class="comment">// by program_A and is loaded via clCreateProgramWithSource</span> |
| cl_program input_headers[<span class="integer">2</span>] = { foo_pg, myinc_pg }; |
| <span class="predefined-type">char</span> * input_header_names[<span class="integer">2</span>] = { foo.h, mydir/myinc.h }; |
| clCompileProgram(program_A, |
| <span class="integer">0</span>, <span class="predefined-constant">NULL</span>, <span class="comment">// num_devices & device_list</span> |
| <span class="predefined-constant">NULL</span>, <span class="comment">// compile_options</span> |
| <span class="integer">2</span>, <span class="comment">// num_input_headers</span> |
| input_headers, |
| input_header_names, |
| <span class="predefined-constant">NULL</span>, <span class="predefined-constant">NULL</span>); <span class="comment">// pfn_notify & user_data</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCompileProgram"><strong>clCompileProgram</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>device_list</em> is <code>NULL</code> and <em>num_devices</em> is greater |
| than zero, or if <em>device_list</em> is not <code>NULL</code> and <em>num_devices</em> is zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_input_headers</em> is zero and |
| <em>header_include_names</em> or <em>input_headers</em> are not <code>NULL</code> or if |
| <em>num_input_headers</em> is not zero and <em>header_include_names</em> or |
| <em>input_headers</em> are <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if device in <em>device_list</em> is not in |
| the list of devices associated with <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_COMPILER_OPTIONS"><code>CL_INVALID_<wbr>COMPILER_<wbr>OPTIONS</code></a> if the compiler options specified by |
| <em>options</em> are invalid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the compilation or build of a program executable |
| for any of the devices listed in <em>device_list</em> by a previous call to |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> for <em>program</em> has not completed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_COMPILER_NOT_AVAILABLE"><code>CL_COMPILER_<wbr>NOT_<wbr>AVAILABLE</code></a> if a compiler is not available, i.e. |
| <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is set to <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_COMPILE_PROGRAM_FAILURE"><code>CL_COMPILE_<wbr>PROGRAM_<wbr>FAILURE</code></a> if there is a failure to compile the program |
| source. |
| This error will be returned if <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> does not return until |
| the compile has completed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if there are kernel objects attached to <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>program</em> has no source or IL available, i.e. it |
| has not been created with <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> or |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To link a set of compiled program objects and libraries for all the devices |
| or a specific device(s) in the OpenCL context and create a library or |
| executable, call the function</p> |
| </div> |
| <div id="clLinkProgram" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_program clLinkProgram( |
| cl_context context, |
| cl_uint num_devices, |
| <span class="directive">const</span> cl_device_id* device_list, |
| <span class="directive">const</span> <span class="predefined-type">char</span>* options, |
| cl_uint num_input_programs, |
| <span class="directive">const</span> cl_program* input_programs, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_program program, <span class="directive">void</span>* user_data), |
| <span class="directive">void</span>* user_data, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>device_list</em> is a pointer to a list of devices that are in <em>context</em>. |
| If <em>device_list</em> is a <code>NULL</code> value, the link is performed for all devices |
| associated with <em>context</em> for which a compiled object is available. |
| If <em>device_list</em> is a non-<code>NULL</code> value, the link is performed for devices |
| specified in this list for which a compiled object is available.</p> |
| </li> |
| <li> |
| <p><em>num_devices</em> is the number of devices listed in <em>device_list</em>.</p> |
| </li> |
| <li> |
| <p><em>options</em> is a pointer to a null-terminated string of characters that |
| describes the link options to be used for building the program executable. |
| The list of supported options is as described in <a href="#linker-options">Linker |
| Options</a>. |
| If the program was created using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> and <em>options</em> |
| is a <code>NULL</code> pointer, the program will be linked as if <em>options</em> were the |
| same as when the program binary was originally built. |
| If the program was created using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> and <em>options</em> |
| string contains anything other than the same options in the same order |
| (whitespace ignored) as when the program binary was originally built, then |
| the behavior is implementation defined. |
| Otherwise, if <em>options</em> is a <code>NULL</code> pointer then it will have the same |
| result as the empty string.</p> |
| </li> |
| <li> |
| <p><em>num_input_programs</em> specifies the number of programs in array referenced by |
| <em>input_programs</em>.</p> |
| </li> |
| <li> |
| <p><em>input_programs</em> is an array of program objects that are compiled binaries |
| or libraries that are to be linked to create the program executable. |
| For each device in <em>device_list</em> or if <em>device_list</em> is <code>NULL</code> the list of |
| devices associated with context, the following cases occur:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All programs specified by <em>input_programs</em> contain a compiled binary or |
| library for the device. |
| In this case, a link is performed to generate a program executable for |
| this device.</p> |
| </li> |
| <li> |
| <p>None of the programs contain a compiled binary or library for that |
| device. |
| In this case, no link is performed and there will be no program |
| executable generated for this device.</p> |
| </li> |
| <li> |
| <p>All other cases will return a <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> error.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>pfn_notify</em> is a function pointer to a notification routine. |
| The notification routine is a callback function that an application can |
| register and which will be called when the program executable has been built |
| (successfully or unsuccessfully).</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>user_data</em> will be passed as an argument when <em>pfn_notify</em> is called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>pfn_notify</em> is not <code>NULL</code>, <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> does not need to wait for the |
| linker to complete, and can return immediately once the linking operation can |
| begin. |
| Once the linker has completed, the <em>pfn_notify</em> callback function is called |
| which returns the program object returned by <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>. |
| Any state changes of the program object that result from calling <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> |
| (e.g. link status or log) will be observable from this callback function. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the applications responsibility to ensure that the callback function |
| is thread-safe.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>pfn_notify</em> is <code>NULL</code>, <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> does not return until the linker |
| has completed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clLinkProgram"><strong>clLinkProgram</strong></a> creates a new program object which contains the library or |
| executable. |
| The library or executable binary can be queried using |
| <a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a>(<em>program</em>, <a href="#CL_PROGRAM_BINARIES"><code>CL_PROGRAM_<wbr>BINARIES</code></a>, …​) and can be specified |
| to <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> to create a new program object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The devices associated with the returned program object will be the list of |
| devices specified by <em>device_list</em> or if <em>device_list</em> is <code>NULL</code> it will be |
| the list of devices associated with <em>context</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The linking operation can begin if the context, list of devices, input |
| programs and linker options specified are all valid and appropriate host and |
| device resources needed to perform the link are available. |
| If the linking operation can begin, <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> returns a valid non-zero |
| program object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>pfn_notify</em> is <code>NULL</code>, the <em>errcode_ret</em> will be set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if |
| the link operation was successful and <a href="#CL_LINK_PROGRAM_FAILURE"><code>CL_LINK_<wbr>PROGRAM_<wbr>FAILURE</code></a> if there is a |
| failure to link the compiled binaries and/or libraries.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>pfn_notify</em> is not <code>NULL</code>, <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> does not have to wait until |
| the linker to complete and can return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> in <em>errcode_ret</em> if the |
| linking operation can begin. |
| The <em>pfn_notify</em> callback function will return a <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> or |
| <a href="#CL_LINK_PROGRAM_FAILURE"><code>CL_LINK_<wbr>PROGRAM_<wbr>FAILURE</code></a> if the linking operation was successful or not.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Otherwise <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> returns a <code>NULL</code> program object with an |
| appropriate error in <em>errcode_ret</em>. |
| The application should query the linker status of this program object to |
| check if the link was successful or not. |
| The list of errors that can be returned are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>device_list</em> is <code>NULL</code> and <em>num_devices</em> is greater |
| than zero, or if <em>device_list</em> is not <code>NULL</code> and <em>num_devices</em> is zero.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_input_programs</em> is zero and <em>input_programs</em> is |
| <code>NULL</code> or if <em>num_input_programs</em> is zero and <em>input_programs</em> is not |
| <code>NULL</code> or if <em>num_input_programs</em> is not zero and <em>input_programs</em> is |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if programs specified in <em>input_programs</em> are not |
| valid program objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not |
| <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if any device in <em>device_list</em> is not in |
| the list of devices associated with <em>context</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_LINKER_OPTIONS"><code>CL_INVALID_<wbr>LINKER_<wbr>OPTIONS</code></a> if the linker options specified by <em>options</em> |
| are invalid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the compilation or build of a program executable |
| for any of the devices listed in <em>device_list</em> by a previous call to |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> for <em>program</em> has not completed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the rules for devices containing compiled |
| binaries or libraries as described in <em>input_programs</em> argument above |
| are not followed.</p> |
| </li> |
| <li> |
| <p><a href="#CL_LINKER_NOT_AVAILABLE"><code>CL_LINKER_<wbr>NOT_<wbr>AVAILABLE</code></a> if a linker is not available, i.e. |
| <a href="#CL_DEVICE_LINKER_AVAILABLE"><code>CL_DEVICE_<wbr>LINKER_<wbr>AVAILABLE</code></a> specified in the |
| <a href="#device-queries-table">Device Queries</a> table is set to <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_LINK_PROGRAM_FAILURE"><code>CL_LINK_<wbr>PROGRAM_<wbr>FAILURE</code></a> if there is a failure to link the compiled |
| binaries and/or libraries.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="compiler-options"><a class="anchor" href="#compiler-options"></a>5.8.6. Compiler Options</h4> |
| <div class="paragraph"> |
| <p>The compiler options are categorized as pre-processor options, options for |
| math intrinsics, options that control optimization and miscellaneous |
| options. |
| This specification defines a standard set of options that must be supported |
| by the compiler when building program executables online or offline from |
| OpenCL C/C++ or, where relevant, from an IL. |
| These may be extended by a set of vendor- or platform-specific options.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="preprocessor-options"><a class="anchor" href="#preprocessor-options"></a>5.8.6.1. Preprocessor options</h5> |
| <div class="paragraph"> |
| <p>These options control the OpenCL C/C++ preprocessor which is run on each |
| program source before actual compilation. |
| These options are ignored for programs created with IL.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-D name</code> </dt> |
| <dd> |
| <p>Predefine <em>name</em> as a macro, with definition 1.</p> |
| </dd> |
| <dt class="hdlist1"><code>-D name=definition</code> </dt> |
| <dd> |
| <p>The contents of <em>definition</em> are tokenized and processed as if they |
| appeared during translation phase three in a <code>#define</code> directive. |
| In particular, the definition will be truncated by embedded newline |
| characters.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><code>-D</code> options are processed in the order they are given in the <em>options</em> |
| argument to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a>. |
| Note that a space is required between the <code>-D</code> option and the symbol it |
| defines, otherwise behavior is implementation defined.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>-I dir</code> </dt> |
| <dd> |
| <p>Add the directory <em>dir</em> to the list of directories to be searched for |
| header files. |
| <em>dir</em> can optionally be enclosed in double quotes.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>This option is not portable due to its dependency on host file system and |
| host operating system. |
| It is supported for backwards compatibility with previous OpenCL versions. |
| Developers are encouraged to create and use explicit header objects by means |
| of <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> followed by <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="math-intrinsics-options"><a class="anchor" href="#math-intrinsics-options"></a>5.8.6.2. Math Intrinsics Options</h5> |
| <div class="paragraph"> |
| <p>These options control compiler behavior regarding floating-point arithmetic. |
| These options trade off between speed and correctness.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-cl-single-precision-constant</code> </dt> |
| <dd> |
| <p>This option forces implicit conversions of double-precision floating-point |
| literals to single precision. |
| This option is ignored for programs created with IL.</p> |
| </dd> |
| <dt class="hdlist1"><code>-cl-denorms-are-zero</code> </dt> |
| <dd> |
| <p>This option controls how single precision and double precision |
| denormalized numbers are handled. |
| If specified as a build option, the single precision denormalized |
| numbers may be flushed to zero; double precision denormalized numbers |
| may also be flushed to zero if the optional extension for double |
| precision is supported. |
| This is intended to be a performance hint and the OpenCL compiler can |
| choose not to flush denorms to zero if the device supports single |
| precision (or double precision) denormalized numbers.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>This option is ignored for single precision numbers if the device does not |
| support single precision denormalized numbers i.e. <a href="#CL_FP_DENORM"><code>CL_FP_<wbr>DENORM</code></a> bit is not |
| set in <a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_DEVICE_<wbr>SINGLE_<wbr>FP_<wbr>CONFIG</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This option is ignored for double precision numbers if the device does not |
| support double precision or if it does support double precision but not |
| double precision denormalized numbers i.e. <a href="#CL_FP_DENORM"><code>CL_FP_<wbr>DENORM</code></a> bit is not set in |
| <a href="#CL_DEVICE_DOUBLE_FP_CONFIG"><code>CL_DEVICE_<wbr>DOUBLE_<wbr>FP_<wbr>CONFIG</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This flag only applies for scalar and vector single precision floating-point |
| variables and computations on these floating-point variables inside a |
| program. |
| It does not apply to reading from or writing to image objects.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>-cl-fp32-correctly-rounded-divide-sqrt</code> </dt> |
| <dd> |
| <p>The <code>-cl-fp32-correctly-rounded-divide-sqrt</code> build option to |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> allows an application to specify |
| that single precision floating-point divide (x/y and 1/x) and sqrt used |
| in the program source are correctly rounded. |
| If this build option is not specified, the minimum numerical accuracy of |
| single precision floating-point divide and sqrt are as defined in the |
| OpenCL C or OpenCL SPIR-V Environment specifications.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>This build option can only be specified if the |
| <a href="#CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"><code>CL_FP_<wbr>CORRECTLY_<wbr>ROUNDED_<wbr>DIVIDE_<wbr>SQRT</code></a> is set in <a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_DEVICE_<wbr>SINGLE_<wbr>FP_<wbr>CONFIG</code></a> (as |
| defined in the <a href="#device-queries-table">Device Queries</a> table) for devices |
| that the program is being build. |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> will fail to compile the program for |
| a device if the <code>-cl-fp32-correctly-rounded-divide-sqrt</code> option is specified |
| and <a href="#CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"><code>CL_FP_<wbr>CORRECTLY_<wbr>ROUNDED_<wbr>DIVIDE_<wbr>SQRT</code></a> is not set for the device.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note: This option is <a href="#unified-spec">missing before</a> version 1.2.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="optimization-options"><a class="anchor" href="#optimization-options"></a>5.8.6.3. Optimization Options</h5> |
| <div class="paragraph"> |
| <p>These options control various sorts of optimizations. |
| Turning on optimization flags makes the compiler attempt to improve the |
| performance and/or code size at the expense of compilation time and possibly |
| the ability to debug the program.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-cl-opt-disable</code> </dt> |
| <dd> |
| <p>This option disables all optimizations. |
| The default is optimizations are enabled.</p> |
| </dd> |
| <dt class="hdlist1"><code>-cl-strict-aliasing</code> </dt> |
| <dd> |
| <p>This option allows the compiler to assume the strictest aliasing rules.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Note: This option is <a href="#unified-spec">deprecated by</a> version 1.1.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>-cl-uniform-work-group-size</code> </dt> |
| <dd> |
| <p>This requires that the global work-size be a multiple of the work-group |
| size specified to <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>. |
| Allow optimizations that are made possible by this restriction.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Note: This option is <a href="#unified-spec">missing before</a> version 2.0.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>-cl-no-subgroup-ifp</code> </dt> |
| <dd> |
| <p>This indicates that kernels in this program do not require subgroups to |
| make independent forward progress. |
| Allows optimizations that are made possible by this restriction. |
| This option has no effect for devices that do not support independent |
| forward progress for subgroups.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Note: This option is <a href="#unified-spec">missing before</a> version 2.1.</p> |
| </div> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>The following options control compiler behavior regarding floating-point |
| arithmetic. |
| These options trade off between performance and correctness and must be |
| specifically enabled. |
| These options are not turned on by default since it can result in incorrect |
| output for programs which depend on an exact implementation of IEEE 754 |
| rules/specifications for math functions.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-cl-mad-enable</code> </dt> |
| <dd> |
| <p>Allow <code>a * b + c</code> to be replaced by a <strong>mad</strong> instruction. |
| The <strong>mad</strong> instruction may compute <code>a * b + c</code> with reduced accuracy |
| in the embedded profile. |
| See the OpenCL C or OpenCL SPIR-V Environment specification for accuracy |
| details. |
| On some hardware the <strong>mad</strong> instruction may provide better performance |
| than the expanded computation.</p> |
| </dd> |
| <dt class="hdlist1"><code>-cl-no-signed-zeros</code> </dt> |
| <dd> |
| <p>Allow optimizations for floating-point arithmetic that ignore the |
| signedness of zero. |
| IEEE 754 arithmetic specifies the distinct behavior of <code>+0.0</code> and <code>-0.0</code> |
| values, which then prohibits simplification of expressions such as <code>x |
| + 0.0</code> or <code>0.0 * x</code> (even with <code>-cl-finite-math-only</code>). |
| This option implies that the sign of a zero result isn’t significant.</p> |
| </dd> |
| <dt class="hdlist1"><code>-cl-unsafe-math-optimizations</code> </dt> |
| <dd> |
| <p>Allow optimizations for floating-point arithmetic that (a) assume that |
| arguments and results are valid, (b) may violate the IEEE 754 standard, |
| (c) assume relaxed OpenCL numerical compliance requirements as defined |
| in the unsafe math optimization section of the OpenCL C or OpenCL SPIR-V |
| Environment specifications, and (d) may violate edge case behavior in the |
| OpenCL C or OpenCL SPIR-V Environment specifications. |
| This option includes the <code>-cl-no-signed-zeros</code>, <code>-cl-mad-enable</code>, and |
| <code>-cl-denorms-are-zero</code> <sup class="footnote">[<a id="_footnoteref_26" class="footnote" href="#_footnotedef_26" title="View footnote.">26</a>]</sup> options.</p> |
| </dd> |
| <dt class="hdlist1"><code>-cl-finite-math-only</code> </dt> |
| <dd> |
| <p>Allow optimizations for floating-point arithmetic that assume that |
| arguments and results are not NaNs, +Inf, -Inf. |
| This option may violate the OpenCL numerical compliance requirements for |
| single precision and double precision floating-point, as well as edge |
| case behavior.</p> |
| </dd> |
| <dt class="hdlist1"><code>-cl-fast-relaxed-math</code> </dt> |
| <dd> |
| <p>Sets the optimization options <code>-cl-finite-math-only</code> and |
| <code>-cl-unsafe-math-optimizations</code>. |
| This option causes the preprocessor macro <code>__FAST_RELAXED_MATH__</code> to |
| be defined in the OpenCL program.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_options_to_request_or_suppress_warnings"><a class="anchor" href="#_options_to_request_or_suppress_warnings"></a>5.8.6.4. Options to Request or Suppress Warnings</h5> |
| <div class="paragraph"> |
| <p>Warnings are diagnostic messages that report constructions which are not |
| inherently erroneous but which are risky or suggest there may have been an |
| error. |
| The following language-independent options do not enable specific warnings |
| but control the kinds of diagnostics produced by the OpenCL compiler. |
| These options are ignored for programs created with IL.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-w</code> </dt> |
| <dd> |
| <p>Inhibit all warning messages.</p> |
| </dd> |
| <dt class="hdlist1"><code>-Werror</code> </dt> |
| <dd> |
| <p>Make all warnings into errors.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="opencl-c-version"><a class="anchor" href="#opencl-c-version"></a>5.8.6.5. Options Controlling the OpenCL C version</h5> |
| <div class="paragraph"> |
| <p>The following option controls the version of OpenCL C that the compiler |
| accepts. |
| These options are ignored for programs created with IL.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-cl-std=</code> </dt> |
| <dd> |
| <p>Determine the OpenCL C language version to use. |
| A value for this option must be provided. |
| Valid values are:</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>CL1.1</code>: Support OpenCL C 1.1 language features defined in <em>section 6</em> of |
| the OpenCL 1.1 specification or in the unified OpenCL C specification.</p> |
| </li> |
| <li> |
| <p><code>CL1.2</code>: Support OpenCL C 1.2 language features defined in <em>section 6</em> of |
| the OpenCL 1.2 specification or in the unified OpenCL C specification.</p> |
| </li> |
| <li> |
| <p><code>CL2.0</code>: Support OpenCL C 2.0 language features defined in the OpenCL C 2.0 |
| specification or in the unified OpenCL C specification.</p> |
| </li> |
| <li> |
| <p><code>CL3.0</code>: Support OpenCL C 3.0 language features defined in the unified |
| OpenCL C specification.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>Calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> with the <code>-cl-std=CL1.1</code> |
| option <strong>will fail</strong> to compile the program for any devices with |
| <a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a> equal to OpenCL C 1.0 and when |
| <a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a> does not include OpenCL C 1.1.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> with the <code>-cl-std=CL1.2</code> |
| option <strong>will fail</strong> to compile the program for any devices with |
| <a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a> equal to OpenCL C 1.1 or earlier |
| and when <a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a> does not include OpenCL C 1.2.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> with the <code>-cl-std=CL2.0</code> |
| option <strong>will fail</strong> to compile the program for any devices with |
| <a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a> equal to OpenCL C 1.2 or earlier |
| and when <a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a> does not include OpenCL C 2.0.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> with the <code>-cl-std=CL3.0</code> |
| option <strong>will fail</strong> to compile the program for any devices with |
| <a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a> equal to OpenCL C 2.0 or earlier |
| and when <a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a> does not include OpenCL C 3.0.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the <code>-cl-std</code> build option is not specified, the highest OpenCL C 1.x |
| language version supported by each device is used when compiling the program |
| for each device. |
| Applications are required to specify the <code>-cl-std=CL2.0</code> build option to |
| compile or build programs with OpenCL C 2.0 and the <code>-cl-std=CL3.0</code> |
| build option to compile or build programs with OpenCL C 3.0.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_options_for_querying_kernel_argument_information"><a class="anchor" href="#_options_for_querying_kernel_argument_information"></a>5.8.6.6. Options for Querying Kernel Argument Information</h5> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Querying for kernel argument information is <a href="#unified-spec">missing |
| before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-cl-kernel-arg-info</code> </dt> |
| <dd> |
| <p>This option allows the compiler to store information about the arguments |
| of a kernel(s) in the program executable. |
| The argument information stored includes the argument name, its type, |
| the address space and access qualifiers used. |
| Refer to description of <a href="#clGetKernelArgInfo"><strong>clGetKernelArgInfo</strong></a> on how to query this |
| information.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_options_for_debugging_your_program"><a class="anchor" href="#_options_for_debugging_your_program"></a>5.8.6.7. Options for debugging your program</h5> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Debugging options are <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-g</code> </dt> |
| <dd> |
| <p>This option can currently be used to generate additional errors for the |
| built-in functions that allow you to enqueue commands on a device (refer |
| to OpenCL kernel languages specifications).</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="linker-options"><a class="anchor" href="#linker-options"></a>5.8.7. Linker Options</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Linker options are <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>This specification defines a standard set of linker options that must be |
| supported by the OpenCL C compiler when linking compiled programs online or |
| offline. |
| These linker options are categorized as library linking options and program |
| linking options. |
| These may be extended by a set of vendor- or platform-specific options.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_library_linking_options"><a class="anchor" href="#_library_linking_options"></a>5.8.7.1. Library Linking Options</h5> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Library linking options are <a href="#unified-spec">missing before</a> version |
| 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following options can be specified when creating a library of compiled |
| binaries.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>-create-library</code> </dt> |
| <dd> |
| <p>Create a library of compiled binaries specified in <em>input_programs</em> |
| argument to <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>.</p> |
| </dd> |
| <dt class="hdlist1"><code>-enable-link-options</code> </dt> |
| <dd> |
| <p>Allows the linker to modify the library behavior based on one or more |
| link options (described in <a href="#program-linking-options">Program Linking |
| Options</a>) when this library is linked with a program executable. |
| This option must be specified with the create-library option.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="program-linking-options"><a class="anchor" href="#program-linking-options"></a>5.8.7.2. Program Linking Options</h5> |
| <div class="paragraph"> |
| <p>The following options can be specified when linking a program executable.</p> |
| </div> |
| <div class="paragraph"> |
| <p><code>-cl-denorms-are-zero</code><br> |
| <code>-cl-no-signed-zeros</code><br> |
| <code>-cl-unsafe-math-optimizations</code><br> |
| <code>-cl-finite-math-only</code><br> |
| <code>-cl-fast-relaxed-math</code><br> |
| <code>-cl-no-subgroup-ifp</code> (<a href="#unified-spec">missing before</a> version 2.1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The options are described in <a href="#math-intrinsics-options">Math Intrinsics |
| Options</a> and <a href="#optimization-options">Optimization Options</a>. |
| The linker may apply these options to all compiled program objects |
| specified to <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>. |
| The linker may apply these options only to libraries which were created |
| with the option <code>-enable-link-options</code>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_unloading_the_opencl_compiler"><a class="anchor" href="#_unloading_the_opencl_compiler"></a>5.8.8. Unloading the OpenCL Compiler</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To unload an OpenCL compiler for a platform, call the function</p> |
| </div> |
| <div id="clUnloadPlatformCompiler" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clUnloadPlatformCompiler( |
| cl_platform_id platform);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clUnloadPlatformCompiler"><strong>clUnloadPlatformCompiler</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>platform</em> is the platform to unload.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This function allows the implementation to release the resources allocated |
| by the OpenCL compiler for <em>platform</em>. |
| This is a hint from the application and does not guarantee that the compiler |
| will not be used in the future or that the compiler will actually be |
| unloaded by the implementation. |
| Calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> after |
| <a href="#clUnloadPlatformCompiler"><strong>clUnloadPlatformCompiler</strong></a> will reload the compiler, if necessary, to build |
| the appropriate program executable.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clUnloadPlatformCompiler"><strong>clUnloadPlatformCompiler</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PLATFORM"><code>CL_INVALID_<wbr>PLATFORM</code></a> if <em>platform</em> is not a valid platform.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Alternatively, if you are not using OpenCL via the ICD loader, you may unload the OpenCL compiler with the function</p> |
| </div> |
| <div id="clUnloadCompiler" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clUnloadCompiler(<span class="directive">void</span>);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clUnloadCompiler"><strong>clUnloadCompiler</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>This function allows the implementation to release the resources allocated |
| by the OpenCL compiler. |
| This is a hint from the application and does not guarantee that the compiler |
| will not be used in the future or that the compiler will actually be |
| unloaded by the implementation. |
| Calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> after |
| <a href="#clUnloadCompiler"><strong>clUnloadCompiler</strong></a> will reload the compiler, if necessary, to build |
| the appropriate program executable.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clUnloadCompiler"><strong>clUnloadCompiler</strong></a> will always return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_program_object_queries"><a class="anchor" href="#_program_object_queries"></a>5.8.9. Program Object Queries</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about a program object, call the function</p> |
| </div> |
| <div id="clGetProgramInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetProgramInfo( |
| cl_program program, |
| cl_program_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> specifies the program object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a> is described in the |
| <a href="#program-info-table">Program Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#program-info-table">Program Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="program-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 29. List of supported param_names by <a href="#clGetProgramInfo">clGetProgramInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Program Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_REFERENCE_COUNT"></a><a href="#CL_PROGRAM_REFERENCE_COUNT"><code>CL_PROGRAM_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_27" class="footnote" href="#_footnotedef_27" title="View footnote.">27</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the <em>program</em> reference count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_CONTEXT"></a><a href="#CL_PROGRAM_CONTEXT"><code>CL_PROGRAM_<wbr>CONTEXT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the context specified when the program object is created</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_NUM_DEVICES"></a><a href="#CL_PROGRAM_NUM_DEVICES"><code>CL_PROGRAM_<wbr>NUM_<wbr>DEVICES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the number of devices associated with <em>program</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_DEVICES"></a><a href="#CL_PROGRAM_DEVICES"><code>CL_PROGRAM_<wbr>DEVICES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>id</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the list of devices associated with the program object. |
| This can be the devices associated with context on which the program |
| object has been created or can be a subset of devices that are |
| specified when a program object is created using |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_SOURCE"></a><a href="#CL_PROGRAM_SOURCE"><code>CL_PROGRAM_<wbr>SOURCE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the program source code specified by |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>. |
| The source string returned is a concatenation of all source strings |
| specified to <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> with a null terminator. |
| The concatenation strips any nulls in the original source strings.</p> |
| <p class="tableblock"> If <em>program</em> is created using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>, |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> or <a href="#clCreateProgramWithBuiltInKernels"><strong>clCreateProgramWithBuiltInKernels</strong></a>, a |
| null string or the appropriate program source code is returned |
| depending on whether or not the program source code is stored in the |
| binary.</p> |
| <p class="tableblock"> The actual number of characters that represents the program source |
| code including the null terminator is returned in |
| <em>param_value_size_ret</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_IL"></a><a href="#CL_PROGRAM_IL"><code>CL_PROGRAM_<wbr>IL</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_il_program</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the program IL for programs created with |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a>.</p> |
| <p class="tableblock"> If <em>program</em> is created with <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>, |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> or <a href="#clCreateProgramWithBuiltInKernels"><strong>clCreateProgramWithBuiltInKernels</strong></a> |
| the memory pointed to by param_value will be unchanged and |
| param_value_size_retwill be set to 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BINARY_SIZES"></a><a href="#CL_PROGRAM_BINARY_SIZES"><code>CL_PROGRAM_<wbr>BINARY_<wbr>SIZES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an array that contains the size in bytes of the program |
| binary (could be an executable binary, compiled binary or library |
| binary) for each device associated with program. |
| The size of the array is the number of devices associated with |
| program. |
| If a binary is not available for a device(s), a size of zero is |
| returned.</p> |
| <p class="tableblock"> If <em>program</em> is created using <a href="#clCreateProgramWithBuiltInKernels"><strong>clCreateProgramWithBuiltInKernels</strong></a>, |
| the implementation may return zero in any entries of the returned |
| array.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BINARIES"></a><a href="#CL_PROGRAM_BINARIES"><code>CL_PROGRAM_<wbr>BINARIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>unsigned char</code>*[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the program binaries (could be an executable binary, compiled |
| binary or library binary) for all devices associated with program. |
| For each device in program, the binary returned can be the binary |
| specified for the device when program is created with |
| <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> or it can be the executable binary |
| generated by <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>. |
| If <em>program</em> is created with <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> or |
| <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a>, the binary returned is the binary generated |
| by <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>. |
| The bits returned can be an implementation-specific intermediate |
| representation (a.k.a. IR) or device specific executable bits or |
| both. |
| The decision on which information is returned in the binary is up to |
| the OpenCL implementation.</p> |
| <p class="tableblock"> param_value points to an array of <code>n</code> pointers allocated by the |
| caller, where <code>n</code> is the number of devices associated with program. |
| The buffer sizes needed to allocate the memory that these <code>n</code> |
| pointers refer to can be queried using the <a href="#CL_PROGRAM_BINARY_SIZES"><code>CL_PROGRAM_<wbr>BINARY_<wbr>SIZES</code></a> |
| query as described in this table.</p> |
| <p class="tableblock"> Each entry in this array is used by the implementation as the |
| location in memory where to copy the program binary for a specific |
| device, if there is a binary available. |
| To find out which device the program binary in the array refers to, |
| use the <a href="#CL_PROGRAM_DEVICES"><code>CL_PROGRAM_<wbr>DEVICES</code></a> query to get the list of devices. |
| There is a one-to-one correspondence between the array of n pointers |
| returned by <a href="#CL_PROGRAM_BINARIES"><code>CL_PROGRAM_<wbr>BINARIES</code></a> and array of devices returned by |
| <a href="#CL_PROGRAM_DEVICES"><code>CL_PROGRAM_<wbr>DEVICES</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_NUM_KERNELS"></a><a href="#CL_PROGRAM_NUM_KERNELS"><code>CL_PROGRAM_<wbr>NUM_<wbr>KERNELS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the number of kernels declared in <em>program</em> that can be |
| created with <a href="#clCreateKernel"><strong>clCreateKernel</strong></a>. |
| This information is only available after a successful program |
| executable has been built for at least one device in the list of |
| devices associated with <em>program</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_KERNEL_NAMES"></a><a href="#CL_PROGRAM_KERNEL_NAMES"><code>CL_PROGRAM_<wbr>KERNEL_<wbr>NAMES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns a semi-colon separated list of kernel names in <em>program</em> |
| that can be created with <a href="#clCreateKernel"><strong>clCreateKernel</strong></a>. |
| This information is only available after a successful program |
| executable has been built for at least one device in the list of |
| devices associated with <em>program</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"></a><a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.2 and <a href="#unified-spec">deprecated by</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This indicates that the <em>program</em> object contains non-trivial |
| constructor(s) that will be executed by runtime before any kernel |
| from the program is executed. |
| This information is only available after a successful program |
| executable has been built for at least one device in the list of |
| devices associated with <em>program</em>.</p> |
| <p class="tableblock"> Querying <a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a> may unconditionally |
| return <a href="#CL_FALSE"><code>CL_FALSE</code></a> if no devices associated with <em>program</em> support |
| constructors for program scope global variables. |
| Support for constructors and destructors for program scope global |
| variables is required only for OpenCL 2.2 devices.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT"></a><a href="#CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>DTORS_<wbr>PRESENT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.2 and <a href="#unified-spec">deprecated by</a> version 3.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This indicates that the program object contains non-trivial |
| destructor(s) that will be executed by runtime when <em>program</em> is |
| destroyed. |
| This information is only available after a successful program |
| executable has been built for at least one device in the list of |
| devices associated with <em>program</em>.</p> |
| <p class="tableblock"> Querying <a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a> may unconditionally |
| return <a href="#CL_FALSE"><code>CL_FALSE</code></a> if no devices associated with <em>program</em> support |
| destructors for program scope global variables. |
| Support for constructors and destructors for program scope global |
| variables is required only for OpenCL 2.2 devices.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#program-info-table">Program Object Queries</a> table and |
| <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is a not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM_EXECUTABLE"><code>CL_INVALID_<wbr>PROGRAM_<wbr>EXECUTABLE</code></a> if <em>param_name</em> is |
| <a href="#CL_PROGRAM_NUM_KERNELS"><code>CL_PROGRAM_<wbr>NUM_<wbr>KERNELS</code></a>, <a href="#CL_PROGRAM_KERNEL_NAMES"><code>CL_PROGRAM_<wbr>KERNEL_<wbr>NAMES</code></a>, |
| <a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a>, or |
| <a href="#CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>DTORS_<wbr>PRESENT</code></a> and a successful program executable |
| has not been built for at least one device in the list of devices |
| associated with <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return build information for each device in the program object, call the |
| function</p> |
| </div> |
| <div id="clGetProgramBuildInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetProgramBuildInfo( |
| cl_program program, |
| cl_device_id device, |
| cl_program_build_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> specifies the program object being queried.</p> |
| </li> |
| <li> |
| <p><em>device</em> specifies the device for which build information is being queried. |
| <em>device</em> must be a valid device associated with <em>program</em>.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetProgramBuildInfo"><strong>clGetProgramBuildInfo</strong></a> is described in the |
| <a href="#program-build-info-table">Program Build Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#program-build-info-table">Program Build Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="program-build-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 30. List of supported param_names by <a href="#clGetProgramBuildInfo">clGetProgramBuildInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Program Build Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BUILD_STATUS"></a><a href="#CL_PROGRAM_BUILD_STATUS"><code>CL_PROGRAM_<wbr>BUILD_<wbr>STATUS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_build_<wbr>status</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the build, compile or link status, whichever was performed |
| last on the specified <em>program</em> object for <em>device</em>.</p> |
| <p class="tableblock"> This can be one of the following:</p> |
| <p class="tableblock"> <a id="CL_BUILD_NONE"></a><a href="#CL_BUILD_NONE"><code>CL_BUILD_<wbr>NONE</code></a> - The build status returned if no <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> has been performed on the |
| specified <em>program</em> object for <em>device</em>).</p> |
| <p class="tableblock"> <a id="CL_BUILD_ERROR"></a><a href="#CL_BUILD_ERROR"><code>CL_BUILD_<wbr>ERROR</code></a> - The build status returned if <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> - whichever was performed last |
| on the specified <em>program</em> object for <em>device</em> - generated an error.</p> |
| <p class="tableblock"> <a id="CL_BUILD_SUCCESS"></a><a href="#CL_BUILD_SUCCESS"><code>CL_BUILD_<wbr>SUCCESS</code></a> - The build status returned if <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> - whichever was performed last |
| on the specified <em>program</em> object for <em>device</em> - was successful.</p> |
| <p class="tableblock"> <a id="CL_BUILD_IN_PROGRESS"></a><a href="#CL_BUILD_IN_PROGRESS"><code>CL_BUILD_<wbr>IN_<wbr>PROGRESS</code></a> - The build status returned if |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> - whichever |
| was performed last on the specified <em>program</em> object for <em>device</em> - has |
| not finished.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BUILD_OPTIONS"></a><a href="#CL_PROGRAM_BUILD_OPTIONS"><code>CL_PROGRAM_<wbr>BUILD_<wbr>OPTIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the build, compile or link options specified by the options |
| argument in <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>, |
| whichever was performed last on the specified <em>program</em> object for |
| <em>device</em>.</p> |
| <p class="tableblock"> If build status of the specified <em>program</em> for <em>device</em> is |
| <a href="#CL_BUILD_NONE"><code>CL_BUILD_<wbr>NONE</code></a>, an empty string is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BUILD_LOG"></a><a href="#CL_PROGRAM_BUILD_LOG"><code>CL_PROGRAM_<wbr>BUILD_<wbr>LOG</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the build, compile or link log for <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>, |
| <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> or <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>, whichever was performed last |
| on program for device.</p> |
| <p class="tableblock"> If build status of the specified <em>program</em> for <em>device</em> is |
| <a href="#CL_BUILD_NONE"><code>CL_BUILD_<wbr>NONE</code></a>, an empty string is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BINARY_TYPE"></a><a href="#CL_PROGRAM_BINARY_TYPE"><code>CL_PROGRAM_<wbr>BINARY_<wbr>TYPE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_program_<wbr>binary_<wbr>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the program binary type for device. |
| This can be one of the following values:</p> |
| <p class="tableblock"> <a id="CL_PROGRAM_BINARY_TYPE_NONE"></a><a href="#CL_PROGRAM_BINARY_TYPE_NONE"><code>CL_PROGRAM_<wbr>BINARY_<wbr>TYPE_<wbr>NONE</code></a> - There is no binary associated |
| with the specified <em>program</em> object for <em>device</em>.</p> |
| <p class="tableblock"> <a id="CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT"></a><a href="#CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT"><code>CL_PROGRAM_<wbr>BINARY_<wbr>TYPE_<wbr>COMPILED_<wbr>OBJECT</code></a> - A compiled binary is |
| associated with <em>device</em>. |
| This is the case when the specified <em>program</em> object was created using |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> and compiled using <a href="#clCompileProgram"><strong>clCompileProgram</strong></a>, or |
| when a compiled binary was loaded using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>.</p> |
| <p class="tableblock"> <a id="CL_PROGRAM_BINARY_TYPE_LIBRARY"></a><a href="#CL_PROGRAM_BINARY_TYPE_LIBRARY"><code>CL_PROGRAM_<wbr>BINARY_<wbr>TYPE_<wbr>LIBRARY</code></a> - A library binary is |
| associated with <em>device</em>. |
| This is the case when the specified <em>program</em> object was linked by |
| <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> using the <code>-create-library</code> link option, or when a |
| compiled library binary was loaded using <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>.</p> |
| <p class="tableblock"> <a id="CL_PROGRAM_BINARY_TYPE_EXECUTABLE"></a><a href="#CL_PROGRAM_BINARY_TYPE_EXECUTABLE"><code>CL_PROGRAM_<wbr>BINARY_<wbr>TYPE_<wbr>EXECUTABLE</code></a> - An executable binary is |
| associated with <em>device</em>. |
| This is the case when the specified <em>program</em> object was linked by |
| <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> without the <code>-create-library</code> link option, or when an |
| executable binary was built using <a href="#clBuildProgram"><strong>clBuildProgram</strong></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROGRAM_BUILD_GLOBAL_VARIABLE_TOTAL_SIZE"></a><a href="#CL_PROGRAM_BUILD_GLOBAL_VARIABLE_TOTAL_SIZE"><code>CL_PROGRAM_<wbr>BUILD_<wbr>GLOBAL_<wbr>VARIABLE_<wbr>TOTAL_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The total amount of storage, in bytes, used by program variables in |
| the global address space.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetProgramBuildInfo"><strong>clGetProgramBuildInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not in the list of devices associated |
| with <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#program-build-info-table">Program Build Queries</a> table and |
| <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is a not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>A program binary (compiled binary, library binary or executable binary) |
| built for a parent device can be used by all its sub-devices. |
| If a program binary has not been built for a sub-device, the program binary |
| associated with the parent device will be used.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A program binary for a device specified with <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a> or |
| queried using <a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a> can be used as the binary for the |
| associated root device, and all sub-devices created from the root-level |
| device or sub-devices thereof.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_kernel_objects"><a class="anchor" href="#_kernel_objects"></a>5.9. Kernel Objects</h3> |
| <div class="paragraph"> |
| <p>A kernel is a function declared in a program. |
| A kernel is identified by the <code>__kernel</code> qualifier applied to any function |
| in a program. |
| A kernel object encapsulates the specific <code>__kernel</code> function declared in |
| a program and the argument values to be used when executing this |
| <code>__kernel</code> function.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_kernel_objects"><a class="anchor" href="#_creating_kernel_objects"></a>5.9.1. Creating Kernel Objects</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a kernel object, use the function</p> |
| </div> |
| <div id="clCreateKernel" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_kernel clCreateKernel( |
| cl_program program, |
| <span class="directive">const</span> <span class="predefined-type">char</span>* kernel_name, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is a program object with a successfully built executable.</p> |
| </li> |
| <li> |
| <p><em>kernel_name</em> is a function name in the program declared with the |
| <code>__kernel</code> qualifier.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateKernel"><strong>clCreateKernel</strong></a> returns a valid non-zero kernel object and <em>errcode_ret</em> is |
| set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the kernel object is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM_EXECUTABLE"><code>CL_INVALID_<wbr>PROGRAM_<wbr>EXECUTABLE</code></a> if there is no successfully built |
| executable for <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL_NAME"><code>CL_INVALID_<wbr>KERNEL_<wbr>NAME</code></a> if <em>kernel_name</em> is not found in <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL_DEFINITION"><code>CL_INVALID_<wbr>KERNEL_<wbr>DEFINITION</code></a> if the function definition for <code>__kernel</code> |
| function given by <em>kernel_name</em> such as the number of arguments, the |
| argument types are not the same for all devices for which the <em>program</em> |
| executable has been built.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>kernel_name</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create kernel objects for all kernel functions in a program, |
| call the function</p> |
| </div> |
| <div id="clCreateKernelsInProgram" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clCreateKernelsInProgram( |
| cl_program program, |
| cl_uint num_kernels, |
| cl_kernel* kernels, |
| cl_uint* num_kernels_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>program</em> is a program object with a successfully built executable.</p> |
| </li> |
| <li> |
| <p><em>num_kernels</em> is the size of memory pointed to by <em>kernels</em> specified as the |
| number of <code>cl_kernel</code> entries.</p> |
| </li> |
| <li> |
| <p><em>kernels</em> is the buffer where the kernel objects for kernels in <em>program</em> |
| will be returned. |
| If <em>kernels</em> is <code>NULL</code>, it is ignored. |
| If <em>kernels</em> is not <code>NULL</code>, <em>num_kernels</em> must be greater than or equal to |
| the number of kernels in <em>program</em>.</p> |
| </li> |
| <li> |
| <p><em>num_kernels_ret</em> is the number of kernels in <em>program</em>. |
| If <em>num_kernels_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Kernel objects are not created for any <code>__kernel</code> functions in <em>program</em> |
| that do not have the same function definition across all devices for which a |
| program executable has been successfully built.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Kernel objects can only be created once you have a program object with a |
| valid program source or binary loaded into the program object and the |
| program executable has been successfully built for one or more devices |
| associated with program. |
| No changes to the program executable are allowed while there are kernel |
| objects associated with a program object. |
| This means that calls to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> and <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> return |
| <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if there are kernel objects attached to a program |
| object. |
| The OpenCL context associated with <em>program</em> will be the context associated |
| with <em>kernel</em>. |
| The list of devices associated with <em>program</em> are the devices associated |
| with <em>kernel</em>. |
| Devices associated with a program object for which a valid program |
| executable has been built can be used to execute kernels declared in the |
| program object.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateKernelsInProgram"><strong>clCreateKernelsInProgram</strong></a> will return <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the kernel objects were |
| successfully allocated. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a> if <em>program</em> is not a valid program object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM_EXECUTABLE"><code>CL_INVALID_<wbr>PROGRAM_<wbr>EXECUTABLE</code></a> if there is no successfully built |
| executable for any device in <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>kernels</em> is not <code>NULL</code> and <em>num_kernels</em> is less |
| than the number of kernels in <em>program</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain a kernel object, call the function</p> |
| </div> |
| <div id="clRetainKernel" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainKernel( |
| cl_kernel kernel);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> is the kernel object to be retained.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>kernel</em> reference count is incremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainKernel"><strong>clRetainKernel</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateKernel"><strong>clCreateKernel</strong></a> or <a href="#clCreateKernelsInProgram"><strong>clCreateKernelsInProgram</strong></a> do an implicit retain.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release a kernel object, call the function</p> |
| </div> |
| <div id="clReleaseKernel" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseKernel( |
| cl_kernel kernel);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> is the kernel object to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>kernel</em> reference count is decremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The kernel object is deleted once the number of instances that are retained |
| to <em>kernel</em> become zero and the kernel object is no longer needed by any |
| enqueued commands that use <em>kernel</em>. |
| Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainKernel"><strong>clRetainKernel</strong></a> causes undefined behavior.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseKernel"><strong>clReleaseKernel</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_setting_kernel_arguments"><a class="anchor" href="#_setting_kernel_arguments"></a>5.9.2. Setting Kernel Arguments</h4> |
| <div class="paragraph"> |
| <p>To execute a kernel, the kernel arguments must be set.</p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To set the argument value for a specific argument of a kernel, call the |
| function</p> |
| </div> |
| <div id="clSetKernelArg" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetKernelArg( |
| cl_kernel kernel, |
| cl_uint arg_index, |
| size_t arg_size, |
| <span class="directive">const</span> <span class="directive">void</span>* arg_value);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> is a valid kernel object.</p> |
| </li> |
| <li> |
| <p><em>arg_index</em> is the argument index. |
| Arguments to the kernel are referred by indices that go from 0 for the |
| leftmost argument to <em>n</em> - 1, where <em>n</em> is the total number of arguments |
| declared by a kernel (see below).</p> |
| </li> |
| <li> |
| <p><em>arg_size</em> specifies the size of the argument value. |
| If the argument is a memory object, the <em>arg_size</em> value must be equal to |
| <code>sizeof(<code>cl_mem</code>)</code>. |
| For arguments declared with the <code>local</code> qualifier, the size specified will |
| be the size in bytes of the buffer that must be allocated for the <code>local</code> |
| argument. |
| If the argument is of type <em>sampler_t</em>, the <em>arg_size</em> value must be equal |
| to <code>sizeof(<code>cl_sampler</code>)</code>. |
| If the argument is of type <em>queue_t</em>, the <em>arg_size</em> value must be equal to |
| <code>sizeof(<code>cl_command_<wbr>queue</code>)</code>. |
| For all other arguments, the size will be the size of argument type.</p> |
| </li> |
| <li> |
| <p><em>arg_value</em> is a pointer to data that should be used as the argument value |
| for argument specified by <em>arg_index</em>. |
| The argument data pointed to by <em>arg_value</em> is copied and the <em>arg_value</em> |
| pointer can therefore be reused by the application after <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a> |
| returns. |
| The argument value specified is the value used by all API calls that enqueue |
| <em>kernel</em> (<a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> and <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a>) until the argument |
| value is changed by a call to <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a> for <em>kernel</em>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For example, consider the following kernel:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">kernel <span class="directive">void</span> image_filter (<span class="predefined-type">int</span> n, |
| <span class="predefined-type">int</span> m, |
| constant <span class="predefined-type">float</span> *filter_weights, |
| read_only image2d_t src_image, |
| write_only image2d_t dst_image) |
| { |
| ... |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Argument index values for <code>image_filter</code> will be 0 for <code>n</code>, 1 for <code>m</code>, 2 for |
| <code>filter_weights</code>, 3 for <code>src_image</code> and 4 for <code>dst_image</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the argument is a memory object (buffer, pipe, image or image array), the |
| <em>arg_value</em> entry will be a pointer to the appropriate buffer, pipe, image |
| or image array object. |
| The memory object must be created with the context associated with the |
| kernel object. |
| If the argument is a buffer object, the <em>arg_value</em> pointer can be <code>NULL</code> or |
| point to a <code>NULL</code> value in which case a <code>NULL</code> value will be used as the |
| value for the argument declared as a pointer to <code>global</code> or <code>constant</code> |
| memory in the kernel. |
| If the argument is declared with the <code>local</code> qualifier, the <em>arg_value</em> |
| entry must be <code>NULL</code>. |
| If the argument is of type <em>sampler_t</em>, the <em>arg_value</em> entry must be a |
| pointer to the sampler object. |
| If the argument is of type <em>queue_t</em>, the <em>arg_value</em> entry must be a |
| pointer to the device queue object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the argument is declared to be a pointer of a built-in scalar or vector |
| type, or a user defined structure type in the global or constant address |
| space, the memory object specified as argument value must be a buffer object |
| (or <code>NULL</code>). |
| If the argument is declared with the <code>constant</code> qualifier, the size in bytes |
| of the memory object cannot exceed <a href="#CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>CONSTANT_<wbr>BUFFER_<wbr>SIZE</code></a> and |
| the number of arguments declared as pointers to <code>constant</code> memory cannot |
| exceed <a href="#CL_DEVICE_MAX_CONSTANT_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>CONSTANT_<wbr>ARGS</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The memory object specified as argument value must be a pipe object if the |
| argument is declared with the <em>pipe</em> qualifier.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The memory object specified as argument value must be a 2D image object if |
| the argument is declared to be of type <em>image2d_t</em>. |
| The memory object specified as argument value must be a 2D image object with |
| image channel order = <a href="#CL_DEPTH"><code>CL_DEPTH</code></a> if the argument is declared to be of type |
| <em>image2d_depth_t</em>. |
| The memory object specified as argument value must be a 3D image object if |
| argument is declared to be of type <em>image3d_t</em>. |
| The memory object specified as argument value must be a 1D image object if |
| the argument is declared to be of type <em>image1d_t</em>. |
| The memory object specified as argument value must be a 1D image buffer |
| object if the argument is declared to be of type <em>image1d_buffer_t</em>. |
| The memory object specified as argument value must be a 1D image array |
| object if argument is declared to be of type <em>image1d_array_t</em>. |
| The memory object specified as argument value must be a 2D image array |
| object if argument is declared to be of type <em>image2d_array_t</em>. |
| The memory object specified as argument value must be a 2D image array |
| object with image channel order = <a href="#CL_DEPTH"><code>CL_DEPTH</code></a> if argument is declared to be of |
| type <em>image2d_array_depth_t</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For all other kernel arguments, the <em>arg_value</em> entry must be a pointer to |
| the actual data to be used as argument value.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>A kernel object does not update the reference count for objects such as |
| memory or sampler objects specified as argument values by <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>. |
| Users may not rely on a kernel object to retain objects specified as |
| argument values to the kernel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Implementations shall not allow <code>cl_kernel</code> objects to hold reference |
| counts to <code>cl_kernel</code> arguments, because no mechanism is provided for the |
| user to tell the kernel to release that ownership right. |
| If the kernel holds ownership rights on kernel args, that would make it |
| impossible for users to tell with certainty when they may safely |
| release user allocated resources associated with OpenCL objects such as |
| the <code>cl_mem</code> backing store used with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function was executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_ARG_INDEX"><code>CL_INVALID_<wbr>ARG_<wbr>INDEX</code></a> if <em>arg_index</em> is not a valid argument index.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_ARG_VALUE"><code>CL_INVALID_<wbr>ARG_<wbr>VALUE</code></a> if <em>arg_value</em> specified is not a valid value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> for an argument declared to be a memory object |
| when the specified <em>arg_value</em> is not a valid memory object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_SAMPLER"><code>CL_INVALID_<wbr>SAMPLER</code></a> for an argument declared to be of type <em>sampler_t</em> |
| when the specified <em>arg_value</em> is not a valid sampler object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE_QUEUE"><code>CL_INVALID_<wbr>DEVICE_<wbr>QUEUE</code></a> for an argument declared to be of type <em>queue_t</em> |
| when the specified <em>arg_value</em> is not a valid device queue object. |
| This error code is <a href="#unified-spec">missing before</a> version 2.0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_ARG_SIZE"><code>CL_INVALID_<wbr>ARG_<wbr>SIZE</code></a> if <em>arg_size</em> does not match the size of the data |
| type for an argument that is not a memory object or if the argument is a |
| memory object and <em>arg_size</em> != <code>sizeof(<code>cl_mem</code>)</code> or if <em>arg_size</em> is |
| zero and the argument is declared with the local qualifier or if the |
| argument is a sampler and <em>arg_size</em> != <code>sizeof(<code>cl_sampler</code>)</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MAX_SIZE_RESTRICTION_EXCEEDED"><code>CL_MAX_<wbr>SIZE_<wbr>RESTRICTION_<wbr>EXCEEDED</code></a> if the size in bytes of the memory |
| object (if the argument is a memory object) or <em>arg_size</em> (if the |
| argument is declared with <code>local</code> qualifier) exceeds a language- |
| specified maximum size restriction for this argument, such as the |
| <strong>MaxByteOffset</strong> SPIR-V decoration. |
| This error code is <a href="#unified-spec">missing before</a> version 2.2.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_ARG_VALUE"><code>CL_INVALID_<wbr>ARG_<wbr>VALUE</code></a> if the argument is an image declared with the |
| <code>read_only</code> qualifier and <em>arg_value</em> refers to an image object created |
| with <em>cl_mem_flags</em> of <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a> or if the image argument is |
| declared with the <code>write_only</code> qualifier and <em>arg_value</em> refers to an |
| image object created with <em>cl_mem_flags</em> of <a href="#CL_MEM_READ_ONLY"><code>CL_MEM_<wbr>READ_<wbr>ONLY</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To set a SVM pointer as the argument value for a specific argument of a |
| kernel, call the function</p> |
| </div> |
| <div id="clSetKernelArgSVMPointer" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetKernelArgSVMPointer( |
| cl_kernel kernel, |
| cl_uint arg_index, |
| <span class="directive">const</span> <span class="directive">void</span>* arg_value);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> is a valid kernel object.</p> |
| </li> |
| <li> |
| <p><em>arg_index</em> is the argument index. |
| Arguments to the kernel are referred by indices that go from 0 for the |
| leftmost argument to <em>n</em> - 1, where <em>n</em> is the total number of arguments |
| declared by a kernel.</p> |
| </li> |
| <li> |
| <p><em>arg_value</em> is the SVM pointer that should be used as the argument value for |
| argument specified by <em>arg_index</em>. |
| The SVM pointer specified is the value used by all API calls that enqueue |
| <em>kernel</em> (<a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> and <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a>) until the argument |
| value is changed by a call to <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a> for <em>kernel</em>. |
| The SVM pointer can only be used for arguments that are declared to be a |
| pointer to <code>global</code> or <code>constant</code> memory. |
| The SVM pointer value must be aligned according to the arguments type. |
| For example, if the argument is declared to be <code>global float4 *p</code>, the SVM |
| pointer value passed for <code>p</code> must be at a minimum aligned to a <code>float4</code>. |
| The SVM pointer value specified as the argument value can be the pointer |
| returned by <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> or can be a pointer offset into the SVM region.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function was executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in the context associated with <em>kernel</em> support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_ARG_INDEX"><code>CL_INVALID_<wbr>ARG_<wbr>INDEX</code></a> if <em>arg_index</em> is not a valid argument index.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_ARG_VALUE"><code>CL_INVALID_<wbr>ARG_<wbr>VALUE</code></a> if <em>arg_value</em> specified is not a valid value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To pass additional information other than argument values to a kernel, call |
| the function</p> |
| </div> |
| <div id="clSetKernelExecInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetKernelExecInfo( |
| cl_kernel kernel, |
| cl_kernel_exec_info param_name, |
| size_t param_value_size, |
| <span class="directive">const</span> <span class="directive">void</span>* param_value);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> is <a href="#unified-spec">missing before</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> specifies the kernel object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to be passed to kernel. |
| The list of supported <em>param_name</em> types and the corresponding values passed |
| in <em>param_value</em> is described in the <a href="#kernel-exec-info-table">Kernel |
| Execution Properties</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> specifies the size in bytes of the memory pointed to by |
| <em>param_value</em>.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate values determined |
| by <em>param_name</em> are specified.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="kernel-exec-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 31. List of supported param_names by <a href="#clSetKernelExecInfo">clSetKernelExecInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Kernel Exec Info</th> |
| <th class="tableblock halign-left valign-top">Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_EXEC_INFO_SVM_PTRS"></a><a href="#CL_KERNEL_EXEC_INFO_SVM_PTRS"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>PTRS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>void</code>*[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">SVM pointers must reference locations contained entirely within |
| buffers that are passed to kernel as arguments, or that are passed |
| through the execution information.</p> |
| <p class="tableblock"> Non-argument SVM buffers must be specified by passing pointers to |
| those buffers via <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> for coarse-grain and |
| fine-grain buffer SVM allocations but not for finegrain system SVM |
| allocations.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"></a><a href="#CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This flag indicates whether the kernel uses pointers that are fine |
| grain system SVM allocations. |
| These fine grain system SVM pointers may be passed as arguments or |
| defined in SVM buffers that are passed as arguments to <em>kernel</em>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is a not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in the context associated with <em>kernel</em> support SVM.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, if <em>param_value</em> is |
| <code>NULL</code> or if the size specified by <em>param_value_size</em> is not valid.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>param_name</em> is |
| <a href="#CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a> and <em>param_value</em> is <a href="#CL_TRUE"><code>CL_TRUE</code></a> |
| but no devices in context associated with <em>kernel</em> support fine-grain |
| system SVM allocations.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Coarse-grain or fine-grain buffer SVM pointers used by a kernel which |
| are not passed as a kernel arguments must be specified using |
| <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> with <a href="#CL_KERNEL_EXEC_INFO_SVM_PTRS"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>PTRS</code></a>. |
| For example, if SVM buffer A contains a pointer to another SVM buffer B, |
| and the kernel dereferences that pointer, then a pointer to B must |
| either be passed as an argument in the call to that kernel or it must be |
| made available to the kernel using <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a>. |
| For example, we might pass extra SVM pointers as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">clSetKernelExecInfo(kernel, |
| CL_KERNEL_EXEC_INFO_SVM_PTRS, |
| num_ptrs * <span class="keyword">sizeof</span>(<span class="directive">void</span> *), |
| extra_svm_ptr_list);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here <code>num_ptrs</code> specifies the number of additional SVM pointers while |
| <code>extra_svm_ptr_list</code> specifies a pointer to memory containing those SVM |
| pointers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When calling <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> with <a href="#CL_KERNEL_EXEC_INFO_SVM_PTRS"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>PTRS</code></a> to |
| specify pointers to non-argument SVM buffers as extra arguments to a kernel, |
| each of these pointers can be the SVM pointer returned by <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> or |
| can be a pointer + offset into the SVM region. |
| It is sufficient to provide one pointer for each SVM buffer used.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a> is used to indicate whether |
| SVM pointers used by a kernel will refer to system allocations or not.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a> = <a href="#CL_FALSE"><code>CL_FALSE</code></a> indicates that the |
| OpenCL implementation may assume that system pointers are not passed as |
| kernel arguments and are not stored inside SVM allocations passed as kernel |
| arguments.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a> = <a href="#CL_TRUE"><code>CL_TRUE</code></a> indicates that the |
| OpenCL implementation must assume that system pointers might be passed as |
| kernel arguments and/or stored inside SVM allocations passed as kernel |
| arguments. |
| In this case, if the device to which the kernel is enqueued does not support |
| system SVM pointers, <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> and <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> will return a |
| <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> error. |
| If none of the devices in the context associated with kernel support |
| fine-grain system SVM allocations, <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> will return a |
| <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> error.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> has not been called with a value for |
| <a href="#CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM"><code>CL_KERNEL_<wbr>EXEC_<wbr>INFO_<wbr>SVM_<wbr>FINE_<wbr>GRAIN_<wbr>SYSTEM</code></a>, the default value is used for |
| this kernel attribute. |
| The default value depends on whether the device on which the kernel is |
| enqueued supports fine-grain system SVM allocations. |
| If so, the default value used is <a href="#CL_TRUE"><code>CL_TRUE</code></a> (system pointers might be passed); |
| otherwise, the default is <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A call to <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> for a given value of <em>param_name</em> |
| replaces any prior value passed for that value of <em>param_name</em>. |
| Only one <em>param_value</em> will be stored for each value of <em>param_name</em>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_copying_kernel_objects"><a class="anchor" href="#_copying_kernel_objects"></a>5.9.3. Copying Kernel Objects</h4> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Copying kernel objects is <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To clone a kernel object, call the function</p> |
| </div> |
| <div id="clCloneKernel" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_kernel clCloneKernel( |
| cl_kernel source_kernel, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCloneKernel"><strong>clCloneKernel</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>source_kernel</em> is a valid <code>cl_kernel</code> object that will be copied. |
| <em>source_kernel</em> will not be modified in any way by this function.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will be assigned an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Cloning is used to make a shallow copy of the kernel object, its arguments |
| and any information passed to the kernel object using <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a>. |
| If the kernel object was ready to be enqueued before copying it, the clone |
| of the kernel object is ready to enqueue.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The returned kernel object is an exact copy of <em>source_kernel</em>, with one |
| caveat: the reference count on the returned kernel object is set as if it |
| had been returned by <a href="#clCreateKernel"><strong>clCreateKernel</strong></a>. |
| The reference count of <em>source_kernel will</em> not be changed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The resulting kernel will be in the same state as if <a href="#clCreateKernel"><strong>clCreateKernel</strong></a> is |
| called to create the resultant kernel with the same arguments as those used |
| to create <em>source_kernel</em>, the latest call to <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a> or |
| <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a> for each argument index applied to kernel and the |
| last call to <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> for each value of the param name |
| parameter are applied to the new kernel object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All arguments of the new kernel object must be intact and it may be |
| correctly used in the same situations as kernel except those that assume a |
| pre-existing reference count. |
| Setting arguments on the new kernel object will not affect <em>source_kernel</em> |
| except insofar as the argument points to a shared underlying entity and in |
| that situation behavior is as if two kernel objects had been created and the |
| same argument applied to each. |
| Only the data stored in the kernel object is copied; data referenced by the |
| kernels arguments are not copied. |
| For example, if a buffer or pointer argument is set on a kernel object, the |
| pointer is copied but the underlying memory allocation is not.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCloneKernel"><strong>clCloneKernel</strong></a> returns a valid non-zero kernel object and <em>errcode_ret</em> is |
| set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the kernel is successfully copied. |
| Otherwise it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_kernel_object_queries"><a class="anchor" href="#_kernel_object_queries"></a>5.9.4. Kernel Object Queries</h4> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about a kernel object, call the function</p> |
| </div> |
| <div id="clGetKernelInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetKernelInfo( |
| cl_kernel kernel, |
| cl_kernel_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> specifies the kernel object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetKernelInfo"><strong>clGetKernelInfo</strong></a> is described in the |
| <a href="#kernel-info-table">Kernel Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#kernel-info-table">Kernel Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="kernel-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 32. List of supported param_names by <a href="#clGetKernelInfo">clGetKernelInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Kernel Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_FUNCTION_NAME"></a><a href="#CL_KERNEL_FUNCTION_NAME"><code>CL_KERNEL_<wbr>FUNCTION_<wbr>NAME</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the kernel function name.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_NUM_ARGS"></a><a href="#CL_KERNEL_NUM_ARGS"><code>CL_KERNEL_<wbr>NUM_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the number of arguments to kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_REFERENCE_COUNT"></a><a href="#CL_KERNEL_REFERENCE_COUNT"><code>CL_KERNEL_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_28" class="footnote" href="#_footnotedef_28" title="View footnote.">28</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the <em>kernel</em> reference count.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_CONTEXT"></a><a href="#CL_KERNEL_CONTEXT"><code>CL_KERNEL_<wbr>CONTEXT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the context associated with <em>kernel</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_PROGRAM"></a><a href="#CL_KERNEL_PROGRAM"><code>CL_KERNEL_<wbr>PROGRAM</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_program</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the program object associated with kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ATTRIBUTES"></a><a href="#CL_KERNEL_ATTRIBUTES"><code>CL_KERNEL_<wbr>ATTRIBUTES</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns any attributes specified using the <code>__attribute__</code> |
| OpenCL C qualifier (or using an OpenCL C++ qualifier syntax [[]] ) |
| with the kernel function declaration in the program source. |
| These attributes include attributes described in the earlier OpenCL |
| C kernel language specifications and other attributes supported by |
| an implementation.</p> |
| <p class="tableblock"> Attributes are returned as they were declared inside |
| <code>__attribute__((...))</code>, with any surrounding whitespace and |
| embedded newlines removed. |
| When multiple attributes are present, they are returned as a single, |
| space delimited string.</p> |
| <p class="tableblock"> For kernels not created from OpenCL C source and the |
| <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> API call the string returned from this |
| query will be empty.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetKernelInfo"><strong>clGetKernelInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#kernel-info-table">Kernel Object Queries</a> table and <em>param_value</em> |
| is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is a not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about the kernel object that may be specific to a |
| device, call the function</p> |
| </div> |
| <div id="clGetKernelWorkGroupInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetKernelWorkGroupInfo( |
| cl_kernel kernel, |
| cl_device_id device, |
| cl_kernel_work_group_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> specifies the kernel object being queried.</p> |
| </li> |
| <li> |
| <p><em>device</em> identifies a specific device in the list of devices associated with |
| <em>kernel</em>. |
| The list of devices is the list of devices in the OpenCL context that is |
| associated with <em>kernel</em>. |
| If the list of devices associated with <em>kernel</em> is a single device, <em>device</em> |
| can be a <code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a> is described in the |
| <a href="#kernel-workgroup-info-table">Kernel Object Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#kernel-workgroup-info-table">Kernel Object Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="kernel-workgroup-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 33. List of supported param_names by <a href="#clGetKernelWorkGroupInfo">clGetKernelWorkGroupInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Kernel Work Group Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_GLOBAL_WORK_SIZE"></a><a href="#CL_KERNEL_GLOBAL_WORK_SIZE"><code>CL_KERNEL_<wbr>GLOBAL_<wbr>WORK_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>[3]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This provides a mechanism for the application to query the maximum |
| global size that can be used to execute a kernel (i.e. |
| <em>global_work_size</em> argument to <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>) on a custom |
| device given by device or a built-in kernel on an OpenCL device |
| given by device.</p> |
| <p class="tableblock"> If device is not a custom device and kernel is not a built-in |
| kernel, <a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a> returns the error |
| <a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_WORK_GROUP_SIZE"></a><a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This provides a mechanism for the application to query the maximum |
| work-group size that can be used to execute the kernel on a specific |
| device given by device. |
| The OpenCL implementation uses the resource requirements of the |
| kernel (register usage etc.) to determine what this work-group size |
| should be.</p> |
| <p class="tableblock"> As a result and unlike <a href="#CL_DEVICE_MAX_WORK_GROUP_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> this value may |
| vary from one kernel to another as well as one device to another.</p> |
| <p class="tableblock"> <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> will be less than or equal to |
| <a href="#CL_DEVICE_MAX_WORK_GROUP_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> for a given kernel object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_COMPILE_WORK_GROUP_SIZE"></a><a href="#CL_KERNEL_COMPILE_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>COMPILE_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>[3]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the work-group size specified in the kernel source or IL.</p> |
| <p class="tableblock"> If the work-group size is not specified in the kernel source or IL, |
| (0, 0, 0) is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_LOCAL_MEM_SIZE"></a><a href="#CL_KERNEL_LOCAL_MEM_SIZE"><code>CL_KERNEL_<wbr>LOCAL_<wbr>MEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the amount of local memory in bytes being used by a kernel. |
| This includes local memory that may be needed by an implementation |
| to execute the kernel, variables declared inside the kernel with the |
| <code>__local</code> address qualifier and local memory to be allocated for |
| arguments to the kernel declared as pointers with the <code>__local</code> |
| address qualifier and whose size is specified with <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>.</p> |
| <p class="tableblock"> If the local memory size, for any pointer argument to the kernel |
| declared with the <code>__local</code> address qualifier, is not specified, |
| its size is assumed to be 0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"></a><a href="#CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"><code>CL_KERNEL_<wbr>PREFERRED_<wbr>WORK_<wbr>GROUP_<wbr>SIZE_<wbr>MULTIPLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the preferred multiple of work-group size for launch. |
| This is a performance hint. |
| Specifying a work-group size that is not a multiple of the value |
| returned by this query as the value of the local work size argument |
| to <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> will not fail to enqueue the kernel for |
| execution unless the work-group size specified is larger than the |
| device maximum.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_PRIVATE_MEM_SIZE"></a><a href="#CL_KERNEL_PRIVATE_MEM_SIZE"><code>CL_KERNEL_<wbr>PRIVATE_<wbr>MEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the minimum amount of private memory, in bytes, used by each |
| work-item in the kernel. |
| This value may include any private memory needed by an |
| implementation to execute the kernel, including that used by the |
| language built-ins and variable declared inside the kernel with the |
| <code>__private</code> qualifier.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not in the list of devices associated |
| with <em>kernel</em> or if <em>device</em> is <code>NULL</code> but there is more than one device |
| associated with <em>kernel</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#kernel-workgroup-info-table">Kernel Object Device Queries</a> table |
| and <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is <a href="#CL_KERNEL_GLOBAL_WORK_SIZE"><code>CL_KERNEL_<wbr>GLOBAL_<wbr>WORK_<wbr>SIZE</code></a> and |
| <em>device</em> is not a custom device and <em>kernel</em> is not a built-in kernel.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is a not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about a kernel object, call the function</p> |
| </div> |
| <div id="clGetKernelSubGroupInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetKernelSubGroupInfo( |
| cl_kernel kernel, |
| cl_device_id device, |
| cl_kernel_sub_group_info param_name, |
| size_t input_value_size, |
| <span class="directive">const</span> <span class="directive">void</span>* input_value, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a> is <a href="#unified-spec">missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> specifies the kernel object being queried.</p> |
| </li> |
| <li> |
| <p><em>device</em> identifies a specific device in the list of devices associated with |
| <em>kernel</em>. |
| The list of devices is the list of devices in the OpenCL context that is |
| associated with <em>kernel</em>. |
| If the list of devices associated with <em>kernel</em> is a single device, <em>device</em> |
| can be a <code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a> is described in the |
| <a href="#kernel-subgroup-info-table">Kernel Object Subgroup Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>input_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>input_value</em>. |
| This size must be == size of input type as described in the table below.</p> |
| </li> |
| <li> |
| <p><em>input_value</em> is a pointer to memory where the appropriate parameterization |
| of the query is passed from. |
| If <em>input_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#kernel-subgroup-info-table">Kernel Object Subgroup Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="kernel-subgroup-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 34. List of supported param_names by <a href="#clGetKernelSubGroupInfo">clGetKernelSubGroupInfo</a></caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Kernel Subgroup Info</th> |
| <th class="tableblock halign-left valign-top">Input Type</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE"></a><a href="#CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE"><code>CL_KERNEL_<wbr>MAX_<wbr>SUB_<wbr>GROUP_<wbr>SIZE_<wbr>FOR_<wbr>NDRANGE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>*</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the maximum sub-group size for this kernel. |
| All sub-groups must be the same size, while the last subgroup in |
| any work-group (i.e. the subgroup with the maximum index) could |
| be the same or smaller size.</p> |
| <p class="tableblock"> The <em>input_value</em> must be an array of <code>size_t</code> values |
| corresponding to the local work size parameter of the intended |
| dispatch. |
| The number of dimensions in the ND-range will be inferred from |
| the value specified for <em>input_value_size</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE"></a><a href="#CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE"><code>CL_KERNEL_<wbr>SUB_<wbr>GROUP_<wbr>COUNT_<wbr>FOR_<wbr>NDRANGE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>*</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the number of sub-groups that will be present in each |
| work-group for a given local work size. |
| All workgroups, apart from the last work-group in each dimension |
| in the presence of non-uniform work-group sizes, will have the |
| same number of sub-groups.</p> |
| <p class="tableblock"> The <em>input_value</em> must be an array of <code>size_t</code> values |
| corresponding to the local work size parameter of the intended |
| dispatch. |
| The number of dimensions in the ND-range will be inferred from |
| the value specified for <em>input_value_size</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT"></a><a href="#CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT"><code>CL_KERNEL_<wbr>LOCAL_<wbr>SIZE_<wbr>FOR_<wbr>SUB_<wbr>GROUP_<wbr>COUNT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the local size that will generate the requested number |
| of sub-groups for the kernel. |
| The output array must be an array of <code>size_t</code> values corresponding |
| to the local size parameter. |
| Any returned work-group will have one dimension. |
| Other dimensions inferred from the value specified for |
| param_value_size will be filled with the value 1. |
| The returned value will produce an exact number of sub-groups |
| and result in no partial groups for an executing kernel except |
| in the case where the last work-group in a dimension has a size |
| different from that of the other groups. |
| If no work-group size can accommodate the requested number of |
| sub-groups, 0 will be returned in each element of the return |
| array.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_MAX_NUM_SUB_GROUPS"></a><a href="#CL_KERNEL_MAX_NUM_SUB_GROUPS"><code>CL_KERNEL_<wbr>MAX_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">ignored</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This provides a mechanism for the application to query the |
| maximum number of sub-groups that may make up each work-group to |
| execute a kernel on a specific device given by device. |
| The OpenCL implementation uses the resource requirements of the |
| kernel (register usage etc.) to determine what this work-group |
| size should be. |
| The returned value may be used to compute a work-group size to |
| enqueue the kernel with to give a round number of sub-groups for |
| an enqueue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_COMPILE_NUM_SUB_GROUPS"></a><a href="#CL_KERNEL_COMPILE_NUM_SUB_GROUPS"><code>CL_KERNEL_<wbr>COMPILE_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.1. |
| Also see extension <strong>cl_khr_subgroups</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">ignored</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the number of sub-groups per work-group specified in the kernel |
| source or IL. If the sub-group count is not specified then 0 is returned.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a> if <em>device</em> is not in the list of devices associated |
| with <em>kernel</em> or if <em>device</em> is <code>NULL</code> but there is more than one device |
| associated with <em>kernel</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>device</em> does not support subgroups.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#kernel-subgroup-info-table">Kernel Object Subgroup Queries</a> table |
| and <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is |
| <a href="#CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE"><code>CL_KERNEL_<wbr>MAX_<wbr>SUB_<wbr>GROUP_<wbr>SIZE_<wbr>FOR_<wbr>NDRANGE</code></a> and the size in bytes specified by |
| <em>input_value_size</em> is not valid or if <em>input_value</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is a not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about the arguments of a kernel, call the function</p> |
| </div> |
| <div id="clGetKernelArgInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetKernelArgInfo( |
| cl_kernel kernel, |
| cl_uint arg_index, |
| cl_kernel_arg_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clGetKernelArgInfo"><strong>clGetKernelArgInfo</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>kernel</em> specifies the kernel object being queried.</p> |
| </li> |
| <li> |
| <p><em>arg_index</em> is the argument index. |
| Arguments to the kernel are referred by indices that go from 0 for the |
| leftmost argument to <em>n</em> - 1, where <em>n</em> is the total number of arguments |
| declared by a kernel.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the argument information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetKernelArgInfo"><strong>clGetKernelArgInfo</strong></a> is described in the |
| <a href="#kernel-argument-info-table">Kernel Argument Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be > size of return type as described in the |
| <a href="#kernel-argument-info-table">Kernel Argument Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Kernel argument information is only available if the program object |
| associated with <em>kernel</em> is created with <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a> and the |
| program executable was built with the <code>-cl-kernel-arg-info option</code> specified |
| in options argument to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> or <a href="#clCompileProgram"><strong>clCompileProgram</strong></a>.</p> |
| </div> |
| <table id="kernel-argument-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 35. List of supported param_names by <a href="#clGetKernelArgInfo">clGetKernelArgInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Kernel Arg Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ARG_ADDRESS_QUALIFIER"></a><a href="#CL_KERNEL_ARG_ADDRESS_QUALIFIER"><code>CL_KERNEL_<wbr>ARG_<wbr>ADDRESS_<wbr>QUALIFIER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_kernel_<wbr>arg_<wbr>address_<wbr>qualifier</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the address qualifier specified for the argument given by |
| <em>arg_index</em>. |
| This can be one of the following values:</p> |
| <p class="tableblock"> <a id="CL_KERNEL_ARG_ADDRESS_GLOBAL"></a><a href="#CL_KERNEL_ARG_ADDRESS_GLOBAL"><code>CL_KERNEL_<wbr>ARG_<wbr>ADDRESS_<wbr>GLOBAL</code></a><br> |
| <a id="CL_KERNEL_ARG_ADDRESS_LOCAL"></a><a href="#CL_KERNEL_ARG_ADDRESS_LOCAL"><code>CL_KERNEL_<wbr>ARG_<wbr>ADDRESS_<wbr>LOCAL</code></a><br> |
| <a id="CL_KERNEL_ARG_ADDRESS_CONSTANT"></a><a href="#CL_KERNEL_ARG_ADDRESS_CONSTANT"><code>CL_KERNEL_<wbr>ARG_<wbr>ADDRESS_<wbr>CONSTANT</code></a><br> |
| <a id="CL_KERNEL_ARG_ADDRESS_PRIVATE"></a><a href="#CL_KERNEL_ARG_ADDRESS_PRIVATE"><code>CL_KERNEL_<wbr>ARG_<wbr>ADDRESS_<wbr>PRIVATE</code></a></p> |
| <p class="tableblock"> If no address qualifier is specified, the default address qualifier |
| which is <a href="#CL_KERNEL_ARG_ADDRESS_PRIVATE"><code>CL_KERNEL_<wbr>ARG_<wbr>ADDRESS_<wbr>PRIVATE</code></a> is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ARG_ACCESS_QUALIFIER"></a><a href="#CL_KERNEL_ARG_ACCESS_QUALIFIER"><code>CL_KERNEL_<wbr>ARG_<wbr>ACCESS_<wbr>QUALIFIER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_kernel_<wbr>arg_<wbr>access_<wbr>qualifier</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the access qualifier specified for the argument given by |
| <em>arg_index</em>. |
| This can be one of the following values:</p> |
| <p class="tableblock"> <a id="CL_KERNEL_ARG_ACCESS_READ_ONLY"></a><a href="#CL_KERNEL_ARG_ACCESS_READ_ONLY"><code>CL_KERNEL_<wbr>ARG_<wbr>ACCESS_<wbr>READ_<wbr>ONLY</code></a><br> |
| <a id="CL_KERNEL_ARG_ACCESS_WRITE_ONLY"></a><a href="#CL_KERNEL_ARG_ACCESS_WRITE_ONLY"><code>CL_KERNEL_<wbr>ARG_<wbr>ACCESS_<wbr>WRITE_<wbr>ONLY</code></a><br> |
| <a id="CL_KERNEL_ARG_ACCESS_READ_WRITE"></a><a href="#CL_KERNEL_ARG_ACCESS_READ_WRITE"><code>CL_KERNEL_<wbr>ARG_<wbr>ACCESS_<wbr>READ_<wbr>WRITE</code></a><br> |
| <a id="CL_KERNEL_ARG_ACCESS_NONE"></a><a href="#CL_KERNEL_ARG_ACCESS_NONE"><code>CL_KERNEL_<wbr>ARG_<wbr>ACCESS_<wbr>NONE</code></a></p> |
| <p class="tableblock"> If argument is not an image type and is not declared with the pipe |
| qualifier, <a href="#CL_KERNEL_ARG_ACCESS_NONE"><code>CL_KERNEL_<wbr>ARG_<wbr>ACCESS_<wbr>NONE</code></a> is returned. |
| If argument is an image type, the access qualifier specified or the |
| default access qualifier is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ARG_TYPE_NAME"></a><a href="#CL_KERNEL_ARG_TYPE_NAME"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>NAME</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the type name specified for the argument given by |
| <em>arg_index</em>. |
| The type name returned will be the argument type name as it was |
| declared with any whitespace removed. |
| If argument type name is an unsigned scalar type (i.e. unsigned |
| char, unsigned short, unsigned int, unsigned long), uchar, ushort, |
| uint and ulong will be returned. |
| The argument type name returned does not include any type |
| qualifiers.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ARG_TYPE_QUALIFIER"></a><a href="#CL_KERNEL_ARG_TYPE_QUALIFIER"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>QUALIFIER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_kernel_<wbr>arg_<wbr>type_<wbr>qualifier</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns a bitfield describing one or more type qualifiers specified |
| for the argument given by <em>arg_index</em>. |
| The returned values can be:</p> |
| <p class="tableblock"> <a id="CL_KERNEL_ARG_TYPE_CONST"></a><a href="#CL_KERNEL_ARG_TYPE_CONST"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>CONST</code></a> |
| <sup class="footnote">[<a id="_footnoteref_29" class="footnote" href="#_footnotedef_29" title="View footnote.">29</a>]</sup> |
| <sup class="footnote">[<a id="_footnoteref_30" class="footnote" href="#_footnotedef_30" title="View footnote.">30</a>]</sup><br> |
| <a id="CL_KERNEL_ARG_TYPE_RESTRICT"></a><a href="#CL_KERNEL_ARG_TYPE_RESTRICT"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>RESTRICT</code></a><br> |
| <a id="CL_KERNEL_ARG_TYPE_VOLATILE"></a><a href="#CL_KERNEL_ARG_TYPE_VOLATILE"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>VOLATILE</code></a><br> |
| <a id="CL_KERNEL_ARG_TYPE_PIPE"></a><a href="#CL_KERNEL_ARG_TYPE_PIPE"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>PIPE</code></a>, or<br> |
| <a id="CL_KERNEL_ARG_TYPE_NONE"></a><a href="#CL_KERNEL_ARG_TYPE_NONE"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>NONE</code></a></p> |
| <p class="tableblock"> <a href="#CL_KERNEL_ARG_TYPE_NONE"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>NONE</code></a> is returned for all parameters passed by |
| value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ARG_NAME"></a><a href="#CL_KERNEL_ARG_NAME"><code>CL_KERNEL_<wbr>ARG_<wbr>NAME</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>char</code>[]</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns the name specified for the argument given by <em>arg_index</em>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a href="#clGetKernelArgInfo"><strong>clGetKernelArgInfo</strong></a> returns CL SUCCESS if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_ARG_INDEX"><code>CL_INVALID_<wbr>ARG_<wbr>INDEX</code></a> if <em>arg_index</em> is not a valid argument index.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value</em> size is < size of return type as described in |
| the <a href="#kernel-argument-info-table">Kernel Argument Queries</a> table and |
| <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_KERNEL_ARG_INFO_NOT_AVAILABLE"><code>CL_KERNEL_<wbr>ARG_<wbr>INFO_<wbr>NOT_<wbr>AVAILABLE</code></a> if the argument information is not |
| available for kernel.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is a not a valid kernel object.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_executing_kernels"><a class="anchor" href="#_executing_kernels"></a>5.10. Executing Kernels</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to execute a kernel on a device, call the function</p> |
| </div> |
| <div id="clEnqueueNDRangeKernel" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueNDRangeKernel( |
| cl_command_queue command_queue, |
| cl_kernel kernel, |
| cl_uint work_dim, |
| <span class="directive">const</span> size_t* global_work_offset, |
| <span class="directive">const</span> size_t* global_work_size, |
| <span class="directive">const</span> size_t* local_work_size, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue. |
| The kernel will be queued for execution on the device associated with |
| <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><em>kernel</em> is a valid kernel object. |
| The OpenCL context associated with <em>kernel</em> and <em>command-queue</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>work_dim</em> is the number of dimensions used to specify the global work-items |
| and work-items in the work-group. |
| <em>work_dim</em> must be greater than zero and less than or equal to |
| <a href="#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>DIMENSIONS</code></a>. |
| If <em>global_work_size</em> is <code>NULL</code>, or the value in any passed dimension is 0 |
| then the kernel command will trivially succeed after its event dependencies |
| are satisfied and subsequently update its completion event. |
| The behavior in this situation is similar to that of an enqueued marker, |
| except that unlike a marker, an enqueued kernel with no events passed to |
| <em>event_wait_list</em> may run at any time.</p> |
| </li> |
| <li> |
| <p><em>global_work_offset</em> can be used to specify an array of <em>work_dim</em> unsigned |
| values that describe the offset used to calculate the global ID of a |
| work-item. |
| If <em>global_work_offset</em> is <code>NULL</code>, the global IDs start at offset (0, 0, 0). |
| <em>global_work_offset</em> must be <code>NULL</code> <a href="#unified-spec">before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><em>global_work_size</em> points to an array of <em>work_dim</em> unsigned values that |
| describe the number of global work-items in <em>work_dim</em> dimensions that will |
| execute the kernel function. |
| The total number of global work-items is computed as <em>global_work_size</em>[0] |
| × …​ × <em>global_work_size</em>[<em>work_dim</em> - 1].</p> |
| </li> |
| <li> |
| <p><em>local_work_size</em> points to an array of <em>work_dim</em> unsigned values that |
| describe the number of work-items that make up a work-group (also referred |
| to as the size of the work-group) that will execute the kernel specified by |
| <em>kernel</em>. |
| The total number of work-items in a work-group is computed as |
| <em>local_work_size</em>[0] × …​ × <em>local_work_size</em>[<em>work_dim</em> - 1]. |
| The total number of work-items in the work-group must be less than or equal |
| to the <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> value specified in the |
| <a href="#kernel-workgroup-info-table">Kernel Object Device Queries</a> table, and the |
| number of work-items specified in <em>local_work_size</em>[0], …​, |
| <em>local_work_size</em>[<em>work_dim</em> - 1] must be less than or equal to the |
| corresponding values specified by <a href="#CL_DEVICE_MAX_WORK_ITEM_SIZES"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>SIZES</code></a>[0], …​, |
| <a href="#CL_DEVICE_MAX_WORK_ITEM_SIZES"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>SIZES</code></a>[<em>work_dim</em> - 1]. |
| The explicitly specified <em>local_work_size</em> will be used to determine how to |
| break the global work-items specified by <em>global_work_size</em> into appropriate |
| work-group instances.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>An ND-range kernel command may require uniform work-groups or may support non-uniform work-groups. |
| To support non-uniform work-groups:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The device associated with <em>command_queue</em> must support non-uniform work-groups.</p> |
| </li> |
| <li> |
| <p>The program object associated with <em>kernel</em> must support non-uniform work-groups. |
| Specifically, this means:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>If the program was created with <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>, the program must be compiled or built using the <code>-cl-std=CL2.0</code> or <code>-cl-std=CL3.0</code> build option and without the <code>-cl-uniform-work-group-size</code> build option.</p> |
| </li> |
| <li> |
| <p>If the program was created with <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> or <a href="#clCreateProgramWithBinary"><strong>clCreateProgramWithBinary</strong></a>, the program must be compiled or built without the <code>-cl-uniform-work-group-size</code> build options.</p> |
| </li> |
| <li> |
| <p>If the program was created using <a href="#clLinkProgram"><strong>clLinkProgram</strong></a>, all input programs must support non-uniform work-groups.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>If non-uniform work-groups are supported, any single dimension |
| for which the global size is not divisible by the local size will be |
| partitioned into two regions. |
| One region will have work-groups that have the same number of work-items as |
| was specified by the local size parameter in that dimension. |
| The other region will have work-groups with less than the number of work |
| items specified by the local size parameter in that dimension. |
| The global IDs and group IDs of the work-items in the first region will be |
| numerically lower than those in the second, and the second region will be at |
| most one work-group wide in that dimension. |
| Work-group sizes could be non-uniform in multiple dimensions, potentially |
| producing work-groups of up to 4 different sizes in a 2D range and 8 |
| different sizes in a 3D range.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If non-uniform work-groups are supported and <em>local_work_size</em> is <code>NULL</code>, the OpenCL runtime may choose a uniform or non-uniform work-group size.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Otherwise, when non-uniform work-groups are not supported, the size of each work-group must be uniform. |
| If <em>local_work_size</em> is specified, the values specified in <em>global_work_size</em>[0], …​, <em>global_work_size</em>[<em>work_dim</em> - 1] must be evenly divisible by the corresponding values specified in <em>local_work_size</em>[0], …​, <em>local_work_size</em>[<em>work_dim</em> - 1]. |
| If <em>local_work_size</em> is <code>NULL</code>, the OpenCL runtime must choose a uniform work-group size.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The work-group size to be used for <em>kernel</em> can also be specified in the |
| program source or intermediate language. |
| In this case the size of work-group specified by <em>local_work_size</em> must |
| match the value specified in the program source.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These work-group instances are executed in parallel across multiple compute |
| units or concurrently on the same compute unit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each work-item is uniquely identified by a global identifier. |
| The global ID, which can be read inside the kernel, is computed using the |
| value given by <em>global_work_size</em> and <em>global_work_offset</em>. |
| In addition, a work-item is also identified within a work-group by a unique |
| local ID. |
| The local ID, which can also be read by the kernel, is computed using the |
| value given by <em>local_work_size</em>. |
| The starting local ID is always (0, 0, …​, 0).</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the kernel-instance was |
| successfully queued. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM_EXECUTABLE"><code>CL_INVALID_<wbr>PROGRAM_<wbr>EXECUTABLE</code></a> if there is no successfully built program |
| executable available for device associated with <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and |
| <em>kernel</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL_ARGS"><code>CL_INVALID_<wbr>KERNEL_<wbr>ARGS</code></a> if the kernel argument values have not been |
| specified.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_DIMENSION"><code>CL_INVALID_<wbr>WORK_<wbr>DIMENSION</code></a> if <em>work_dim</em> is not a valid value (i.e. a |
| value between 1 and <a href="#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>DIMENSIONS</code></a>).</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_GLOBAL_WORK_SIZE"><code>CL_INVALID_<wbr>GLOBAL_<wbr>WORK_<wbr>SIZE</code></a> if <em>global_work_size</em> is NULL or if any of |
| the values specified in <em>global_work_size</em>[0], …​ |
| <em>global_work_size</em>[<em>work_dim</em> - 1] are 0. |
| Returning this error code under these circumstances is <a href="#unified-spec">deprecated by</a> version 2.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_GLOBAL_WORK_SIZE"><code>CL_INVALID_<wbr>GLOBAL_<wbr>WORK_<wbr>SIZE</code></a> if any of the values specified in |
| <em>global_work_size</em>[0], …​ <em>global_work_size</em>[<em>work_dim</em> - 1] exceed the |
| maximum value representable by <code>size_t</code> on the device on which the |
| kernel-instance will be enqueued.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_GLOBAL_OFFSET"><code>CL_INVALID_<wbr>GLOBAL_<wbr>OFFSET</code></a> if the value specified in <em>global_work_size</em> |
| + the corresponding values in <em>global_work_offset</em> for any |
| dimensions is greater than the maximum value representable by size t on |
| the device on which the kernel-instance will be enqueued, or if |
| <em>global_work_offset</em> is non-<code>NULL</code> <a href="#unified-spec">before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> if <em>local_work_size</em> is specified and does |
| not match the required work-group size for <em>kernel</em> in the program |
| source.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> if <em>local_work_size</em> is specified and is not |
| consistent with the required number of sub-groups for <em>kernel</em> in the |
| program source.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> if <em>local_work_size</em> is specified and the |
| total number of work-items in the work-group computed as |
| <em>local_work_size</em>[0] × …​ <em>local_work_size</em>[<em>work_dim</em> - 1] is |
| greater than the value specified by <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_KERNEL_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> in the |
| <a href="#kernel-workgroup-info-table">Kernel Object Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> if the work-group size must be uniform and |
| the <em>local_work_size</em> is not <code>NULL</code>, is not equal to the required |
| work-group size specified in the kernel source, or the |
| <em>global_work_size</em> is not evenly divisible by the <em>local_work_size</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_ITEM_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>ITEM_<wbr>SIZE</code></a> if the number of work-items specified in any |
| of <em>local_work_size</em>[0], …​ <em>local_work_size</em>[<em>work_dim</em> - 1] is |
| greater than the corresponding values specified by |
| <a href="#CL_DEVICE_MAX_WORK_ITEM_SIZES"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>SIZES</code></a>[0], …​, |
| <a href="#CL_DEVICE_MAX_WORK_ITEM_SIZES"><code>CL_DEVICE_<wbr>MAX_<wbr>WORK_<wbr>ITEM_<wbr>SIZES</code></a>[<em>work_dim</em> - 1].</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if a sub-buffer object is specified as |
| the value for an argument that is a buffer object and the <em>offset</em> |
| specified when the sub-buffer object is created is not aligned to |
| <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if an image object is specified as an argument |
| value and the image dimensions (image width, height, specified or |
| compute row and/or slice pitch) are not supported by device associated |
| with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if an image object is specified as an |
| argument value and the image format (image channel order and data type) |
| is not supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to queue the execution |
| instance of <em>kernel</em> on the command-queue because of insufficient |
| resources needed to execute the kernel. |
| For example, the explicitly specified <em>local_work_size</em> causes a failure |
| to execute the kernel because of insufficient resources such as |
| registers or local memory. |
| Another example would be the number of read-only image args used in |
| <em>kernel</em> exceed the <a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a> value for device or |
| the number of write-only and read-write image args used in <em>kernel</em> |
| exceed the <a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a> value for device or the |
| number of samplers used in <em>kernel</em> exceed <a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_DEVICE_<wbr>MAX_<wbr>SAMPLERS</code></a> for |
| device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with image or buffer objects specified |
| as arguments to <em>kernel</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if SVM pointers are passed as arguments to a kernel |
| and the device does not support SVM or if system pointers are passed as |
| arguments to a kernel and/or stored inside SVM allocations passed as |
| kernel arguments and the device does not support fine grain system SVM |
| allocations.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to execute a kernel on a device, using a single work-item, |
| call the function</p> |
| </div> |
| <div id="clEnqueueTask" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueTask( |
| cl_command_queue command_queue, |
| cl_kernel kernel, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> is <a href="#unified-spec">deprecated by</a> version 2.0. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue. |
| The kernel will be queued for execution on the device associated with |
| <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><em>kernel</em> is a valid kernel object. |
| The OpenCL context associated with <em>kernel</em> and <em>command-queue</em> must be the |
| same.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed. |
| If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait |
| on any event to complete. |
| If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> is equivalent to calling <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> with |
| <em>work_dim</em> set to 1, <em>global_work_offset</em> set to <code>NULL</code>, <em>global_work_size[0]</em> |
| set to 1, and <em>local_work_size[0]</em> set to 1.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the kernel-instance was successfully |
| queued. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_PROGRAM_EXECUTABLE"><code>CL_INVALID_<wbr>PROGRAM_<wbr>EXECUTABLE</code></a> if there is no successfully built program |
| executable available for device associated with <em>command_queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a> if <em>kernel</em> is not a valid kernel object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and |
| <em>kernel</em> are not the same or if the context associated with |
| <em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_KERNEL_ARGS"><code>CL_INVALID_<wbr>KERNEL_<wbr>ARGS</code></a> if the kernel argument values have not been |
| specified.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> if a work-group size is specified for <em>kernel</em> |
| in the program source and it is not (1, 1, 1).</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a> if the required number of sub-groups is |
| specified for <em>kernel</em> in the program source and is not consistent with a |
| work-group size of (1, 1, 1).</p> |
| </li> |
| <li> |
| <p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a> if a sub-buffer object is specified as |
| the value for an argument that is a buffer object and the <em>offset</em> |
| specified when the sub-buffer object is created is not aligned to |
| <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> value for device associated with <em>queue</em>. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a> if an image object is specified as an argument |
| value and the image dimensions (image width, height, specified or |
| compute row and/or slice pitch) are not supported by device associated |
| with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a> if an image object is specified as an |
| argument value and the image format (image channel order and data type) |
| is not supported by device associated with <em>queue</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to queue the execution |
| instance of <em>kernel</em> on the command-queue because of insufficient |
| resources needed to execute the kernel. See how this error code is used |
| with <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> for examples.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with image or buffer objects specified |
| as arguments to <em>kernel</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if SVM pointers are passed as arguments to a kernel |
| and the device does not support SVM or if system pointers are passed as |
| arguments to a kernel and/or stored inside SVM allocations passed as |
| kernel arguments and the device does not support fine grain system SVM |
| allocations.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a command to execute a native C/C++ function not compiled using |
| the OpenCL compiler, call the function</p> |
| </div> |
| <div id="clEnqueueNativeKernel" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueNativeKernel( |
| cl_command_queue command_queue, |
| <span class="directive">void</span> (CL_CALLBACK* user_func)(<span class="directive">void</span>*), |
| <span class="directive">void</span>* args, |
| size_t cb_args, |
| cl_uint num_mem_objects, |
| <span class="directive">const</span> cl_mem* mem_list, |
| <span class="directive">const</span> <span class="directive">void</span>** args_mem_loc, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue. |
| A native user function can only be executed on a command-queue created on a |
| device that has <a href="#CL_EXEC_NATIVE_KERNEL"><code>CL_EXEC_<wbr>NATIVE_<wbr>KERNEL</code></a> capability set in |
| <a href="#CL_DEVICE_EXECUTION_CAPABILITIES"><code>CL_DEVICE_<wbr>EXECUTION_<wbr>CAPABILITIES</code></a> as specified in the |
| <a href="#device-queries-table">Device Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>user_func</em> is a pointer to a host-callable user function.</p> |
| </li> |
| <li> |
| <p><em>args</em> is a pointer to the args list that <em>user_func</em> should be called with.</p> |
| </li> |
| <li> |
| <p><em>cb_args</em> is the size in bytes of the args list that <em>args</em> points to.</p> |
| </li> |
| <li> |
| <p><em>num_mem_objects</em> is the number of buffer objects that are passed in <em>args</em>.</p> |
| </li> |
| <li> |
| <p><em>mem_list</em> is a list of valid buffer objects, if <em>num_mem_objects</em> > 0. |
| The buffer object values specified in <em>mem_list</em> are memory object handles |
| (<code><code>cl_mem</code></code> values) returned by <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or <a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a>, |
| or <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><em>args_mem_loc</em> is a pointer to appropriate locations that <em>args</em> points to |
| where memory object handles (<code>cl_mem</code> values) are stored. |
| Before the user function is executed, the memory object handles are replaced |
| by pointers to global memory.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em>, <em>num_events_in_wait_list</em> and <em>event</em> are as described in |
| <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The data pointed to by <em>args</em> and <em>cb_args</em> bytes in size will be copied and |
| a pointer to this copied region will be passed to <em>user_func</em>. |
| The copy needs to be done because the memory objects (<code>cl_mem</code> values) that |
| <em>args</em> may contain need to be modified and replaced by appropriate pointers |
| to global memory. |
| When <a href="#clEnqueueNativeKernel"><strong>clEnqueueNativeKernel</strong></a> returns, the memory region pointed to by <em>args</em> |
| can be reused by the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueNativeKernel"><strong>clEnqueueNativeKernel</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the user function execution |
| instance was successfully queued. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>user_func</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>args</em> is a <code>NULL</code> value and <em>cb_args</em> > 0, or if |
| <em>args</em> is a <code>NULL</code> value and <em>num_mem_objects</em> > 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>args</em> is not <code>NULL</code> and <em>cb_args</em> is 0.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_mem_objects</em> > 0 and <em>mem_list</em> or |
| <em>args_mem_loc</em> are <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_mem_objects</em> = 0 and <em>mem_list</em> or |
| <em>args_mem_loc</em> are not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> |
| cannot execute the native kernel.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> if one or more memory objects specified in |
| <em>mem_list</em> are not valid or are not buffer objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to queue the execution |
| instance of <em>kernel</em> on the command-queue because of insufficient |
| resources needed to execute the kernel.</p> |
| </li> |
| <li> |
| <p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a> if there is a failure to allocate |
| memory for data store associated with buffer objects specified as |
| arguments to <em>kernel</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if SVM pointers are passed as arguments to a kernel |
| and the device does not support SVM or if system pointers are passed as |
| arguments to a kernel and/or stored inside SVM allocations passed as |
| kernel arguments and the device does not support fine grain system SVM |
| allocations.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The total number of read-only images specified as arguments to a kernel |
| cannot exceed <a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a>. |
| Each image array argument to a kernel declared with the <code>read_only</code> |
| qualifier counts as one image. |
| The total number of write-only images specified as arguments to a kernel |
| cannot exceed <a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a>. |
| Each image array argument to a kernel declared with the <code>write_only</code> |
| qualifier counts as one image.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The total number of read-write images specified as arguments to a kernel |
| cannot exceed <a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a>. |
| Each image array argument to a kernel declared with the <code>read_write</code> |
| qualifier counts as one image.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="event-objects"><a class="anchor" href="#event-objects"></a>5.11. Event Objects</h3> |
| <div class="paragraph"> |
| <p>An event object can be used to track the execution status of a command. |
| The API calls that enqueue commands to a command-queue create a new event |
| object that is returned in the <em>event</em> argument. |
| In case of an error enqueuing the command in the command-queue the event |
| argument does not return an event object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The execution status of an enqueued command at any given point in time can |
| be one of the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a id="CL_QUEUED"></a><a href="#CL_QUEUED"><code>CL_QUEUED</code></a>: Indicates that the command has been enqueued in a |
| command-queue. |
| This is the initial state of all events except user events.</p> |
| </li> |
| <li> |
| <p><a id="CL_SUBMITTED"></a><a href="#CL_SUBMITTED"><code>CL_SUBMITTED</code></a>: The initial state for all user events. |
| For all other events, indicates that the command has been submitted |
| by the host to the device.</p> |
| </li> |
| <li> |
| <p><a id="CL_RUNNING"></a><a href="#CL_RUNNING"><code>CL_RUNNING</code></a>: Indicates that the device has started executing this |
| command. |
| In order for the execution status of an enqueued command to change from |
| <a href="#CL_SUBMITTED"><code>CL_SUBMITTED</code></a> to <a href="#CL_RUNNING"><code>CL_RUNNING</code></a>, all events that this command is waiting on |
| must have completed successfully i.e. their execution status must be |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| <li> |
| <p><a id="CL_COMPLETE"></a><a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>: Indicates that the command has successfully completed.</p> |
| </li> |
| <li> |
| <p>An Error Code: A negative integer value indicating that the command was |
| abnormally terminated. Abnormal termination may occur for a number of reasons, |
| such as a bad memory access.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>A command is considered to be complete if its execution status is |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or is a negative integer value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the execution of a command is terminated, the command-queue associated |
| with this terminated command, and the associated context (and all other |
| command-queues in this context) may no longer be available. |
| The behavior of OpenCL API calls that use this context (and command-queues |
| associated with this context) are now considered to be |
| implementation-defined. |
| The user registered callback function specified when context is created can |
| be used to report appropriate error information.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To create a user event object, call the function</p> |
| </div> |
| <div id="clCreateUserEvent" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_event clCreateUserEvent( |
| cl_context context, |
| cl_int* errcode_ret);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clCreateUserEvent"><strong>clCreateUserEvent</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>context</em> must be a valid OpenCL context.</p> |
| </li> |
| <li> |
| <p><em>errcode_ret</em> will return an appropriate error code. |
| If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>User events allow applications to enqueue commands that wait on a user event |
| to finish before the command is executed by the device.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clCreateUserEvent"><strong>clCreateUserEvent</strong></a> returns a valid non-zero event object and <em>errcode_ret</em> |
| is set to <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the user event object is created successfully. |
| Otherwise, it returns a <code>NULL</code> value with one of the following error values |
| returned in <em>errcode_ret</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if <em>context</em> is not a valid context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The initial execution status for the user event object is <a href="#CL_SUBMITTED"><code>CL_SUBMITTED</code></a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To set the execution status of a user event object, call the function</p> |
| </div> |
| <div id="clSetUserEventStatus" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetUserEventStatus( |
| cl_event event, |
| cl_int execution_status);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> is a user event object created using <a href="#clCreateUserEvent"><strong>clCreateUserEvent</strong></a>.</p> |
| </li> |
| <li> |
| <p><em>execution_status</em> specifies the new execution status to be set and can be |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or a negative integer value to indicate an error. |
| A negative integer value causes all enqueued commands that wait on this user |
| event to be terminated. |
| <a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a> can only be called once to change the execution |
| status of <em>event</em>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>If there are enqueued commands with user events in the <em>event_wait_list</em> |
| argument of <strong>clEnqueue*</strong> commands, the user must ensure that the status of |
| these user events being waited on are set using <a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a> |
| before any OpenCL APIs that release OpenCL objects except for event objects |
| are called; otherwise the behavior is undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, the following code sequence will result in undefined behavior |
| of <a href="#clReleaseMemObject"><strong>clReleaseMemObject</strong></a>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">ev1 = clCreateUserEvent(ctx, <span class="predefined-constant">NULL</span>); |
| clEnqueueWriteBuffer(cq, buf1, CL_FALSE, ..., <span class="integer">1</span>, &ev1, <span class="predefined-constant">NULL</span>); |
| clEnqueueWriteBuffer(cq, buf2, CL_FALSE, ...); |
| clReleaseMemObject(buf2); |
| clSetUserEventStatus(ev1, CL_COMPLETE);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following code sequence, however, works correctly.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">ev1 = clCreateUserEvent(ctx, <span class="predefined-constant">NULL</span>); |
| clEnqueueWriteBuffer(cq, buf1, CL_FALSE, ..., <span class="integer">1</span>, &ev1, <span class="predefined-constant">NULL</span>); |
| clEnqueueWriteBuffer(cq, buf2, CL_FALSE, ...); |
| clSetUserEventStatus(ev1, CL_COMPLETE); |
| clReleaseMemObject(buf2);</code></pre> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function was executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if <em>event</em> is not a valid user event object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if the <em>execution_status</em> is not <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or a |
| negative integer value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the <em>execution_status</em> for <em>event</em> has already |
| been changed by a previous call to <a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To wait for events to complete, call the function</p> |
| </div> |
| <div id="clWaitForEvents" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clWaitForEvents( |
| cl_uint num_events, |
| <span class="directive">const</span> cl_event* event_list);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>num_events</em> is the number of events in <em>event_list</em>.</p> |
| </li> |
| <li> |
| <p><em>event_list</em> is a pointer to a list of event object handles.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This function waits on the host thread for commands identified by event |
| objects in <em>event_list</em> to complete. |
| A command is considered complete if its execution status is <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or a |
| negative value. |
| The events specified in <em>event_list</em> act as synchronization points.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the execution status of all events |
| in <em>event_list</em> is <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_events</em> is zero or <em>event_list</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if events specified in <em>event_list</em> do not belong to |
| the same context.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if event objects specified in <em>event_list</em> are not |
| valid event objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a> if the execution status of |
| any of the events in <em>event_list</em> is a negative integer value. |
| This error code is <a href="#unified-spec">missing before</a> version 1.1.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return information about an event object, call the function</p> |
| </div> |
| <div id="clGetEventInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetEventInfo( |
| cl_event event, |
| cl_event_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> specifies the event object being queried.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the information to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetEventInfo"><strong>clGetEventInfo</strong></a> is described in the |
| <a href="#event-info-table">Event Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#event-info-table">Event Object Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="event-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 36. List of supported param_names by <a href="#clGetEventInfo">clGetEventInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Event Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_EVENT_COMMAND_QUEUE"></a><a href="#CL_EVENT_COMMAND_QUEUE"><code>CL_EVENT_<wbr>COMMAND_<wbr>QUEUE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>queue</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the command-queue associated with <em>event</em>. |
| For user event objects, a <code>NULL</code> value is returned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_EVENT_CONTEXT"></a><a href="#CL_EVENT_CONTEXT"><code>CL_EVENT_<wbr>CONTEXT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_context</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the context associated with <em>event</em>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_EVENT_COMMAND_TYPE"></a><a href="#CL_EVENT_COMMAND_TYPE"><code>CL_EVENT_<wbr>COMMAND_<wbr>TYPE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_command_<wbr>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the command type associated with <em>event</em> as described in the |
| <a href="#event-command-type-table">Event Command Types</a> table.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_EVENT_COMMAND_EXECUTION_STATUS"></a><a href="#CL_EVENT_COMMAND_EXECUTION_STATUS"><code>CL_EVENT_<wbr>COMMAND_<wbr>EXECUTION_<wbr>STATUS</code></a> <sup class="footnote">[<a id="_footnoteref_31" class="footnote" href="#_footnotedef_31" title="View footnote.">31</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_int</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the execution status of the command identified by event. |
| Valid values are:</p> |
| <p class="tableblock"> <a href="#CL_QUEUED"><code>CL_QUEUED</code></a> (command has been enqueued in the command-queue),</p> |
| <p class="tableblock"> <a href="#CL_SUBMITTED"><code>CL_SUBMITTED</code></a> (enqueued command has been submitted by the host to the |
| device associated with the command-queue),</p> |
| <p class="tableblock"> <a href="#CL_RUNNING"><code>CL_RUNNING</code></a> (device is currently executing this command),</p> |
| <p class="tableblock"> <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> (the command has completed), or</p> |
| <p class="tableblock"> Error code given by a negative integer value. (command was |
| abnormally terminated - this may be caused by a bad memory access |
| etc.). |
| These error codes come from the same set of error codes that are |
| returned from the platform or runtime API calls as return values or |
| errcode_ret values.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_EVENT_REFERENCE_COUNT"></a><a href="#CL_EVENT_REFERENCE_COUNT"><code>CL_EVENT_<wbr>REFERENCE_<wbr>COUNT</code></a> <sup class="footnote">[<a id="_footnoteref_32" class="footnote" href="#_footnotedef_32" title="View footnote.">32</a>]</sup></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return the <em>event</em> reference count.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <table id="event-command-type-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 37. List of supported event command types</caption> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>Events Created By</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Event Command Type</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_NDRANGE_KERNEL"></a><a href="#CL_COMMAND_NDRANGE_KERNEL"><code>CL_COMMAND_<wbr>NDRANGE_<wbr>KERNEL</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_TASK"></a><a href="#CL_COMMAND_TASK"><code>CL_COMMAND_<wbr>TASK</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueNativeKernel"><strong>clEnqueueNativeKernel</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_NATIVE_KERNEL"></a><a href="#CL_COMMAND_NATIVE_KERNEL"><code>CL_COMMAND_<wbr>NATIVE_<wbr>KERNEL</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_READ_BUFFER"></a><a href="#CL_COMMAND_READ_BUFFER"><code>CL_COMMAND_<wbr>READ_<wbr>BUFFER</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_WRITE_BUFFER"></a><a href="#CL_COMMAND_WRITE_BUFFER"><code>CL_COMMAND_<wbr>WRITE_<wbr>BUFFER</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueCopyBuffer"><strong>clEnqueueCopyBuffer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_COPY_BUFFER"></a><a href="#CL_COMMAND_COPY_BUFFER"><code>CL_COMMAND_<wbr>COPY_<wbr>BUFFER</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_READ_IMAGE"></a><a href="#CL_COMMAND_READ_IMAGE"><code>CL_COMMAND_<wbr>READ_<wbr>IMAGE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_WRITE_IMAGE"></a><a href="#CL_COMMAND_WRITE_IMAGE"><code>CL_COMMAND_<wbr>WRITE_<wbr>IMAGE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueCopyImage"><strong>clEnqueueCopyImage</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_COPY_IMAGE"></a><a href="#CL_COMMAND_COPY_IMAGE"><code>CL_COMMAND_<wbr>COPY_<wbr>IMAGE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueCopyBufferToImage"><strong>clEnqueueCopyBufferToImage</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_COPY_BUFFER_TO_IMAGE"></a><a href="#CL_COMMAND_COPY_BUFFER_TO_IMAGE"><code>CL_COMMAND_<wbr>COPY_<wbr>BUFFER_<wbr>TO_<wbr>IMAGE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueCopyImageToBuffer"><strong>clEnqueueCopyImageToBuffer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_COPY_IMAGE_TO_BUFFER"></a><a href="#CL_COMMAND_COPY_IMAGE_TO_BUFFER"><code>CL_COMMAND_<wbr>COPY_<wbr>IMAGE_<wbr>TO_<wbr>BUFFER</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_MAP_BUFFER"></a><a href="#CL_COMMAND_MAP_BUFFER"><code>CL_COMMAND_<wbr>MAP_<wbr>BUFFER</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_MAP_IMAGE"></a><a href="#CL_COMMAND_MAP_IMAGE"><code>CL_COMMAND_<wbr>MAP_<wbr>IMAGE</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_UNMAP_MEM_OBJECT"></a><a href="#CL_COMMAND_UNMAP_MEM_OBJECT"><code>CL_COMMAND_<wbr>UNMAP_<wbr>MEM_<wbr>OBJECT</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueMarker"><strong>clEnqueueMarker</strong></a>,<br> |
| <a href="#clEnqueueMarkerWithWaitList"><strong>clEnqueueMarkerWithWaitList</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_MARKER"></a><a href="#CL_COMMAND_MARKER"><code>CL_COMMAND_<wbr>MARKER</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_READ_BUFFER_RECT"></a><a href="#CL_COMMAND_READ_BUFFER_RECT"><code>CL_COMMAND_<wbr>READ_<wbr>BUFFER_<wbr>RECT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_WRITE_BUFFER_RECT"></a><a href="#CL_COMMAND_WRITE_BUFFER_RECT"><code>CL_COMMAND_<wbr>WRITE_<wbr>BUFFER_<wbr>RECT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueCopyBufferRect"><strong>clEnqueueCopyBufferRect</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_COPY_BUFFER_RECT"></a><a href="#CL_COMMAND_COPY_BUFFER_RECT"><code>CL_COMMAND_<wbr>COPY_<wbr>BUFFER_<wbr>RECT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clCreateUserEvent"><strong>clCreateUserEvent</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_USER"></a><a href="#CL_COMMAND_USER"><code>CL_COMMAND_<wbr>USER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueBarrier"><strong>clEnqueueBarrier</strong></a>,<br> |
| <a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_BARRIER"></a><a href="#CL_COMMAND_BARRIER"><code>CL_COMMAND_<wbr>BARRIER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_MIGRATE_MEM_OBJECTS"></a><a href="#CL_COMMAND_MIGRATE_MEM_OBJECTS"><code>CL_COMMAND_<wbr>MIGRATE_<wbr>MEM_<wbr>OBJECTS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_FILL_BUFFER"></a><a href="#CL_COMMAND_FILL_BUFFER"><code>CL_COMMAND_<wbr>FILL_<wbr>BUFFER</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_FILL_IMAGE"></a><a href="#CL_COMMAND_FILL_IMAGE"><code>CL_COMMAND_<wbr>FILL_<wbr>IMAGE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_SVM_FREE"></a><a href="#CL_COMMAND_SVM_FREE"><code>CL_COMMAND_<wbr>SVM_<wbr>FREE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_SVM_MEMCPY"></a><a href="#CL_COMMAND_SVM_MEMCPY"><code>CL_COMMAND_<wbr>SVM_<wbr>MEMCPY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMMemFill"><strong>clEnqueueSVMMemFill</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_SVM_MEMFILL"></a><a href="#CL_COMMAND_SVM_MEMFILL"><code>CL_COMMAND_<wbr>SVM_<wbr>MEMFILL</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_SVM_MAP"></a><a href="#CL_COMMAND_SVM_MAP"><code>CL_COMMAND_<wbr>SVM_<wbr>MAP</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_SVM_UNMAP"></a><a href="#CL_COMMAND_SVM_UNMAP"><code>CL_COMMAND_<wbr>SVM_<wbr>UNMAP</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMMAND_SVM_MIGRATE_MEM"></a><a href="#CL_COMMAND_SVM_MIGRATE_MEM"><code>CL_COMMAND_<wbr>SVM_<wbr>MIGRATE_<wbr>MEM</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 3.0.</p> |
| <p class="tableblock">Prior to OpenCL 3.0, implementations should return |
| <a href="#CL_COMMAND_MIGRATE_MEM_OBJECTS"><code>CL_COMMAND_<wbr>MIGRATE_<wbr>MEM_<wbr>OBJECTS</code></a>, but may return an implementation-defined |
| event command type for <a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Using <a href="#clGetEventInfo"><strong>clGetEventInfo</strong></a> to determine if a command identified by <em>event</em> has |
| finished execution (i.e. <a href="#CL_EVENT_COMMAND_EXECUTION_STATUS"><code>CL_EVENT_<wbr>COMMAND_<wbr>EXECUTION_<wbr>STATUS</code></a> returns |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>) is not a synchronization point. |
| There are no guarantees that the memory objects being modified by command |
| associated with <em>event</em> will be visible to other enqueued commands.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetEventInfo"><strong>clGetEventInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#kernel-argument-info-table">Kernel Argument Queries</a> table and |
| <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if information to query given in <em>param_name</em> cannot be |
| queried for <em>event</em>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if <em>event</em> is a not a valid event object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To register a user callback function for a specific command execution |
| status, call the function</p> |
| </div> |
| <div id="clSetEventCallback" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetEventCallback( |
| cl_event event, |
| cl_int command_exec_callback_type, |
| <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(cl_event event, cl_int event_command_status, <span class="directive">void</span> *user_data), |
| <span class="directive">void</span>* user_data);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clSetEventCallback"><strong>clSetEventCallback</strong></a> is <a href="#unified-spec">missing before</a> version 1.1. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> is a valid event object.</p> |
| </li> |
| <li> |
| <p><em>command_exec_callback_type</em> specifies the command execution status for |
| which the callback is registered. |
| The command execution callback values for which a callback can be registered |
| are: <a href="#CL_SUBMITTED"><code>CL_SUBMITTED</code></a>, <a href="#CL_RUNNING"><code>CL_RUNNING</code></a>, or |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> <sup class="footnote">[<a id="_footnoteref_33" class="footnote" href="#_footnotedef_33" title="View footnote.">33</a>]</sup>. |
| There is no guarantee that the callback functions registered for various |
| execution status values for an event will be called in the exact order that |
| the execution status of a command changes. |
| Furthermore, it should be noted that receiving a call back for an event with |
| a status other than <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>, in no way implies that the memory model or |
| execution model as defined by the OpenCL specification has changed. |
| For example, it is not valid to assume that a corresponding memory transfer |
| has completed unless the event is in a state <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| <li> |
| <p><em>pfn_event_notify</em> is the event callback function that can be registered by |
| the application. |
| This callback function may be called asynchronously by the OpenCL |
| implementation. |
| It is the applications responsibility to ensure that the callback function |
| is thread-safe. |
| The parameters to this callback function are:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> is the event object for which the callback function is invoked.</p> |
| </li> |
| <li> |
| <p><em>event_command_status</em> is equal to the <em>command_exec_callback_type</em> |
| used while registering the callback. |
| Refer to the <a href="#event-info-table">Event Object Queries</a> |
| table for the command execution status values. |
| If the callback is called as the result of the command associated with |
| event being abnormally terminated, an appropriate error code for the |
| error that caused the termination will be passed to |
| <em>event_command_status</em> instead.</p> |
| </li> |
| <li> |
| <p><em>user_data</em> is a pointer to user supplied data.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is |
| called. |
| <em>user_data</em> can be <code>NULL</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The registered callback function will be called when the execution status of |
| command associated with <em>event</em> changes to an execution status equal to or |
| past the status specified by <em>command_exec_status</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each call to <a href="#clSetEventCallback"><strong>clSetEventCallback</strong></a> registers the specified user callback |
| function on a callback stack associated with <em>event</em>. |
| The order in which the registered user callback functions are called is |
| undefined.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All callbacks registered for an event object must be called before the event |
| object is destroyed. |
| Callbacks should return promptly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Behavior is undefined when calling expensive system routines, OpenCL APIs to |
| create contexts or command-queues, or blocking OpenCL APIs in an event callback. |
| Rather than calling a blocking OpenCL API in an event callback, applications |
| may call a non-blocking OpenCL API, then register a completion callback |
| for the non-blocking OpenCL API with the remainder of the work.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Because commands in a command-queue are not required to begin execution |
| until the command-queue is flushed, callbacks that enqueue commands on a |
| command-queue should either call <a href="#clFlush"><strong>clFlush</strong></a> on the queue before returning, |
| or arrange for the command-queue to be flushed later.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clSetEventCallback"><strong>clSetEventCallback</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if <em>event</em> is not a valid event object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>pfn_event_notify</em> is <code>NULL</code> or if |
| <em>command_exec_callback_type</em> is not <a href="#CL_SUBMITTED"><code>CL_SUBMITTED</code></a>, <a href="#CL_RUNNING"><code>CL_RUNNING</code></a>, or |
| <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To retain an event object, call the function</p> |
| </div> |
| <div id="clRetainEvent" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainEvent( |
| cl_event event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> is the event object to be retained.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>event</em> reference count is incremented. |
| The OpenCL commands that return an event perform an implicit retain.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clRetainEvent"><strong>clRetainEvent</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if <em>event</em> is not a valid event object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To release an event object, call the function</p> |
| </div> |
| <div id="clReleaseEvent" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseEvent( |
| cl_event event);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> is the event object to be released.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>event</em> reference count is decremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The event object is deleted once the reference count becomes zero, the |
| specific command identified by this event has completed (or terminated) and |
| there are no commands in the command-queues of a context that require a wait |
| for this event to complete. |
| Using this function to release a reference that was not obtained by creating |
| the object or by calling <a href="#clRetainEvent"><strong>clRetainEvent</strong></a> causes undefined behavior.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Developers should be careful when releasing their last reference count on |
| events created by <a href="#clCreateUserEvent"><strong>clCreateUserEvent</strong></a> that have not yet been set to status |
| of <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or an error. |
| If the user event was used in the event_wait_list argument passed to a |
| <strong>clEnqueue*</strong> API or another application host thread is waiting for it in |
| <a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a>, those commands and host threads will continue to wait for |
| the event status to reach <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or error, even after the application |
| has released the object. |
| Since in this scenario the application has released its last reference count |
| to the user event, it would be in principle no longer valid for the |
| application to change the status of the event to unblock all the other |
| machinery. |
| As a result the waiting tasks will wait forever, and associated events, |
| <code>cl_mem</code> objects, command queues and contexts are likely to leak. |
| In-order command queues caught up in this deadlock may cease to do any work.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clReleaseEvent"><strong>clReleaseEvent</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if <em>event</em> is not a valid event object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="markers-barriers-waiting-for-events"><a class="anchor" href="#markers-barriers-waiting-for-events"></a>5.12. Markers, Barriers and Waiting for Events</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a marker command which waits for events or commands to complete, |
| call the function</p> |
| </div> |
| <div id="clEnqueueMarkerWithWaitList" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueMarkerWithWaitList( |
| cl_command_queue command_queue, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueMarkerWithWaitList"><strong>clEnqueueMarkerWithWaitList</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>event_wait_list</em> is <code>NULL</code>, then this particular command waits until all |
| previous enqueued commands to <em>command_queue</em> have completed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The marker command either waits for a list of events to complete, or if the |
| list is empty it waits for all commands previously enqueued in |
| <em>command_queue</em> to complete before it completes. |
| This command returns an <em>event</em> which can be waited on, i.e. this event can |
| be waited on to insure that all events either in the <em>event_wait_list</em> or |
| all previously enqueued commands, queued before this command to |
| <em>command_queue</em>, have completed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMarkerWithWaitList"><strong>clEnqueueMarkerWithWaitList</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is |
| successfully executed. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a marker command which waits for previous commands to complete, call |
| the function</p> |
| </div> |
| <div id="clEnqueueMarker" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueMarker( |
| cl_command_queue command_queue, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueMarker"><strong>clEnqueueMarker</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The marker command waits for all commands previously enqueued in <em>command_queue</em> to complete before it completes. |
| This command returns an <em>event</em> which can be waited on, i.e. this event can be |
| waited on to insure that all previously enqueued commands, queued before this |
| command to <em>command_queue</em>, have completed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueMarker"><strong>clEnqueueMarker</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is successfully |
| executed. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>event</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a wait for a specific event or a list of events to complete before any future commands queued in a command-queue are executed, call the function</p> |
| </div> |
| <div id="clEnqueueWaitForEvents" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWaitForEvents( |
| cl_command_queue command_queue, |
| cl_uint num_events, |
| <span class="directive">const</span> cl_event* event_list);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueWaitForEvents"><strong>clEnqueueWaitForEvents</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>event_list</em> and <em>num_events</em> specify events that need to complete before |
| this particular command can be executed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The events specified in <em>event_list</em> act as synchronization points. |
| The context associated with events in <em>event_list</em> and <em>command_queue</em> must be |
| the same. |
| The memory associated with <em>event_list</em> can be reused or freed after the |
| function returns.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueWaitForEvents"><strong>clEnqueueWaitForEvents</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is successfully |
| executed. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>num_events</em> is 0 or <em>event_list</em> is <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a barrier command which waits for events or commands to complete, |
| call the function</p> |
| </div> |
| <div id="clEnqueueBarrierWithWaitList" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueBarrierWithWaitList( |
| cl_command_queue command_queue, |
| cl_uint num_events_in_wait_list, |
| <span class="directive">const</span> cl_event* event_wait_list, |
| cl_event* event);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> is <a href="#unified-spec">missing before</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue.</p> |
| </li> |
| <li> |
| <p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to |
| complete before this particular command can be executed.</p> |
| </li> |
| <li> |
| <p>If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. |
| If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by |
| <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be |
| greater than 0. |
| The events specified in <em>event_wait_list</em> act as synchronization points. |
| The context associated with events in <em>event_wait_list</em> and <em>command_queue</em> |
| must be the same. |
| The memory associated with <em>event_wait_list</em> can be reused or freed after |
| the function returns.</p> |
| </li> |
| <li> |
| <p><em>event</em> returns an event object that identifies this command and |
| can be used to query or wait for this command to complete. |
| If <em>event</em> is <code>NULL</code> or the enqueue is unsuccessful, no event will be |
| created and therefore it will not be possible to query the status of this |
| command or to wait for this command to complete. |
| If <em>event_wait_list</em> and <em>event</em> are not <code>NULL</code>, <em>event</em> must not refer |
| to an element of the <em>event_wait_list</em> array.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If <em>event_wait_list</em> is <code>NULL</code>, then this particular command waits until all |
| previous enqueued commands to <em>command_queue</em> have completed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The barrier command either waits for a list of events to complete, or if the |
| list is empty it waits for all commands previously enqueued in |
| <em>command_queue</em> to complete before it completes. |
| This command blocks command execution, that is, any following commands |
| enqueued after it do not execute until it completes. |
| This command returns an <em>event</em> which can be waited on, i.e. this event can |
| be waited on to insure that all events either in the <em>event_wait_list</em> or |
| all previously enqueued commands, queued before this command to |
| <em>command_queue</em>, have completed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is |
| successfully executed. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a> if context associated with <em>command_queue</em> and events |
| in <em>event_wait_list</em> are not the same.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and |
| <em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and |
| <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> |
| are not valid events.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To enqueue a barrier command which waits for commands to complete, call the |
| function</p> |
| </div> |
| <div id="clEnqueueBarrier" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueBarrier( |
| cl_command_queue command_queue);</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| <a href="#clEnqueueBarrier"><strong>clEnqueueBarrier</strong></a> is <a href="#unified-spec">deprecated by</a> version 1.2. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is a valid host command-queue.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The barrier command waits for all commands previously enqueued in |
| <em>command_queue</em> to complete before it completes. |
| This command blocks command execution, that is, any following commands |
| enqueued after it do not execute until it completes. |
| The barrier command is a synchronization point.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clEnqueueBarrier"><strong>clEnqueueBarrier</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is successfully |
| executed. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_out_of_order_execution_of_kernels_and_memory_object_commands"><a class="anchor" href="#_out_of_order_execution_of_kernels_and_memory_object_commands"></a>5.13. Out-of-order Execution of Kernels and Memory Object Commands</h3> |
| <div class="paragraph"> |
| <p>The OpenCL functions that are submitted to a command-queue are enqueued in |
| the order the calls are made but can be configured to execute in-order or |
| out-of-order. |
| The <em>properties</em> argument in <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> or |
| <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a> can be used to specify the execution order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> property of a command-queue is |
| not set, the commands enqueued to a command-queue execute in order. |
| For example, if an application calls <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> to execute |
| kernel A followed by a <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> to execute kernel B, the |
| application can assume that kernel A finishes first and then kernel B is |
| executed. |
| If the memory objects output by kernel A are inputs to kernel B then kernel |
| B will see the correct data in memory objects produced by execution of |
| kernel A. |
| If the <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> property of a command-queue is |
| set, then there is no guarantee that kernel A will finish before kernel B |
| starts execution.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Applications can configure the commands enqueued to a command-queue to |
| execute out-of-order by setting the <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> |
| property of the command-queue. |
| This can be specified when the command-queue is created. |
| In out-of-order execution mode there is no guarantee that the enqueued |
| commands will finish execution in the order they were queued. |
| As there is no guarantee that kernels will be executed in order, i.e. based |
| on when the <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> or <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> calls are made within a |
| command-queue, it is therefore possible that an earlier |
| <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> call to execute kernel A identified by event A may |
| execute and/or finish later than a <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> call to execute |
| kernel B which was called by the application at a later point in time. |
| To guarantee a specific order of execution of kernels, a wait on a |
| particular event (in this case event A) can be used. |
| The wait for event A can be specified in the <em>event_wait_list</em> argument to |
| <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> for kernel B.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition, a marker (<a href="#clEnqueueMarker"><strong>clEnqueueMarker</strong></a> or <a href="#clEnqueueMarkerWithWaitList"><strong>clEnqueueMarkerWithWaitList</strong></a>) or a |
| barrier (<a href="#clEnqueueBarrier"><strong>clEnqueueBarrier</strong></a> or <a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a>) command can be |
| enqueued to the command-queue. |
| The marker command ensures that previously enqueued commands identified by |
| the list of events to wait for (or all previous commands) have finished. |
| A barrier command is similar to a marker command, but additionally |
| guarantees that no later-enqueued commands will execute until the waited-for |
| commands have executed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Similarly, commands to read, write, copy or map memory objects that are |
| enqueued after <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>, <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> or |
| <a href="#clEnqueueNativeKernel"><strong>clEnqueueNativeKernel</strong></a> commands are not guaranteed to wait for kernels |
| scheduled for execution to have completed (if the |
| <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_QUEUE_<wbr>OUT_<wbr>OF_<wbr>ORDER_<wbr>EXEC_<wbr>MODE_<wbr>ENABLE</code></a> property is set). |
| To ensure correct ordering of commands, the event object returned by |
| <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>, <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> or <a href="#clEnqueueNativeKernel"><strong>clEnqueueNativeKernel</strong></a> can be |
| used to enqueue a wait for event or a barrier command can be enqueued that must |
| complete before reads or writes to the memory object(s) occur.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="profiling-operations"><a class="anchor" href="#profiling-operations"></a>5.14. Profiling Operations on Memory Objects and Kernels</h3> |
| <div class="paragraph"> |
| <p>This section describes the profiling of OpenCL functions that are enqueued |
| as commands to a command-queue. Profiling of OpenCL commands can be enabled |
| by using a command-queue created with the <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a> |
| flag set in the <a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a> bitfield in the <em>properties</em> argument to |
| <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a>, or in the <em>properties</em> argument to |
| <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a>. |
| When profiling is enabled, the event objects that are created from |
| enqueuing a command store a timestamp for each of their state transitions.</p> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To return profiling information for a command associated with an event when |
| profiling is enabled, call the function</p> |
| </div> |
| <div id="clGetEventProfilingInfo" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetEventProfilingInfo( |
| cl_event event, |
| cl_profiling_info param_name, |
| size_t param_value_size, |
| <span class="directive">void</span>* param_value, |
| size_t* param_value_size_ret);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>event</em> specifies the event object.</p> |
| </li> |
| <li> |
| <p><em>param_name</em> specifies the profiling data to query. |
| The list of supported <em>param_name</em> types and the information returned in |
| <em>param_value</em> by <a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> is described in the |
| <a href="#event-profiling-info-table">Event Profiling Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value</em> is a pointer to memory where the appropriate result being |
| queried is returned. |
| If <em>param_value</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| <li> |
| <p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to |
| by <em>param_value</em>. |
| This size must be ≥ size of return type as described in the |
| <a href="#event-profiling-info-table">Event Profiling Queries</a> table.</p> |
| </li> |
| <li> |
| <p><em>param_value_size_ret</em> returns the actual size in bytes of data being |
| queried by <em>param_name</em>. |
| If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <table id="event-profiling-info-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 38. List of supported param_names by <a href="#clGetEventProfilingInfo">clGetEventProfilingInfo</a></caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Event Profiling Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROFILING_COMMAND_QUEUED"></a><a href="#CL_PROFILING_COMMAND_QUEUED"><code>CL_PROFILING_<wbr>COMMAND_<wbr>QUEUED</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A 64-bit value that describes the current device time counter in |
| nanoseconds when the command identified by event is enqueued in a |
| command-queue by the host.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROFILING_COMMAND_SUBMIT"></a><a href="#CL_PROFILING_COMMAND_SUBMIT"><code>CL_PROFILING_<wbr>COMMAND_<wbr>SUBMIT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A 64-bit value that describes the current device time counter in |
| nanoseconds when the command identified by event that has been |
| enqueued is submitted by the host to the device associated with the |
| command-queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROFILING_COMMAND_START"></a><a href="#CL_PROFILING_COMMAND_START"><code>CL_PROFILING_<wbr>COMMAND_<wbr>START</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A 64-bit value that describes the current device time counter in |
| nanoseconds when the command identified by event starts execution on |
| the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROFILING_COMMAND_END"></a><a href="#CL_PROFILING_COMMAND_END"><code>CL_PROFILING_<wbr>COMMAND_<wbr>END</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A 64-bit value that describes the current device time counter in |
| nanoseconds when the command identified by event has finished |
| execution on the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROFILING_COMMAND_COMPLETE"></a><a href="#CL_PROFILING_COMMAND_COMPLETE"><code>CL_PROFILING_<wbr>COMMAND_<wbr>COMPLETE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A 64-bit value that describes the current device time counter in |
| nanoseconds when the command identified by event and any child |
| commands enqueued by this command on the device have finished |
| execution.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The unsigned 64-bit values returned can be used to measure the time in |
| nano-seconds consumed by OpenCL commands.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL devices are required to correctly track time across changes in device |
| frequency and power states. |
| The <a href="#CL_DEVICE_PROFILING_TIMER_RESOLUTION"><code>CL_DEVICE_<wbr>PROFILING_<wbr>TIMER_<wbr>RESOLUTION</code></a> specifies the resolution of the |
| timer i.e. the number of nanoseconds elapsed before the timer is |
| incremented.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function is executed |
| successfully and the profiling information has been recorded. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_PROFILING_INFO_NOT_AVAILABLE"><code>CL_PROFILING_<wbr>INFO_<wbr>NOT_<wbr>AVAILABLE</code></a> if the <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a> flag is |
| not set for the command-queue, if the execution status of the command |
| identified by <em>event</em> is not <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or if <em>event</em> is a user event |
| object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes |
| specified by <em>param_value_size</em> is < size of return type as described in |
| the <a href="#event-profiling-info-table">Event Profiling Queries</a> table and |
| <em>param_value</em> is not <code>NULL</code>.</p> |
| </li> |
| <li> |
| <p><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a> if <em>event</em> is a not a valid event object.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_flush_and_finish"><a class="anchor" href="#_flush_and_finish"></a>5.15. Flush and Finish</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To flush commands to a device, call the function</p> |
| </div> |
| <div id="clFlush" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clFlush( |
| cl_command_queue command_queue);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is the command queue to flush.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>All previously queued OpenCL commands in <em>command_queue</em> are issued to the |
| device associated with <em>command_queue</em>. |
| <a href="#clFlush"><strong>clFlush</strong></a> only guarantees that all queued commands to <em>command_queue</em> will |
| eventually be submitted to the appropriate device. |
| There is no guarantee that they will be complete after <a href="#clFlush"><strong>clFlush</strong></a> returns.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Any blocking commands queued in a command-queue and <a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a> |
| perform an implicit flush of the command-queue. |
| These blocking commands are <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a>, |
| <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a>, <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a>, with <em>blocking_read</em> set to |
| <a href="#CL_TRUE"><code>CL_TRUE</code></a>; <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a>, <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a>, |
| <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> with <em>blocking_write</em> set to <a href="#CL_TRUE"><code>CL_TRUE</code></a>; |
| <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>, <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> with <em>blocking_map</em> set to |
| <a href="#CL_TRUE"><code>CL_TRUE</code></a>; <a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a> with <em>blocking_copy</em> set to <a href="#CL_TRUE"><code>CL_TRUE</code></a>; |
| <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> with <em>blocking_map</em> set to <a href="#CL_TRUE"><code>CL_TRUE</code></a> or <a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To use event objects that refer to commands enqueued in a command-queue as |
| event objects to wait on by commands enqueued in a different command-queue, |
| the application must call a <a href="#clFlush"><strong>clFlush</strong></a> or any blocking commands that perform |
| an implicit flush of the command-queue where the commands that refer to |
| these event objects are enqueued.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clFlush"><strong>clFlush</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function call was executed successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>To wait for completion of commands on a device, call the function</p> |
| </div> |
| <div id="clFinish" class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c++">cl_int clFinish( |
| cl_command_queue command_queue);</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>command_queue</em> is the command queue to wait for.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>All previously queued OpenCL commands in <em>command_queue</em> are issued to the |
| associated device, and the function blocks until all previously queued |
| commands have completed. |
| <a href="#clFinish"><strong>clFinish</strong></a> does not return until all previously queued commands in |
| <em>command_queue</em> have been processed and completed. |
| <a href="#clFinish"><strong>clFinish</strong></a> is also a synchronization point.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#clFinish"><strong>clFinish</strong></a> returns <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> if the function call was executed |
| successfully. |
| Otherwise, it returns one of the following errors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> if <em>command_queue</em> is not a valid host |
| command-queue.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> if there is a failure to allocate resources required |
| by the OpenCL implementation on the device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a> if there is a failure to allocate resources |
| required by the OpenCL implementation on the host.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_associated_opencl_specification"><a class="anchor" href="#_associated_opencl_specification"></a>6. Associated OpenCL specification</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="spirv-il"><a class="anchor" href="#spirv-il"></a>6.1. SPIR-V Intermediate Language</h3> |
| <div class="paragraph"> |
| <p>OpenCL 2.1 and 2.2 require support for the SPIR-V intermediate |
| language that allows offline compilation to a binary |
| format that may be consumed by the <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> interface.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OpenCL specification includes a specification for the SPIR-V |
| intermediate language as a cross-platform input language. |
| In addition, platform vendors may support their own IL if this is |
| appropriate. |
| The OpenCL runtime will return a list of supported IL versions using the |
| <a href="#CL_DEVICE_IL_VERSION"><code>CL_DEVICE_<wbr>IL_<wbr>VERSION</code></a> or <a href="#CL_DEVICE_ILS_WITH_VERSION"><code>CL_DEVICE_<wbr>ILS_<wbr>WITH_<wbr>VERSION</code></a> parameter to |
| the <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> query.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="opencl-extensions"><a class="anchor" href="#opencl-extensions"></a>6.2. Extensions to OpenCL</h3> |
| <div class="paragraph"> |
| <p>In addition to the specification of core features, OpenCL provides a number |
| of extensions to the API, kernel language or intermediate representation. |
| These features are defined in the OpenCL extension specification document.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Extensions defined against earlier versions of the OpenCL specifications, |
| whether the API or language specification, are defined in the matching |
| versions of the extension specification document.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="opencl-c-kernel-language"><a class="anchor" href="#opencl-c-kernel-language"></a>6.3. The OpenCL C Kernel Language</h3> |
| <div class="paragraph"> |
| <p>The OpenCL C kernel language is not defined in the OpenCL unified |
| specification. |
| The OpenCL C kernel languages are instead defined in the OpenCL 1.0, |
| OpenCL 1.1, OpenCL 1.2, OpenCL C 2.0 Kernel Language, and OpenCL C 3.0 |
| Kernel Language specifications. |
| When OpenCL devices support one or more versions of the OpenCL C |
| kernel language (see <a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a> and |
| <a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a>), |
| OpenCL program objects may be created by passing OpenCL C source |
| strings to <a href="#clCreateProgramWithSource"><strong>clCreateProgramWithSource</strong></a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="opencl-embedded-profile"><a class="anchor" href="#opencl-embedded-profile"></a>7. OpenCL Embedded Profile</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The OpenCL specification describes the feature requirements for desktop |
| platforms. |
| This section describes the OpenCL embedded profile that allows us to |
| target a subset of the OpenCL specification for handheld and embedded |
| platforms. |
| The optional extensions defined in the OpenCL Extension Specification |
| apply to both profiles.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OpenCL embedded profile has the following restrictions until version 2.0 (i.e. the optionality described below was <a href="#unified-spec">deprecated by</a> version 2.0):</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Support for 3D images is optional.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>If <a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a> and |
| <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a> are zero, calls to <a href="#clCreateImage"><strong>clCreateImage</strong></a> or |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> will fail to create the 3D image, and |
| the <em>errcode_ret</em> argument will return <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a>. |
| Declaring arguments of type <code>image3d_t</code> in a kernel will result in a |
| compilation error.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a> and |
| <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a> are greater than zero 0, calls to |
| <a href="#clCreateImage"><strong>clCreateImage</strong></a> and <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a> will behave as |
| described for full profile implementations, and the <code>image3d_t</code> |
| data type can be used in a kernel.</p> |
| </div> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Support for 2D image array writes is optional. |
| If the <strong>cles_khr_2d_image_array_writes</strong> extension is supported by the |
| embedded profile, writes to 2D image arrays are supported.</p> |
| </li> |
| <li> |
| <p>Image and image arrays created with an |
| <code>image_channel_data_type</code> value of <a href="#CL_FLOAT"><code>CL_FLOAT</code></a> or <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a> can only be |
| used with samplers that use a filter mode of <a href="#CL_FILTER_NEAREST"><code>CL_FILTER_<wbr>NEAREST</code></a>. |
| The values returned by <strong>read_imagef</strong> <sup class="footnote">[<a id="_footnoteref_34" class="footnote" href="#_footnotedef_34" title="View footnote.">34</a>]</sup> for 2D and 3D |
| images if <code>image_channel_data_type</code> value is <a href="#CL_FLOAT"><code>CL_FLOAT</code></a> or <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a> |
| and sampler with filter_mode = <a href="#CL_FILTER_LINEAR"><code>CL_FILTER_<wbr>LINEAR</code></a> are undefined.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, the OpenCL embedded profile has the following restrictions for all |
| versions:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>64 bit integers i.e. long, ulong including the appropriate vector data |
| types and operations on 64-bit integers are optional. |
| The <strong>cles_khr_int64</strong> <sup class="footnote">[<a id="_footnoteref_35" class="footnote" href="#_footnotedef_35" title="View footnote.">35</a>]</sup> extension string will |
| be reported if the embedded profile implementation supports 64-bit integers. |
| If double precision is supported i.e. <a href="#CL_DEVICE_DOUBLE_FP_CONFIG"><code>CL_DEVICE_<wbr>DOUBLE_<wbr>FP_<wbr>CONFIG</code></a> is not |
| zero, then <strong>cles_khr_int64</strong> must also be supported.</p> |
| </li> |
| <li> |
| <p>The mandated minimum single precision floating-point capability given by |
| <a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_DEVICE_<wbr>SINGLE_<wbr>FP_<wbr>CONFIG</code></a> is <a href="#CL_FP_ROUND_TO_ZERO"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>ZERO</code></a> or |
| <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a>. |
| If <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a> is supported, the default rounding mode will |
| be round to nearest even; otherwise the default rounding mode will be |
| round to zero.</p> |
| </li> |
| <li> |
| <p>The single precision floating-point operations (addition, subtraction |
| and multiplication) shall be correctly rounded. |
| Zero results may always be positive 0.0. |
| The accuracy of division and sqrt are given in the OpenCL C and OpenCL |
| SPIR-V Environment specifications.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>If <a href="#CL_FP_INF_NAN"><code>CL_FP_<wbr>INF_<wbr>NAN</code></a> is not set in <a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_DEVICE_<wbr>SINGLE_<wbr>FP_<wbr>CONFIG</code></a>, and one of the |
| operands or the result of addition, subtraction, multiplication or division |
| would signal the overflow or invalid exception (see IEEE 754 specification), |
| the value of the result is implementation-defined. |
| Likewise, single precision comparison operators (<, >, <=, >=, ==, |
| !=) return implementation-defined values when one or more operands is a |
| NaN.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In all cases, conversions (see the OpenCL C and OpenCL SPIR-V Environment |
| specifications) shall be correctly rounded as described for the FULL_PROFILE, |
| including those that consume or produce an INF or NaN. |
| The built-in math functions shall behave as described for the FULL_PROFILE, |
| including edge case behavior, but with slightly different accuracy rules. |
| Edge case behavior and accuracy rules are described in the OpenCL C |
| and OpenCL SPIR-V Environment specifications.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="title">Note</div> |
| <div class="paragraph"> |
| <p>If addition, subtraction and multiplication have default round to zero |
| rounding mode, then <strong>fract</strong>, <strong>fma</strong> and <strong>fdim</strong> shall produce the correctly |
| rounded result for round to zero rounding mode.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This relaxation of the requirement to adhere to IEEE 754 requirements for |
| basic floating-point operations, though extremely undesirable, is to provide |
| flexibility for embedded devices that have lot stricter requirements on |
| hardware area budgets.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Denormalized numbers for the half data type which may be generated when |
| converting a float to a half using variants of the <strong>vstore_half</strong> |
| function or when converting from a half to a float using variants of the |
| <strong>vload_half</strong> function can be flushed to zero. |
| The OpenCL SPIR-V Environment Specification for details.</p> |
| </li> |
| <li> |
| <p>The precision of conversions from <a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a>, <a href="#CL_SNORM_INT8"><code>CL_SNORM_<wbr>INT8</code></a>, |
| <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a>, <a href="#CL_SNORM_INT16"><code>CL_SNORM_<wbr>INT16</code></a>, <a href="#CL_UNORM_INT_101010"><code>CL_UNORM_<wbr>INT_<wbr>101010</code></a>, and |
| <a href="#CL_UNORM_INT_101010_2"><code>CL_UNORM_<wbr>INT_<wbr>101010_<wbr>2</code></a> to float is ≤ 2 ulp for the embedded profile |
| instead of ≤ 1.5 ulp as defined in the full profile. |
| The exception cases described in the full profile and given below apply |
| to the embedded profile.</p> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>For <a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>0 must convert to 0.0f and</p> |
| </li> |
| <li> |
| <p>255 must convert to 1.0f</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>0 must convert to 0.0f and</p> |
| </li> |
| <li> |
| <p>65535 must convert to 1.0f</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For <a href="#CL_SNORM_INT8"><code>CL_SNORM_<wbr>INT8</code></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>-128 and -127 must convert to -1.0f,</p> |
| </li> |
| <li> |
| <p>0 must convert to 0.0f and</p> |
| </li> |
| <li> |
| <p>127 must convert to 1.0f</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For <a href="#CL_SNORM_INT16"><code>CL_SNORM_<wbr>INT16</code></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>-32768 and -32767 must convert to -1.0f,</p> |
| </li> |
| <li> |
| <p>0 must convert to 0.0f and</p> |
| </li> |
| <li> |
| <p>32767 must convert to 1.0f</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For <a href="#CL_UNORM_INT_101010"><code>CL_UNORM_<wbr>INT_<wbr>101010</code></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>0 must convert to 0.0f and</p> |
| </li> |
| <li> |
| <p>1023 must convert to 1.0f</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For <a href="#CL_UNORM_INT_101010_2"><code>CL_UNORM_<wbr>INT_<wbr>101010_<wbr>2</code></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>0 must convert to 0.0f and</p> |
| </li> |
| <li> |
| <p>1023 must convert to 1.0f (for RGB)</p> |
| </li> |
| <li> |
| <p>3 must convert to 1.0f (for A)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#CL_PLATFORM_PROFILE"><code>CL_PLATFORM_<wbr>PROFILE</code></a> defined in the <a href="#platform-queries-table">OpenCL Platform |
| Queries</a> table will return the string EMBEDDED_PROFILE if the OpenCL |
| implementation supports the embedded profile only.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The minimum maximum values specified in the <a href="#device-queries-table">OpenCL |
| Device Queries</a> table that have been modified for the OpenCL embedded |
| profile are listed in the <a href="#embedded-device-queries-table">OpenCL Embedded |
| Device Queries</a> table.</p> |
| </div> |
| <table id="embedded-device-queries-table" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 39. List of supported param_names by <a href="#clGetDeviceInfo">clGetDeviceInfo</a> for embedded profile</caption> |
| <colgroup> |
| <col style="width: 33%;"> |
| <col style="width: 17%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Device Info</th> |
| <th class="tableblock halign-left valign-top">Return Type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the |
| <code>read_only</code> qualifier. |
| The minimum value is 8 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the |
| <code>write_only</code> qualifier. |
| The minimum value is 8 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the |
| <code>write_only</code> or <code>read_write</code> qualifier. |
| The minimum value is 8 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max width of 2D image in pixels. |
| The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>HEIGHT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max height of 2D image in pixels. |
| The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max width of 3D image in pixels. |
| The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max height of 3D image in pixels. |
| The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max depth of 3D image in pixels. |
| The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"><code>CL_DEVICE_<wbr>IMAGE_<wbr>MAX_<wbr>BUFFER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of pixels for a 1D image created from a buffer object.</p> |
| <p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"><code>CL_DEVICE_<wbr>IMAGE_<wbr>MAX_<wbr>ARRAY_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of images in a 1D or 2D image array.</p> |
| <p class="tableblock"> The minimum value is 256 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_DEVICE_<wbr>MAX_<wbr>SAMPLERS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of samplers that can be used in a kernel.</p> |
| <p class="tableblock"> The minimum value is 8 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, |
| the value is 0 otherwise.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_PARAMETER_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>PARAMETER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max size in bytes of all arguments that can be passed to a kernel. |
| The minimum value is 256 bytes for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_DEVICE_<wbr>SINGLE_<wbr>FP_<wbr>CONFIG</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_device_<wbr>fp_<wbr>config</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Describes single precision floating-point capability of the device. |
| This is a bit-field that describes one or more of the following |
| values:</p> |
| <p class="tableblock"> <a href="#CL_FP_DENORM"><code>CL_FP_<wbr>DENORM</code></a> - denorms are supported</p> |
| <p class="tableblock"> <a href="#CL_FP_INF_NAN"><code>CL_FP_<wbr>INF_<wbr>NAN</code></a> - INF and quiet NaNs are supported.</p> |
| <p class="tableblock"> <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a> - round to nearest even rounding mode |
| supported</p> |
| <p class="tableblock"> <a href="#CL_FP_ROUND_TO_ZERO"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>ZERO</code></a> - round to zero rounding mode supported</p> |
| <p class="tableblock"> <a href="#CL_FP_ROUND_TO_INF"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>INF</code></a> - round to positive and negative infinity |
| rounding modes supported</p> |
| <p class="tableblock"> <a href="#CL_FP_FMA"><code>CL_FP_<wbr>FMA</code></a> - IEEE754-2008 fused multiply-add is supported.</p> |
| <p class="tableblock"> <a href="#CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"><code>CL_FP_<wbr>CORRECTLY_<wbr>ROUNDED_<wbr>DIVIDE_<wbr>SQRT</code></a> - divide and sqrt are correctly |
| rounded as defined by the IEEE754 specification.</p> |
| <p class="tableblock"> <a href="#CL_FP_SOFT_FLOAT"><code>CL_FP_<wbr>SOFT_<wbr>FLOAT</code></a> - Basic floating-point operations (such as |
| addition, subtraction, multiplication) are implemented in software.</p> |
| <p class="tableblock"> <a id="embedded-profile-single-fp-config-requirements"></a> |
| The mandated minimum floating-point capability is: |
| <a href="#CL_FP_ROUND_TO_ZERO"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>ZERO</code></a> or <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_FP_<wbr>ROUND_<wbr>TO_<wbr>NEAREST</code></a> for devices that are |
| not of type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>CONSTANT_<wbr>BUFFER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max size in bytes of a constant buffer allocation. |
| The minimum value is 1 KB for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_MAX_CONSTANT_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>CONSTANT_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Max number of arguments declared with the <code>__constant</code> qualifier |
| in a kernel. |
| The minimum value is 4 for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_LOCAL_MEM_SIZE"><code>CL_DEVICE_<wbr>LOCAL_<wbr>MEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_ulong</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Size of local memory arena in bytes. |
| The minimum value is 1 KB for devices that are not of type |
| <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_DEVICE_<wbr>TYPE_<wbr>CUSTOM</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_FALSE"><code>CL_FALSE</code></a> if the implementation does not have a compiler available |
| to compile the program source.</p> |
| <p class="tableblock"> Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the compiler is available. |
| This can be <a href="#CL_FALSE"><code>CL_FALSE</code></a> for the embedded platform profile only.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_LINKER_AVAILABLE"><code>CL_DEVICE_<wbr>LINKER_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_bool</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_FALSE"><code>CL_FALSE</code></a> if the implementation does not have a linker available. |
| Is <a href="#CL_TRUE"><code>CL_TRUE</code></a> if the linker is available.</p> |
| <p class="tableblock"> This can be <a href="#CL_FALSE"><code>CL_FALSE</code></a> for the embedded platform profile only.</p> |
| <p class="tableblock"> This must be <a href="#CL_TRUE"><code>CL_TRUE</code></a> if <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>MAX_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cl_uint</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The max. size of the device queue in bytes. |
| The minimum value is 64 KB for the embedded profile</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEVICE_PRINTF_BUFFER_SIZE"><code>CL_DEVICE_<wbr>PRINTF_<wbr>BUFFER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>size_t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum size in bytes of the internal buffer that holds the output |
| of printf calls from a kernel. |
| The minimum value for the EMBEDDED profile is 1 KB.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>If <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the <a href="#device-queries-table">OpenCL |
| Device Queries</a> table is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the values assigned to |
| <a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a>, <a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a>, |
| <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE2D_<wbr>MAX_<wbr>HEIGHT</code></a>, |
| <a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>HEIGHT</code></a>, |
| <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_DEVICE_<wbr>IMAGE3D_<wbr>MAX_<wbr>DEPTH</code></a>, and <a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_DEVICE_<wbr>MAX_<wbr>SAMPLERS</code></a> by the implementation |
| must be greater than or equal to the minimum values specified in the |
| <a href="#embedded-device-queries-table">OpenCL Embedded Device Queries</a> table.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>SUPPORT</code></a> specified in the <a href="#device-queries-table">OpenCL |
| Device Queries</a> table is <a href="#CL_TRUE"><code>CL_TRUE</code></a>, the minimum list of supported |
| image formats for either reading or writing in a kernel for embedded |
| profile devices is:</p> |
| </div> |
| <table id="min-supported-image-formats-embedded-profile" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 40. Minimum list of supported image formats for reading or writing (embedded profile)</caption> |
| <colgroup> |
| <col style="width: 34%;"> |
| <col style="width: 33%;"> |
| <col style="width: 33%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">num_channels</th> |
| <th class="tableblock halign-left valign-top">channel_order</th> |
| <th class="tableblock halign-left valign-top">channel_data_type</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_RGBA</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_UNORM_<wbr>INT8</code></a><br> |
| <a href="#CL_UNORM_INT16"><code>CL_UNORM_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT8"><code>CL_SIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_SIGNED_INT16"><code>CL_SIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_SIGNED_INT32"><code>CL_SIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_UNSIGNED_INT8"><code>CL_UNSIGNED_<wbr>INT8</code></a><br> |
| <a href="#CL_UNSIGNED_INT16"><code>CL_UNSIGNED_<wbr>INT16</code></a><br> |
| <a href="#CL_UNSIGNED_INT32"><code>CL_UNSIGNED_<wbr>INT32</code></a><br> |
| <a href="#CL_HALF_FLOAT"><code>CL_HALF_<wbr>FLOAT</code></a><br> |
| <a href="#CL_FLOAT"><code>CL_FLOAT</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>For embedded profiles devices that support reading from and writing to the same |
| image object from the same kernel instance (see <a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a>) |
| there is no required minimum list of supported image formats.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_host_environment_and_thread_safety"><a class="anchor" href="#_host_environment_and_thread_safety"></a>Appendix A: Host environment and thread safety</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="shared-opencl-objects"><a class="anchor" href="#shared-opencl-objects"></a>Shared OpenCL Objects</h3> |
| <div class="paragraph"> |
| <p>This section describes which objects can be shared across multiple |
| command-queues created within a host process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL memory objects, program objects and kernel objects are created using |
| a context and can be shared across multiple command-queues created using the |
| same context. |
| Event objects can be created when a command is queued to a command-queue. |
| These event objects can be shared across multiple command-queues created |
| using the same context.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The application needs to implement appropriate synchronization across |
| threads on the host processor to ensure that the changes to the state of a |
| shared object (such as a command-queue object, memory object, program or |
| kernel object) happen in the correct order (deemed correct by the |
| application) when multiple command-queues in multiple threads are making |
| changes to the state of a shared object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A command-queue can cache changes to the state of a memory object on the |
| device associated with the command-queue. |
| To synchronize changes to a memory object across command-queues, the |
| application must do the following:</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the command-queue that includes commands that modify the state of a |
| memory object, the application must do the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Get appropriate event objects for commands that modify the state of the |
| shared memory object.</p> |
| </li> |
| <li> |
| <p>Call the <a href="#clFlush"><strong>clFlush</strong></a> (or <a href="#clFinish"><strong>clFinish</strong></a>) API to issue any outstanding commands |
| from this command-queue.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In the command-queue that wants to synchronize to the latest state of a |
| memory object, commands queued by the application must use the appropriate |
| event objects that represent commands that modify the state of the shared |
| memory object as event objects to wait on. |
| This is to ensure that commands that use this shared memory object complete |
| in the previous command-queue before the memory objects are used by commands |
| executing in this command-queue.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The results of modifying a shared resource in one command-queue while it is |
| being used by another command-queue are undefined.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_multiple_host_threads"><a class="anchor" href="#_multiple_host_threads"></a>Multiple Host Threads</h3> |
| <div class="paragraph"> |
| <p>All OpenCL API calls are thread-safe <sup class="footnote">[<a id="_footnoteref_36" class="footnote" href="#_footnotedef_36" title="View footnote.">36</a>]</sup> except those |
| that modify the state of <code>cl_kernel</code> objects: <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>, |
| <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a>, <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> and <a href="#clCloneKernel"><strong>clCloneKernel</strong></a>. |
| <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>, <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a>, <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> and |
| <a href="#clCloneKernel"><strong>clCloneKernel</strong></a> are safe to call from any host thread, and safe to call |
| re-entrantly so long as concurrent calls to any combination of these API |
| calls operate on different <code>cl_kernel</code> objects. |
| The state of the <code>cl_kernel</code> object is undefined if <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>, |
| <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a>, <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> or <a href="#clCloneKernel"><strong>clCloneKernel</strong></a> are |
| called from multiple host threads on the same <code>cl_kernel</code> object at the same |
| time <sup class="footnote">[<a id="_footnoteref_37" class="footnote" href="#_footnotedef_37" title="View footnote.">37</a>]</sup>. |
| Please note that there are additional limitations as to which OpenCL APIs |
| may be called from <a href="#event-objects">OpenCL callback functions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The behavior of OpenCL APIs called from an interrupt or signal handler is |
| implementation-defined</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OpenCL implementation should be able to create multiple command-queues |
| for a given OpenCL context and multiple OpenCL contexts in an application |
| running on the host processor.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_global_constructors_and_destructors"><a class="anchor" href="#_global_constructors_and_destructors"></a>Global constructors and destructors</h3> |
| <div class="paragraph"> |
| <p>The execution order of global constructors and destructors is left undefined |
| by the C and C++ standards. It is therefore not possible to know the relative |
| execution order of an OpenCL implementation’s global constructors and destructors |
| with respect to an OpenCL application’s or library’s.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The behavior of OpenCL API functions called from global constructors or |
| destructors is therefore implementation-defined.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_portability"><a class="anchor" href="#_portability"></a>Appendix B: Portability</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>OpenCL is designed to be portable to other architectures and hardware |
| designs. |
| OpenCL has used at its core a C99 based programming language and follows |
| rules based on that heritage. |
| Floating-point arithmetic is based on the <strong>IEEE-754</strong> and <strong>IEEE-754-2008</strong> |
| standards. |
| The memory objects, pointer qualifiers and weakly ordered memory are |
| designed to provide maximum compatibility with discrete memory architectures |
| implemented by OpenCL devices. |
| Command-queues and barriers allow for synchronization between the host and |
| OpenCL devices. |
| The design, capabilities and limitations of OpenCL are very much a |
| reflection of the capabilities of underlying hardware.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Unfortunately, there are a number of areas where idiosyncrasies of one |
| hardware platform may allow it to do some things that do not work on |
| another. |
| By virtue of the rich operating system resident on the CPU, on some |
| implementations the kernels executing on a CPU may be able to call out to |
| system services whereas the same calls on the GPU will likely fail for now. |
| Since there is some advantage to having these services available for |
| debugging purposes, implementations can use the OpenCL extension mechanism |
| to implement these services.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Likewise, the heterogeneity of computing architectures might mean that a |
| particular loop construct might execute at an acceptable speed on the CPU |
| but very poorly on a GPU, for example. |
| CPUs are designed in general to work well on latency sensitive algorithms on |
| single threaded tasks, whereas common GPUs may encounter extremely long |
| latencies, potentially orders of magnitude worse. |
| Developers interested in writing portable code may need to test their |
| software on a diversity of hardware designs to make sure that key algorithms |
| are structured in a way that works well on a diversity of hardware. |
| We suggest favoring more work-items over fewer. |
| It is anticipated that over the coming months and years experience will |
| produce a set of best practices that will help foster a uniformly favorable |
| experience on a diversity of computing devices.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Of somewhat more concern is the topic of endianness. |
| Since a majority of devices supported by the initial implementation of |
| OpenCL are little-endian, developers need to make sure that their kernels |
| are tested on both big-endian and little-endian devices to ensure source |
| compatibility with OpenCL devices now and in the future. |
| The endian attribute qualifier is supported by the SPIR-V IL to allow |
| developers to specify whether the data uses the endianness of the host or |
| the OpenCL device. |
| This allows the OpenCL compiler to do appropriate endian-conversion on load |
| and store operations from or to this data.</p> |
| </div> |
| <div class="paragraph"> |
| <p>We also describe how endianness can leak into an implementation causing |
| kernels to produce unintended results:</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a big-endian vector machine (e.g. AltiVec, CELL SPE) loads a vector, |
| the order of the data is retained. |
| That is both the order of the bytes within each element and the order of the |
| elements in the vector are the same as in memory. |
| When a little-endian vector machine (e.g. SSE) loads a vector, the order of |
| the data in register (where all the work is done) is reversed. |
| <strong>Both</strong> the order of the bytes within each element and the order of the |
| elements with respect to one another in the vector are reversed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Memory:</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x00010203</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x04050607</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x08090A0B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0C0D0E0F</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>In register (big-endian):</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x00010203</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x04050607</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x08090A0B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0C0D0E0F</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>In register (little-endian):</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0F0E0D0C</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0B0A0908</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x07060504</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x03020100</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>This allows little-endian machines to use a single vector load to load |
| little-endian data, regardless of how large each piece of data is in the |
| vector. |
| That is the transformation is equally valid whether that vector was a |
| <code>uchar16</code> or a <code>ulong2</code>. |
| Of course, as is well known, little-endian machines |
| actually <sup class="footnote">[<a id="_footnoteref_38" class="footnote" href="#_footnotedef_38" title="View footnote.">38</a>]</sup> store their data in reverse byte order to |
| compensate for the little-endian storage format of the array elements:</p> |
| </div> |
| <div class="paragraph"> |
| <p>Memory (big-endian):</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x00010203</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x04050607</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x08090A0B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0C0D0E0F</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Memory (little-endian):</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x03020100</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x07060504</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0B0A0908</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0F0E0D0C</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Once that data is loaded into a vector, we end up with this:</p> |
| </div> |
| <div class="paragraph"> |
| <p>In register (big-endian):</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x00010203</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x04050607</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x08090A0B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0C0D0E0F</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>In register (little-endian):</p> |
| </div> |
| <div class="paragraph"> |
| <p>uint4 a =</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x0C0D0E0F</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x08090A0B</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x04050607</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">0x00010203</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>That is, in the process of correcting the endianness of the bytes within |
| each element, the machine ends up reversing the order that the elements |
| appear in the vector with respect to each other within the vector. |
| 0x00010203 appears at the left of the big-endian vector and at the right of |
| the little-endian vector.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the host and device have different endianness, the developer must |
| ensure that kernel argument values are processed correctly. |
| The implementation may or may not automatically convert endianness of kernel |
| arguments. |
| Developers should consult vendor documentation for guidance on how to handle |
| kernel arguments in these situations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL provides a consistent programming model across architectures by |
| numbering elements according to their order in memory. |
| Concepts such as <code>even</code>/<code>odd</code> and <code>high</code>/<code>low</code> follow accordingly. |
| Once the data is loaded into registers, we find that element 0 is at the |
| left of the big-endian vector and element 0 is at the right of the |
| little-endian vector:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="predefined-type">float</span> x[<span class="integer">4</span>]; |
| float4 v = vload4( <span class="integer">0</span>, x );</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Big-endian:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">v contains { x[<span class="integer">0</span>], x[<span class="integer">1</span>], x[<span class="integer">2</span>], x[<span class="integer">3</span>] }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Little-endian:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">v contains { x[<span class="integer">3</span>], x[<span class="integer">2</span>], x[<span class="integer">1</span>], x[<span class="integer">0</span>] }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The compiler is aware that this swap occurs and references elements |
| accordingly. |
| So long as we refer to them by a numeric index such as <code>.s0123456789abcdef</code> |
| or by descriptors such as <code>.xyzw</code>, <code>.hi</code>, <code>.lo</code>, <code>.even</code> and <code>.odd</code>, |
| everything works transparently. |
| Any ordering reversal is undone when the data is stored back to memory. |
| The developer should be able to work with a big-endian programming model and |
| ignore the element ordering problem in the vector …​ for most problems. |
| This mechanism relies on the fact that we can rely on a consistent element |
| numbering. |
| Once we change numbering system, for example by conversion-free casting |
| (using <code>as_type_</code><em>n</em>) a vector to another vector of the same size but a |
| different number of elements, then we get different results on different |
| implementations depending on whether the system is big-endian, or |
| little-endian or indeed has no vector unit at all. |
| (Thus, the behavior of bitcasts to vectors of different numbers of elements |
| is implementation-defined, see section 6.4.4 of OpenCL C specification.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="predefined-type">float</span> x[<span class="integer">4</span>] = { <span class="float">0</span><span class="float">.0f</span>, <span class="float">1</span><span class="float">.0f</span>, <span class="float">2</span><span class="float">.0f</span>, <span class="float">3</span><span class="float">.0f</span> }; |
| float4 v = vload4( <span class="integer">0</span>, x ); |
| uint4 y = as_uint4(v); <span class="comment">// legal, portable</span> |
| ushort8 z = as_ushort8(v); <span class="comment">// legal, not portable</span> |
| <span class="comment">// element size changed</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Big-endian:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">v contains { <span class="float">0</span><span class="float">.0f</span>, <span class="float">1</span><span class="float">.0f</span>, <span class="float">2</span><span class="float">.0f</span>, <span class="float">3</span><span class="float">.0f</span> } |
| y contains { <span class="hex">0x00000000</span>, <span class="hex">0x3f800000</span>, |
| <span class="hex">0x40000000</span>, <span class="hex">0x40400000</span> } |
| z contains { <span class="hex">0x0000</span>, <span class="hex">0x0000</span>, <span class="hex">0x3f80</span>, <span class="hex">0x0000</span>, |
| <span class="hex">0x4000</span>, <span class="hex">0x0000</span>, <span class="hex">0x4040</span>, <span class="hex">0x0000</span> } |
| z.z is <span class="hex">0x3f80</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Little-endian:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">v contains { <span class="float">3</span><span class="float">.0f</span>, <span class="float">2</span><span class="float">.0f</span>, <span class="float">1</span><span class="float">.0f</span>, <span class="float">0</span><span class="float">.0f</span> } |
| y contains { <span class="hex">0x40400000</span>, <span class="hex">0x40000000</span>, |
| <span class="hex">0x3f800000</span>, <span class="hex">0x00000000</span> } |
| z contains { <span class="hex">0x4040</span>, <span class="hex">0x0000</span>, <span class="hex">0x4000</span>, <span class="hex">0x0000</span>, |
| <span class="hex">0x3f80</span>, <span class="hex">0x0000</span>, <span class="hex">0x0000</span>, <span class="hex">0x0000</span> } |
| z.z is <span class="integer">0</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here, the value in <code>z.z</code> is not the same between big- and little-endian |
| vector machines</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL could have made it illegal to do a conversion free cast that changes |
| the number of elements in the name of portability. |
| However, while OpenCL provides a common set of operators drawing from the |
| set that are typically found on vector machines, it can not provide access |
| to everything every ISA may offer in a consistent uniform portable manner. |
| Many vector ISAs provide special purpose instructions that greatly |
| accelerate specific operations such as DCT, SAD, or 3D geometry. |
| It is not intended for OpenCL to be so heavy handed that time-critical |
| performance sensitive algorithms can not be written by knowledgeable |
| developers to perform at near peak performance. |
| Developers willing to throw away portability should be able to use the |
| platform-specific instructions in their code. |
| For this reason, OpenCL is designed to allow traditional vector C language |
| programming extensions, such as the AltiVec C Programming Interface or the |
| Intel C programming interfaces (such as those found in emmintrin.h) to be |
| used directly in OpenCL with OpenCL data types as an extension to OpenCL. |
| As these interfaces rely on the ability to do conversion-free casts that |
| change the number of elements in the vector to function properly, OpenCL |
| allows them too.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As a general rule, any operation that operates on vector types in segments |
| that are not the same size as the vector element size may break on other |
| hardware with different endianness or different vector architecture.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples might include:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Combining two <code>uchar8</code>'s containing high and low bytes of a ushort, to |
| make a <code>ushort8</code> using <code>.even</code> and <code>.odd</code> operators (please use |
| <strong>upsample()</strong> for this)</p> |
| </li> |
| <li> |
| <p>Any bitcast that changes the number of elements in the vector. |
| (Operations on the new type are non-portable.)</p> |
| </li> |
| <li> |
| <p>Swizzle operations that change the order of data using chunk sizes that |
| are not the same as the element size</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Examples of operations that are portable:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Combining two <code>uint8</code>'s to make a <code>uchar16</code> using <code>.even</code> and <code>.odd</code> |
| operators. |
| For example to interleave left and right audio streams.</p> |
| </li> |
| <li> |
| <p>Any bitcast that does not change the number of elements (e.g. <code>(float4) |
| uint4</code>) — we define the storage format for floating-point types)</p> |
| </li> |
| <li> |
| <p>Swizzle operations that swizzle elements of the same size as the |
| elements of the vector.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL has made some additions to C to make application behavior more |
| dependable than C. |
| Most notably in a few cases OpenCL defines the behavior of some operations |
| that are undefined in C99:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>OpenCL provides <code>convert_</code> operators for conversion between all types. |
| C99 does not define what happens when a floating-point type is converted |
| to integer type and the floating-point value lies outside the |
| representable range of the integer type after rounding. |
| When the <code><em>sat</code> variant of the conversion is used, the float shall be |
| converted to the nearest representable integer value. |
| Similarly, OpenCL also makes recommendations about what should happen |
| with NaN. |
| Hardware manufacturers that provide the saturated conversion in hardware |
| may use the saturated conversion hardware for both the saturated and |
| non-saturated versions of the OpenCL <code>convert</em></code> operator. |
| OpenCL does not define what happens for the non-saturated conversions |
| when floating-point operands are outside the range representable |
| integers after rounding.</p> |
| </li> |
| <li> |
| <p>The format of <code>half</code>, <code>float</code>, and <code>double</code> types is defined to be the |
| binary16, binary32 and binary64 formats in the draft IEEE-754 standard. |
| (The latter two are identical to the existing IEEE-754 standard.) You |
| may depend on the positioning and meaning of the bits in these types.</p> |
| </li> |
| <li> |
| <p>OpenCL defines behavior for oversized shift values. |
| Shift operations that shift greater than or equal to the number of bits |
| in the first operand reduce the shift value modulo the number of bits in |
| the element. |
| For example, if we shift an <code>int4</code> left by <code>33</code> bits, OpenCL treats this |
| as shift left by <code>33%32 = 1</code> bit.</p> |
| </li> |
| <li> |
| <p>A number of edge cases for math library functions are more rigorously |
| defined than in C99. |
| Please see <em>section 7.5</em> of the OpenCL C specification.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="data-types"><a class="anchor" href="#data-types"></a>Appendix C: Application Data Types</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This section documents the provided host application types and constant |
| definitions. |
| The documented material describes the commonly defined data structures, |
| types and constant values available to all platforms and architectures. |
| The addition of these details demonstrates our commitment to maintaining a |
| portable programming environment and potentially deters changes to the |
| supplied headers.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="scalar-data-types"><a class="anchor" href="#scalar-data-types"></a>Supported Application Scalar Data Types</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The following application scalar types are provided for application |
| convenience.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">cl_char |
| cl_uchar |
| cl_short |
| cl_ushort |
| cl_int |
| cl_uint |
| cl_long |
| cl_ulong |
| cl_half |
| cl_float |
| cl_double</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="vector-data-types"><a class="anchor" href="#vector-data-types"></a>Supported Application Vector Data Types</h3> |
| <div class="openblock"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Application vector types are unions used to create vectors of the above |
| application scalar types. |
| The following application vector types are provided for application |
| convenience.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">cl_char<n> |
| cl_uchar<n> |
| cl_short<n> |
| cl_ushort<n> |
| cl_int<n> |
| cl_uint<n> |
| cl_long<n> |
| cl_ulong<n> |
| cl_half<n> |
| cl_float<n> |
| cl_double<n></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>n</em> can be 2, 3, 4, 8 or 16.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The application scalar and vector data types are defined in the |
| <strong>cl_platform.h</strong> header file.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="alignment-app-data-types"><a class="anchor" href="#alignment-app-data-types"></a>Alignment of Application Data Types</h3> |
| <div class="paragraph"> |
| <p>The user is responsible for ensuring that pointers passed into and out of |
| OpenCL kernels are natively aligned relative to the data type of the |
| parameter as defined in the kernel language and SPIR-V specifications. |
| This implies that OpenCL buffers created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> need to |
| provide an appropriately aligned host memory pointer that is aligned to the |
| data types used to access these buffers in a kernel(s), that SVM allocations |
| must correctly align and that pointers into SVM allocations must also be |
| correctly aligned. |
| The user is also responsible for ensuring image data passed is aligned to |
| the granularity of the data representing a single pixel (e.g. |
| <code>image_num_channels * sizeof(image_channel_data_type)</code>) except for <a href="#CL_RGB"><code>CL_RGB</code></a> |
| and <a href="#CL_RGBx"><code>CL_RGBx</code></a> images where the data must be aligned to the granularity of a |
| single channel in a pixel (i.e. <code>sizeof(image_channel_data_type)</code>). |
| This implies that OpenCL images created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_MEM_<wbr>USE_<wbr>HOST_<wbr>PTR</code></a> must align |
| correctly. |
| The image alignment value can be queried using the |
| <a href="#CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>BASE_<wbr>ADDRESS_<wbr>ALIGNMENT</code></a> query. |
| In addition, source pointers for <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> and other operations |
| that copy to the OpenCL runtime, as well as destination pointers for |
| <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and other operations that copy from the OpenCL runtime |
| must follow the same alignment rules.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL makes no requirement about the alignment of OpenCL application |
| defined data types outside of buffers and images, except that the underlying |
| vector primitives (e.g. <code>__cl_float4</code>) where defined shall be directly |
| accessible as such using appropriate named fields in the cl_type union (see |
| <a href="#vector-components">Vector Components</a>. |
| Nevertheless, it is recommended that the <strong>cl_platform.h</strong> header should |
| attempt to naturally align OpenCL defined application data types (e.g. |
| <code>cl_float4</code>) according to their type.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_vector_literals"><a class="anchor" href="#_vector_literals"></a>Vector Literals</h3> |
| <div class="paragraph"> |
| <p>Application vector literals may be used in assignments of individual vector |
| components. |
| Literal usage follows the convention of the underlying application compiler.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">cl_float2 foo = { .s[<span class="integer">1</span>] = <span class="float">2</span><span class="float">.0f</span> }; |
| cl_int8 bar = {{ <span class="integer">2</span>, <span class="integer">4</span>, <span class="integer">6</span>, <span class="integer">8</span>, <span class="integer">10</span>, <span class="integer">12</span>, <span class="integer">14</span>, <span class="integer">16</span> }};</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="vector-components"><a class="anchor" href="#vector-components"></a>Vector Components</h3> |
| <div class="paragraph"> |
| <p>The components of application vector types can be addressed using the |
| <code><vector_name>.s[<index>]</code> notation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">foo.s[<span class="integer">0</span>] = <span class="float">1</span><span class="float">.0f</span>; <span class="comment">// Sets the 1st vector component of foo</span> |
| pos.s[<span class="integer">6</span>] = <span class="integer">2</span>; <span class="comment">// Sets the 7th vector component of bar</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In some cases vector components may also be accessed using the following |
| notations. |
| These notations are not guaranteed to be supported on all implementations, |
| so their use should be accompanied by a check of the corresponding |
| preprocessor symbol.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_named_vector_components_notation"><a class="anchor" href="#_named_vector_components_notation"></a>Named vector components notation</h4> |
| <div class="paragraph"> |
| <p>Vector data type components may be accessed using the <code>.sN</code>, <code>.sn</code> or |
| <code>.xyzw</code> field naming convention, similar to how they are used within the |
| OpenCL C language. |
| Use of the <code>.xyzw</code> field naming convention only allows accessing of the |
| first 4 component fields. |
| Support of these notations is identified by the <code>CL_HAS_NAMED_VECTOR_FIELDS</code> |
| preprocessor symbol. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#ifdef</span> CL_HAS_NAMED_VECTOR_FIELDS |
| cl_float4 foo; |
| cl_int16 bar; |
| foo.x = <span class="float">1</span><span class="float">.0f</span>; <span class="comment">// Set first component</span> |
| foo.s0 = <span class="float">1</span><span class="float">.0f</span>; <span class="comment">// Same as above</span> |
| bar.z = <span class="integer">3</span>; <span class="comment">// Set third component</span> |
| bar.se = <span class="integer">11</span>; <span class="comment">// Same as bar.s[0xe]</span> |
| bar.sD = <span class="integer">12</span>; <span class="comment">// Same as bar.s[0xd]</span> |
| <span class="preprocessor">#endif</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Vector data type components may also be accessed using the <code>.rgba</code> field |
| naming convention, similar to how they are used within the OpenCL C 3.0 |
| language. |
| Use of the <code>.rgba</code> field naming convention only allows accessing of the |
| first 4 component fields. |
| Support of these notations is identified by the <code>CL_HAS_NAMED_RGBA_VECTOR_FIELDS</code> |
| preprocessor symbol. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#ifdef</span> CL_HAS_NAMED_RGBA_VECTOR_FIELDS |
| cl_float4 foo; |
| cl_int16 bar; |
| foo.r = <span class="float">1</span><span class="float">.0f</span>; <span class="comment">// Set first component</span> |
| bar.b = <span class="integer">3</span>; <span class="comment">// Set third component</span> |
| <span class="preprocessor">#endif</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Unlike the OpenCL C language type usage of named vector fields, only one |
| component field may be accessed at a time. |
| This restriction prevents the ability to swizzle or replicate components as |
| is possible with the OpenCL C language types. |
| Attempting to access beyond the number of components for a type also results |
| in a failure.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c">foo.xy <span class="comment">// illegal - illegal field name combination</span> |
| bar.s1234 <span class="comment">// illegal - illegal field name combination</span> |
| foo.s7 <span class="comment">// illegal - no component s7</span></code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_highlow_vector_component_notation"><a class="anchor" href="#_highlow_vector_component_notation"></a>High/Low vector component notation</h4> |
| <div class="paragraph"> |
| <p>Vector data type components may be accessed using the <code>.hi</code> and <code>.lo</code> |
| notation similar to that supported within the language types. |
| Support of this notation is identified by the <code>CL_HAS_HI_LO_VECTOR_FIELDS</code> |
| preprocessor symbol. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#ifdef</span> CL_HAS_HI_LO_VECTOR_FIELDS |
| cl_float4 foo; |
| cl_float2 new_hi = <span class="float">2</span><span class="float">.0f</span>, new_lo = <span class="float">4</span><span class="float">.0f</span>; |
| foo.hi = new_hi; |
| foo.lo = new_lo; |
| <span class="preprocessor">#endif</span></code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_native_vector_type_notation"><a class="anchor" href="#_native_vector_type_notation"></a>Native vector type notation</h4> |
| <div class="paragraph"> |
| <p>Certain native vector types are defined for providing a mapping of vector |
| types to architecturally built-in vector types. |
| Unlike the above described application vector types, these native types are |
| supported on a limited basis depending on the supporting architecture and |
| compiler.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These types are not unions, but rather convenience mappings to the |
| underlying architectures' built-in vector types. |
| The native types share the name of their application counterparts but are |
| preceded by a double underscore "__".</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, <code>__cl_float4</code> is the native built-in vector type equivalent of |
| the <code>cl_float4</code> application vector type. |
| The <code>__cl_float4</code> type may provide direct access to the architectural |
| built-in <code>__m128</code> or vector float type, whereas the <code>cl_float4</code> is treated |
| as a union.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition, the above described application data types may have native |
| vector data type members for access convenience. |
| The native components are accessed using the <code>.vN</code> sub-vector notation, |
| where <code>N</code> is the number of elements in the sub-vector. |
| In cases where the native type is a subset of a larger type (more |
| components), the notation becomes an index based array of the sub-vector |
| type.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Support of the native vector types is identified by a <code>__CL_TYPEN__</code> |
| preprocessor symbol matching the native type name. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#ifdef</span> __CL_FLOAT4__ <span class="comment">// Check for native cl_float4 type</span> |
| cl_float8 foo; |
| __cl_float4 bar; <span class="comment">// Use of native type</span> |
| bar = foo.v4[<span class="integer">1</span>]; <span class="comment">// Access the second native float4 vector</span> |
| <span class="preprocessor">#endif</span></code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_implicit_conversions"><a class="anchor" href="#_implicit_conversions"></a>Implicit Conversions</h3> |
| <div class="paragraph"> |
| <p>Implicit conversions between application vector types are not supported.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_explicit_casts"><a class="anchor" href="#_explicit_casts"></a>Explicit Casts</h3> |
| <div class="paragraph"> |
| <p>Explicit casting of application vector types (<code>cl_typen</code>) is not supported. |
| Explicit casting of native vector types (<code>__cl_typen</code>) is defined by the |
| external compiler.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_other_operators_and_functions"><a class="anchor" href="#_other_operators_and_functions"></a>Other operators and functions</h3> |
| <div class="paragraph"> |
| <p>The behavior of standard operators and function on both application vector |
| types (<code>cl_typen</code>) and native vector types (<code>__cl_typen</code>) is defined by |
| the external compiler.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_application_constant_definitions"><a class="anchor" href="#_application_constant_definitions"></a>Application constant definitions</h3> |
| <div class="paragraph"> |
| <p>In addition to the above application type definitions, the following literal |
| definitions are also available.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><a id="CL_CHAR_BIT"></a><a href="#CL_CHAR_BIT"><code>CL_CHAR_<wbr>BIT</code></a></th> |
| <th class="tableblock halign-left valign-top">Bit width of a character</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SCHAR_MAX"></a><a href="#CL_SCHAR_MAX"><code>CL_SCHAR_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_char</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SCHAR_MIN"></a><a href="#CL_SCHAR_MIN"><code>CL_SCHAR_<wbr>MIN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of a type <code>cl_char</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CHAR_MAX"></a><a href="#CL_CHAR_MAX"><code>CL_CHAR_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_char</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CHAR_MIN"></a><a href="#CL_CHAR_MIN"><code>CL_CHAR_<wbr>MIN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of a type <code>cl_char</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UCHAR_MAX"></a><a href="#CL_UCHAR_MAX"><code>CL_UCHAR_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_uchar</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SHRT_MAX"></a><a href="#CL_SHRT_MAX"><code>CL_SHRT_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_short</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SHRT_MIN"></a><a href="#CL_SHRT_MIN"><code>CL_SHRT_<wbr>MIN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of a type <code>cl_short</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_USHRT_MAX"></a><a href="#CL_USHRT_MAX"><code>CL_USHRT_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_ushort</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INT_MAX"></a><a href="#CL_INT_MAX"><code>CL_INT_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_int</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INT_MIN"></a><a href="#CL_INT_MIN"><code>CL_INT_<wbr>MIN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of a type <code>cl_int</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UINT_MAX"></a><a href="#CL_UINT_MAX"><code>CL_UINT_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_uint</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_LONG_MAX"></a><a href="#CL_LONG_MAX"><code>CL_LONG_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_long</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_LONG_MIN"></a><a href="#CL_LONG_MIN"><code>CL_LONG_<wbr>MIN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of a type <code>cl_long</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_ULONG_MAX"></a><a href="#CL_ULONG_MAX"><code>CL_ULONG_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a type <code>cl_ulong</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_DIG"></a><a href="#CL_FLT_DIG"><code>CL_FLT_<wbr>DIG</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Number of decimal digits of precision for the type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MANT_DIG"></a><a href="#CL_FLT_MANT_DIG"><code>CL_FLT_<wbr>MANT_<wbr>DIG</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Number of digits in the mantissa of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MAX_10_EXP"></a><a href="#CL_FLT_MAX_10_EXP"><code>CL_FLT_<wbr>MAX_<wbr>10_<wbr>EXP</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum positive integer such that 10 raised to this power minus one can |
| be represented as a normalized floating-point number of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MAX_EXP"></a><a href="#CL_FLT_MAX_EXP"><code>CL_FLT_<wbr>MAX_<wbr>EXP</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum exponent value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MIN_10_EXP"></a><a href="#CL_FLT_MIN_10_EXP"><code>CL_FLT_<wbr>MIN_<wbr>10_<wbr>EXP</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum negative integer such that 10 raised to this power minus one can |
| be represented as a normalized floating-point number of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MIN_EXP"></a><a href="#CL_FLT_MIN_EXP"><code>CL_FLT_<wbr>MIN_<wbr>EXP</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum exponent value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_RADIX"></a><a href="#CL_FLT_RADIX"><code>CL_FLT_<wbr>RADIX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Base value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MAX"></a><a href="#CL_FLT_MAX"><code>CL_FLT_<wbr>MAX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_MIN"></a><a href="#CL_FLT_MIN"><code>CL_FLT_<wbr>MIN</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLT_EPSILON"></a><a href="#CL_FLT_EPSILON"><code>CL_FLT_<wbr>EPSILON</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum positive floating-point number of type <code>cl_float</code> such that <code>1.0 |
| + <a href="#CL_FLT_EPSILON"><code>CL_FLT_<wbr>EPSILON</code></a> != 1</code> is true.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_DIG"></a><a href="#CL_DBL_DIG"><code>CL_DBL_<wbr>DIG</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Number of decimal digits of precision for the type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MANT_DIG"></a><a href="#CL_DBL_MANT_DIG"><code>CL_DBL_<wbr>MANT_<wbr>DIG</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Number of digits in the mantissa of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MAX_10_EXP"></a><a href="#CL_DBL_MAX_10_EXP"><code>CL_DBL_<wbr>MAX_<wbr>10_<wbr>EXP</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum positive integer such that 10 raised to this power minus one can |
| be represented as a normalized floating-point number of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MAX_EXP"></a><a href="#CL_DBL_MAX_EXP"><code>CL_DBL_<wbr>MAX_<wbr>EXP</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum exponent value of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MIN_10_EXP"></a><a href="#CL_DBL_MIN_10_EXP"><code>CL_DBL_<wbr>MIN_<wbr>10_<wbr>EXP</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum negative integer such that 10 raised to this power minus one can |
| be represented as a normalized floating-point number of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MIN_EXP"></a><a href="#CL_DBL_MIN_EXP"><code>CL_DBL_<wbr>MIN_<wbr>EXP</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum exponent value of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_RADIX"></a><a href="#CL_DBL_RADIX"><code>CL_DBL_<wbr>RADIX</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Base value of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MAX"></a><a href="#CL_DBL_MAX"><code>CL_DBL_<wbr>MAX</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_MIN"></a><a href="#CL_DBL_MIN"><code>CL_DBL_<wbr>MIN</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DBL_EPSILON"></a><a href="#CL_DBL_EPSILON"><code>CL_DBL_<wbr>EPSILON</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2. |
| Also see extension <strong>cl_khr_fp64</strong>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum positive floating-point number of type <code>cl_double</code> such that |
| <code>1.0 + <a href="#CL_DBL_EPSILON"><code>CL_DBL_<wbr>EPSILON</code></a> != 1</code> is true.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_NAN"></a><a href="#CL_NAN"><code>CL_NAN</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Macro expanding to a value representing NaN</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_HUGE_VALF"></a><a href="#CL_HUGE_VALF"><code>CL_HUGE_<wbr>VALF</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Largest representative value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_HUGE_VAL"></a><a href="#CL_HUGE_VAL"><code>CL_HUGE_<wbr>VAL</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Largest representative value of type <code>cl_double</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAXFLOAT"></a><a href="#CL_MAXFLOAT"><code>CL_MAXFLOAT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of type <code>cl_float</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INFINITY"></a><a href="#CL_INFINITY"><code>CL_INFINITY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Macro expanding to a value representing infinity</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>These literal definitions are defined in the <strong>cl_platform.h</strong> header.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="check-copy-overlap"><a class="anchor" href="#check-copy-overlap"></a>Appendix D: Checking for Memory Copy Overlap</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The following code describes how to determine if there is overlap between |
| the source and destination rectangles specified to <a href="#clEnqueueCopyBufferRect"><strong>clEnqueueCopyBufferRect</strong></a> |
| provided the source and destination buffers refer to the same buffer object.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="c"><span class="predefined-type">unsigned</span> <span class="predefined-type">int</span> |
| check_copy_overlap(<span class="directive">const</span> size_t src_origin[], |
| <span class="directive">const</span> size_t dst_origin[], |
| <span class="directive">const</span> size_t region[], |
| <span class="directive">const</span> size_t row_pitch, |
| <span class="directive">const</span> size_t slice_pitch ) |
| { |
| <span class="directive">const</span> size_t slice_size = (region[<span class="integer">1</span>] - <span class="integer">1</span>) * row_pitch + region[<span class="integer">0</span>]; |
| <span class="directive">const</span> size_t block_size = (region[<span class="integer">2</span>] - <span class="integer">1</span>) * slice_pitch + slice_size; |
| <span class="directive">const</span> size_t src_start = src_origin[<span class="integer">2</span>] * slice_pitch |
| + src_origin[<span class="integer">1</span>] * row_pitch |
| + src_origin[<span class="integer">0</span>]; |
| <span class="directive">const</span> size_t src_end = src_start + block_size; |
| <span class="directive">const</span> size_t dst_start = dst_origin[<span class="integer">2</span>] * slice_pitch |
| + dst_origin[<span class="integer">1</span>] * row_pitch |
| + dst_origin[<span class="integer">0</span>]; |
| <span class="directive">const</span> size_t dst_end = dst_start + block_size; |
| |
| <span class="comment">/* No overlap if dst ends before src starts or if src ends |
| * before dst starts. |
| */</span> |
| <span class="keyword">if</span>( (dst_end <= src_start) || (src_end <= dst_start) ){ |
| <span class="keyword">return</span> <span class="integer">0</span>; |
| } |
| |
| <span class="comment">/* No overlap if region[0] for dst or src fits in the gap |
| * between region[0] and row_pitch. |
| */</span> |
| { |
| <span class="directive">const</span> size_t src_dx = src_origin[<span class="integer">0</span>] % row_pitch; |
| <span class="directive">const</span> size_t dst_dx = dst_origin[<span class="integer">0</span>] % row_pitch; |
| |
| <span class="keyword">if</span>( ((dst_dx >= src_dx + region[<span class="integer">0</span>]) && |
| (dst_dx + region[<span class="integer">0</span>] <= src_dx + row_pitch)) || |
| ((src_dx >= dst_dx + region[<span class="integer">0</span>]) && |
| (src_dx + region[<span class="integer">0</span>] <= dst_dx + row_pitch)) ) |
| { |
| <span class="keyword">return</span> <span class="integer">0</span>; |
| } |
| } |
| |
| <span class="comment">/* No overlap if region[1] for dst or src fits in the gap |
| * between region[1] and slice_pitch. |
| */</span> |
| { |
| <span class="directive">const</span> size_t src_dy = |
| (src_origin[<span class="integer">1</span>] * row_pitch + src_origin[<span class="integer">0</span>]) % slice_pitch; |
| <span class="directive">const</span> size_t dst_dy = |
| (dst_origin[<span class="integer">1</span>] * row_pitch + dst_origin[<span class="integer">0</span>]) % slice_pitch; |
| |
| <span class="keyword">if</span>( ((dst_dy >= src_dy + slice_size) && |
| (dst_dy + slice_size <= src_dy + slice_pitch)) || |
| ((src_dy >= dst_dy + slice_size) && |
| (src_dy + slice_size <= dst_dy + slice_pitch)) ) { |
| <span class="keyword">return</span> <span class="integer">0</span>; |
| } |
| } |
| |
| <span class="comment">/* Otherwise src and dst overlap. */</span> |
| <span class="keyword">return</span> <span class="integer">1</span>; |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="changes_to_opencl"><a class="anchor" href="#changes_to_opencl"></a>Appendix E: Changes to OpenCL</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Changes to the OpenCL API and OpenCL C between successive versions are |
| summarized below.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_changes_from_opencl_1_0_to_opencl_1_1"><a class="anchor" href="#_summary_of_changes_from_opencl_1_0_to_opencl_1_1"></a>Summary of changes from OpenCL 1.0 to OpenCL 1.1</h3> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL 1.1 platform layer and |
| runtime (<em>sections 4 and 5</em>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Following queries to <em>table 4.3</em></p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>CHAR</code></a>, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>SHORT</code></a>, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_INT"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>INT</code></a>, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>LONG</code></a>, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>FLOAT</code></a>, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>DOUBLE</code></a>, |
| <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"><code>CL_DEVICE_<wbr>NATIVE_<wbr>VECTOR_<wbr>WIDTH_<wbr>HALF</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_HOST_UNIFIED_MEMORY"><code>CL_DEVICE_<wbr>HOST_<wbr>UNIFIED_<wbr>MEMORY</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>VERSION</code></a></p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><a href="#CL_CONTEXT_NUM_DEVICES"><code>CL_CONTEXT_<wbr>NUM_<wbr>DEVICES</code></a> to the list of queries specified to |
| <a href="#clGetContextInfo"><strong>clGetContextInfo</strong></a>.</p> |
| </li> |
| <li> |
| <p>Optional image formats: <a href="#CL_Rx"><code>CL_Rx</code></a>, <a href="#CL_RGx"><code>CL_RGx</code></a>, and <a href="#CL_RGBx"><code>CL_RGBx</code></a>.</p> |
| </li> |
| <li> |
| <p>Support for sub-buffer objects ability to create a buffer object that |
| refers to a specific region in another buffer object using |
| <a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a>, <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> and |
| <a href="#clEnqueueCopyBufferRect"><strong>clEnqueueCopyBufferRect</strong></a> APIs to read from, write to and copy a |
| rectangular region of a buffer object respectively.</p> |
| </li> |
| <li> |
| <p><a href="#clSetMemObjectDestructorCallback"><strong>clSetMemObjectDestructorCallback</strong></a> API to allow a user to register a |
| callback function that will be called when the memory object is deleted |
| and its resources freed.</p> |
| </li> |
| <li> |
| <p>Options that <a href="#opencl-c-version">control the OpenCL C version</a> used |
| when building a program executable.</p> |
| </li> |
| <li> |
| <p><a href="#CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"><code>CL_KERNEL_<wbr>PREFERRED_<wbr>WORK_<wbr>GROUP_<wbr>SIZE_<wbr>MULTIPLE</code></a> to the list of queries |
| specified to <a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a>.</p> |
| </li> |
| <li> |
| <p>Support for user events. |
| User events allow applications to enqueue commands that wait on a user |
| event to finish before the command is executed by the device. |
| Following new APIs are added - <a href="#clCreateUserEvent"><strong>clCreateUserEvent</strong></a> and |
| <a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#clSetEventCallback"><strong>clSetEventCallback</strong></a> API to register a callback function for a specific |
| command execution status.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following modifications are made to the OpenCL 1.1 platform layer and |
| runtime (<em>sections 4 and 5</em>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Following queries in <em>table 4.3</em></p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The minimum FULL_PROFILE value for <a href="#CL_DEVICE_MAX_PARAMETER_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>PARAMETER_<wbr>SIZE</code></a> |
| increased from 256 to 1024 bytes</p> |
| </li> |
| <li> |
| <p>The minimum FULL_PROFILE value for <a href="#CL_DEVICE_LOCAL_MEM_SIZE"><code>CL_DEVICE_<wbr>LOCAL_<wbr>MEM_<wbr>SIZE</code></a> increased |
| from 16 KB to 32 KB.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>The <em>global_work_offset</em> argument in <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> can be a |
| non-<code>NULL</code> value.</p> |
| </li> |
| <li> |
| <p>All API calls except <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a> are thread-safe.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL C programming language |
| (<em>section 6</em>) in OpenCL 1.1:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>3-component vector data types.</p> |
| </li> |
| <li> |
| <p>New built-in functions</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>get_global_offset</strong> work-item function defined in section <em>6.15.1</em>.</p> |
| </li> |
| <li> |
| <p><strong>minmag</strong>, <strong>maxmag</strong> math functions defined in section <em>6.15.2</em>.</p> |
| </li> |
| <li> |
| <p><strong>clamp</strong> integer function defined in <em>section 6.15.3</em>.</p> |
| </li> |
| <li> |
| <p>(vector, scalar) variant of integer functions <strong>min</strong> and <strong>max</strong> in |
| <em>section 6.12.3</em>.</p> |
| </li> |
| <li> |
| <p><strong>async_work_group_strided_copy</strong> defined in section <em>6.15.11</em>.</p> |
| </li> |
| <li> |
| <p><strong>vec_step</strong>, <strong>shuffle</strong> and <strong>shuffle2</strong> defined in section <em>6.15.13</em>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><strong>cl_khr_byte_addressable_store</strong> extension is a core feature.</p> |
| </li> |
| <li> |
| <p><strong>cl_khr_global_int32_base_atomics</strong>, |
| <strong>cl_khr_global_int32_extended_atomics</strong>, |
| <strong>cl_khr_local_int32_base_atomics</strong> and |
| <strong>cl_khr_local_int32_extended_atomics</strong> extensions are core features. |
| The built-in atomic function names are changed to use the <strong>atomic_</strong> |
| prefix instead of <strong>atom_</strong>.</p> |
| </li> |
| <li> |
| <p>Macros <code>CL_VERSION_1_0</code> and <code>CL_VERSION_1_1</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following features in OpenCL 1.0 are deprecated (see glossary) in OpenCL |
| 1.1:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <a href="#clSetCommandQueueProperty"><strong>clSetCommandQueueProperty</strong></a> API is deprecated, which simplifies |
| implementations and possibly improves performance by enforcing that |
| command queue properties are invariant. |
| Applications are encouraged to create multiple command queues with |
| different properties versus modifying the properties of a single |
| command queue.</p> |
| </li> |
| <li> |
| <p>The <code>-cl-strict-aliasing</code> build option has been deprecated. |
| It is no longer required after defining type-based aliasing rules.</p> |
| </li> |
| <li> |
| <p>The <strong>cl_khr_select_fprounding_mode</strong> extension is deprecated and its |
| use is no longer recommended.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following new extensions are added to <em>section 9</em> in OpenCL 1.1:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>cl_khr_gl_event</strong> for creating a CL event object from a GL sync object.</p> |
| </li> |
| <li> |
| <p><strong>cl_khr_d3d10_sharing</strong> for sharing memory objects with Direct3D 10.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following modifications are made to the OpenCL ES Profile described in |
| <em>section 10</em> in OpenCL 1.1:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>64-bit integer support is optional.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_changes_from_opencl_1_1_to_opencl_1_2"><a class="anchor" href="#_summary_of_changes_from_opencl_1_1_to_opencl_1_2"></a>Summary of changes from OpenCL 1.1 to OpenCL 1.2</h3> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL 1.2 platform layer and |
| runtime (<em>sections 4 and 5</em>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Custom devices and built-in kernels are supported. |
| <a href="#clCreateProgramWithBuiltInKernels"><strong>clCreateProgramWithBuiltInKernels</strong></a> has been added to allow creation of |
| a <code>cl_program</code> using built-in kernels.</p> |
| </li> |
| <li> |
| <p>Device partitioning that allows a device to be partitioned based on a |
| number of partitioning schemes supported by the device. This is done by |
| using <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> to create a new <code>cl_device_<wbr>id</code> based on a |
| partitioning.</p> |
| </li> |
| <li> |
| <p><a href="#clCompileProgram"><strong>clCompileProgram</strong></a> and <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> to allow handling these aspects |
| <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> separately.</p> |
| </li> |
| <li> |
| <p>Extend <code>cl_mem_<wbr>flags</code> to describe how the host accesses the data in a |
| <code>cl_mem</code> object.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a> and <a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a> to support filling a |
| buffer with a pattern or an image with a color.</p> |
| </li> |
| <li> |
| <p>Add <a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_MAP_<wbr>WRITE_<wbr>INVALIDATE_<wbr>REGION</code></a> to <code>cl_map_<wbr>flags</code>. |
| Appropriate clarification to the behavior of <a href="#CL_MAP_WRITE"><code>CL_MAP_<wbr>WRITE</code></a> has been added |
| to the spec.</p> |
| </li> |
| <li> |
| <p>New image types: 1D image, 1D image from a buffer object, 1D image array |
| and 2D image arrays.</p> |
| </li> |
| <li> |
| <p><a href="#clCreateImage"><strong>clCreateImage</strong></a> to create an image object.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueMigrateMemObjects"><strong>clEnqueueMigrateMemObjects</strong></a> API that allows a developer to have |
| explicit control over the location of memory objects or to migrate a |
| memory object from one device to another.</p> |
| </li> |
| <li> |
| <p>Support separate compilation and linking of programs.</p> |
| </li> |
| <li> |
| <p>Additional queries to get the number of kernels and kernel names in a |
| program have been added to <a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a>.</p> |
| </li> |
| <li> |
| <p>Additional queries to get the compile and link status and options have |
| been added to <a href="#clGetProgramBuildInfo"><strong>clGetProgramBuildInfo</strong></a>.</p> |
| </li> |
| <li> |
| <p><a href="#clGetKernelArgInfo"><strong>clGetKernelArgInfo</strong></a> API that returns information about the arguments of |
| a kernel.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueMarkerWithWaitList"><strong>clEnqueueMarkerWithWaitList</strong></a> and <a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> APIs.</p> |
| </li> |
| <li> |
| <p><a href="#clUnloadPlatformCompiler"><strong>clUnloadPlatformCompiler</strong></a> to request that a single platform’s compiler is |
| unloaded. This is compatible with the <strong>cl_khr_icd</strong> extension if that is |
| supported, unlike <a href="#clUnloadCompiler"><strong>clUnloadCompiler</strong></a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL C programming language |
| (<em>section 6</em>) in OpenCL 1.2:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Double-precision is now an optional core feature instead of an |
| extension.</p> |
| </li> |
| <li> |
| <p>New built in image types: <strong>image1d_t</strong>, <strong>image1d_buffer_t</strong>, |
| <strong>image1d_array_t</strong>, and <strong>image2d_array_t</strong>.</p> |
| </li> |
| <li> |
| <p>New built-in functions</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Functions to read from and write to a 1D image, 1D and 2D image arrays |
| described in <em>sections 6.15.15.2</em>, <em>6.15.15.3</em> and <em>6.15.15.4</em>.</p> |
| </li> |
| <li> |
| <p>Sampler-less image read functions described in <em>section 6.15.15.3</em>.</p> |
| </li> |
| <li> |
| <p><strong>popcount</strong> integer function described in <em>section 6.15.3</em>.</p> |
| </li> |
| <li> |
| <p><strong>printf</strong> function described in <em>section 6.15.14</em>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Storage class specifiers extern and static as described in <em>section |
| 6.10</em>.</p> |
| </li> |
| <li> |
| <p>Macros <code>CL_VERSION_1_2</code> and <code>__OPENCL_C_VERSION__</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following APIs in OpenCL 1.1 are deprecated (see glossary) in OpenCL |
| 1.2:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <a href="#clEnqueueMarker"><strong>clEnqueueMarker</strong></a>, <a href="#clEnqueueBarrier"><strong>clEnqueueBarrier</strong></a> and <a href="#clEnqueueWaitForEvents"><strong>clEnqueueWaitForEvents</strong></a> |
| APIs are deprecated to simplify the API. |
| The <a href="#clEnqueueMarkerWithWaitList"><strong>clEnqueueMarkerWithWaitList</strong></a> and <a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> |
| APIs provide equivalent functionality and support explicit event |
| wait lists.</p> |
| </li> |
| <li> |
| <p>The <a href="#clCreateImage2D"><strong>clCreateImage2D</strong></a>, <a href="#clCreateImage3D"><strong>clCreateImage3D</strong></a>, <strong>clCreateFromGLTexture2D</strong> and |
| <strong>clCreateFromGLTexture3D</strong> APIs are deprecated to simplify the API. |
| The <a href="#clCreateImage"><strong>clCreateImage</strong></a> and <strong>clCreateFromGLTexture</strong> APIs provide equivalent |
| functionality and support additional image types and properties.</p> |
| </li> |
| <li> |
| <p><a href="#clUnloadCompiler"><strong>clUnloadCompiler</strong></a> and <a href="#clGetExtensionFunctionAddress"><strong>clGetExtensionFunctionAddress</strong></a> APIs are deprecated. |
| The <a href="#clUnloadPlatformCompiler"><strong>clUnloadPlatformCompiler</strong></a> and <a href="#clGetExtensionFunctionAddressForPlatform"><strong>clGetExtensionFunctionAddressForPlatform</strong></a> |
| APIs provide equivalent functionality are compatible with the <strong>cl_khr_icd</strong> |
| extension.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following queries are deprecated (see glossary) in OpenCL 1.2:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <a href="#CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE"><code>CL_DEVICE_<wbr>MIN_<wbr>DATA_<wbr>TYPE_<wbr>ALIGN_<wbr>SIZE</code></a> query is deprecated. |
| The minimum data type alignment can be derived from |
| <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a>.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_changes_from_opencl_1_2_to_opencl_2_0"><a class="anchor" href="#_summary_of_changes_from_opencl_1_2_to_opencl_2_0"></a>Summary of changes from OpenCL 1.2 to OpenCL 2.0</h3> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL 2.0 platform layer and |
| runtime (<em>sections 4 and 5</em>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Shared virtual memory. The associated API additions are:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a> to control which shared virtual memory (SVM) |
| pointer to associate with a kernel instance.</p> |
| </li> |
| <li> |
| <p><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>, <a href="#clSVMFree"><strong>clSVMFree</strong></a> and <a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a> to allocate and free |
| memory for use with SVM.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a> and <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a> to map and unmap to update |
| regions of an SVM buffer from host.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a> and <a href="#clEnqueueSVMMemFill"><strong>clEnqueueSVMMemFill</strong></a> to copy or fill SVM memory |
| regions.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Device queues used to enqueue kernels on the device.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> is added to allow creation of a |
| command queue with properties that affect both host command queues and |
| device queues.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Pipes.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clCreatePipe"><strong>clCreatePipe</strong></a> and <a href="#clGetPipeInfo"><strong>clGetPipeInfo</strong></a> have been added to the API for host |
| side creation and querying of pipes.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Images support for 2D image from buffer, depth images and sRGB images.</p> |
| </li> |
| <li> |
| <p><a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following modifications are made to the OpenCL 2.0 platform layer and |
| runtime (sections 4 and 5):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All API calls except <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>, <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a> and |
| <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> are thread-safe. |
| Note that this statement does not imply that other API calls were not |
| thread-safe in earlier versions of the specification.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL C programming language |
| (<em>section 6</em>) in OpenCL 2.0:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Clang Blocks.</p> |
| </li> |
| <li> |
| <p>Kernels enqueuing kernels to a device queue.</p> |
| </li> |
| <li> |
| <p>Program scope variables in global address space.</p> |
| </li> |
| <li> |
| <p>Generic address space.</p> |
| </li> |
| <li> |
| <p>C1x atomics.</p> |
| </li> |
| <li> |
| <p>New built-in functions (sections 6.15.10, 6.15.12, and 6.15.16).</p> |
| </li> |
| <li> |
| <p>Support images with the read_write qualifier.</p> |
| </li> |
| <li> |
| <p>3D image writes are a core feature.</p> |
| </li> |
| <li> |
| <p>The <code>CL_VERSION_2_0</code> and <code>NULL</code> macros.</p> |
| </li> |
| <li> |
| <p>The <code>opencl_unroll_hint</code> attribute.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following APIs are deprecated (see glossary) in OpenCL 2.0:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <a href="#clCreateCommandQueue"><strong>clCreateCommandQueue</strong></a> API has been deprecated to simplify |
| the API. |
| The <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> API provides equivalent |
| functionality and supports specifying additional command queue |
| properties.</p> |
| </li> |
| <li> |
| <p>The <a href="#clCreateSampler"><strong>clCreateSampler</strong></a> API has been deprecated to simplify the |
| API. |
| The <a href="#clCreateSamplerWithProperties"><strong>clCreateSamplerWithProperties</strong></a> API provides equivalent |
| functionality and supports specifying additional sampler |
| properties.</p> |
| </li> |
| <li> |
| <p>The <a href="#clEnqueueTask"><strong>clEnqueueTask</strong></a> API has been deprecated to simplify the API. |
| The <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> API provides equivalent functionality.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following queries are deprecated (see glossary) in OpenCL 2.0:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <a href="#CL_DEVICE_HOST_UNIFIED_MEMORY"><code>CL_DEVICE_<wbr>HOST_<wbr>UNIFIED_<wbr>MEMORY</code></a> query is deprecated. |
| This query was purely informational and had different meanings |
| for different implementations. |
| Its use is no longer recommended.</p> |
| </li> |
| <li> |
| <p>The <a href="#CL_IMAGE_BUFFER"><code>CL_IMAGE_<wbr>BUFFER</code></a> query has been deprecated to simplify the API. |
| The <a href="#CL_MEM_ASSOCIATED_MEMOBJECT"><code>CL_MEM_<wbr>ASSOCIATED_<wbr>MEMOBJECT</code></a> query provides equivalent |
| functionality.</p> |
| </li> |
| <li> |
| <p>The <a href="#CL_DEVICE_QUEUE_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>PROPERTIES</code></a> query has been deprecated and |
| replaced by <a href="#CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>HOST_<wbr>PROPERTIES</code></a>.</p> |
| </li> |
| <li> |
| <p>Atomics and Fences</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The Explicit Memory Fence Functions defined in section 6.12.9 of the |
| OpenCL 1.2 specification have been deprecated to simplify the |
| programming language. |
| The <strong>atomic_work_item_fence</strong> function provides equivalent |
| functionality. |
| The deprecated functions are still described in section 6.15.9 of this |
| specification.</p> |
| </li> |
| <li> |
| <p>The Atomic Functions defined in section 6.12.11 of the OpenCL 1.2 |
| specification have been deprecated to simplify the programming |
| language. |
| The <strong>atomic_fetch</strong> and modify functions provide equivalent |
| functionality. |
| The deprecated functions are still described in section 6.15.12.8 of this |
| specification.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_changes_from_opencl_2_0_to_opencl_2_1"><a class="anchor" href="#_summary_of_changes_from_opencl_2_0_to_opencl_2_1"></a>Summary of changes from OpenCL 2.0 to OpenCL 2.1</h3> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL 2.1 platform layer and |
| runtime (<em>sections 4 and 5</em>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a> API call.</p> |
| </li> |
| <li> |
| <p><a href="#CL_KERNEL_MAX_NUM_SUB_GROUPS"><code>CL_KERNEL_<wbr>MAX_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a>, <a href="#CL_KERNEL_COMPILE_NUM_SUB_GROUPS"><code>CL_KERNEL_<wbr>COMPILE_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a> |
| additions to table 5.21 of the API specification.</p> |
| </li> |
| <li> |
| <p><a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> API call.</p> |
| </li> |
| <li> |
| <p><a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> and <a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> API calls.</p> |
| </li> |
| <li> |
| <p><a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a> API call.</p> |
| </li> |
| <li> |
| <p><a href="#clCloneKernel"><strong>clCloneKernel</strong></a> API call.</p> |
| </li> |
| <li> |
| <p><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a> API call.</p> |
| </li> |
| <li> |
| <p><a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_PLATFORM_<wbr>HOST_<wbr>TIMER_<wbr>RESOLUTION</code></a> added to table 4.1 of the API |
| specification.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_IL_VERSION"><code>CL_DEVICE_<wbr>IL_<wbr>VERSION</code></a>, <a href="#CL_DEVICE_MAX_NUM_SUB_GROUPS"><code>CL_DEVICE_<wbr>MAX_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a>, |
| <a href="#CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"><code>CL_DEVICE_<wbr>SUB_<wbr>GROUP_<wbr>INDEPENDENT_<wbr>FORWARD_<wbr>PROGRESS</code></a> added to table 4.3 of |
| the API specification.</p> |
| </li> |
| <li> |
| <p><a href="#CL_PROGRAM_IL"><code>CL_PROGRAM_<wbr>IL</code></a> to table 5.17 of the API specification.</p> |
| </li> |
| <li> |
| <p><a href="#CL_QUEUE_DEVICE_DEFAULT"><code>CL_QUEUE_<wbr>DEVICE_<wbr>DEFAULT</code></a> added to table 5.2 of the API specification.</p> |
| </li> |
| <li> |
| <p>Added table 5.22 to the API specification with the enums: |
| <a href="#CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE"><code>CL_KERNEL_<wbr>MAX_<wbr>SUB_<wbr>GROUP_<wbr>SIZE_<wbr>FOR_<wbr>NDRANGE</code></a>, |
| <a href="#CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE"><code>CL_KERNEL_<wbr>SUB_<wbr>GROUP_<wbr>COUNT_<wbr>FOR_<wbr>NDRANGE</code></a> and |
| <a href="#CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT"><code>CL_KERNEL_<wbr>LOCAL_<wbr>SIZE_<wbr>FOR_<wbr>SUB_<wbr>GROUP_<wbr>COUNT</code></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following modifications are made to the OpenCL 2.1 platform layer and |
| runtime (sections 4 and 5):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All API calls except <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a>, <a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a>, |
| <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a> and <a href="#clCloneKernel"><strong>clCloneKernel</strong></a> are thread-safe. |
| Note that this statement does not imply that other API calls were not |
| thread-safe in earlier versions of the specification.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the OpenCL C kernel language is not updated for OpenCL 2.1. |
| The OpenCL 2.0 kernel language will still be consumed by OpenCL 2.1 |
| runtimes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The SPIR-V and OpenCL SPIR-V Environment specifications have been added.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_changes_from_opencl_2_1_to_opencl_2_2"><a class="anchor" href="#_summary_of_changes_from_opencl_2_1_to_opencl_2_2"></a>Summary of changes from OpenCL 2.1 to OpenCL 2.2</h3> |
| <div class="paragraph"> |
| <p>The following changes have been made to the OpenCL 2.2 execution model |
| (section 3)</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Added the third prerequisite (executing non-trivial constructors for |
| program scope global variables).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following features are added to the OpenCL 2.2 platform layer and |
| runtime (<em>sections 4 and 5</em>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clSetProgramSpecializationConstant"><strong>clSetProgramSpecializationConstant</strong></a> API call</p> |
| </li> |
| <li> |
| <p><a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a> API call</p> |
| </li> |
| <li> |
| <p>Queries for <a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a> and |
| <a href="#CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>DTORS_<wbr>PRESENT</code></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following modifications are made to the OpenCL 2.2 platform layer and |
| runtime (section 4 and 5):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Modified description of <a href="#CL_DEVICE_MAX_CLOCK_FREQUENCY"><code>CL_DEVICE_<wbr>MAX_<wbr>CLOCK_<wbr>FREQUENCY</code></a> query.</p> |
| </li> |
| <li> |
| <p>Added a new error code <a href="#CL_MAX_SIZE_RESTRICTION_EXCEEDED"><code>CL_MAX_<wbr>SIZE_<wbr>RESTRICTION_<wbr>EXCEEDED</code></a> to |
| <a href="#clSetKernelArg"><strong>clSetKernelArg</strong></a> API call</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Added definition of Deprecation and Specialization constants to the |
| glossary.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_changes_from_opencl_2_2_to_opencl_3_0"><a class="anchor" href="#_summary_of_changes_from_opencl_2_2_to_opencl_3_0"></a>Summary of changes from OpenCL 2.2 to OpenCL 3.0</h3> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 is a major revision that breaks backwards compatibility with |
| previous versions of OpenCL, see |
| <a href="#opencl-3.0-backwards-compatibility">OpenCL 3.0 Backwards Compatibility</a> |
| for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds new queries to determine optional capabilities for a |
| device:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>MEMORY_<wbr>CAPABILITIES</code></a> and |
| <a href="#CL_DEVICE_ATOMIC_FENCE_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>FENCE_<wbr>CAPABILITIES</code></a> to determine the |
| atomic memory and atomic fence capabilities of a device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_NON_UNIFORM_WORK_GROUP_SUPPORT"><code>CL_DEVICE_<wbr>NON_<wbr>UNIFORM_<wbr>WORK_<wbr>GROUP_<wbr>SUPPORT</code></a> to |
| determine if a device supports non-uniform work-group sizes.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_WORK_GROUP_COLLECTIVE_FUNCTIONS_SUPPORT"><code>CL_DEVICE_<wbr>WORK_<wbr>GROUP_<wbr>COLLECTIVE_<wbr>FUNCTIONS_<wbr>SUPPORT</code></a> |
| to determine whether a device supports optional work-group |
| collective functions, such as broadcasts, scans, and reductions.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT"><code>CL_DEVICE_<wbr>GENERIC_<wbr>ADDRESS_<wbr>SPACE_<wbr>SUPPORT</code></a> to |
| determine whether a device supports the generic address space.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_DEVICE_ENQUEUE_CAPABILITIES"><code>CL_DEVICE_<wbr>DEVICE_<wbr>ENQUEUE_<wbr>CAPABILITIES</code></a> to determine the device-side enqueue |
| capabilities of a device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_PIPE_SUPPORT"><code>CL_DEVICE_<wbr>PIPE_<wbr>SUPPORT</code></a> to determine whether a device supports |
| pipe memory objects.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_PREFERRED_WORK_GROUP_SIZE_MULTIPLE"><code>CL_DEVICE_<wbr>PREFERRED_<wbr>WORK_<wbr>GROUP_<wbr>SIZE_<wbr>MULTIPLE</code></a> to determine the |
| the preferred work-group size multiple for a device.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds new queries to conveniently and precisely |
| describe supported features and versions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_PLATFORM_NUMERIC_VERSION"><code>CL_PLATFORM_<wbr>NUMERIC_<wbr>VERSION</code></a> to describe the platform |
| version as a numeric value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_PLATFORM_EXTENSIONS_WITH_VERSION"><code>CL_PLATFORM_<wbr>EXTENSIONS_<wbr>WITH_<wbr>VERSION</code></a> to describe supported |
| platform extensions and their supported version.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_NUMERIC_VERSION"><code>CL_DEVICE_<wbr>NUMERIC_<wbr>VERSION</code></a> to describe the device version |
| as a numeric value.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_EXTENSIONS_WITH_VERSION"><code>CL_DEVICE_<wbr>EXTENSIONS_<wbr>WITH_<wbr>VERSION</code></a> to describe supported |
| device extensions and their supported version.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_ILS_WITH_VERSION"><code>CL_DEVICE_<wbr>ILS_<wbr>WITH_<wbr>VERSION</code></a> to describe supported |
| intermediate languages (ILs) and their supported version.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION"><code>CL_DEVICE_<wbr>BUILT_<wbr>IN_<wbr>KERNELS_<wbr>WITH_<wbr>VERSION</code></a> to describe supported |
| built-in kernels and their supported version.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds a new API to register a function that will be called |
| when a context is destroyed, enabling an application to safely free |
| user data associated with a context callback function.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clSetContextDestructorCallback"><strong>clSetContextDestructorCallback</strong></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds two new APIs to support creating buffer and image |
| memory objects with additional properties. |
| Although no new properties are added in OpenCL 3.0, these APIs enable |
| new buffer and image extensions to be added easily and consistently:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#clCreateBufferWithProperties"><strong>clCreateBufferWithProperties</strong></a></p> |
| </li> |
| <li> |
| <p><a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds new queries for the properties arrays specified |
| when creating buffers, images, pipes, samplers, and command queues:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_MEM_PROPERTIES"><code>CL_MEM_<wbr>PROPERTIES</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_PIPE_PROPERTIES"><code>CL_PIPE_<wbr>PROPERTIES</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_SAMPLER_PROPERTIES"><code>CL_SAMPLER_<wbr>PROPERTIES</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_QUEUE_PROPERTIES_ARRAY"><code>CL_QUEUE_<wbr>PROPERTIES_<wbr>ARRAY</code></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Program initialization and clean-up kernels are not supported in OpenCL |
| 3.0 due to implementation complexity and lack of demand. |
| The following APIs and queries for program initialization and clean-up |
| kernels are deprecated in OpenCL 3.0:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a></p> |
| </li> |
| <li> |
| <p><a href="#CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>DTORS_<wbr>PRESENT</code></a></p> |
| </li> |
| <li> |
| <p><a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds the OpenCL 3.0 C kernel language, which includes |
| feature macros to describe OpenCL C language support. |
| Please refer to the OpenCL C specification for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Scalar input arguments to the <strong>any</strong> and <strong>all</strong> built-in functions have |
| been deprecated in the OpenCL 3.0 C kernel language. |
| These functions behaved inconsistently with the C language’s use of |
| scalar integers as logical values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds new queries to determine supported OpenCL C language |
| versions and supported OpenCL C features:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_DEVICE_OPENCL_C_ALL_VERSIONS"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>ALL_<wbr>VERSIONS</code></a> to determine the set |
| of OpenCL C language versions supported by a device.</p> |
| </li> |
| <li> |
| <p><a href="#CL_DEVICE_OPENCL_C_FEATURES"><code>CL_DEVICE_<wbr>OPENCL_<wbr>C_<wbr>FEATURES</code></a> to determine |
| optional OpenCL C language features supported by a device.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds an event command type to identify events |
| associated with the OpenCL 2.1 command <a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_COMMAND_SVM_MIGRATE_MEM"><code>CL_COMMAND_<wbr>SVM_<wbr>MIGRATE_<wbr>MEM</code></a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 adds a new query to determine the latest version of the conformance |
| test suite that the device has fully passed in accordance with the official |
| conformance process:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#CL_DEVICE_LATEST_CONFORMANCE_VERSION_PASSED"><code>CL_DEVICE_<wbr>LATEST_<wbr>CONFORMANCE_<wbr>VERSION_<wbr>PASSED</code></a></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="error_codes"><a class="anchor" href="#error_codes"></a>Appendix F: Error Codes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This section lists OpenCL error codes and their meanings.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>Error Code</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Brief Description</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SUCCESS"></a><a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a special error code to indicate that the API executed successfully, without errors.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_BUILD_PROGRAM_FAILURE"></a><a href="#CL_BUILD_PROGRAM_FAILURE"><code>CL_BUILD_<wbr>PROGRAM_<wbr>FAILURE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> failed to build the specified program.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMPILE_PROGRAM_FAILURE"></a><a href="#CL_COMPILE_PROGRAM_FAILURE"><code>CL_COMPILE_<wbr>PROGRAM_<wbr>FAILURE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> failed to compile the specified program.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_COMPILER_NOT_AVAILABLE"></a><a href="#CL_COMPILER_NOT_AVAILABLE"><code>CL_COMPILER_<wbr>NOT_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when compiling or building a program from source or IL when <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NOT_FOUND"></a><a href="#CL_DEVICE_NOT_FOUND"><code>CL_DEVICE_<wbr>NOT_<wbr>FOUND</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when no devices were found that match the specified device type.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NOT_AVAILABLE"></a><a href="#CL_DEVICE_NOT_AVAILABLE"><code>CL_DEVICE_<wbr>NOT_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to use a device when <a href="#CL_DEVICE_AVAILABLE"><code>CL_DEVICE_<wbr>AVAILABLE</code></a> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_FAILED"></a><a href="#CL_DEVICE_PARTITION_FAILED"><code>CL_DEVICE_<wbr>PARTITION_<wbr>FAILED</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when device partitioning is supported but the device could not be further partitioned.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"></a><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_EXEC_<wbr>STATUS_<wbr>ERROR_<wbr>FOR_<wbr>EVENTS_<wbr>IN_<wbr>WAIT_<wbr>LIST</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by blocking APIs when an event in the event wait list has a negative value, indicating it is in an error state.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_FORMAT_MISMATCH"></a><a href="#CL_IMAGE_FORMAT_MISMATCH"><code>CL_IMAGE_<wbr>FORMAT_<wbr>MISMATCH</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to copy images that do not use the same image format.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_FORMAT_NOT_SUPPORTED"></a><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_IMAGE_<wbr>FORMAT_<wbr>NOT_<wbr>SUPPORTED</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to create or use an image format that is not supported.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_ARG_INDEX"></a><a href="#CL_INVALID_ARG_INDEX"><code>CL_INVALID_<wbr>ARG_<wbr>INDEX</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to get or set a kernel argument using an invalid index for the specified kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_ARG_SIZE"></a><a href="#CL_INVALID_ARG_SIZE"><code>CL_INVALID_<wbr>ARG_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified size of a kernel argument does not match the size of the kernel argument.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_ARG_VALUE"></a><a href="#CL_INVALID_ARG_VALUE"><code>CL_INVALID_<wbr>ARG_<wbr>VALUE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to set a kernel argument that is not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_BINARY"></a><a href="#CL_INVALID_BINARY"><code>CL_INVALID_<wbr>BINARY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a program binary is not valid for a device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_BUFFER_SIZE"></a><a href="#CL_INVALID_BUFFER_SIZE"><code>CL_INVALID_<wbr>BUFFER_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to create a buffer or a sub-buffer with an invalid size.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_BUILD_OPTIONS"></a><a href="#CL_INVALID_BUILD_OPTIONS"><code>CL_INVALID_<wbr>BUILD_<wbr>OPTIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when build options passed to <a href="#clBuildProgram"><strong>clBuildProgram</strong></a> are not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_COMMAND_QUEUE"></a><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified command queue is not a valid command queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_COMPILER_OPTIONS"></a><a href="#CL_INVALID_COMPILER_OPTIONS"><code>CL_INVALID_<wbr>COMPILER_<wbr>OPTIONS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when compiler options passed to <a href="#clCompileProgram"><strong>clCompileProgram</strong></a> are not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_CONTEXT"></a><a href="#CL_INVALID_CONTEXT"><code>CL_INVALID_<wbr>CONTEXT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified context is not a valid context, or when mixing objects from multiple contexts.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_DEVICE"></a><a href="#CL_INVALID_DEVICE"><code>CL_INVALID_<wbr>DEVICE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified device is not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_DEVICE_PARTITION_COUNT"></a><a href="#CL_INVALID_DEVICE_PARTITION_COUNT"><code>CL_INVALID_<wbr>DEVICE_<wbr>PARTITION_<wbr>COUNT</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the requested device partitioning using <a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_DEVICE_<wbr>PARTITION_<wbr>BY_<wbr>COUNTS</code></a> is not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_DEVICE_QUEUE"></a><a href="#CL_INVALID_DEVICE_QUEUE"><code>CL_INVALID_<wbr>DEVICE_<wbr>QUEUE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when setting a device queue kernel argument to a value that is not a valid device command queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_DEVICE_TYPE"></a><a href="#CL_INVALID_DEVICE_TYPE"><code>CL_INVALID_<wbr>DEVICE_<wbr>TYPE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the requested device type is not a valid value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_EVENT"></a><a href="#CL_INVALID_EVENT"><code>CL_INVALID_<wbr>EVENT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified event object is not a valid event object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_EVENT_WAIT_LIST"></a><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_INVALID_<wbr>EVENT_<wbr>WAIT_<wbr>LIST</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified event wait list or number of events in the wait list is not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_GLOBAL_OFFSET"></a><a href="#CL_INVALID_GLOBAL_OFFSET"><code>CL_INVALID_<wbr>GLOBAL_<wbr>OFFSET</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified global offset and global work size exceeds the limits of the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_GLOBAL_WORK_SIZE"></a><a href="#CL_INVALID_GLOBAL_WORK_SIZE"><code>CL_INVALID_<wbr>GLOBAL_<wbr>WORK_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified global work size exceeds the limits of the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_HOST_PTR"></a><a href="#CL_INVALID_HOST_PTR"><code>CL_INVALID_<wbr>HOST_<wbr>PTR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified host pointer is not valid for the specified flags.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_IMAGE_DESCRIPTOR"></a><a href="#CL_INVALID_IMAGE_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>DESCRIPTOR</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified image descriptor is <code>NULL</code> or specifies invalid values.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"></a><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_INVALID_<wbr>IMAGE_<wbr>FORMAT_<wbr>DESCRIPTOR</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified image format descriptor is <code>NULL</code> or specifies invalid value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_IMAGE_SIZE"></a><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_INVALID_<wbr>IMAGE_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified image dimensions exceed the maximum dimensions for a device or all devices in a context.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_KERNEL"></a><a href="#CL_INVALID_KERNEL"><code>CL_INVALID_<wbr>KERNEL</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified kernel is not a valid kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_KERNEL_ARGS"></a><a href="#CL_INVALID_KERNEL_ARGS"><code>CL_INVALID_<wbr>KERNEL_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when enqueing a kernel when some kernel arguments have not been set or are invalid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_KERNEL_DEFINITION"></a><a href="#CL_INVALID_KERNEL_DEFINITION"><code>CL_INVALID_<wbr>KERNEL_<wbr>DEFINITION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when creating a kernel for multiple devices where the number of kernel arguments or kernel argument types are not the same for all devices.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_KERNEL_NAME"></a><a href="#CL_INVALID_KERNEL_NAME"><code>CL_INVALID_<wbr>KERNEL_<wbr>NAME</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when creating a kernel when no kernel with the specified name exists in the program object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_LINKER_OPTIONS"></a><a href="#CL_INVALID_LINKER_OPTIONS"><code>CL_INVALID_<wbr>LINKER_<wbr>OPTIONS</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when build options passed to <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> are not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_MEM_OBJECT"></a><a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified memory object is not a valid memory object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_OPERATION"></a><a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a generic error code that is returned when the requested operation is not a valid operation.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_PIPE_SIZE"></a><a href="#CL_INVALID_PIPE_SIZE"><code>CL_INVALID_<wbr>PIPE_<wbr>SIZE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.0.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when attempting to create a pipe with an invalid packet size or number of packets.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_PLATFORM"></a><a href="#CL_INVALID_PLATFORM"><code>CL_INVALID_<wbr>PLATFORM</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified platform is not a valid platform.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_PROGRAM"></a><a href="#CL_INVALID_PROGRAM"><code>CL_INVALID_<wbr>PROGRAM</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified program is not a valid program object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_PROGRAM_EXECUTABLE"></a><a href="#CL_INVALID_PROGRAM_EXECUTABLE"><code>CL_INVALID_<wbr>PROGRAM_<wbr>EXECUTABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified program is valid but has not been successfully built.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_PROPERTY"></a><a href="#CL_INVALID_PROPERTY"><code>CL_INVALID_<wbr>PROPERTY</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified property name is invalid, when the value for a property name is invalid, or when the same property name is specified more than once.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_QUEUE_PROPERTIES"></a><a href="#CL_INVALID_QUEUE_PROPERTIES"><code>CL_INVALID_<wbr>QUEUE_<wbr>PROPERTIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when specified queue properties are valid but are not supported by the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_SAMPLER"></a><a href="#CL_INVALID_SAMPLER"><code>CL_INVALID_<wbr>SAMPLER</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a specified sampler is not a valid sampler object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_SPEC_ID"></a><a href="#CL_INVALID_SPEC_ID"><code>CL_INVALID_<wbr>SPEC_<wbr>ID</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the specified specialization constant ID is not valid for the specified program.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_VALUE"></a><a href="#CL_INVALID_VALUE"><code>CL_INVALID_<wbr>VALUE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a generic error that is returned when a specified value is not a valid value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_WORK_DIMENSION"></a><a href="#CL_INVALID_WORK_DIMENSION"><code>CL_INVALID_<wbr>WORK_<wbr>DIMENSION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> when the specified work dimension is not valid.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_WORK_GROUP_SIZE"></a><a href="#CL_INVALID_WORK_GROUP_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>GROUP_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> when the specified total work-group size is not valid for the specified kernel or device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INVALID_WORK_ITEM_SIZE"></a><a href="#CL_INVALID_WORK_ITEM_SIZE"><code>CL_INVALID_<wbr>WORK_<wbr>ITEM_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> when the specified work-group size in one dimension is not valid for the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_KERNEL_ARG_INFO_NOT_AVAILABLE"></a><a href="#CL_KERNEL_ARG_INFO_NOT_AVAILABLE"><code>CL_KERNEL_<wbr>ARG_<wbr>INFO_<wbr>NOT_<wbr>AVAILABLE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clGetKernelArgInfo"><strong>clGetKernelArgInfo</strong></a> when kernel argument information is not available for the specified kernel.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_LINK_PROGRAM_FAILURE"></a><a href="#CL_LINK_PROGRAM_FAILURE"><code>CL_LINK_<wbr>PROGRAM_<wbr>FAILURE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> when there is a failure to link the specified binaries or libraries.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_LINKER_NOT_AVAILABLE"></a><a href="#CL_LINKER_NOT_AVAILABLE"><code>CL_LINKER_<wbr>NOT_<wbr>AVAILABLE</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clLinkProgram"><strong>clLinkProgram</strong></a> when <a href="#CL_DEVICE_LINKER_AVAILABLE"><code>CL_DEVICE_<wbr>LINKER_<wbr>AVAILABLE</code></a> is <a href="#CL_FALSE"><code>CL_FALSE</code></a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_FAILURE"></a><a href="#CL_MAP_FAILURE"><code>CL_MAP_<wbr>FAILURE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when there is a failure to map the specified region into the host address space.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_COPY_OVERLAP"></a><a href="#CL_MEM_COPY_OVERLAP"><code>CL_MEM_<wbr>COPY_<wbr>OVERLAP</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when copying from one region of a memory object to another where the source and destination regions overlap.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_ALLOCATION_FAILURE"></a><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_MEM_<wbr>OBJECT_<wbr>ALLOCATION_<wbr>FAILURE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when there is a failure to allocate memory for a memory object.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MISALIGNED_SUB_BUFFER_OFFSET"></a><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_MISALIGNED_<wbr>SUB_<wbr>BUFFER_<wbr>OFFSET</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.1.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when a sub-buffer object is created or used that is not aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_DEVICE_<wbr>MEM_<wbr>BASE_<wbr>ADDR_<wbr>ALIGN</code></a> for the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_OUT_OF_HOST_MEMORY"></a><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_OUT_<wbr>OF_<wbr>HOST_<wbr>MEMORY</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a generic error that is returned when memory could not be allocated on the host.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_OUT_OF_RESOURCES"></a><a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">This is a generic error that is returned when resources could not be allocated on the device.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAX_SIZE_RESTRICTION_EXCEEDED"></a><a href="#CL_MAX_SIZE_RESTRICTION_EXCEEDED"><code>CL_MAX_<wbr>SIZE_<wbr>RESTRICTION_<wbr>EXCEEDED</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 2.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned when the size of the specified kernel argument value exceeds the maximum size defined for the kernel argument.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PROFILING_INFO_NOT_AVAILABLE"></a><a href="#CL_PROFILING_INFO_NOT_AVAILABLE"><code>CL_PROFILING_<wbr>INFO_<wbr>NOT_<wbr>AVAILABLE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returned by <a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> when the command associated with the specified event was not enqueued into a command queue with <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_QUEUE_<wbr>PROFILING_<wbr>ENABLE</code></a>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="error_other_misc_enums"><a class="anchor" href="#error_other_misc_enums"></a>Appendix G: Other Miscellaneous Enums</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This section lists other miscellaneous OpenCL enumerants and their meanings.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>Enumerant</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Brief Description</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_TRUE"></a><a href="#CL_TRUE"><code>CL_TRUE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a boolean "true" value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FALSE"></a><a href="#CL_FALSE"><code>CL_FALSE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Indicates a boolean "false" value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_NONE"></a><a href="#CL_NONE"><code>CL_NONE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Indicates that none of the other enumerations or conditions are applicable.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_BLOCKING"></a><a href="#CL_BLOCKING"><code>CL_BLOCKING</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Alias of <a href="#CL_TRUE"><code>CL_TRUE</code></a> that can be used to improve the readability of calls to |
| enqueue functions that can block.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_NON_BLOCKING"></a><a href="#CL_NON_BLOCKING"><code>CL_NON_<wbr>BLOCKING</code></a></p> |
| <p class="tableblock"><a href="#unified-spec">Missing before</a> version 1.2.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Alias of <a href="#CL_FALSE"><code>CL_FALSE</code></a> that can be used to improve the readability of calls to |
| enqueue function that can block.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="opencl-3.0-backwards-compatibility"><a class="anchor" href="#opencl-3.0-backwards-compatibility"></a>Appendix H: OpenCL 3.0 Backwards Compatibility</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>OpenCL 3.0 breaks backwards compatibility with earlier versions of OpenCL by making some features that were previously required for FULL_PROFILE or EMBEDDED_PROFILE devices optional. |
| This appendix describes the features that were previously required that are now optional, how to detect whether an optional feature is supported, and expected behavior when an optional feature is not supported.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Informally, in the tables below the first row usually describes a feature detection mechanism ("May return this value indicating that the feature is not supported") and subsequent rows usually describe behavior when a feature is not supported ("Returns this value if the feature is not supported"). |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_shared_virtual_memory_2"><a class="anchor" href="#_shared_virtual_memory_2"></a>Shared Virtual Memory</h3> |
| <div class="paragraph"> |
| <p>Shared Virtual Memory (SVM) is optional for devices supporting OpenCL 3.0. |
| When Shared Virtual Memory is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_SVM_CAPABILITIES"><code>CL_DEVICE_<wbr>SVM_<wbr>CAPABILITIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>device</em> does not support Shared Virtual Memory.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a>, passing<br> |
| <a href="#CL_MEM_USES_SVM_POINTER"><code>CL_MEM_<wbr>USES_<wbr>SVM_<wbr>POINTER</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_FALSE"><code>CL_FALSE</code></a> if no devices in the context associated with <em>memobj</em> support Shared Virtual Memory.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>NULL</code> if no devices in <em>context</em> support Shared Virtual Memory.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSVMFree"><strong>clSVMFree</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Is a NOP if no devices in <em>context</em> support Shared Virtual Memory.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueSVMFree"><strong>clEnqueueSVMFree</strong></a>,<br> |
| <a href="#clEnqueueSVMMemcpy"><strong>clEnqueueSVMMemcpy</strong></a>,<br> |
| <a href="#clEnqueueSVMMemFill"><strong>clEnqueueSVMMemFill</strong></a>,<br> |
| <a href="#clEnqueueSVMMap"><strong>clEnqueueSVMMap</strong></a>,<br> |
| <a href="#clEnqueueSVMUnmap"><strong>clEnqueueSVMUnmap</strong></a>,<br> |
| <a href="#clEnqueueSVMMigrateMem"><strong>clEnqueueSVMMigrateMem</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the device associated with <em>command_queue</em> does not support Shared Virtual Memory.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSetKernelArgSVMPointer"><strong>clSetKernelArgSVMPointer</strong></a>,<br> |
| <a href="#clSetKernelExecInfo"><strong>clSetKernelExecInfo</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in the context associated with <em>kernel</em> support Shared Virtual Memory.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_memory_consistency_model"><a class="anchor" href="#_memory_consistency_model"></a>Memory Consistency Model</h3> |
| <div class="paragraph"> |
| <p>Some aspects of the OpenCL memory consistency model are optional for devices supporting OpenCL 3.0. |
| New device queries were added to <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> to allow capabilities to be precisely reported. |
| When the full memory consistency model is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>MEMORY_<wbr>CAPABILITIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return:</p> |
| <p class="tableblock"><a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a></p> |
| <p class="tableblock">indicating that <em>device</em> does not support the full memory consistency model for atomic memory operations.</p> |
| <p class="tableblock">Note that a device that provides the same level of capabilities as an OpenCL 2.x device would be expected to return:</p> |
| <p class="tableblock"><a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_ORDER_ACQ_REL"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>ACQ_<wbr>REL</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_ORDER_SEQ_CST"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>SEQ_<wbr>CST</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_DEVICE"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>DEVICE</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_ALL_DEVICES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>ALL_<wbr>DEVICES</code></a></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_ATOMIC_FENCE_CAPABILITIES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>FENCE_<wbr>CAPABILITIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return:</p> |
| <p class="tableblock"><a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_ORDER_ACQ_REL"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>ACQ_<wbr>REL</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a></p> |
| <p class="tableblock">indicating that <em>device</em> does not support the full memory consistency model for atomic fence operations.</p> |
| <p class="tableblock">Note that a device that provides the same level of capabilities as an OpenCL 2.x device would be expected to return:</p> |
| <p class="tableblock"><a href="#CL_DEVICE_ATOMIC_ORDER_RELAXED"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>RELAXED</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_ORDER_ACQ_REL"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>ACQ_<wbr>REL</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_ORDER_SEQ_CST"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>ORDER_<wbr>SEQ_<wbr>CST</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_ITEM"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>ITEM</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_WORK_GROUP"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>WORK_<wbr>GROUP</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_DEVICE"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>DEVICE</code></a> |<br> |
| <a href="#CL_DEVICE_ATOMIC_SCOPE_ALL_DEVICES"><code>CL_DEVICE_<wbr>ATOMIC_<wbr>SCOPE_<wbr>ALL_<wbr>DEVICES</code></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting atomics orders or scopes beyond the mandated |
| minimum will define some or all of following feature macros as appropriate:</p> |
| </div> |
| <div class="ulist none"> |
| <ul class="none"> |
| <li> |
| <p><code>__opencl_c_atomic_order_acq_rel</code> — Indicating atomic operations support acquire-release orderings.</p> |
| </li> |
| <li> |
| <p><code>__opencl_c_atomic_order_seq_cst</code> — Indicating atomic operations and fences support acquire sequentially consistent orderings.</p> |
| </li> |
| <li> |
| <p><code>__opencl_c_atomic_scope_device</code> — Indicating atomic operations and fences support device-wide memory ordering constraints.</p> |
| </li> |
| <li> |
| <p><code>__opencl_c_atomic_scope_all_devices</code> — Indicating atomic operations and fences support all-device memory ordering constraints, across any host threads and all devices that can share SVM memory with each other and the host process.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_device_side_enqueue"><a class="anchor" href="#_device_side_enqueue"></a>Device-Side Enqueue</h3> |
| <div class="paragraph"> |
| <p>Device-side enqueue and on-device queues are optional for devices supporting OpenCL 3.0. |
| When device-side enqueue is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_DEVICE_ENQUEUE_CAPABILITIES"><code>CL_DEVICE_<wbr>DEVICE_<wbr>ENQUEUE_<wbr>CAPABILITIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>device</em> does not support device-side enqueue and on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>PROPERTIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>0</code> if <em>device</em> does not support device-side enqueue and on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>PREFERRED_<wbr>SIZE</code></a>,<br> |
| <a href="#CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"><code>CL_DEVICE_<wbr>QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>MAX_<wbr>SIZE</code></a>,<br> |
| <a href="#CL_DEVICE_MAX_ON_DEVICE_QUEUES"><code>CL_DEVICE_<wbr>MAX_<wbr>ON_<wbr>DEVICE_<wbr>QUEUES</code></a>, or<br> |
| <a href="#CL_DEVICE_MAX_ON_DEVICE_EVENTS"><code>CL_DEVICE_<wbr>MAX_<wbr>ON_<wbr>DEVICE_<wbr>EVENTS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>0</code> if <em>device</em> does not support device-side enqueue and on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetCommandQueueInfo"><strong>clGetCommandQueueInfo</strong></a>, passing<br> |
| <a href="#CL_QUEUE_SIZE"><code>CL_QUEUE_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_INVALID_<wbr>COMMAND_<wbr>QUEUE</code></a> since <em>command_queue</em> cannot be a valid device command-queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetCommandQueueInfo"><strong>clGetCommandQueueInfo</strong></a>, passing<br> |
| <a href="#CL_QUEUE_DEVICE_DEFAULT"><code>CL_QUEUE_<wbr>DEVICE_<wbr>DEFAULT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>NULL</code> if the device associated with <em>command_queue</em> does not support on-device queues.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a>, passing<br> |
| <a href="#CL_PROFILING_COMMAND_COMPLETE"><code>CL_PROFILING_<wbr>COMMAND_<wbr>COMPLETE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns a value equivalent to passing <a href="#CL_PROFILING_COMMAND_END"><code>CL_PROFILING_<wbr>COMMAND_<wbr>END</code></a> if the device associated with <em>event</em> does not support device-side enqueue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>device</em> does not support on-device queues.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>When device-side enqueue is supported but a replaceable default on-device queue is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_DEVICE_ENQUEUE_CAPABILITIES"><code>CL_DEVICE_<wbr>DEVICE_<wbr>ENQUEUE_<wbr>CAPABILITIES</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May omit <a href="#CL_DEVICE_QUEUE_REPLACEABLE_DEFAULT"><code>CL_DEVICE_<wbr>QUEUE_<wbr>REPLACEABLE_<wbr>DEFAULT</code></a>, indicating that <em>device</em> does not support a replaceable default on-device queue.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>device</em> does not support a replaceable default on-device queue.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting device-side enqueue and on-device queues will define the feature macro <code>__opencl_c_device_enqueue</code>. |
| OpenCL C compilers that define the feature macro <code>__opencl_c_device_enqueue</code> must also define the feature macro <code>__opencl_c_generic_address_space</code> because some OpenCL C functions for device-side Enqueue accept pointers to the generic address space.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_pipes_2"><a class="anchor" href="#_pipes_2"></a>Pipes</h3> |
| <div class="paragraph"> |
| <p>Pipe memory objects are optional for devices supporting OpenCL 3.0. |
| When pipes are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_PIPE_SUPPORT"><code>CL_DEVICE_<wbr>PIPE_<wbr>SUPPORT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <a href="#CL_FALSE"><code>CL_FALSE</code></a>, indicating that <em>device</em> does not support pipes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_MAX_PIPE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>PIPE_<wbr>ARGS</code></a>,<br> |
| <a href="#CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS"><code>CL_DEVICE_<wbr>PIPE_<wbr>MAX_<wbr>ACTIVE_<wbr>RESERVATIONS</code></a>, or<br> |
| <a href="#CL_DEVICE_PIPE_MAX_PACKET_SIZE"><code>CL_DEVICE_<wbr>PIPE_<wbr>MAX_<wbr>PACKET_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>0</code> if <em>device</em> does not support pipes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clCreatePipe"><strong>clCreatePipe</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in <em>context</em> support pipes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetPipeInfo"><strong>clGetPipeInfo</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_MEM_OBJECT"><code>CL_INVALID_<wbr>MEM_<wbr>OBJECT</code></a> since <em>pipe</em> cannot be a valid pipe object.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting pipes will define the feature macro <code>__opencl_c_pipes</code>. |
| OpenCL C compilers that define the feature macro <code>__opencl_c_pipes</code> must also define the feature macro <code>__opencl_c_generic_address_space</code> because some OpenCL C functions for pipes accept pointers to the generic address space.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_program_scope_global_variables"><a class="anchor" href="#_program_scope_global_variables"></a>Program Scope Global Variables</h3> |
| <div class="paragraph"> |
| <p>Program scope global variables are optional for devices supporting OpenCL 3.0. |
| When program scope global variables are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE"><code>CL_DEVICE_<wbr>MAX_<wbr>GLOBAL_<wbr>VARIABLE_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>device</em> does not support program scope global variables.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE"><code>CL_DEVICE_<wbr>GLOBAL_<wbr>VARIABLE_<wbr>PREFERRED_<wbr>TOTAL_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>0</code> if <em>device</em> does not support program scope global variables.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetProgramBuildInfo"><strong>clGetProgramBuildInfo</strong></a>, passing<br> |
| <a href="#CL_PROGRAM_BUILD_GLOBAL_VARIABLE_TOTAL_SIZE"><code>CL_PROGRAM_<wbr>BUILD_<wbr>GLOBAL_<wbr>VARIABLE_<wbr>TOTAL_<wbr>SIZE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>0</code> if <em>device</em> does not support program scope global variables.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting program scope global variables will define the feature macro <code>__opencl_c_program_scope_global_variables</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_non_uniform_work_groups"><a class="anchor" href="#_non_uniform_work_groups"></a>Non-Uniform Work Groups</h3> |
| <div class="paragraph"> |
| <p>Support for non-uniform work-groups is optional for devices supporting OpenCL 3.0. |
| When non-uniform work-groups are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_NON_UNIFORM_WORK_GROUP_SUPPORT"><code>CL_DEVICE_<wbr>NON_<wbr>UNIFORM_<wbr>WORK_<wbr>GROUP_<wbr>SUPPORT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <a href="#CL_FALSE"><code>CL_FALSE</code></a>, indicating that <em>device</em> does not support non-uniform work-groups.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Behaves as though non-uniform Work Groups were not enabled for <em>kernel</em>, if the device associated with <em>command_queue</em> does not support non-uniform work-groups.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_read_write_images"><a class="anchor" href="#_read_write_images"></a>Read-Write Images</h3> |
| <div class="paragraph"> |
| <p>Read-write images, that may be read from and written to in the same kernel, are optional for devices supporting OpenCL 3.0. |
| When read-write images are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>WRITE_<wbr>IMAGE_<wbr>ARGS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>device</em> does not support read-write images.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a>, passing<br> |
| <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an empty set (such as <em>num_image_formats</em> equal to <code>0</code>), indicating that no image formats are supported for reading and writing in the same kernel, if no devices in <em>context</em> support read-write images.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting read-write images will define the feature macro <code>__opencl_c_read_write_images</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_creating_2d_images_from_buffers"><a class="anchor" href="#_creating_2d_images_from_buffers"></a>Creating 2D Images from Buffers</h3> |
| <div class="paragraph"> |
| <p>Creating a 2D image from a buffer is optional for devices supporting OpenCL 3.0. |
| When creating a 2D image from a buffer is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_IMAGE_PITCH_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>PITCH_<wbr>ALIGNMENT</code></a> or<br> |
| <a href="#CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"><code>CL_DEVICE_<wbr>IMAGE_<wbr>BASE_<wbr>ADDRESS_<wbr>ALIGNMENT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>device</em> does not support creating a 2D image from a Buffer.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_EXTENSIONS"><code>CL_DEVICE_<wbr>EXTENSIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Will not describe support for the <code>cl_khr_image2d_from_buffer</code> extension if <em>device</em> does not support creating a 2D image from a buffer.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clCreateImage"><strong>clCreateImage</strong></a> or<br> |
| <a href="#clCreateImageWithProperties"><strong>clCreateImageWithProperties</strong></a>, passing<br> |
| <em>image_type</em> equal to <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE2D</code></a> and<br> |
| <em>mem_object</em> not equal to <code>NULL</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in <em>context</em> support creating a 2D image from a buffer.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_srgb_images"><a class="anchor" href="#_srgb_images"></a>sRGB Images</h3> |
| <div class="paragraph"> |
| <p>All of the sRGB image channel orders (such as <a href="#CL_sRGBA"><code>CL_sRGBA</code></a>) are optional for devices supporting OpenCL 3.0. |
| When sRGB images are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Will not return return any image formats with <code>image_channel_order</code> equal to an sRGB image channel order if no devices in <em>context</em> support sRGB images.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_depth_images"><a class="anchor" href="#_depth_images"></a>Depth Images</h3> |
| <div class="paragraph"> |
| <p>The <a href="#CL_DEPTH"><code>CL_DEPTH</code></a> image channel order is optional for devices supporting OpenCL 3.0. |
| When depth images are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Will not return any image formats with <code>image_channel_order</code> equal to <a href="#CL_DEPTH"><code>CL_DEPTH</code></a> if no devices in <em>context</em> support depth images.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_device_and_host_timer_synchronization"><a class="anchor" href="#_device_and_host_timer_synchronization"></a>Device and Host Timer Synchronization</h3> |
| <div class="paragraph"> |
| <p>Synchronizing the device and host timers is optional for platforms supporting OpenCL 3.0. |
| When device and host timer synchronization is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a>, passing<br> |
| <a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_PLATFORM_<wbr>HOST_<wbr>TIMER_<wbr>RESOLUTION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>platform</em> does not support device and host timer synchronization.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a>, |
| <a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if the platform associated with <em>device</em> does not support device and host timer synchronization.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_intermediate_language_programs"><a class="anchor" href="#_intermediate_language_programs"></a>Intermediate Language Programs</h3> |
| <div class="paragraph"> |
| <p>Creating programs from an intermediate language (such as SPIR-V) is optional for devices supporting OpenCL 3.0. |
| When intermediate language programs are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_IL_VERSION"><code>CL_DEVICE_<wbr>IL_<wbr>VERSION</code></a> or<br> |
| <a href="#CL_DEVICE_ILS_WITH_VERSION"><code>CL_DEVICE_<wbr>ILS_<wbr>WITH_<wbr>VERSION</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return an empty string and empty array, indicating that <em>device</em> does not support intermediate language programs.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a>, passing<br> |
| <a href="#CL_PROGRAM_IL"><code>CL_PROGRAM_<wbr>IL</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an empty buffer (such as <em>param_value_size_ret</em> equal to <code>0</code>) if no devices in the context associated with <em>program</em> support intermediate language programs.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in <em>context</em> support intermediate language programs.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSetProgramSpecializationConstant"><strong>clSetProgramSpecializationConstant</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices associated with <em>program</em> support intermediate language programs.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a>, passing<br> |
| <a href="#CL_KERNEL_COMPILE_NUM_SUB_GROUPS"><code>CL_KERNEL_<wbr>COMPILE_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <code>0</code> if <em>device</em> does not support intermediate language programs, since there is currently no way to require a number of subgroups per work-group for programs created from source.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_subgroups"><a class="anchor" href="#_subgroups"></a>Subgroups</h3> |
| <div class="paragraph"> |
| <p>Subgroups are optional for devices supporting OpenCL 3.0. |
| When subgroups are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_MAX_NUM_SUB_GROUPS"><code>CL_DEVICE_<wbr>MAX_<wbr>NUM_<wbr>SUB_<wbr>GROUPS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <code>0</code>, indicating that <em>device</em> does not support subgroups.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"><code>CL_DEVICE_<wbr>SUB_<wbr>GROUP_<wbr>INDEPENDENT_<wbr>FORWARD_<wbr>PROGRESS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_FALSE"><code>CL_FALSE</code></a> if <em>device</em> does not support subgroups.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_EXTENSIONS"><code>CL_DEVICE_<wbr>EXTENSIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Will not describe support for the <code>cl_khr_subgroups</code> extension if <em>device</em> does not support subgroups.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if <em>device</em> does not support subgroups.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting subgroups will define the feature macro <code>__opencl_c_subgroups</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_program_initialization_and_clean_up_kernels"><a class="anchor" href="#_program_initialization_and_clean_up_kernels"></a>Program Initialization and Clean-Up Kernels</h3> |
| <div class="paragraph"> |
| <p>Program initialization and clean-up kernels are not supported in OpenCL 3.0, and the APIs and queries for program initialization and clean-up kernels are deprecated in OpenCL 3.0. |
| When program initialization and clean-up kernels are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetProgramInfo"><strong>clGetProgramInfo</strong></a>, passing<br> |
| <a href="#CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>CTORS_<wbr>PRESENT</code></a> or<br> |
| <a href="#CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT"><code>CL_PROGRAM_<wbr>SCOPE_<wbr>GLOBAL_<wbr>DTORS_<wbr>PRESENT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_FALSE"><code>CL_FALSE</code></a> if no devices in the context associated with <em>program</em> support program initialization and clean-up kernels.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clSetProgramReleaseCallback"><strong>clSetProgramReleaseCallback</strong></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns <a href="#CL_INVALID_OPERATION"><code>CL_INVALID_<wbr>OPERATION</code></a> if no devices in the context associated with <em>program</em> support program initialization and clean-up kernels.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="_3d_image_writes"><a class="anchor" href="#_3d_image_writes"></a>3D Image Writes</h3> |
| <div class="paragraph"> |
| <p>Kernel built-in functions for writing to 3D image objects are optional for devices supporting OpenCL 3.0. |
| When writing to 3D image objects is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_EXTENSIONS"><code>CL_DEVICE_<wbr>EXTENSIONS</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Will not describe support for the <code>cl_khr_3d_image_writes</code> extension if <em>device</em> does not support writing to 3D image objects.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a>, passing<br> |
| <a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_MEM_<wbr>OBJECT_<wbr>IMAGE3D</code></a> and one of<br> |
| <a href="#CL_MEM_WRITE_ONLY"><code>CL_MEM_<wbr>WRITE_<wbr>ONLY</code></a>,<br> |
| <a href="#CL_MEM_READ_WRITE"><code>CL_MEM_<wbr>READ_<wbr>WRITE</code></a>, or<br> |
| <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_MEM_<wbr>KERNEL_<wbr>READ_<wbr>AND_<wbr>WRITE</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Returns an empty set (such as <em>num_image_formats</em> equal to <code>0</code>), indicating that no image formats are supported for writing to 3D image objects, if no devices in <em>context</em> support writing to 3D image objects.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting writing to 3D image objects will define the feature macro <code>__opencl_c_3d_image_writes</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_work_group_collective_functions"><a class="anchor" href="#_work_group_collective_functions"></a>Work Group Collective Functions</h3> |
| <div class="paragraph"> |
| <p>Work-group collective functions for broadcasts, scans, and reductions are optional for devices supporting OpenCL 3.0. |
| When work-group collective functions are not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_WORK_GROUP_COLLECTIVE_FUNCTIONS_SUPPORT"><code>CL_DEVICE_<wbr>WORK_<wbr>GROUP_<wbr>COLLECTIVE_<wbr>FUNCTIONS_<wbr>SUPPORT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <a href="#CL_FALSE"><code>CL_FALSE</code></a>, indicating that <em>device</em> does not support work-group collective functions.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting work-group collective functions will define the feature macro <code>__opencl_c_work_group_collective_functions</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_generic_address_space"><a class="anchor" href="#_generic_address_space"></a>Generic Address Space</h3> |
| <div class="paragraph"> |
| <p>Support for the generic address space is optional for devices supporting OpenCL 3.0. |
| When the generic address space is not supported:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><strong>API</strong></th> |
| <th class="tableblock halign-left valign-top"><strong>Behavior</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>, passing<br> |
| <a href="#CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT"><code>CL_DEVICE_<wbr>GENERIC_<wbr>ADDRESS_<wbr>SPACE_<wbr>SUPPORT</code></a></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">May return <a href="#CL_FALSE"><code>CL_FALSE</code></a>, indicating that <em>device</em> does not support the generic address space.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>OpenCL C compilers supporting the generic address space will define the feature macro <code>__opencl_c_generic_address_space</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_language_features_that_were_already_optional"><a class="anchor" href="#_language_features_that_were_already_optional"></a>Language Features that Were Already Optional</h3> |
| <div class="paragraph"> |
| <p>Some OpenCL C language features were already optional before OpenCL 3.0, the API mechanisms for querying these have not changed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>New feature macros for these optional features have been added to OpenCL C to provide a consistent mechanism for using optional features in OpenCL C 3.0. |
| OpenCL C compilers supporting images will define the feature macro <code>__opencl_c_images</code>. |
| OpenCL C compilers supporting the <code>double</code> type will define the feature macro <code>__opencl_c_fp64</code>. |
| OpenCL C compilers supporting the <code>long</code>, <code>unsigned long</code> and <code>ulong</code> types will define the feature macro <code>__opencl_c_int64</code>, note that compilers for FULL_PROFILE devices must support these types and define the macro unconditionally.</p> |
| </div> |
| <div style="page-break-after: always;"></div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_acknowledgements"><a class="anchor" href="#_acknowledgements"></a>Acknowledgements</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The OpenCL specification is the result of the contributions of many people, |
| representing a cross section of the desktop, hand-held, and embedded |
| computer industry. |
| Following is a partial list of the contributors, including the company that |
| they represented at the time of their contribution:</p> |
| </div> |
| <div class="paragraph"> |
| <p>Chuck Rose, Adobe<br> |
| Eric Berdahl, Adobe<br> |
| Shivani Gupta, Adobe<br> |
| Bill Licea Kane, AMD<br> |
| Ed Buckingham, AMD<br> |
| Jan Civlin, AMD<br> |
| Laurent Morichetti, AMD<br> |
| Mark Fowler, AMD<br> |
| Marty Johnson, AMD<br> |
| Michael Mantor, AMD<br> |
| Norm Rubin, AMD<br> |
| Ofer Rosenberg, AMD<br> |
| Brian Sumner, AMD<br> |
| Victor Odintsov, AMD<br> |
| Aaftab Munshi, Apple<br> |
| Abe Stephens, Apple<br> |
| Alexandre Namaan, Apple<br> |
| Anna Tikhonova, Apple<br> |
| Chendi Zhang, Apple<br> |
| Eric Bainville, Apple<br> |
| David Hayward, Apple<br> |
| Giridhar Murthy, Apple<br> |
| Ian Ollmann, Apple<br> |
| Inam Rahman, Apple<br> |
| James Shearer, Apple<br> |
| MonPing Wang, Apple<br> |
| Tanya Lattner, Apple<br> |
| Mikael Bourges-Sevenier, Aptina<br> |
| Brice Videau, Argonne National Laboratory<br> |
| Anton Lokhmotov, ARM<br> |
| Dave Shreiner, ARM<br> |
| Einar Hov, ARM<br> |
| Hedley Francis, ARM<br> |
| Kevin Petit, ARM<br> |
| Neil Hickey, ARM<br> |
| Robert Elliott, ARM<br> |
| Scott Moyers, ARM<br> |
| Stuart Brady, ARM<br> |
| Sven Van Haastregt, Arm<br> |
| Tom Olson, ARM<br> |
| Anastasia Stulova, ARM<br> |
| Christopher Thompson-Walsh, Broadcom<br> |
| Holger Waechtler, Broadcom<br> |
| Norman Rink, Broadcom<br> |
| Andrew Richards, Codeplay<br> |
| Maria Rovatsou, Codeplay<br> |
| Alistair Donaldson, Codeplay<br> |
| Alastair Murray, Codeplay<br> |
| Ewan Crawford, Codeplay<br> |
| Stephen Frye, Electronic Arts<br> |
| Eric Schenk, Electronic Arts<br> |
| Daniel Laroche, Freescale<br> |
| David Neto, Google<br> |
| James Price, Google<br> |
| Robin Grosman, Huawei<br> |
| Craig Davies, Huawei<br> |
| Brian Horton, IBM<br> |
| Brian Watt, IBM<br> |
| Gordon Fossum, IBM<br> |
| Greg Bellows, IBM<br> |
| Joaquin Madruga, IBM<br> |
| Mark Nutter, IBM<br> |
| Mike Perks, IBM<br> |
| Sean Wagner, IBM<br> |
| Jeremy Kemp, Imagination Technologies<br> |
| Jon Parr, Imagination Technologies<br> |
| Paul Fradgley, Imagination Technologies<br> |
| Robert Quill, Imagination Technologies<br> |
| James McCarthy, Imagination Technologies<br> |
| Jon Leech, Independent<br> |
| Aaron Kunze, Intel<br> |
| Aaron Lefohn, Intel<br> |
| Adam Lake, Intel<br> |
| Alexey Bader, Intel<br> |
| Allen Hux, Intel<br> |
| Andrew Brownsword, Intel<br> |
| Andrew Lauritzen, Intel<br> |
| Anton Zabaznov, Intel<br> |
| Bartosz Sochacki, Intel<br> |
| Ben Ashbaugh, Intel<br> |
| Boaz Ouriel, Intel<br> |
| Brian Lewis, Intel<br> |
| Filip Hazubski, Intel<br> |
| Geoff Berry, Intel<br> |
| Grzegorz Wawiorko, Intel<br> |
| Hong Jiang, Intel<br> |
| Jayanth Rao, Intel<br> |
| Josh Fryman, Intel<br> |
| Kevin Stevens, Intel<br> |
| Larry Seiler, Intel<br> |
| Michael Kinsner, Intel<br> |
| Michal Mrozek, Intel<br> |
| Mike MacPherson, Intel<br> |
| Murali Sundaresan, Intel<br> |
| Paul Lalonde, Intel<br> |
| Stephen Junkins, Intel<br> |
| Tim Foley, Intel<br> |
| Timothy Mattson, Intel<br> |
| Yariv Aridor, Intel<br> |
| Sébastien Le Duc, Kalray<br> |
| Benjamin Bergen, Los Alamos National Laboratory<br> |
| Roy Ju, Mediatek<br> |
| Bor-Sung Liang, Mediatek<br> |
| Rahul Agarwal, Mediatek<br> |
| Michal Witaszek, Mobica<br> |
| JenqKuen Lee, NTHU<br> |
| Amit Rao, NVIDIA<br> |
| Ashish Srivastava, NVIDIA<br> |
| Bastiaan Aarts, NVIDIA<br> |
| Chris Cameron, NVIDIA<br> |
| Christopher Lamb, NVIDIA<br> |
| Dibyapran Sanyal, NVIDIA<br> |
| Guatam Chakrabarti, NVIDIA<br> |
| Ian Buck, NVIDIA<br> |
| Jaydeep Marathe, NVIDIA<br> |
| Jian-Zhong Wang, NVIDIA<br> |
| Karthik Raghavan Ravi, NVIDIA<br> |
| Kedar Patil, NVIDIA<br> |
| Manjunath Kudlur, NVIDIA<br> |
| Mark Harris, NVIDIA<br> |
| Michael Gold, NVIDIA<br> |
| Neil Trevett, NVIDIA<br> |
| Nikhil Joshi, NVIDIA<br> |
| Richard Johnson, NVIDIA<br> |
| Sean Lee, NVIDIA<br> |
| Tushar Kashalikar, NVIDIA<br> |
| Vinod Grover, NVIDIA<br> |
| Xiangyun Kong, NVIDIA<br> |
| Yogesh Kini, NVIDIA<br> |
| Yuan Lin, NVIDIA<br> |
| Mayuresh Pise, NVIDIA<br> |
| Allan Tzeng, QUALCOMM<br> |
| Alex Bourd, QUALCOMM<br> |
| Andrew Gruber, QUALCOMM<br> |
| Andrzej Mamona, QUALCOMM<br> |
| Anirudh Acharya, QUALCOMM<br> |
| Balaji Calidas, QUALCOMM<br> |
| Benedict Gaster, QUALCOMM<br> |
| Bill Torzewski, QUALCOMM<br> |
| Bob Rychlik, QUALCOMM<br> |
| Chihong Zhang, QUALCOMM<br> |
| Chris Mei, QUALCOMM<br> |
| Colin Sharp, QUALCOMM<br> |
| David Garcia, QUALCOMM<br> |
| David Ligon, QUALCOMM<br> |
| Hongqiang Wang, QUALCOMM<br> |
| Jay Yun, QUALCOMM<br> |
| Jian Liu, QUALCOMM<br> |
| Joshua Kelly, QUALCOMM<br> |
| Lee Howes, QUALCOMM<br> |
| Lihan Bin, QUALCOMM<br> |
| Richard Ruigrok, QUALCOMM<br> |
| Robert J. Simpson, QUALCOMM<br> |
| Ruihao Zhang, QUALCOMM<br> |
| Samuel Pauls, QUALCOMM<br> |
| Sreelakshmi Haridas, QUALCOMM<br> |
| Sumesh Udayakumaran, QUALCOMM<br> |
| Vineet Goel, QUALCOMM<br> |
| Vlad Shimanskiy, QUALCOMM<br> |
| Yu-Chi Huang, QUALCOMM<br> |
| Yuehai Du, QUALCOMM<br> |
| Raun Krisch, Samsung<br> |
| Tasneem Brutch, Samsung<br> |
| Yoonseo Choi, Samsung<br> |
| Dennis Adams, Sony<br> |
| Pr-Anders Aronsson, Sony<br> |
| Jim Rasmusson, Sony<br> |
| Thierry Lepley, STMicroelectronics<br> |
| Anton Gorenko, StreamHPC<br> |
| Jakub Szuppe, StreamHPC<br> |
| Máté Ferenc Nagy-Egri, StreamHPC<br> |
| Vincent Hindriksen, StreamHPC<br> |
| Ajay Jayaraj, Texas Instruments<br> |
| Alan Ward, Texas Instruments<br> |
| Yuan Zhao, Texas Instruments<br> |
| Pete Curry, Texas Instruments<br> |
| Simon McIntosh-Smith, University of Bristol<br> |
| Paul Preney, University of Windsor<br> |
| Shane Peelar, University of Windsor<br> |
| Wei-Lun Kao, VeriSilicon<br> |
| Yanjun Zhang, VeriSilicon<br> |
| Brian Hutsell, Vivante<br> |
| Mike Cai, Vivante<br> |
| Sumeet Kumar, Vivante<br> |
| Xing Wang, Vivante<br> |
| Jeff Fifield, Xilinx<br> |
| Hem C. Neema, Xilinx<br> |
| Henry Styles, Xilinx<br> |
| Ralph Wittig, Xilinx<br> |
| Ronan Keryell, Xilinx<br> |
| AJ Guillon, YetiWare Inc<br></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="footnotes"> |
| <hr> |
| <div class="footnote" id="_footnotedef_1"> |
| <a href="#_footnoteref_1">1</a>. This value for memory_scope can only be used with atomic_work_item_fence with flags set to <code>CLK_IMAGE_MEM_FENCE</code>. |
| </div> |
| <div class="footnote" id="_footnotedef_2"> |
| <a href="#_footnoteref_2">2</a>. The platform profile returns the profile that is implemented by the OpenCL framework. If the platform profile returned is FULL_PROFILE, the OpenCL framework will support devices that are FULL_PROFILE and may also support devices that are EMBEDDED_PROFILE. The compiler must be available for all devices i.e. <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_DEVICE_<wbr>COMPILER_<wbr>AVAILABLE</code></a> is <a href="#CL_TRUE"><code>CL_TRUE</code></a>. If the platform profile returned is EMBEDDED_PROFILE, then devices that are only EMBEDDED_PROFILE are supported. |
| </div> |
| <div class="footnote" id="_footnotedef_3"> |
| <a href="#_footnoteref_3">3</a>. A null terminated string is returned by OpenCL query function calls if the return type of the information being queried is a <code>char</code>[]. |
| </div> |
| <div class="footnote" id="_footnotedef_4"> |
| <a href="#_footnoteref_4">4</a>. The OpenCL specification does not describe the order of precedence for error codes returned by API calls. |
| </div> |
| <div class="footnote" id="_footnotedef_5"> |
| <a href="#_footnoteref_5">5</a>. <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> may return all or a subset of the actual physical devices present in the platform and that match <em>device_type</em>. |
| </div> |
| <div class="footnote" id="_footnotedef_6"> |
| <a href="#_footnoteref_6">6</a>. OpenCL adopters must report a valid vendor ID for their implementation. If there is no valid PCI vendor ID defined for the physical device, implementations must obtain a Khronos vendor ID. This is a unique identifier greater than the largest PCI vendor ID (<code>0x10000</code>) and is representable by a <code>cl_uint</code>. Khronos vendor IDs are synchronized across APIs by utilizing Vulkan’s vk.xml as the central Khronos vendor ID registry. An ID must be reserved here prior to use in OpenCL, regardless of whether a vendor implements Vulkan. Only once the ID has been allotted may it be exposed to OpenCL by proposing a merge request against cl.xml, in the master branch of the OpenCL-Docs project. The merge must define a new enumerant by adding an <code><enum></code> tag to the <code>cl_khronos_<wbr>vendor_<wbr>id</code> <code><enums></code> tag, with the <code><value></code> attribute set as the acquired Khronos vendor ID. The <code><name></code> attribute must identify the vendor/adopter, and be of the form <code>CL_KHRONOS_VENDOR_ID_<vendor></code>. |
| </div> |
| <div class="footnote" id="_footnotedef_7"> |
| <a href="#_footnoteref_7">7</a>. A kernel that uses an image argument with the write_only or read_write image qualifier may result in additional read_only images resources being created internally by an implementation. The internally created read_only image resources will count against the max supported read image arguments given by <a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_DEVICE_<wbr>MAX_<wbr>READ_<wbr>IMAGE_<wbr>ARGS</code></a>. Enqueuing a kernel that requires more images than the implementation can support will result in a <a href="#CL_OUT_OF_RESOURCES"><code>CL_OUT_<wbr>OF_<wbr>RESOURCES</code></a> error being returned. |
| </div> |
| <div class="footnote" id="_footnotedef_8"> |
| <a href="#_footnoteref_8">8</a>. The optional rounding modes should be included as a device capability only if it is supported natively. All explicit conversion functions with specific rounding modes must still operate correctly. |
| </div> |
| <div class="footnote" id="_footnotedef_9"> |
| <a href="#_footnoteref_9">9</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_10"> |
| <a href="#_footnoteref_10">10</a>. Note that this flag does not provide meaning for atomic memory operations, but only for atomic fence operations in certain circumstances, refer to the Memory Scope section of the OpenCL C specification. |
| </div> |
| <div class="footnote" id="_footnotedef_11"> |
| <a href="#_footnoteref_11">11</a>. Duplicate devices specified in <em>devices</em> are ignored. |
| </div> |
| <div class="footnote" id="_footnotedef_12"> |
| <a href="#_footnoteref_12">12</a>. <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> may may create a context for all or a subset of the actual physical devices present in the platform that match <em>device_type</em>. |
| </div> |
| <div class="footnote" id="_footnotedef_13"> |
| <a href="#_footnoteref_13">13</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_14"> |
| <a href="#_footnoteref_14">14</a>. Only out-of-order device queues are supported. |
| </div> |
| <div class="footnote" id="_footnotedef_15"> |
| <a href="#_footnoteref_15">15</a>. The application must create a default device queue if any kernels containing calls to <code>get_default_queue</code> are enqueued. There can only be one default device queue for each device within a context. If a default device queue has already been created, calling <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> with <a href="#CL_QUEUE_PROPERTIES"><code>CL_QUEUE_<wbr>PROPERTIES</code></a> set to <a href="#CL_QUEUE_ON_DEVICE"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE</code></a> and <a href="#CL_QUEUE_ON_DEVICE_DEFAULT"><code>CL_QUEUE_<wbr>ON_<wbr>DEVICE_<wbr>DEFAULT</code></a> will return the default device queue that has already been created and increment its reference count by 1. |
| </div> |
| <div class="footnote" id="_footnotedef_16"> |
| <a href="#_footnoteref_16">16</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_17"> |
| <a href="#_footnoteref_17">17</a>. Note that reading and writing 2D image arrays from a kernel with <code>image_array_size</code> equal to one may perform worse than 2D images. |
| </div> |
| <div class="footnote" id="_footnotedef_18"> |
| <a href="#_footnoteref_18">18</a>. To create a 2D image from a buffer object that share the data store between the image and buffer object. |
| </div> |
| <div class="footnote" id="_footnotedef_19"> |
| <a href="#_footnoteref_19">19</a>. To create an image object from another image object that share the data store between these image objects. |
| </div> |
| <div class="footnote" id="_footnotedef_20"> |
| <a href="#_footnoteref_20">20</a>. This allows creation of a sRGB view of the image from a linear RGB view or vice-versa, i.e. the pixels stored in the image can be accessed as linear RGB or sRGB values. |
| </div> |
| <div class="footnote" id="_footnotedef_21"> |
| <a href="#_footnoteref_21">21</a>. Support for the <a href="#CL_DEPTH"><code>CL_DEPTH</code></a> image channel order is required only for 2D images and 2D image arrays. |
| </div> |
| <div class="footnote" id="_footnotedef_22"> |
| <a href="#_footnoteref_22">22</a>. Support for reading from the <a href="#CL_sRGBA"><code>CL_sRGBA</code></a> image channel order is optional for 1D image buffers. Support for writing to the <a href="#CL_sRGBA"><code>CL_sRGBA</code></a> image channel order is optional for all image types. |
| </div> |
| <div class="footnote" id="_footnotedef_23"> |
| <a href="#_footnoteref_23">23</a>. The map count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for debugging. |
| </div> |
| <div class="footnote" id="_footnotedef_24"> |
| <a href="#_footnoteref_24">24</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_25"> |
| <a href="#_footnoteref_25">25</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_26"> |
| <a href="#_footnoteref_26">26</a>. As per the definition of <code>-cl-denorms-are-zero</code>, the inclusion of this option with <code>-cl-unsafe-math-optimizations</code> means that the implementation may flush denormal numbers to zero but is not required to. |
| </div> |
| <div class="footnote" id="_footnotedef_27"> |
| <a href="#_footnoteref_27">27</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_28"> |
| <a href="#_footnoteref_28">28</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_29"> |
| <a href="#_footnoteref_29">29</a>. <a href="#CL_KERNEL_ARG_TYPE_CONST"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>CONST</code></a> is returned if the argument is a pointer and the referenced type is declared with the const qualifier. For example, a kernel argument declared as <code>global int const *x</code> returns <a href="#CL_KERNEL_ARG_TYPE_CONST"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>CONST</code></a> but a kernel argument declared as <code>global int * const x</code> does not.<br> Similarly, <a href="#CL_KERNEL_ARG_TYPE_RESTRICT"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>RESTRICT</code></a> will be returned if the pointer type is marked <code>restrict</code>. For example, <code>global int * restrict x</code> returns <a href="#CL_KERNEL_ARG_TYPE_RESTRICT"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>RESTRICT</code></a>.<br> <a href="#CL_KERNEL_ARG_TYPE_VOLATILE"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>VOLATILE</code></a> is returned for <a href="#CL_KERNEL_ARG_TYPE_QUALIFIER"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>QUALIFIER</code></a> if the argument is a pointer and the referenced type is declared with the volatile qualifier. For example, a kernel argument declared as <code>global int volatile *x</code> returns <a href="#CL_KERNEL_ARG_TYPE_VOLATILE"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>VOLATILE</code></a> but a kernel argument declared as <code>global int * volatile x</code> does not. |
| </div> |
| <div class="footnote" id="_footnotedef_30"> |
| <a href="#_footnoteref_30">30</a>. <a href="#CL_KERNEL_ARG_TYPE_CONST"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>CONST</code></a> is returned for <a href="#CL_KERNEL_ARG_TYPE_QUALIFIER"><code>CL_KERNEL_<wbr>ARG_<wbr>TYPE_<wbr>QUALIFIER</code></a> if the argument is declared with the <code>constant</code> address space qualifier. |
| </div> |
| <div class="footnote" id="_footnotedef_31"> |
| <a href="#_footnoteref_31">31</a>. The error code values are negative, and event state values are positive. The event state values are ordered from the largest value <a href="#CL_QUEUED"><code>CL_QUEUED</code></a> for the first or initial state to the smallest value (<a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> or negative integer value) for the last or complete state. The value of <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> and <a href="#CL_SUCCESS"><code>CL_SUCCESS</code></a> are the same. |
| </div> |
| <div class="footnote" id="_footnotedef_32"> |
| <a href="#_footnoteref_32">32</a>. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
| </div> |
| <div class="footnote" id="_footnotedef_33"> |
| <a href="#_footnoteref_33">33</a>. The callback function registered for a <em>command_exec_callback_type</em> value of <a href="#CL_COMPLETE"><code>CL_COMPLETE</code></a> will be called when the command has completed successfully or is abnormally terminated. |
| </div> |
| <div class="footnote" id="_footnotedef_34"> |
| <a href="#_footnoteref_34">34</a>. And <strong>read_imageh</strong>, if the <strong>cl_khr_fp16</strong> extension is supported. |
| </div> |
| <div class="footnote" id="_footnotedef_35"> |
| <a href="#_footnoteref_35">35</a>. Note that the performance of 64-bit integer arithmetic can vary significantly between embedded devices. |
| </div> |
| <div class="footnote" id="_footnotedef_36"> |
| <a href="#_footnoteref_36">36</a>. Please refer to the OpenCL glossary for the OpenCL definition of thread-safe. This definition may be different from usage of the term in other contexts. |
| </div> |
| <div class="footnote" id="_footnotedef_37"> |
| <a href="#_footnoteref_37">37</a>. There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>. Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. Rather than attempt to share <code>cl_kernel</code> objects among multiple host threads, applications are strongly encouraged to make additional <code>cl_kernel</code> objects for kernel functions for each host thread. |
| </div> |
| <div class="footnote" id="_footnotedef_38"> |
| <a href="#_footnoteref_38">38</a>. Note that we are talking about the programming model here. In reality, little endian systems might choose to simply address their bytes from "the right" or reverse the "order" of the bits in the byte. Either of these choices would mean that no big swap would need to occur in hardware. |
| </div> |
| </div> |
| <div id="footer"> |
| <div id="footer-text"> |
| Version v3.0.8<br> |
| Last updated 2021-06-29 12:20:08 -0700 |
| </div> |
| </div> |
| |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script> |
| </body> |
| </html> |