linux-kernel - [PATCH 0/5] x86/sgx: Fix kernel-doc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20251112160708.1343355-1-seanjc@google.com>
Date: Wed, 12 Nov 2025 08:07:03 -0800
From: Sean Christopherson <seanjc@...gle.com>
To: Jarkko Sakkinen <jarkko@...nel.org>, Thomas Gleixner <tglx@...utronix.de>, 
	Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>, 
	Dave Hansen <dave.hansen@...ux.intel.com>, x86@...nel.org
Cc: linux-sgx@...r.kernel.org, linux-kernel@...r.kernel.org, 
	Stephen Rothwell <sfr@...b.auug.org.au>, Sean Christopherson <seanjc@...gle.com>
Subject: [PATCH 0/5] x86/sgx: Fix kernel-doc warnings

Fix a pile of kernel-doc warnings in the SGX code that have been hiding for
years, and were discovered after recent fix for "make htmldocs"[*].

Note, processing arch/x86/include/asm/sgx.h will still generate several
warnings, but nothing actually processes arch/x86/include/asm/sgx.h today,
and documenting a bunch of reserved fields seems to be counter-productive.
(I found and fixed a few asm/sgx.h issues because I included the header in
an .rst file to figure out why htmldocs warned about SGX_PAGE_MEASURE not
being documented, but not all the other enums that used the same syntax).

  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved1' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved2' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved3' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved4' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:243 struct member 'reserved' not described in 'sgx_tcs'
  WARNING: ./arch/x86/include/asm/sgx.h:319 struct member 'reserved' not described in 'sgx_secinfo'
  WARNING: ./arch/x86/include/asm/sgx.h:338 struct member 'secinfo' not described in 'sgx_pcmd'
  WARNING: ./arch/x86/include/asm/sgx.h:338 struct member 'reserved' not described in 'sgx_pcmd'
  WARNING: ./arch/x86/include/asm/sgx.h:360 struct member 'reserved1' not described in 'sgx_sigstruct_header'
  WARNING: ./arch/x86/include/asm/sgx.h:386 struct member 'reserved2' not described in 'sgx_sigstruct_body'
  WARNING: ./arch/x86/include/asm/sgx.h:386 struct member 'reserved3' not described in 'sgx_sigstruct_body'
  WARNING: ./arch/x86/include/asm/sgx.h:410 struct member 'reserved4' not described in 'sgx_sigstruct'

https://lore.kernel.org/all/20251104215502.1049817-1-andriy.shevchenko@linux.intel.com

Sean Christopherson (5):
  x86/sgx: Add a missing colon in kernel-doc markup for "struct
    sgx_enclave_run"
  x86/sgx: Add kernel-doc descriptions for params passed to vDSO user
    handler
  x86/sgx: Document structs and enums with '@', not '%'
  x86/sgx: Remove superfluous asterisk from copyright comment in
    asm/sgx.h
  x86/sgx: Fix a typo in the kernel-doc comment for enum sgx_attribute

 arch/x86/include/asm/sgx.h      | 64 ++++++++++++++++-----------------
 arch/x86/include/uapi/asm/sgx.h | 10 ++++--
 2 files changed, 40 insertions(+), 34 deletions(-)


base-commit: 19e2126bba55df9de15d9100b922df1dad6d39a4
-- 
2.51.2.1041.gc1ab5b90ca-goog