diff --git a/.github/workflows/build-quick-static-n-1.yml b/.github/workflows/build-quick-static-n-1.yml index fc3b7006..b4a85636 100644 --- a/.github/workflows/build-quick-static-n-1.yml +++ b/.github/workflows/build-quick-static-n-1.yml @@ -28,7 +28,7 @@ jobs: steps: # ----- Spec-generated loader preamble (loader-head, see loader-integration.yml) ----- - name: Checkout spec-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true fetch-depth: 0 @@ -66,13 +66,12 @@ jobs: ghcr.io/oneapi-src/spec-build:latest \ /opt/spec-venv/bin/python3 ./run.py --debug '--!html' '--!rst' '--!build' --ver $VER - name: Checkout loader-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: oneapi-src/level-zero ref: master path: loader-head - token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} - name: json2src head run: | #bash docker run \ @@ -92,13 +91,12 @@ jobs: xargs -I{} cp -v ./{} ../loader-head/{} # ----- loader-base: plain loader master, built as-is (n-1 / static side) ----- - name: Checkout loader-base - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: oneapi-src/level-zero ref: master path: loader-base - token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} # ----- Re-created build-quick-static-n-1 logic ----- - name: Build static loader from loader master working-directory: loader-base diff --git a/.github/workflows/build-quick-static.yml b/.github/workflows/build-quick-static.yml index 4e3e0554..aaacfcd4 100644 --- a/.github/workflows/build-quick-static.yml +++ b/.github/workflows/build-quick-static.yml @@ -27,7 +27,7 @@ jobs: steps: # ----- Spec-generated loader preamble (see loader-integration.yml) ----- - name: Checkout spec-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true fetch-depth: 0 @@ -65,13 +65,12 @@ jobs: ghcr.io/oneapi-src/spec-build:latest \ /opt/spec-venv/bin/python3 ./run.py --debug '--!html' '--!rst' '--!build' --ver $VER - name: Checkout loader-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: oneapi-src/level-zero ref: master path: loader-head - token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} - name: json2src head run: | #bash docker run \ diff --git a/.github/workflows/build-quick.yml b/.github/workflows/build-quick.yml index 33aee087..917833fb 100644 --- a/.github/workflows/build-quick.yml +++ b/.github/workflows/build-quick.yml @@ -47,7 +47,7 @@ jobs: steps: # ----- Spec-generated loader preamble (see loader-integration.yml) ----- - name: Checkout spec-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true fetch-depth: 0 @@ -85,13 +85,12 @@ jobs: ghcr.io/oneapi-src/spec-build:latest \ /opt/spec-venv/bin/python3 ./run.py --debug '--!html' '--!rst' '--!build' --ver $VER - name: Checkout loader-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: oneapi-src/level-zero ref: master path: loader-head - token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} - name: json2src head run: | #bash docker run \ diff --git a/.github/workflows/cleanup-pr-docs.yml b/.github/workflows/cleanup-pr-docs.yml index 3bb97340..ee0bb95b 100644 --- a/.github/workflows/cleanup-pr-docs.yml +++ b/.github/workflows/cleanup-pr-docs.yml @@ -19,7 +19,7 @@ jobs: if: github.repository_owner == 'intel-innersource' steps: - name: Checkout gh-pages branch - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: gh-pages path: gh-pages-repo diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 00000000..e5e82613 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,46 @@ +name: CodeQL + +# Static analysis (SAST) of the Python generator scripts and the workflow files. +# Results go to the public repo's Security > Code scanning tab. Runs only on the +# public repo, like scorecard.yml; internal mirrors block ubuntu-latest runners. +on: + # Allow manual runs from the Actions tab ("Run workflow" button). + workflow_dispatch: + push: + branches: [ "master" ] + schedule: + - cron: '41 20 * * 4' + +permissions: + contents: read + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-latest + if: github.repository_owner == 'oneapi-src' + permissions: + # Needed to upload the results to code-scanning dashboard. + security-events: write + contents: read + strategy: + fail-fast: false + matrix: + language: [ "python", "actions" ] + + steps: + - name: Checkout code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Initialize CodeQL + uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3 + with: + languages: ${{ matrix.language }} + build-mode: none + + - name: Perform CodeQL analysis + uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3 + with: + category: "/language:${{ matrix.language }}" diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index 1c0b94eb..9b56d9af 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -42,7 +42,7 @@ jobs: runs-on: [self-hosted, Linux] if: github.repository_owner == 'intel-innersource' steps: - - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Run codespell # Configuration (skip/ignore lists) is picked up from .codespellrc. A spelling # finding must not fail this step: the report has to be published to the PR @@ -79,7 +79,7 @@ jobs: }' codespell.txt - name: Post or update PR comment if: github.event_name == 'pull_request' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: script: | const fs = require('fs'); diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index c0f690b2..9320a196 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -29,7 +29,7 @@ jobs: if: github.repository_owner == 'intel-innersource' steps: - name: Checkout - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true fetch-depth: 0 @@ -97,107 +97,77 @@ jobs: ghcr.io/oneapi-src/spec-build:latest \ /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' --ver $VER --versions_url_override "$VERSIONS_URL_OVERRIDE" - # Doxygen runs with WARN_AS_ERROR=FAIL_ON_WARNINGS (scripts/Doxyfile), so any - # unresolvable doc reference fails the build. generate_docs.py saves doxygen's - # stderr -- which is diagnostics only, no progress noise -- to this file, so we can - # quote just the actionable lines rather than the whole build log. - - name: Report documentation warnings + # Each docs build phase that can fail on bad references saves just its actionable + # lines to a log under docs/, so we quote those rather than the whole build log: + # - rst-errors.log: unresolved symbols in scripts/
/*.rst (run.py phase 3) + # - doxygen-warnings.log: doxygen runs with WARN_AS_ERROR=FAIL_ON_WARNINGS + # - sphinx-warnings.log: sphinx-build runs with -W, e.g. a broken :ref: label + - name: Report documentation errors if: steps.gen_docs.outcome == 'failure' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | const fs = require('fs'); - const path = 'docs/doxygen-warnings.log'; + const reports = [ + { + path: 'docs/rst-errors.log', + what: n => `Generation reported **${n}** unresolved ${n === 1 ? 'reference' : 'references'} in the spec RST/sample code`, + hint: '> These reference symbols that do not exist in the parsed spec. ' + + 'Fix the reference in the source `scripts/
/*.rst` page ' + + '(or add the missing symbol to `scripts/
/*.yml`).\n', + }, + { + path: 'docs/doxygen-warnings.log', + what: n => `Doxygen reported **${n}** unresolved documentation ${n === 1 ? 'reference' : 'references'}`, + hint: '> Line numbers refer to the **generated** headers. Fix the source ' + + 'YAML in `scripts/
/*.yml` instead.\n' + + '> To reference a struct member write ``` `memberName` member of ' + + '$x_some_struct_t ``` rather than `$x_some_struct_t.memberName`.\n', + }, + { + path: 'docs/sphinx-warnings.log', + what: n => `Sphinx reported **${n}** ${n === 1 ? 'warning' : 'warnings'}`, + hint: '> Paths refer to the **generated** `docs/source` pages. Fix the source ' + + '`scripts/
/*.rst` page or `scripts/templates/*.mako` template. ' + + 'An `undefined label` usually means a `:ref:` target page is missing.\n', + }, + ]; - if (!fs.existsSync(path) || !fs.readFileSync(path, 'utf8').trim()) { - core.info('No doxygen warning log; documentation generation failed for another reason.'); - return; - } - - // Strip the runner's absolute workspace prefix so paths read as repo-relative. - let lines = fs.readFileSync(path, 'utf8') - .split('\n') - .filter(l => l.trim()) - .map(l => l.replace(`${process.env.GITHUB_WORKSPACE}/`, '')); - - const total = lines.length; const MAX = 50; - const shown = lines.slice(0, MAX); - const omitted = total - shown.length; + let posted = false; + for (const r of reports) { + if (!fs.existsSync(r.path) || !fs.readFileSync(r.path, 'utf8').trim()) continue; - let body = '## ❌ Documentation build failed\n\n'; - body += `Doxygen reported **${total}** unresolved documentation `; - body += `${total === 1 ? 'reference' : 'references'}:\n\n`; - body += '```\n' + shown.join('\n') + '\n```\n'; - if (omitted > 0) { - body += `\n_…and ${omitted} more. See the workflow log for the full list._\n`; - } - body += '\n> Line numbers refer to the **generated** headers. Fix the source '; - body += 'YAML in `scripts/
/*.yml` instead.\n'; - body += '> To reference a struct member write ``` `memberName` member of '; - body += '$x_some_struct_t ``` rather than `$x_some_struct_t.memberName`.\n'; + // Strip the runner's absolute workspace prefix so paths read as repo-relative. + const lines = fs.readFileSync(r.path, 'utf8') + .split('\n') + .filter(l => l.trim()) + .map(l => l.replace(`${process.env.GITHUB_WORKSPACE}/`, '')); + const shown = lines.slice(0, MAX); + const omitted = lines.length - shown.length; - core.summary.addRaw(body).write(); + let body = '## ❌ Documentation build failed\n\n'; + body += `${r.what(lines.length)}:\n\n`; + body += '```\n' + shown.join('\n') + '\n```\n'; + if (omitted > 0) { + body += `\n_…and ${omitted} more. See the workflow log for the full list._\n`; + } + body += '\n' + r.hint; - if (context.eventName === 'pull_request') { - await github.rest.issues.createComment({ - issue_number: context.payload.pull_request.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: body - }); + core.summary.addRaw(body).write(); + if (context.eventName === 'pull_request') { + await github.rest.issues.createComment({ + issue_number: context.payload.pull_request.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: body + }); + } + posted = true; } - - # RST generation (generate_docs.py) resolves the symbols referenced in the - # hand-authored scripts/
/*.rst pages and sample code. An unresolved - # reference is collected via util.makeError and fails run.py in phase 3 -- before - # doxygen runs -- with the actionable lines saved to docs/rst-errors.log. - - name: Report reference errors - if: steps.gen_docs.outcome == 'failure' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const fs = require('fs'); - const path = 'docs/rst-errors.log'; - - if (!fs.existsSync(path) || !fs.readFileSync(path, 'utf8').trim()) { - core.info('No RST error log; documentation generation failed for another reason.'); - return; - } - - // Strip the runner's absolute workspace prefix so paths read as repo-relative. - let lines = fs.readFileSync(path, 'utf8') - .split('\n') - .filter(l => l.trim()) - .map(l => l.replace(`${process.env.GITHUB_WORKSPACE}/`, '')); - - const total = lines.length; - const MAX = 50; - const shown = lines.slice(0, MAX); - const omitted = total - shown.length; - - let body = '## ❌ Documentation build failed\n\n'; - body += `Generation reported **${total}** unresolved `; - body += `${total === 1 ? 'reference' : 'references'} in the spec RST/sample code:\n\n`; - body += '```\n' + shown.join('\n') + '\n```\n'; - if (omitted > 0) { - body += `\n_…and ${omitted} more. See the workflow log for the full list._\n`; - } - body += '\n> These reference symbols that do not exist in the parsed spec. '; - body += 'Fix the reference in the source `scripts/
/*.rst` page '; - body += '(or add the missing symbol to `scripts/
/*.yml`).\n'; - - core.summary.addRaw(body).write(); - - if (context.eventName === 'pull_request') { - await github.rest.issues.createComment({ - issue_number: context.payload.pull_request.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: body - }); + if (!posted) { + core.info('No documentation error log; generation failed for another reason.'); } - name: Fail if documentation generation failed @@ -303,7 +273,7 @@ jobs: echo "Prepared documentation in directory: $DIR_NAME" - name: Checkout gh-pages branch - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: gh-pages path: gh-pages-repo diff --git a/.github/workflows/loader-integration.yml b/.github/workflows/loader-integration.yml index a6627c25..5e7fd33e 100644 --- a/.github/workflows/loader-integration.yml +++ b/.github/workflows/loader-integration.yml @@ -39,14 +39,14 @@ jobs: echo "=== Disk ===" df -h --output=target,size,used,avail,pcent | grep -E "^Filesystem|^/$|^/home|^/tmp" - name: Checkout spec-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true fetch-depth: 0 fetch-tags: true path: spec-head - name: Checkout spec-base - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: master clean: true @@ -58,7 +58,7 @@ jobs: run: echo "sha=$(git -C spec-base rev-parse HEAD)" >> $GITHUB_OUTPUT - name: Restore spec-base artifacts cache id: cache-spec-base - uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: | spec-base/docs @@ -85,6 +85,8 @@ jobs: VER=$(echo "$LATEST_TAG" | grep -oP '^v\K[0-9]+\.[0-9]+') echo "Detected version: $VER (from tag $LATEST_TAG)" echo "VER=$VER" >> $GITHUB_ENV + # Docs warnings are gated (and reported) once, by deploy-docs.yml; here they must not + # stop the loader/ABI diffs. - name: Generate spec-head artifacts run: | #bash docker run \ @@ -93,7 +95,7 @@ jobs: -w $PWD/spec-head/scripts \ -e TZ=UTC \ ghcr.io/oneapi-src/spec-build:latest \ - /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' --ver $VER + /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' '--!warnings_as_errors' --ver $VER - name: Generate spec-base artifacts if: steps.cache-spec-base.outputs.cache-hit != 'true' run: | #bash @@ -103,7 +105,7 @@ jobs: -w $PWD/spec-base/scripts \ -e TZ=UTC \ ghcr.io/oneapi-src/spec-build:latest \ - /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' --ver $VER + /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' '--!warnings_as_errors' --ver $VER - name: Determine if there is a diff between header files id: include-diff # Keep --no-index. Other workflows can leave a .git in the shared runner @@ -135,7 +137,7 @@ jobs: # HTTP(S)_PROXY settings and the upload fails with ECONNRESET. v7.0.1 # reworked the upload path and uploads successfully through the proxy, so # every artifact upload in this job is pinned to v7.0.1. - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 if: steps.include-diff.outputs.diff == '1' id: upload-diff-artifact with: @@ -146,7 +148,7 @@ jobs: run: echo 'Artifact URL is ${{ steps.upload-diff-artifact.outputs.artifact-url }}' - name: Write comment to PR if: steps.include-diff.outputs.diff == '1' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -178,7 +180,7 @@ jobs: diff_comment = f"```diff\n{diff_content}\n```" with open('rst_results_comment.txt', 'w') as results_file: results_file.write(diff_comment) - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 if: steps.rst-diff.outputs.diff == '1' id: upload-rst-diff-artifact with: @@ -189,7 +191,7 @@ jobs: run: echo 'RST Artifact URL is ${{ steps.upload-rst-diff-artifact.outputs.artifact-url }}' - name: Write RST diff comment to PR if: steps.rst-diff.outputs.diff == '1' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -221,7 +223,7 @@ jobs: diff_comment = f"```diff\n{diff_content}\n```" with open('html_results_comment.txt', 'w') as results_file: results_file.write(diff_comment) - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 if: steps.html-diff.outputs.diff == '1' id: upload-html-diff-artifact with: @@ -232,7 +234,7 @@ jobs: run: echo 'HTML Artifact URL is ${{ steps.upload-html-diff-artifact.outputs.artifact-url }}' - name: Write HTML diff comment to PR if: steps.html-diff.outputs.diff == '1' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -245,7 +247,7 @@ jobs: }); - name: Upload HTML documentation artifacts for preview if: steps.html-diff.outputs.diff == '1' - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 id: upload-html-docs with: name: html-documentation-preview @@ -255,7 +257,7 @@ jobs: retention-days: 30 - name: Comment with HTML preview info if: steps.html-diff.outputs.diff == '1' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -287,21 +289,19 @@ jobs: body: body }); - name: Checkout loader-head - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: oneapi-src/level-zero ref: master path: loader-head - token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} - name: Get loader master HEAD SHA # Fetch the current HEAD SHA of the loader master branch. This SHA is used # as the cache key for base.dump — so we only rebuild the base when master # has actually changed, not on every PR run. id: loader-master-sha - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: - github-token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} script: | const { data } = await github.rest.repos.getBranch({ owner: 'oneapi-src', @@ -322,20 +322,19 @@ jobs: # Note: save-always is deprecated — saving is handled by the explicit # actions/cache/save step at the end of the job using if: always(). id: cache-base-abi-dump - uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: base.dump key: base-abi-dump-${{ steps.loader-master-sha.outputs.sha }} restore-keys: | base-abi-dump- - name: Checkout loader-base - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: oneapi-src/level-zero ref: master path: loader-base - token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }} - name: json2src head run: | #bash docker run \ @@ -374,7 +373,7 @@ jobs: loader_diff_comment = f"```diff\n{loader_diff_content}\n```" with open('loader_results_comment.txt', 'w') as results_file: results_file.write(loader_diff_comment) - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 if: steps.loader-source-diff.outputs.diff == '1' id: upload-loader-diff-artifact with: @@ -385,7 +384,7 @@ jobs: run: echo 'Artifact URL is ${{ steps.upload-loader-diff-artifact.outputs.artifact-url }}' - name: Write loader diff comment to PR if: steps.loader-source-diff.outputs.diff == '1' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -433,7 +432,7 @@ jobs: make -j$(nproc) EOF - name: Checkout abi-dumper - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true repository: lvc/abi-dumper @@ -488,7 +487,7 @@ jobs: - name: Restore abi-compliance-checker cache id: cache-acc - uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: abi-compliance-checker key: abi-compliance-checker-2.3 @@ -560,7 +559,7 @@ jobs: - name: Check for reviewer approval of ABI failure id: check-approval if: steps.abi-check.outcome == 'failure' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -583,7 +582,7 @@ jobs: console.log('No reviewer approval found for ABI failure'); core.setOutput('approved', 'false'); } - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 id: abi-report-artifact continue-on-error: true with: @@ -592,7 +591,7 @@ jobs: - name: Write loader ABI Report comment to PR continue-on-error: true if: "steps.loader-source-diff.outputs.diff == '1' || steps.include-diff.outputs.diff == '1' || steps.rst-diff.outputs.diff == '1' || steps.html-diff.outputs.diff == '1'" - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -616,7 +615,7 @@ jobs: }); - name: Save spec-base artifacts cache if: always() && steps.cache-spec-base.outputs.cache-primary-key != '' && steps.cache-spec-base.outputs.cache-hit != 'true' - uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: | spec-base/docs @@ -624,7 +623,7 @@ jobs: key: ${{ steps.cache-spec-base.outputs.cache-primary-key }} - name: Save abi-compliance-checker cache if: always() && steps.cache-acc.outputs.cache-primary-key != '' && steps.cache-acc.outputs.cache-hit != 'true' - uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: abi-compliance-checker key: ${{ steps.cache-acc.outputs.cache-primary-key }} @@ -638,7 +637,7 @@ jobs: # The hashFiles guard ensures we never cache a missing base.dump under the # master-SHA key (which would poison subsequent runs on a false cache hit). if: always() && steps.cache-base-abi-dump.outputs.cache-primary-key != '' && steps.cache-base-abi-dump.outputs.cache-hit != 'true' && hashFiles('base.dump') != '' - uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: base.dump key: ${{ steps.cache-base-abi-dump.outputs.cache-primary-key }} diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 3d35c328..0ceae1db 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -36,12 +36,12 @@ jobs: steps: - name: "Checkout code" - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: "Run analysis" - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4 + uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0 with: results_file: results.sarif results_format: sarif @@ -63,7 +63,7 @@ jobs: # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF # format to the repository Actions tab. - name: "Upload artifact" - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: SARIF file path: results.sarif @@ -71,6 +71,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: "Upload to code-scanning" - uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2 + uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3 with: sarif_file: results.sarif diff --git a/.github/workflows/spec-validate.yml b/.github/workflows/spec-validate.yml index 4a01427f..4e302e34 100644 --- a/.github/workflows/spec-validate.yml +++ b/.github/workflows/spec-validate.yml @@ -42,7 +42,7 @@ jobs: if: github.repository_owner == 'intel-innersource' steps: - name: Checkout - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: clean: true # Full history + tags: the spec version is derived from the most recent tag. @@ -98,7 +98,7 @@ jobs: - name: Report validation failure if: steps.generate.outcome == 'failure' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -183,7 +183,7 @@ jobs: # PR does not keep showing an obsolete error at the top of the thread. - name: Resolve previous failure comment if: steps.generate.outcome == 'success' && github.event_name == 'pull_request' - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | diff --git a/scripts/core/copy.yml b/scripts/core/copy.yml index a22db1e7..56b847eb 100644 --- a/scripts/core/copy.yml +++ b/scripts/core/copy.yml @@ -149,6 +149,7 @@ returns: - $X_RESULT_ERROR_UNSUPPORTED_ALIGNMENT - $X_RESULT_ERROR_INVALID_SIZE: - "`(nullptr == phWaitEvents) && (0 < numWaitEvents)`" + - "`(0 == pattern_size) || (0 != (pattern_size & (pattern_size - 1)))`" - "`size % pattern_size != 0`" --- #-------------------------------------------------------------------------- type: function @@ -203,6 +204,7 @@ returns: - $X_RESULT_ERROR_UNSUPPORTED_ALIGNMENT - $X_RESULT_ERROR_INVALID_SIZE: - "`(nullptr == phWaitEvents) && (0 < numWaitEvents)`" + - "`(0 == pattern_size) || (0 != (pattern_size & (pattern_size - 1)))`" - "`size % pattern_size != 0`" - $X_RESULT_ERROR_UNSUPPORTED_FEATURE: - "an extension passed via pNext is not supported" diff --git a/scripts/generate_docs.py b/scripts/generate_docs.py index f2cbbb53..e2a45247 100644 --- a/scripts/generate_docs.py +++ b/scripts/generate_docs.py @@ -230,6 +230,9 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta): # build log. Written under docs/, which is gitignored. DOXYGEN_WARNINGS_FILENAME = "doxygen-warnings.log" +# Same idea for sphinx-build: its -w option copies just the warnings to this file. +SPHINX_WARNINGS_FILENAME = "sphinx-warnings.log" + """ Collect enum values whose version exceeds their enum's version (i.e. added to an already-existing enum) into _ETOR_SINCE, keyed by the C enumerator name exactly as @@ -809,7 +812,7 @@ def generate_common(dstpath, sections, ver, rev, versions_url, warnings_as_error Entry-point: generate HTML files using reStructuredText (rst) and Doxygen template """ -def generate_html(dstpath): +def generate_html(dstpath, warnings_as_errors=True): sourcepath = os.path.join(dstpath, "source") print("Generating HTML...") @@ -817,12 +820,28 @@ def generate_html(dstpath): # so it works correctly when invoked via a virtualenv (e.g. /opt/spec-venv). sphinx_build = os.path.join(os.path.dirname(sys.executable), "sphinx-build") cmdline = "%s -M html %s ../docs -j auto" % (sphinx_build, sourcepath) + + # Drop any log from a previous run so CI can never quote stale diagnostics. + warnlog = os.path.join(dstpath, SPHINX_WARNINGS_FILENAME) + if util.exists(warnlog): + os.remove(warnlog) + cmdline += " -w %s" % warnlog + if warnings_as_errors: + # --keep-going reports every warning, not just the first, before failing. + cmdline += " -W --keep-going" + else: + print(" WARNING: sphinx warnings-as-errors DISABLED (--!warnings_as_errors)") + print(cmdline) os.environ["PYTHONWARNINGS"] = "ignore" rc = os.waitstatus_to_exitcode(os.system(cmdline)) os.environ.pop("PYTHONWARNINGS") if rc > 0: - raise Exception("sphinx-build returned %d"%rc) + raise Exception( + "sphinx-build returned %d.\n" + "A WARNING above such as \"undefined label\" is a broken :ref: link in a page " + "generated from scripts/
/*.rst -- fix the label or add the missing page.\n" + "As a last resort, re-run with --!warnings_as_errors." % rc) # Annotate later-added enum values with "(since vX)" in the final HTML. Done here # (on pinned Breathe/Sphinx output) rather than on Doxygen's XML for cross-env parity. diff --git a/scripts/run.py b/scripts/run.py index 67a3133b..f74eb9c3 100755 --- a/scripts/run.py +++ b/scripts/run.py @@ -312,7 +312,7 @@ def main(): # phase 6: publish documentation if args['html']: - generate_docs.generate_html(docpath) + generate_docs.generate_html(docpath, args['warnings_as_errors']) produced = ( (["rst"] if args["rst"] else []) + diff --git a/scripts/sysman/common.yml b/scripts/sysman/common.yml index 248d7217..9b35fd52 100644 --- a/scripts/sysman/common.yml +++ b/scripts/sysman/common.yml @@ -312,14 +312,6 @@ etors: value: "0x00020023" desc: $s_info_log_read_status_ext_t version: "1.19" - - name: PCI_CONFIG_EXT_PROPERTIES - value: "0x00020024" - desc: $s_pci_config_ext_properties_t - version: "1.20" - - name: DRIVER_PCI_DEVICE_PROPERTIES - value: "0x00020025" - desc: $s_driver_pci_device_properties_t - version: "1.20" --- #------------------------------------------------------------------------- type: struct desc: "Base for all properties types" diff --git a/scripts/sysman/device.yml b/scripts/sysman/device.yml index 2d69ed41..545ad341 100644 --- a/scripts/sysman/device.yml +++ b/scripts/sysman/device.yml @@ -410,9 +410,6 @@ etors: desc: "The link is up but has quality and/or bandwidth degradation" - name: STABILITY_ISSUES desc: "The link has stability issues and preventing workloads making forward progress" - - name: LINK_ERROR - desc: "The device does not respond on the bus and its configuration space reads back as all ones" - version: "1.20" --- #-------------------------------------------------------------------------- type: enum desc: "PCI link quality degradation reasons" diff --git a/scripts/sysman/pciConfig.yml b/scripts/sysman/pciConfig.yml deleted file mode 100644 index d038cf1b..00000000 --- a/scripts/sysman/pciConfig.yml +++ /dev/null @@ -1,128 +0,0 @@ -# -# Copyright (C) 2026 Intel Corporation -# -# SPDX-License-Identifier: MIT -# -# See YaML.md for syntax definition -# ---- #-------------------------------------------------------------------------- -type: header -desc: "Intel $OneApi Level-Zero Sysman APIs for PCI configuration space and driver PCI device properties" -version: "1.20" ---- #-------------------------------------------------------------------------- -type: macro -desc: "PCI Configuration Space Extension Name" -version: "1.20" -name: $S_PCI_CONFIG_EXT_NAME -value: '"$XS_extension_pci_config"' ---- #-------------------------------------------------------------------------- -type: enum -desc: "PCI Configuration Space Extension Version(s)" -version: "1.20" -name: $s_pci_config_ext_version_t -etors: - - name: "1_0" - value: "$X_MAKE_VERSION( 1, 0 )" - desc: "version 1.0" ---- #-------------------------------------------------------------------------- -type: enum -desc: "Supported PCI link speeds reported by $s_pci_config_ext_properties_t" -version: "1.20" -class: $sDevice -name: $s_pci_link_speed_ext_flags_t -etors: - - name: GEN1 - desc: "gen 1, 2.5 GT/s, is supported" - - name: GEN2 - desc: "gen 2, 5 GT/s, is supported" - - name: GEN3 - desc: "gen 3, 8 GT/s, is supported" - - name: GEN4 - desc: "gen 4, 16 GT/s, is supported" - - name: GEN5 - desc: "gen 5, 32 GT/s, is supported" - - name: GEN6 - desc: "gen 6, 64 GT/s, is supported" - - name: GEN7 - desc: "gen 7, 128 GT/s, is supported" ---- #-------------------------------------------------------------------------- -type: struct -desc: "Identification and link capability registers from the PCI configuration space." -version: "1.20" -class: $sDevice -name: $s_pci_config_ext_properties_t -base: $s_base_properties_t -members: - - type: uint16_t - name: "vendorId" - desc: "[out] The PCI vendor id of the device." - - type: uint16_t - name: "deviceId" - desc: "[out] The PCI device id of the device." - - type: uint16_t - name: "subsystemVendorId" - desc: "[out] The PCI subsystem vendor id of the device." - - type: uint16_t - name: "subsystemDeviceId" - desc: "[out] The PCI subsystem device id of the device." - - type: uint32_t - name: "pcieCapabilityVersion" - desc: "[out] The PCI Express capability version. Zero if the capability could not be read." - - type: $s_pci_link_speed_ext_flags_t - name: "supportedLinkSpeeds" - desc: "[out] The supported link speeds, a combination of $s_pci_link_speed_ext_flag_t. Zero if the capability could not be read." - - type: uint8_t - name: "revision" - desc: "[out] The PCI revision id of the device." -details: - - "This structure may be passed to $sDevicePciGetProperties via the `pNext` member of $s_pci_properties_t." - - "This structure is also passed to $sDriverGetPciDeviceProperties, so that PCI properties of supported devices can be queried before device enumeration." ---- #-------------------------------------------------------------------------- -type: struct -desc: "PCI device properties queried using $sDriverGetPciDeviceProperties" -version: "1.20" -class: $sDriver -name: $s_driver_pci_device_properties_t -base: $s_base_properties_t -members: - - type: $s_pci_address_t - name: "address" - desc: "[out] The BDF address of the device." - - type: $s_pci_speed_t - name: "maxSpeed" - desc: "[out] Fastest port configuration supported by the device (sum of all lanes). Each member is -1 when it could not be determined." - - type: $s_pci_config_ext_properties_t - name: "configProperties" - desc: "[out] The PCI configuration space properties of the device." - - type: $s_pci_link_status_t - name: "status" - desc: "[out] The link status of the device." ---- #-------------------------------------------------------------------------- -type: function -desc: "Get the PCI properties of every device supported by the driver that is present on the PCI bus" -version: "1.20" -class: $sDriver -name: GetPciDeviceProperties -details: - - "This function reports every device supported by the driver that is present on the PCI bus, whether or not a kernel mode driver is installed or bound to it." - - "SR-IOV virtual functions are not reported." - - "This function is supported when $sInit is called with $S_INIT_FLAG_NO_DEVICES." - - "The application may call this function from simultaneous threads." -params: - - type: $s_driver_handle_t - name: hDriver - desc: "[in] handle of the sysman driver instance" - - type: "uint32_t*" - name: pCount - desc: | - [in,out] pointer to the number of PCI devices. - if count is zero, then the driver shall update the value with the total number of PCI devices supported by the driver. - if count is greater than the number of PCI devices supported by the driver, then the driver shall update the value with the correct number of PCI devices supported by the driver. - - type: "$s_driver_pci_device_properties_t*" - name: pProperties - desc: | - [in,out][optional][range(0, *pCount)] array of PCI device properties. - if count is less than the number of PCI devices supported by the driver, then the driver shall only retrieve that number of PCI device properties. -returns: - - $X_RESULT_ERROR_INVALID_ARGUMENT: - - "`nullptr != pProperties[i].pNext`, as no extension structures are currently supported." diff --git a/scripts/tools/PROG.rst b/scripts/tools/PROG.rst index a6ec14c5..86e176ed 100644 --- a/scripts/tools/PROG.rst +++ b/scripts/tools/PROG.rst @@ -234,6 +234,16 @@ There are two modes of metrics collection supported: :ref:`time-based` are not supported by the Metrics APIs: + +- The notification event passed to ${t}MetricStreamerOpen and ${t}MetricTracerCreateExp must be a regular event created from a host visible event pool. It is signaled by the Driver from the host and reset by the application, and neither operation is allowed for a Counter Based Event. +- The completion event passed to ${t}CommandListAppendMetricQueryEnd must be a regular event. + +Passing a Counter Based Event to any of these functions returns ${X}_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT. + .. _Time-based: Metric Streamer diff --git a/scripts/tools/metric.yml b/scripts/tools/metric.yml index d7e1e215..c5be4f6a 100644 --- a/scripts/tools/metric.yml +++ b/scripts/tools/metric.yml @@ -333,6 +333,7 @@ name: Open decl: static details: - "The notification event must have been created from an event pool that was created using $X_EVENT_POOL_FLAG_HOST_VISIBLE flag." + - "The notification event must **not** be a Counter Based Event. The Driver signals the notification event from the host and the application resets it, neither of which is allowed for Counter Based Events. $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT is returned if `hNotificationEvent` is a Counter Based Event." - "The duration of the signal event created from an event pool that was created using $X_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality." - "The application must **not** call this function from simultaneous threads with the same device handle." params: @@ -558,6 +559,7 @@ details: - "The application must ensure the metric query and events are accessible by the device on which the command list was created." - "The application must ensure the command list, events and metric query were created on the same context." - "The duration of the signal event created from an event pool that was created using $X_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality." + - "`hSignalEvent` must **not** be a Counter Based Event. $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT is returned if `hSignalEvent` is a Counter Based Event." - "If numWaitEvents is zero, then all previous commands are completed prior to the execution of the query." - "If numWaitEvents is non-zero, then all phWaitEvents must be signaled prior to the execution of the query." - "This command blocks all following commands from beginning until the execution of the query completes." diff --git a/scripts/tools/metricTracer.yml b/scripts/tools/metricTracer.yml index 0cad56e5..9b85766b 100644 --- a/scripts/tools/metricTracer.yml +++ b/scripts/tools/metricTracer.yml @@ -81,6 +81,7 @@ name: CreateExp decl: static details: - "The notification event must have been created from an event pool that was created using $X_EVENT_POOL_FLAG_HOST_VISIBLE flag." + - "The notification event must **not** be a Counter Based Event. The Driver signals the notification event from the host and the application resets it, neither of which is allowed for Counter Based Events. $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT is returned if `hNotificationEvent` is a Counter Based Event." - "The duration of the signal event created from an event pool that was created using $X_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality." - "The application must **not** call this function from simultaneous threads with the same device handle." - "The metric tracer is created in disabled state"