<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/59678>59678</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            Confusing/missing documentation for __builtin_shufflevector
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          lawben
      </td>
    </tr>
</table>

<pre>
    I've recently been playing around with `__builtin_shufflevector` (and `__builtin_shuffle` in GCC). GCC's `_builtin_shuffle` allows me to pass a vector and a mask `__builtin_shuffle(vec, mask);`. The [LLVM documentation on `_builtin_shufflevector`](https://clang.llvm.org/docs/LanguageExtensions.html#builtin-shufflevector) says that clang requires two vectors and then indixes to shuffle from them.

Only signature in documentation:
> ```__builtin_shufflevector(vec1, vec2, index1, index2, ...)```

Strictly following this signature and the examples further down in the documentation severely limits the use of `__builtin_shufflevector`, as all indexes must be known at compile time. However, the documentation omits the fact that `vec2` can be the mask and not just an input. I only found this by chance while looking at the [code that emits the vector shuffle code](https://github.com/llvm/llvm-project/blob/28b52abeec3c90c9826803c2caa03ed2096a7830/clang/lib/CodeGen/CGExprScalar.cpp#L1643-L1679).

So a valid signature would also be:
```__builtin_shufflevector(vec, mask); // vec and mask must have same type```

With this signature, the use is a lot closer to GCC's `__builtin_shuffle`, which allows me to write the following code snipptet to support both compilers.

```cpp
// 16 Byte vector of 4x uint32_t
using VecT __attribute__((vector_size(16))) = uint32_t;  

VecT shuffle_vector(VecT vec, VecT mask) {
#if GCC_COMPILER
  return __builtin_shuffle(vec, mask);
#else
  return __builtin_shufflevector(vec, mask);
#endif
}
```

Here is a short [godbolt example](https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1DIApACYAQuYukl9ZATwDKjdAGFUtAK4sGISQDspK4AMngMmAByPgBGmMQgAGykAA6oCoRODB7evv5BaRmOAmER0SxxCcl2mA5ZQgRMxAQ5Pn6Btpj2xQwNTQSlUbHxSbaNza15HQrjA%2BFDFSOJAJS2qF7EyOwc5gDM4cjeWADUJrtuMYQKAPQz6KaW1gB0CGfYJhoAgh%2BfXhlGxwAarVdmZVJJjgB9SFMAgEYh4GJeAiYaFQAButSIxEhGQAXpgIFwVstlqddgARY5ecIEUGQghnKxfH7A5Cg8HHBQILxUKj0SGYhwkCBsjkQoWkIEgsEQlhMBQAazJJgCzO%2BZn2VGOECwNAi6Ag0IA4pE5G5oSqzIlzIljmAwHr5oboYdDMBLcsfscfcdiJgCBsGFDIUi6I4GLieXz6BBJcd5Uqvbt1Xsukpvb7/YHiMHoWHaBGo7z%2BZghdi47UpYnlUyfmmGPgqPWAhT619aQmmOEICq1ZmfWLZccheSqaqLFwNFKzNPjrs55INKq2ynTl9fdL2cOa2PTmrdjOj8cuCumevPpuh5z1gQUsi99ySwLyyL4zXk%2BrN9drschAh1lodBjhSBFBBAY4lylBdoLnWcBy5Ah0BAFBb3JNwzjcY5b3vRkAFYLGXPDx3OTDTjMMwpXMMwL03Oi6MwsicOREwCNPYj0LI6iqIohD6M3Rjzmw5FcNYiwzFYkiMKE7jyIkjd%2BPowSsOY/CLF2STOKEu4UNcWg6xZVsOFWWhODw3g/A4LRSFQTgMMeSwuXWTZMHI3YeFIAhNGM1ZFRAXZdieALgpC0LklMjhJAs7ybM4XgFBAacvKs4zSDgWAYEQVCWBSOh4nISg0ByvKEjdIwuDwjRpywdE8C2QE8EwAB3AB5FJGE4DyaELeIEogGIYsuZhiAAT063girYQQWoYWgxpS0gsHlIxxAW/B/TqTEEoWzBVFqZFtms2kuhi2hEWIJoRo8LAYvhPAWHG1Z%2BSYYAFAa5q2o67heH4QQRDEdgpBkQRFBUdQFt0SiDCMFBrGsfREQSyBVlQFIem2gBaFrdmODH5U2V5KVEBRRCwAxFVc3G7jOCkHisSxZ3irosSyFxG0mPwuGCRtBnKSo9EKTIBA5gX0iFhheeGBIuZqOoBD6CZPDaPRZZ6BW5jKKWVdmEWZdmSXFml1YFGcrYJBMszooW2yOGOVQAA5EgxxIITK4ATzwp4NC9nVcEIEg3K4ZZeGSrRSVIPyAqC0KY4C/ROCi0gHsq0hLOsm34sSzzvNWdKstUgqICK3L6GISJWG2B2nZd443Y9r2vd4TB8GxPBkK537hFEcQgc70G1BiyHSCai6Uke%2BOOHM1OYptlqRIfVBtSr53Xeh92KobjQdQ8YrS7csxg%2BzlLw4QTAmCwBJewnxPk%2BnNPeAz2ws9DnyI/8wLY9j8LOF2K307io%2BYc0qZTzhAJAxcSqFwgaXEAwAuAUUWmWOqmB3qtXapZLq4ZeqUAGgtIal1xqkEmowAgM05oxSWu6Va1l1osy2jFXa%2B0UQxWOhFayZ0YgXVGtdQ6IcEQPW%2Bk9Awr1UGfQwT9WQ/0e7SD7koAeEM9Br1hg5GwHCkZX1RujTgWMcZ4yaMgQmtMFSky6EwCmPoMbUyJnDBm1lVaswgK4XW3N0AG35lzQWPRnGeKyG4kYMtmZy16DrJWeQAndHqPreYfN/FjH6M4mY/Q/FGzWBsM2QcJ5T3vrFW2y8a7AGQMgE8Zgng0QgH7bEgdD4v3DpHD%2Bn9QrX14Lfae1sAEJSSjnYB8AwEgALhQIuqBd7xHLmwTgeSIQFKKfA0pTcW4kDbnoTuUjAYyNkP3cG1ldBcxHkwMegjMl/wfpwOed4F5L0divY4UzimlO3kMku8QqkhxzqsU%2B58RhXwijfEAKdsmPw6YA1%2BdTo4NOChPX%2BrT/4cBecfC2HAzBHJybCsOqxMTEAyM4SQQA%3D%3D) that shows that this vector+mask signature is actually correct. It would be really helpful to add this to the documentation to make clear that clang also supports runtime masks in the shuffle.
</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJyUWF1zqsyT_zScG-pJwfCiXuRiBgFREREV8SY1wggoMMqAgJ9-C0zOOdnNs_vfqpQSpumXX_-66RYzlsYFIe-cgjhl-gvXVULL9ww3J1L8OtGoe7c4MHoQviQhKaqs40-EFPwtw11axDwuaV1EfJNWCc-pwsfHqU6zKi0-WFKfzxl5kLCiJacKPAfGuIh-FOqP04I3NY0Dk7fX94gNoj9I4iyjDeNzwleUv2HGeMy_zPC9AcznmF1_tgPGDxJyQBtEODDhJMSpwhu_TQjPKWi53Nt8RMM6J0WFq5QWPC1-cuN3VJwy5cA4qaob4yTIAYMDRpjhIn7Lskf-RsuYA0ZEQ8YBY4mLuMYx0duKFCylBXtLqjzjgPSp_Z_v2sGEZ7hjfJXgih-U8iW512lJGF819DNmNgRdJaTg0yJK2_6Q8p-a-HNJ8_4wf-OEKSfA16dTZB3f5x1XdUl66L8F3Ufykpb0PvrX37-ldsBU7EF9kBD032kRkVb8fTXce3t76_H-Uva3N15VpmFPrDPtM9uzqkpS9peDnxHypMX5LSOMP9dllZCSj2jThz0cfs8bIw9SkqzjszRPKzZI1Izw9Py_07T3FbOeYy_nCePzmlX8ifDXorfW54LmtzQjfJXm5I2f0aa31T_4P92gv42fcVi9UsmpwoCUKvAhLnrN_flA2j7Qglb8pTeJ-9BudfXGWzwtBnzqAYiU8aeODxNchIRvkt6VjNLrUI7VoIxTUEgj8rJHfvvwWSVf5OhFfiJwnFZJfXoLac4Bo-fx59c_t5JeSFhxwDhl9MQBA4xPCsAnQkIpnAjhZAzUsSCFIMRYkEgEhImKR2NJ-KqKXlHaP6jRiJik6K9Mvb2VXogzXL6FtxsHpKWoytI_S1EdTfp-8I0rtC92nKXRX_RoaJ1FPM4Y5U_kD3n_I-J-bwb8C4AeqCEXQ1KG_Cf4QXiG-6bT3ciPPPb7HviduV-k6JmX9n0qo30pU0bKvkr_bnQ_dLr-6SZJw-R7y2vKtHpx5k_BDNlmRXq7VaQaGkB9u9Gy4k-0Sr4IW7JvWP4Ookf9decVvajyqKt-04Weebnl67SoJPBRvSRr1lvdk3DLf3zgqirTU12Rjw8OjF-4VrT8YOmzb7mi2oM7_PGcNP2jSUI8_7dDg7rP8D9-J2m4-5mp4fozXTw3Ql9uS-m5B_NDc-y1tdQ3r_s8X5KqLgv-P3sRfOkiGSP_l4J_p9AfNUWUnj__G03_G-R_hz0j5Sc7WNKnjFNQTKMTzaqvhvdjkb5EPl8xHJCenASdYBkn0ED3SHG1FgbNOkC2lqNNhJbQEF0thHita9B-Nqiy4Qi6jVHZLurgJp4sKjfQYcfSk-AeoNaOEYILioothDs4uzXQfkAj2HrVPBanFrxBLYBuHdTXbHKE22a6uETQNHYVXMjMtDx3ym4LGdpFbOcQdesYmbntxtDsrhCqVKMbZ4pG5PFQEN7kDsz1jeC1rRZmIIfK0Y03dgtdZV2oqLpdQOs2q63rZbvTrPVOePXEojJzywvkgAKQMTU8Zw7nHrgbI71zmlCJp7YcXogPp7t5WdV24C7g2n2qC-yLMRI08xzMEwrjZFBwPiSZ2TYQl_soP-7n80uMJp5hw1gPEtmcE5gG2HAhqivPavXEdOHhFltGs2dVdo-iGG4ChYSWvjPdOCkW7Xk2gooWj2cz5FrLdre4CJ4ZJM1VQ-xydal_tfSY6W6W2MiF-Dmfx9rTGXw5FmBvOrrWrGCqwliwoHzTFVOh3v1pZU8ru-SwmZUKPdEgmtpoGbIzC89hlM5jDTHTmFq7VLVkc5mSw1NFaB5Gyu7-OFXigdXX2-M04oARzFJ7Rv0ZRiYdPV-G4yRK5dHuFhTZrjvnubmO72sfJltVnGA3zx3d0u7iMT_7y2MYJsS74_vSaFbG4rlaX0qmKNZqcQddsc0m52gJQgeD9TYvo4tzGYe1Vufksb7VifIUY3fH0smk85pl1y3l5-E6uFCuJlHJwgQmYkYjdEk8ZCAEAznrMhTRZeGHqFNgIiBooJM0XzXPSxgoJ-mxuUIjWJqH9bSVnO10e7Ht5naw7WYpSE6q2g1LQ2ejN9pqHVyEpaWmd4smU9WWNpdn3ihGuArS5mkE19Re6KNLZ10v0eDTmjYec4L-ZbU0gLd1Fnot71ahH6vtcc8cw_cTZ9pIfSFCebnxDHcb2zbxmvrgb4_2zJICYlgwWZm2eDQ28HCMUgKX8U0TltfMviRzyEbdyZYPsYEgDh8LJj-9aezDQHf3mo88J5ELy4sF1D0W-iWymnraXDa3ron0sQZcfaw3EEkQKcbc1OVph_UlsXQam1bA6mOSQrgVVClOy8B1fRr4cXvzhJjNMqttoc8BA3HA2N63uk79J9ob96NR5Qxc6yQFie5bc7qh4yUMHska-jNTPA7AeEEADYiVO6DqKCEz2XU3Uz2Kb-jqbgy0i1yjErx0qtkGKk123uiu16F95hoWyUGMsFFGuTOdKTuwVxZ7HW02WgNbYx9K5ujiaNdZyrz2KKUlZV5ntKaQr5va1DYVKhYeneiLrYWgEh-E1EgSQkxk1ce7Q9FU1Y7rKV5vjkcV-cplsfD3Ua77xyj3DkaeiYFhhmUwRzZ7UuqDzjGdvQuhosdta1nbhQy3z-Ymr7RJsQ91S4-lhXw8EtMrN97eWnfwrgmLQNY4YGwcLRXiGbsLydJhuSQz7_l8rPxowapdfLe0hbRUTcub-yZAoDhGsiwFkxI8InmLxma7RteFIo0SQw_dOBwJpojSbuZpOFV3VzLg7DgzW3SCW5XdN9Z5jyqvVKQDSSZgQU8XN3LHQemNQtbGg_gzWzayu4W51qA5aYp2_aqtYrUm8AkaNpkWncUBY9wsg8llvHQMsJCEUUoHsSAU7sftM4Fz2Ibe3WhifNBhA2u42_m579xzJN2rA74dl3f5SO47aMaVhTOxvV_1nDYwtgWFtp5fq3ssZiJlHbgYBzwoF3Zu6zuJgbujEMSHvVlFrmqFurv2h_PrBDaluDPPbrOd-C4HDIGMvOnoSiHR7QkqxSRWzGamXY8HcVNftrFvh0e5w3bs5pVteNdO1RstX1P7tOvmxRTlYrbHrIkX8sGXVgI0JSV7uv56U5hk0ZnyNbCr_NiJ6rSc-8SFRTS7r0sSnFccMIzLTLXlvK_93hfDfPqI2cAN58pWepSGD7oxHkHTtWN9fIyLWHDj2eikx9FUfkjT22z6Qn7ilgdRXp4xERnU5553KQI0ho0ew2XiWvUdRaN2tsybbUw8yzUWizMUbtvQl6_TU0G39e4Cg251XUuhKWYRCtvZtbFJfLEzDhjN-dY4JJINZSlE6SOQd880zxzpal_rsXu_Ju3zznaDJ8p4kxya9HLW4SJi-bpRAygOJ9GWyitHS9aHVyPecsCQQ0TCswZm8Ilm8-6kMefe2lsddrbsuW7_7pWmnx-T17bBkn5SHS6HWfhrUkLDLP3X0sl4HFY1zrKOD2lZkrBfdKrPYf5E-JIMZwnJbuc662daHH1uPxX9YdWqKJ_jK-HDjODy76V5WAw-52HGl3XR723DxMa-dsfPqe7tV_QuRRNpgn-Rd1EdiWMRqOLkV_KOVQyAosgjMonkkwyEiRiGZ3VyFggZk5P6K30HAgAiAJKoAkmavIVjUVSAPB6fxTOYhDInCyTHafb7h4FfKWM1eVcm6mj8K8MnkrGvH2HK92HdOtUx42QhS1nF_jxWpVVG3jVanIchnANGnrJhHP-Ox5mW_za3_qrL7P3_vfMN_jIOGIPL_xUAAP__bLz86A">