clang/test/TableGen/builtin-docs.td

// RUN: clang-tblgen -gen-builtin-docs -I%p/../../include %s -o - 2>&1 | \
// RUN:    FileCheck %s

// Test that the Undocumented category always sorts after all documented
// categories, even when its name would come earlier alphabetically (e.g.
// "Undocumented" < "Work-Item Builtins").
// RUN: clang-tblgen -gen-builtin-docs -I%p/../../include %s -o - 2>&1 | \
// RUN:    FileCheck --check-prefix=CAT-ORDER %s
// CAT-ORDER:     ABI Builtins
// CAT-ORDER:     Instruction Builtins
// CAT-ORDER:     Work-Item Builtins
// CAT-ORDER:     Undocumented

// Test that mismatched ArgNames count produces an error.
// RUN: not clang-tblgen -gen-builtin-docs -I%p/../../include %s -o - \
// RUN:    -DERROR_ARGNAMES_MISMATCH 2>&1 | \
// RUN:    FileCheck --check-prefix=ERROR-MISMATCH %s

include "clang/Basic/BuiltinsBase.td"

//===----------------------------------------------------------------------===//
// Test categories
//===----------------------------------------------------------------------===//

def DocCatTestABI : DocumentationCategory<"ABI Builtins"> {
  let Content = [{
These builtins provide access to ABI-related information.
}];
}

def DocCatTestWorkItem : DocumentationCategory<"Work-Item Builtins"> {
  let Content = [{
These builtins return work-item identification.
}];
}

def DocCatTestInstruction : DocumentationCategory<"Instruction Builtins"> {
  let Content = [{
These builtins map to specific hardware instructions.
}];
}

//===----------------------------------------------------------------------===//
// Standalone documentation record (defined separately from the builtin)
//===----------------------------------------------------------------------===//

def TestDispatchPtrDoc : Documentation {
  let Category = DocCatTestABI;
  let Content = [{
Returns a pointer to the dispatch packet.
  }];
}

//===----------------------------------------------------------------------===//
// GlobalDocumentation (required by the emitter)
//===----------------------------------------------------------------------===//

def GlobalDocumentation {
  code Intro = [{..
  -------------------------------------------------------------------
  NOTE: This file is automatically generated by running clang-tblgen
  -gen-builtin-docs. Do not edit this file by hand!!
  -------------------------------------------------------------------

========================
Test Builtin Reference
========================
.. contents::
   :local:

Introduction
============

This is a test for builtin documentation generation.
}];
}

//===----------------------------------------------------------------------===//
// Test builtin class and definitions
//===----------------------------------------------------------------------===//

class TestBuiltin<string prototype> : TargetBuiltin {
  let Spellings = [NAME];
  let Prototype = prototype;
  let Features = "";
}

class TestBuiltinFeat<string prototype, string feat> : TargetBuiltin {
  let Spellings = [NAME];
  let Prototype = prototype;
  let Features = feat;
}

// --- Using a standalone documentation record (defined above) ---

let Documentation = [TestDispatchPtrDoc] in
def __builtin_test_dispatch_ptr : TestBuiltin<"void *()">;

// --- Using inline documentation records (defined next to the builtin) ---

// No arguments, address-space qualified return type.
def KernargPtrDocs : Documentation {
  let Category = DocCatTestABI;
  let Content = [{
Returns a pointer to the kernarg segment in constant address space.
  }];
}
def __builtin_test_kernarg_ptr : TestBuiltin<"void address_space<4> *()"> {
  let Documentation = [KernargPtrDocs];
}

// No arguments, scalar return, with target feature.
def WorkitemIdXDocs : Documentation {
  let Category = DocCatTestWorkItem;
  let Content = [{
Returns the work-item id in the x dimension.
  }];
}
def __builtin_test_workitem_id_x : TestBuiltinFeat<"unsigned int()", "some-feature"> {
  let Documentation = [WorkitemIdXDocs];
}

// Multiple float arguments with ArgNames and target feature.
def FmaDocs : Documentation {
  let Category = DocCatTestInstruction;
  let Content = [{
Performs a fused multiply-add: returns ``x * y + z``.
  }];
}
def __builtin_test_fma : TestBuiltinFeat<"float(float, float, float)", "fma-feature"> {
  let ArgNames = ["x", "y", "z"];
  let Documentation = [FmaDocs];
}

// Multiple unsigned int arguments with ArgNames.
def BfeDocs : Documentation {
  let Category = DocCatTestInstruction;
  let Content = [{
Performs a bitfield extract on a 32-bit integer.
  }];
}
def __builtin_test_bfe : TestBuiltin<"unsigned int(unsigned int, unsigned int, unsigned int)"> {
  let ArgNames = ["src", "offset", "width"];
  let Documentation = [BfeDocs];
}

// Void return with a single argument and ArgNames.
def FenceDocs : Documentation {
  let Category = DocCatTestInstruction;
  let Content = [{
Inserts a scheduling fence with the specified ordering.
  }];
}
def __builtin_test_fence : TestBuiltin<"void(unsigned int)"> {
  let ArgNames = ["ordering"];
  let Documentation = [FenceDocs];
}

