@@ -301,6 +301,7 @@ File: libffi.info, Node: Types, Next: Multiple ABIs, Prev: Simple Example, U
301301* Type Example:: Structure type example.
302302* Complex:: Complex types.
303303* Complex Type Example:: Complex type example.
304+ * Vector Types:: Vector (SIMD) types.
304305
305306
306307File: libffi.info, Node: Primitive Types, Next: Structures, Up: Types
@@ -660,7 +661,7 @@ functions ‘ffi_prep_cif’ and ‘ffi_prep_args’ abort the program if they
660661encounter a complex type.
661662
662663
663- File: libffi.info, Node: Complex Type Example, Prev: Complex, Up: Types
664+ File: libffi.info, Node: Complex Type Example, Next: Vector Types, Prev: Complex, Up: Types
664665
6656662.3.7 Complex Type Example
666667--------------------------
@@ -746,6 +747,92 @@ compilers that support them:
746747 The new type descriptors can then be used like one of the built-in
747748type descriptors in the previous example.
748749
750+
751+ File: libffi.info, Node: Vector Types, Prev: Complex Type Example, Up: Types
752+
753+ 2.3.8 Vector Types
754+ ------------------
755+
756+ ‘libffi’ can marshal vector (SIMD) types -- the values produced by GCC's
757+ ‘__attribute__((vector_size (N)))’ and Clang's ‘ext_vector_type’ -- on
758+ the platforms listed in the support table below. A vector is described
759+ just like a structure, except that every element pointer refers to the
760+ _same_ fundamental scalar type and the number of elements is the number
761+ of vector lanes.
762+
763+ -- Data type: ffi_type
764+ ‘size_t size’
765+ This must be set to ‘0’. ‘libffi’ computes the storage size
766+ (see below) from the element type and lane count.
767+
768+ ‘unsigned short alignment’
769+ This must be set to ‘0’. ‘libffi’ computes the alignment.
770+
771+ ‘unsigned short type’
772+ For a vector type, this must be set to ‘FFI_TYPE_VECTOR’.
773+
774+ ‘ffi_type **elements’
775+ This is a ‘NULL’-terminated array of pointers to ‘ffi_type’
776+ objects. Every entry must point to the same scalar element
777+ type, and the number of entries is the vector's lane count N
778+ (N >= 1). The element type must be one of ‘ffi_type_float’,
779+ ‘ffi_type_double’, or a fixed-width integer (‘ffi_type_uint8’
780+ through ‘ffi_type_sint64’); ‘long double’ and aggregate
781+ element types are not permitted.
782+
783+ Computed layout
784+ ...............
785+
786+ Because the caller leaves ‘size’ and ‘alignment’ at ‘0’, ‘libffi’
787+ derives them so that applications need not encode compiler- or
788+ platform-specific rules:
789+
790+ • ‘size’ is lane\_size \times N rounded _up_ to the next power of
791+ two. This matches Clang's ‘ext_vector_type’ storage -- for example
792+ a three-lane ‘float’ vector occupies 16 bytes and a three-lane
793+ ‘double’ vector occupies 32 bytes. GCC's ‘vector_size’ already
794+ requires power-of-two byte totals, so the rule is identical there.
795+
796+ • ‘alignment’ is ‘min(size, 16)’.
797+
798+ If the element list is heterogeneous, empty, or uses a disallowed
799+ element type, ‘ffi_prep_cif’ returns ‘FFI_BAD_TYPEDEF’.
800+
801+ psABI framing
802+ .............
803+
804+ At the call boundary the platform's processor-specific ABI (AAPCS64 on
805+ AArch64, the System V x86-64 psABI on x86-64) decides how a vector is
806+ passed and returned, independently of which compiler produced it. The
807+ historical divergence between GCC's ‘vector_size’ and Clang's
808+ ‘ext_vector_type’ concerns only in-memory _layout_ (notably the padding
809+ of odd-lane vectors such as ‘float3’); the power-of-two size rule above
810+ pins that layout down, so a value marshalled by ‘libffi’ matches what a
811+ natively compiled caller or callee expects.
812+
813+ Per-port support
814+ ................
815+
816+ Port Vector support
817+ --------------------------------------------------------------------------
818+ AArch64 (AAPCS64) 8- and 16-byte vectors in a single V/Q register;
819+ homogeneous vector aggregates (structs of up to
820+ four identical 8- or 16-byte vectors) in
821+ consecutive V/Q registers. A bare vector larger
822+ than 16 bytes (for example a 32-byte ‘double4’)
823+ has no short-vector register class and is passed
824+ and returned in memory, exactly as AAPCS64 and
825+ current compilers do.
826+ x86-64 (System V 8- and 16-byte vectors in an SSE register (‘%xmm0’
827+ psABI) for returns). A bare vector larger than 16 bytes
828+ needs ‘%ymm’/‘%zmm’ register handling that this
829+ port does not yet implement, so ‘ffi_prep_cif’
830+ returns ‘FFI_BAD_TYPEDEF’ for it.
831+ Other ports Not supported: ‘ffi_prep_cif’ returns
832+ ‘FFI_BAD_TYPEDEF’ for any signature that mentions
833+ a vector type, including one nested inside a
834+ struct.
835+
749836
750837File: libffi.info, Node: Multiple ABIs, Next: Reusable Call Plans, Prev: Types, Up: Using libffi
751838
@@ -795,6 +882,14 @@ prepared ‘ffi_cif’.
795882 is harmless. The ‘ffi_cif’ the plan was built from is not
796883 affected.
797884
885+ -- Function: size_t ffi_call_plan_size (ffi_call_plan *PLAN)
886+ Returns the total number of bytes ‘libffi’ allocated for PLAN,
887+ including any internal argument-placement data it owns. Returns
888+ zero when PLAN is ‘NULL’. The result does not include the
889+ ‘ffi_cif’, which the caller owns. This is intended for embedders
890+ that account for the memory held by long-lived plans and would
891+ otherwise have to guess at the size of an opaque type.
892+
798893
799894File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Reusable Call Plans, Up: Using libffi
800895
@@ -1056,6 +1151,7 @@ Index
10561151* ffi_call_plan_alloc: Reusable Call Plans. (line 12)
10571152* ffi_call_plan_free: Reusable Call Plans. (line 32)
10581153* ffi_call_plan_invoke: Reusable Call Plans. (line 22)
1154+ * ffi_call_plan_size: Reusable Call Plans. (line 37)
10591155* ffi_closure_alloc: The Closure API. (line 19)
10601156* ffi_closure_free: The Closure API. (line 26)
10611157* FFI_CLOSURES: The Closure API. (line 13)
@@ -1075,6 +1171,8 @@ Index
10751171* ffi_type <1>: Structures. (line 10)
10761172* ffi_type <2>: Complex. (line 15)
10771173* ffi_type <3>: Complex. (line 15)
1174+ * ffi_type <4>: Vector Types. (line 13)
1175+ * ffi_type <5>: Vector Types. (line 13)
10781176* ffi_type_complex_double: Primitive Types. (line 82)
10791177* ffi_type_complex_float: Primitive Types. (line 79)
10801178* ffi_type_complex_longdouble: Primitive Types. (line 85)
@@ -1101,6 +1199,7 @@ Index
11011199* ffi_type_void: Primitive Types. (line 10)
11021200* Foreign Function Interface: Introduction. (line 31)
11031201* size_t: The Basics. (line 125)
1202+ * size_t <1>: Reusable Call Plans. (line 37)
11041203* unsigned int: The Basics. (line 122)
11051204* unsigned long: The Basics. (line 117)
11061205* void: The Basics. (line 72)
@@ -1118,21 +1217,22 @@ Node: Using libffi4569
11181217Node: The Basics5172
11191218Node: Simple Example11346
11201219Node: Types12403
1121- Node: Primitive Types12914
1122- Node: Structures15231
1123- Node: Size and Alignment16342
1124- Node: Arrays Unions Enums18613
1125- Node: Type Example21590
1126- Node: Complex22896
1127- Node: Complex Type Example24410
1128- Node: Multiple ABIs27462
1129- Node: Reusable Call Plans27849
1130- Node: The Closure API29566
1131- Node: Closure Example33908
1132- Node: Thread Safety35552
1133- Node: Memory Usage36385
1134- Node: Missing Features37660
1135- Node: Index38037
1220+ Node: Primitive Types12967
1221+ Node: Structures15284
1222+ Node: Size and Alignment16395
1223+ Node: Arrays Unions Enums18666
1224+ Node: Type Example21643
1225+ Node: Complex22949
1226+ Node: Complex Type Example24463
1227+ Node: Vector Types27536
1228+ Node: Multiple ABIs31575
1229+ Node: Reusable Call Plans31962
1230+ Node: The Closure API34155
1231+ Node: Closure Example38497
1232+ Node: Thread Safety40141
1233+ Node: Memory Usage40974
1234+ Node: Missing Features42249
1235+ Node: Index42626
11361236
11371237End Tag Table
11381238
0 commit comments