1 /*
2 * Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
1022 * These operations are:
1023 * <ul>
1024 *
1025 * <li>The {@link #slice(int,Vector) slice()} family of methods,
1026 * which extract contiguous slice of {@code VLENGTH} fields from
1027 * a given origin point within a concatenated pair of vectors.
1028 *
1029 * <li>The {@link #unslice(int,Vector,int) unslice()} family of
1030 * methods, which insert a contiguous slice of {@code VLENGTH} fields
1031 * into a concatenated pair of vectors at a given origin point.
1032 *
1033 * <li>The {@link #rearrange(VectorShuffle) rearrange()} family of
1034 * methods, which select an arbitrary set of {@code VLENGTH} lanes
1035 * from one or two input vectors, and assemble them in an arbitrary
1036 * order. The selection and order of lanes is controlled by a
1037 * {@code VectorShuffle} object, which acts as an routing table
1038 * mapping source lanes to destination lanes. A {@code VectorShuffle}
1039 * can encode a mathematical permutation as well as many other
1040 * patterns of data movement.
1041 *
1042 * </ul>
1043 * <p> Some vector operations are not lane-wise, but rather move data
1044 * across lane boundaries. Such operations are typically rare in SIMD
1045 * code, though they are sometimes necessary for specific algorithms
1046 * that manipulate data formats at a low level, and/or require SIMD
1047 * data to move in complex local patterns. (Local movement in a small
1048 * window of a large array of data is relatively unusual, although
1049 * some highly patterned algorithms call for it.) In this API such
1050 * methods are always clearly recognizable, so that simpler lane-wise
1051 * reasoning can be confidently applied to the rest of the code.
1052 *
1053 * <p> In some cases, vector lane boundaries are discarded and
1054 * "redrawn from scratch", so that data in a given input lane might
1055 * appear (in several parts) distributed through several output lanes,
1056 * or (conversely) data from several input lanes might be consolidated
1057 * into a single output lane. The fundamental method which can redraw
1058 * lanes boundaries is
1059 * {@link #reinterpretShape(VectorSpecies,int) reinterpretShape()}.
1060 * Built on top of this method, certain convenience methods such
1061 * as {@link #reinterpretAsBytes() reinterpretAsBytes()} or
2672 *
2673 * <p> This method returns the value of this pseudocode:
2674 * <pre>{@code
2675 * Vector<E> r1 = this.rearrange(s.wrapIndexes());
2676 * // or else: r1 = this.rearrange(s, s.laneIsValid());
2677 * Vector<E> r2 = v.rearrange(s.wrapIndexes());
2678 * return r2.blend(r1,s.laneIsValid());
2679 * }</pre>
2680 *
2681 * @param s the shuffle controlling lane selection from both input vectors
2682 * @param v the second input vector
2683 * @return the rearrangement of lane elements of this vector and
2684 * a second input vector
2685 * @see #rearrange(VectorShuffle)
2686 * @see #rearrange(VectorShuffle,VectorMask)
2687 * @see VectorShuffle#laneIsValid()
2688 * @see #slice(int,Vector)
2689 */
2690 public abstract Vector<E> rearrange(VectorShuffle<E> s, Vector<E> v);
2691
2692 /**
2693 * Using index values stored in the lanes of this vector,
2694 * assemble values stored in second vector {@code v}.
2695 * The second vector thus serves as a table, whose
2696 * elements are selected by indexes in the current vector.
2697 *
2698 * This is a cross-lane operation that rearranges the lane
2699 * elements of the argument vector, under the control of
2700 * this vector.
2701 *
2702 * For each lane {@code N} of this vector, and for each lane
2703 * value {@code I=this.lane(N)} in this vector,
2704 * the output lane {@code N} obtains the value from
2705 * the argument vector at lane {@code I}.
2706 *
2707 * In this way, the result contains only values stored in the
2708 * argument vector {@code v}, but presented in an order which
2709 * depends on the index values in {@code this}.
2710 *
2711 * The result is the same as the expression
|
1 /*
2 * Copyright (c) 2017, 2021, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
1022 * These operations are:
1023 * <ul>
1024 *
1025 * <li>The {@link #slice(int,Vector) slice()} family of methods,
1026 * which extract contiguous slice of {@code VLENGTH} fields from
1027 * a given origin point within a concatenated pair of vectors.
1028 *
1029 * <li>The {@link #unslice(int,Vector,int) unslice()} family of
1030 * methods, which insert a contiguous slice of {@code VLENGTH} fields
1031 * into a concatenated pair of vectors at a given origin point.
1032 *
1033 * <li>The {@link #rearrange(VectorShuffle) rearrange()} family of
1034 * methods, which select an arbitrary set of {@code VLENGTH} lanes
1035 * from one or two input vectors, and assemble them in an arbitrary
1036 * order. The selection and order of lanes is controlled by a
1037 * {@code VectorShuffle} object, which acts as an routing table
1038 * mapping source lanes to destination lanes. A {@code VectorShuffle}
1039 * can encode a mathematical permutation as well as many other
1040 * patterns of data movement.
1041 *
1042 * <li>The {@link #compress(VectorMask)} and {@link #expand(VectorMask)}
1043 * methods, which select up to {@code VLENGTH} lanes from an
1044 * input vector, and assemble them in lane order. The selection of lanes
1045 * is controlled by a {@code VectorMask}, with set lane elements mapping, by
1046 * compression or expansion in lane order, source lanes to destination lanes.
1047 *
1048 * </ul>
1049 * <p> Some vector operations are not lane-wise, but rather move data
1050 * across lane boundaries. Such operations are typically rare in SIMD
1051 * code, though they are sometimes necessary for specific algorithms
1052 * that manipulate data formats at a low level, and/or require SIMD
1053 * data to move in complex local patterns. (Local movement in a small
1054 * window of a large array of data is relatively unusual, although
1055 * some highly patterned algorithms call for it.) In this API such
1056 * methods are always clearly recognizable, so that simpler lane-wise
1057 * reasoning can be confidently applied to the rest of the code.
1058 *
1059 * <p> In some cases, vector lane boundaries are discarded and
1060 * "redrawn from scratch", so that data in a given input lane might
1061 * appear (in several parts) distributed through several output lanes,
1062 * or (conversely) data from several input lanes might be consolidated
1063 * into a single output lane. The fundamental method which can redraw
1064 * lanes boundaries is
1065 * {@link #reinterpretShape(VectorSpecies,int) reinterpretShape()}.
1066 * Built on top of this method, certain convenience methods such
1067 * as {@link #reinterpretAsBytes() reinterpretAsBytes()} or
2678 *
2679 * <p> This method returns the value of this pseudocode:
2680 * <pre>{@code
2681 * Vector<E> r1 = this.rearrange(s.wrapIndexes());
2682 * // or else: r1 = this.rearrange(s, s.laneIsValid());
2683 * Vector<E> r2 = v.rearrange(s.wrapIndexes());
2684 * return r2.blend(r1,s.laneIsValid());
2685 * }</pre>
2686 *
2687 * @param s the shuffle controlling lane selection from both input vectors
2688 * @param v the second input vector
2689 * @return the rearrangement of lane elements of this vector and
2690 * a second input vector
2691 * @see #rearrange(VectorShuffle)
2692 * @see #rearrange(VectorShuffle,VectorMask)
2693 * @see VectorShuffle#laneIsValid()
2694 * @see #slice(int,Vector)
2695 */
2696 public abstract Vector<E> rearrange(VectorShuffle<E> s, Vector<E> v);
2697
2698 /**
2699 * Compresses the lane elements of this vector selecting lanes
2700 * under the control of a specific mask.
2701 *
2702 * This is a cross-lane operation that compresses the lane
2703 * elements of this vector as selected by the specified mask.
2704 *
2705 * For each lane {@code N} of the mask, if the mask at
2706 * lane {@code N} is set, the element at lane {@code N}
2707 * of input vector is selected and stored into the output
2708 * vector contiguously starting from the lane {@code 0}.
2709 * All the upper remaining lanes, if any, of the output
2710 * vector are set to zero.
2711 *
2712 * @param m the mask controlling the compression
2713 * @return the compressed lane elements of this vector
2714 */
2715 public abstract Vector<E> compress(VectorMask<E> m);
2716
2717 /**
2718 * Expands the lane elements of this vector
2719 * under the control of a specific mask.
2720 *
2721 * This is a cross-lane operation that expands the contiguous lane
2722 * elements of this vector into lanes of an output vector
2723 * as selected by the specified mask.
2724 *
2725 * For each lane {@code N} of the mask, if the mask at
2726 * lane {@code N} is set, the next contiguous element of input vector
2727 * starting from lane {@code 0} is selected and stored into the output
2728 * vector at lane {@code N}.
2729 * All the remaining lanes, if any, of the output vector are set to zero.
2730 *
2731 * @param m the mask controlling the compression
2732 * @return the expanded lane elements of this vector
2733 */
2734 public abstract Vector<E> expand(VectorMask<E> m);
2735
2736 /**
2737 * Using index values stored in the lanes of this vector,
2738 * assemble values stored in second vector {@code v}.
2739 * The second vector thus serves as a table, whose
2740 * elements are selected by indexes in the current vector.
2741 *
2742 * This is a cross-lane operation that rearranges the lane
2743 * elements of the argument vector, under the control of
2744 * this vector.
2745 *
2746 * For each lane {@code N} of this vector, and for each lane
2747 * value {@code I=this.lane(N)} in this vector,
2748 * the output lane {@code N} obtains the value from
2749 * the argument vector at lane {@code I}.
2750 *
2751 * In this way, the result contains only values stored in the
2752 * argument vector {@code v}, but presented in an order which
2753 * depends on the index values in {@code this}.
2754 *
2755 * The result is the same as the expression
|