// Mixed types with ArgNames and address_space in a parameter.
def StoreDocs : Documentation {
  let Category = DocCatTestInstruction;
  let Content = [{
Stores a value to the given global memory pointer.
  }];
}
def __builtin_test_store : TestBuiltin<"void(int, int address_space<1> *)"> {
  let ArgNames = ["val", "ptr"];
  let Documentation = [StoreDocs];
}

// Variadic function with ArgNames (only named params should be listed).
def PrintfDocs : Documentation {
  let Category = DocCatTestInstruction;
  let Content = [{
Prints formatted output to the console.
  }];
}
def __builtin_test_printf : TestBuiltin<"int(char address_space<4> *, ...)"> {
  let ArgNames = ["fmt"];
  let Documentation = [PrintfDocs];
}

// This builtin uses default Undocumented documentation (no ArgNames).
def __builtin_test_undocumented : TestBuiltin<"void()">;

// This builtin has no "let Documentation" at all -- the most common case for
// existing builtins. It should still work and land in the Undocumented section.
def __builtin_test_no_doc : TestBuiltin<"int(int, int)">;

// CHECK: Test Builtin Reference
// CHECK: This is a test for builtin documentation generation.

// --- ABI Builtins (sorted first alphabetically) ---
// CHECK:      ABI Builtins
// CHECK-NEXT: ============
// CHECK: These builtins provide access to ABI-related information.

// void pointer return, no args (standalone doc record).
// CHECK:      ``__builtin_test_dispatch_ptr``
// CHECK:      void * __builtin_test_dispatch_ptr()
// CHECK:      Returns a pointer to the dispatch packet.

// Address-space qualified pointer return, no args (inline doc).
// CHECK:      ``__builtin_test_kernarg_ptr``
// CHECK:      void address_space<4> * __builtin_test_kernarg_ptr()
// CHECK:      Returns a pointer to the kernarg segment in constant address space.

// --- Instruction Builtins ---
// CHECK:      Instruction Builtins
// CHECK-NEXT: ====================
// CHECK:      These builtins map to specific hardware instructions.

// Multiple unsigned int arguments with ArgNames.
// CHECK:      ``__builtin_test_bfe``
// CHECK:      unsigned int __builtin_test_bfe(unsigned int src, unsigned int offset, unsigned int width)
// CHECK:      Performs a bitfield extract on a 32-bit integer.

// Void return with single ArgName.
// CHECK:      ``__builtin_test_fence``
// CHECK:      void __builtin_test_fence(unsigned int ordering)
// CHECK:      Inserts a scheduling fence with the specified ordering.

// Multiple float arguments with ArgNames and target feature.
// CHECK:      ``__builtin_test_fma``
// CHECK:      float __builtin_test_fma(float x, float y, float z)
// CHECK:      **Target Features:** fma-feature
// CHECK:      Performs a fused multiply-add: returns ``x * y + z``.

// Variadic function with ArgNames -- named params then "...".
// CHECK:      ``__builtin_test_printf``
// CHECK:      int __builtin_test_printf(char address_space<4> * fmt, ...)
// CHECK:      Prints formatted output to the console.

// Mixed types with ArgNames including address_space in a parameter.
// CHECK:      ``__builtin_test_store``
// CHECK:      void __builtin_test_store(int val, int address_space<1> * ptr)
// CHECK:      Stores a value to the given global memory pointer.

// --- Work-Item Builtins (inline doc, no ArgNames) ---
// CHECK:      Work-Item Builtins
// CHECK-NEXT: ==================
// CHECK:      These builtins return work-item identification.
// CHECK:      ``__builtin_test_workitem_id_x``
// CHECK:      unsigned int __builtin_test_workitem_id_x()
// CHECK:      **Target Features:** some-feature
// CHECK:      Returns the work-item id in the x dimension.

// --- Undocumented (sorted last, after all documented categories) ---
// CHECK:      Undocumented
// CHECK-NEXT: ============

// Builtin with no "let Documentation" at all -- uses the class default.
// CHECK:      ``__builtin_test_no_doc``
// CHECK:      int __builtin_test_no_doc(int, int)
// CHECK:      No documentation.

// CHECK:      ``__builtin_test_undocumented``
// CHECK:      void __builtin_test_undocumented()
// CHECK:      No documentation.

//===----------------------------------------------------------------------===//
// Error test: ArgNames count mismatch
//===----------------------------------------------------------------------===//

#ifdef ERROR_ARGNAMES_MISMATCH
def MismatchDocs : Documentation {
  let Category = DocCatTestInstruction;
  let Content = [{This should error.}];
}
// ERROR-MISMATCH: error: number of ArgNames (2) does not match number of prototype parameters (3)
def __builtin_test_mismatch : TestBuiltin<"void(int, int, int)"> {
  let ArgNames = ["a", "b"];
  let Documentation = [MismatchDocs];
}
#endif