[PATCH] D117296: Document several clang-supported builtins

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

Thanks for this new documentation! I'm by no means an expert in these builtins, so I had some questions on places we might want to expand things a bit more.



================
Comment at: clang/docs/LanguageExtensions.rst:2183
+                        n * sizeof(float),
+                        8 * alignof(float));
+    init(mem, n);
----------------



================
Comment at: clang/docs/LanguageExtensions.rst:2569-2570
+
+``__builtin_expect`` is used to indicate that an expression is expected (I;e.
+very likely to) take a given value.
+
----------------



================
Comment at: clang/docs/LanguageExtensions.rst:2588
+
+The ``__builtin_expect()`` builtin is expected to be used with control flow
+conditions such as in ``if`` and ``switch`` statements to help branch
----------------



================
Comment at: clang/docs/LanguageExtensions.rst:2617
+
+The ``__builtin_expect_with_probability()`` builtin is expected to be used with control flow
+conditions such as in ``if`` and ``switch`` statements to help branch
----------------



================
Comment at: clang/docs/LanguageExtensions.rst:2620
+prediction. It means that its first argument ``expr`` is expected to take the
+value of its second argument ``val`` with probability ``p``. It always returns ``expr``.
+
----------------
Should we mention that the probability should be specified as a value between [0.0, 1.0]?


================
Comment at: clang/docs/LanguageExtensions.rst:2627-2628
+
+``__builtin_prefetch`` is used to communicate with the cache handler and bring
+data in cache before it gets used.
+
----------------



================
Comment at: clang/docs/LanguageExtensions.rst:2647-2648
+are going to be used next. ``addr`` is the address that needs to be brought into
+the cache. ``rw`` indicates the expected access mode: ``0`` for *read* and ``1``
+for *write*. ``locality`` indicates the expected persistance of data in cache,
+from ``0`` which means that data can be discarded from cache after its next use
----------------
Is there a way to specify both read and write at the same time? Or does write access imply read access? (If so, it'd be good to make that explicit.)


================
Comment at: clang/docs/LanguageExtensions.rst:2649-2650
+for *write*. ``locality`` indicates the expected persistance of data in cache,
+from ``0`` which means that data can be discarded from cache after its next use
+to ``3`` which means that data is going to be resued a lot once in cache.
+
----------------
How do users know whether to pick `1` or `2`? Should we list the values in table form with some prose describing when to use each value?


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D117296/new/

https://reviews.llvm.org/D117296