mirokaku/musa.veil/veil-update

Veil Update Skill

Overview

Veil is a Windows native API header library that synchronizes with phnt and adapts it to Veil's coding conventions.

Prerequisites

Update Workflow

Phase 1 — Prepare

1. Read VERSION_COMMIT for the current upstream commit hash.
2. Sparse-clone or pull winsiderss/systeminformer into .cache/systeminformer/.
3. Run git diff <old> <new> -- phnt/include/ to generate per-file diffs.
4. Identify which phnt files changed and map them to Veil headers (see File Mapping).

Phase 2 — Apply

For each changed phnt file that has a Veil mapping:

1. Read the diff section and the latest phnt source.
2. Read the current Veil header.
3. Apply new additions (functions, structs, enums, macros, typedefs) that don't

already exist in Veil.

1. Do not remove existing Veil content — only add or update.
2. Handle each change type as described below.

Phase 3 — Convert

Macro Conversion

Replace all PHNT_* macros with Veil equivalents:

Example:

// phnt:        #if (PHNT_VERSION >= PHNT_WINDOWS_10_RS1)
// Veil after:  #if (NTDDI_VERSION >= NTDDI_WIN10_RS1)

Nt Function Formatting

Add __kernel_entry before NTSYSCALLAPI for all Nt* syscall declarations. Ensure the closing ); has no leading spaces.

Before (phnt):

NTSYSCALLAPI
NTSTATUS
NTAPI
NtFlushKey(
    _In_ HANDLE KeyHandle
    );

After (Veil):

__kernel_entry NTSYSCALLAPI
NTSTATUS
NTAPI
NtFlushKey(
    _In_ HANDLE KeyHandle
);

Zw Function Pair

Immediately after each Nt* function, add the corresponding Zw* function:

_IRQL_requires_max_(PASSIVE_LEVEL)
NTSYSAPI
NTSTATUS
NTAPI
ZwFlushKey(
    _In_ HANDLE KeyHandle
);

Use _IRQL_requires_max_(PASSIVE_LEVEL) and NTSYSAPI for Zw functions.

Other Conversions

• static_assert → STATIC_ASSERT
• Replace phnt-style _Kernel_entry_ → Veil __kernel_entry
• Sync Zw parameter annotation fixes from upstream when applicable

Phase 4 — Validate

After each file update, run the build:

taskkill /f /im MSBuild.exe
Veil.Test/BuildAllTargets.cmd

Fix compilation errors before proceeding to the next file.

Phase 5 — Finalize

1. Update VERSION_COMMIT with the new upstream commit hash (hash only, no URL or date).
2. Report changes from ntmisc.h separately to the user.
3. Clean up .cache/ directory.

File Mapping

Unmapped (skip): nttypesafe.h, ntstrsafe.h, ntintsafe.h, ntd3dkmt.h

Code Conventions

File Header

Every Veil header starts with:

/*
 * PROJECT:   Veil
 * FILE:      Veil.System.<Module>.h
 * PURPOSE:   This file is part of Veil.
 *
 * LICENSE:   MIT License
 *
 * DEVELOPER: MeeSong (meesong@outlook.com)
 */
 
#pragma once
 
// Warnings which disabled for compiling
#if _MSC_VER >= 1200
#pragma warning(push)
#pragma warning(disable:4201)
#pragma warning(disable:4214)
#pragma warning(disable:4324)
#pragma warning(disable:4471)
#endif
 
VEIL_BEGIN()
 
// ... content ...
 
VEIL_END()
 
#if _MSC_VER >= 1200
#pragma warning(pop)
#endif

Kernel/User Mode Guards

#ifndef _KERNEL_MODE
// User-mode only definitions
#endif // !_KERNEL_MODE
 
#ifdef _KERNEL_MODE
// Kernel-mode only definitions
#endif // _KERNEL_MODE

Enum Definition

/**
 * Brief description.
 * \sa https://learn.microsoft.com/...
 */
typedef enum _ENUM_NAME
{
    EnumValue1, // ASSOCIATED_STRUCTURE_1
    EnumValue2, // ASSOCIATED_STRUCTURE_2
    MaxEnumValue
} ENUM_NAME;

Structure Definition

/**
 * Brief description.
 * \sa https://learn.microsoft.com/...
 */
typedef struct _STRUCTURE_NAME
{
    TYPE Field1;
    TYPE Field2;
    _Field_size_bytes_(Length) TYPE VariableField[1];
} STRUCTURE_NAME, *PSTRUCTURE_NAME;

Verification Checklist

• [ ] All PHNT_WINDOWS_* macros converted to NTDDI_*
• [ ] All Nt* functions have __kernel_entry attribute
• [ ] All Nt* functions have corresponding Zw* pairs
• [ ] Closing parentheses aligned (no leading spaces before );)
• [ ] No compilation errors in BuildAllTargets.cmd
• [ ] Definition order respects dependencies
• [ ] ntmisc.h changes reported separately
• [ ] VERSION_COMMIT updated
• [ ] .cache/ cleaned up

Error Handling

Communication

• All interactions with the user: Chinese
• All documents/AI-readable content: English