1 /*
   2  * Copyright (c) 2019, 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
  23  * questions.
  24  */
  25 package java.foreign.layout;
  26 
  27 import java.util.Map;
  28 import java.util.Objects;
  29 import java.util.Optional;
  30 
  31 /**
  32  * The layout corresponding to a memory address. An address layout can (optionally) be associated with a descriptor
  33  * describing the contents of the target memory region pointed to by the address - either a function or a layout
  34  * (see {@link Descriptor}).
  35  */
  36 public final class Address extends Value {
  37 
  38     /**
  39      * The addressee kind. Denotes the contents of the memory region pointed at by an address.
  40      */
  41     private enum PointeeKind {
  42         /**
  43          * The address points to some data with given layout.
  44          */
  45         LAYOUT,
  46         /**
  47          * The address points to the entry point of some native function.
  48          */
  49         FUNCTION,
  50         /**
  51          * The address does not have any associated pointee info.
  52          */
  53         VOID
  54     }
  55 
  56     private final PointeeKind pointeeKind;
  57     private final Descriptor descriptor;
  58 
  59     private Address(PointeeKind pointeeKind, Descriptor descriptor, long size, Kind kind, Endianness endianness, Optional<Group> contents, Map<String, String> annotations) {
  60         super(kind, endianness, size, contents, annotations);
  61         this.pointeeKind = pointeeKind;
  62         this.descriptor = descriptor;
  63     }
  64 
  65     @Override
  66     public Address withContents(Group contents) {
  67         return new Address(pointeeKind, descriptor, bitsSize(), kind(), endianness(), Optional.of(contents), annotations());
  68     }
  69 
  70     /**
  71      * Obtain the {@link Function} object associated with the memory region pointed to by this address (if any).
  72      * @return an optional {@link Function} object.
  73      */
  74     public Optional<Function> function() {
  75         return pointeeKind == PointeeKind.FUNCTION ?
  76                 Optional.of((Function)descriptor) : Optional.empty();
  77     }
  78 
  79     /**
  80      * Obtain the {@link Layout} object associated with the memory region pointed to by this address (if any).
  81      * @return an optional {@link Layout} object.
  82      */
  83     public Optional<Layout> layout() {
  84         return pointeeKind == PointeeKind.LAYOUT ?
  85                 Optional.of((Layout)descriptor) : Optional.empty();
  86     }
  87 
  88     /**
  89      * Create a new address of given size.
  90      * @param size address size.
  91      * @return the new address layout.
  92      */
  93     public static Address ofVoid(long size) {
  94         return ofVoid(size, Kind.INTEGRAL_UNSIGNED);
  95     }
  96 
  97     /**
  98      * Create a new address of given size and kind.
  99      * @param size address size.
 100      * @param kind address kind.
 101      * @return the new address layout.
 102      */
 103     public static Address ofVoid(long size, Kind kind) {
 104         return ofVoid(size, kind, Endianness.hostEndian());
 105     }
 106 
 107     /**
 108      * Create a new address of given size, kind and endianness.
 109      * @param size address size.
 110      * @param kind address kind.
 111      * @param endianness address endianness.
 112      * @return the new address layout.
 113      */
 114     public static Address ofVoid(long size, Kind kind, Endianness endianness) {
 115         return new Address(PointeeKind.VOID, null, size, kind, endianness, Optional.empty(), NO_ANNOS);
 116     }
 117 
 118     /**
 119      * Create a new address of given size and addressee layout.
 120      * @param size address size.
 121      * @param layout addressee layout.
 122      * @return the new address layout.
 123      */
 124     public static Address ofLayout(long size, Layout layout) {
 125         return ofLayout(size, layout, Kind.INTEGRAL_UNSIGNED);
 126     }
 127 
 128     /**
 129      * Create a new address of given size, kind and addressee layout.
 130      * @param size address size.
 131      * @param kind address kind.
 132      * @param layout addressee layout.
 133      * @return the new address layout.
 134      */
 135     public static Address ofLayout(long size, Layout layout, Kind kind) {
 136         return ofLayout(size, layout, kind, Endianness.hostEndian());
 137     }
 138 
 139     /**
 140      * Create a new address of given size, kind, endianness and addressee layout.
 141      * @param size address size.
 142      * @param kind address sign.
 143      * @param endianness address endianness.
 144      * @param layout addressee layout.
 145      * @return the new address layout.
 146      */
 147     public static Address ofLayout(long size, Layout layout, Kind kind, Endianness endianness) {
 148         return new Address(PointeeKind.LAYOUT, layout, size, kind, endianness, Optional.empty(), NO_ANNOS);
 149     }
 150 
 151     /**
 152      * Create a new address of given size and addressee function.
 153      * @param size address size.
 154      * @param function addressee function.
 155      * @return the new address layout.
 156      */
 157     public static Address ofFunction(long size, Function function) {
 158         return ofFunction(size, function, Kind.INTEGRAL_UNSIGNED);
 159     }
 160 
 161     /**
 162      * Create a new address of given size, kind and addressee function.
 163      * @param size address size.
 164      * @param kind address kind.
 165      * @param function addressee function.
 166      * @return the new address layout.
 167      */
 168     public static Address ofFunction(long size, Function function, Kind kind) {
 169         return ofFunction(size, function, kind, Endianness.hostEndian());
 170     }
 171 
 172     /**
 173      * Create a new address of given size, kind, endianness and addressee function.
 174      * @param size address size.
 175      * @param kind address kind.
 176      * @param endianness address endianness.
 177      * @param function addressee function.
 178      * @return the new address layout.
 179      */
 180     public static Address ofFunction(long size, Function function, Kind kind, Endianness endianness) {
 181         return new Address(PointeeKind.FUNCTION, function, size, kind, endianness, Optional.empty(), NO_ANNOS);
 182     }
 183 
 184     @Override
 185     public boolean equals(Object other) {
 186         if (this == other) {
 187             return true;
 188         }
 189         if (!(other instanceof Address)) {
 190             return false;
 191         }
 192         Address addr = (Address)other;
 193         return super.equals(other) &&
 194                 Objects.equals(descriptor, addr.descriptor);
 195     }
 196 
 197     @Override
 198     public int hashCode() {
 199         return super.hashCode() ^ Objects.hashCode(descriptor);
 200     }
 201 
 202     @Override
 203     public String toString() {
 204         return super.toString() + ":" + (descriptor == null ? "v" : descriptor.toString());
 205     }
 206 
 207     @Override
 208     Address withAnnotations(Map<String, String> annotations) {
 209         return new Address(pointeeKind, descriptor, bitsSize(), kind(), endianness(), contents(), annotations);
 210     }
 211 
 212     @Override
 213     public Address stripAnnotations() {
 214         return (Address)super.stripAnnotations();
 215     }
 216 
 217     @Override
 218     public Address withAnnotation(String name, String value) {
 219         return (Address)super.withAnnotation(name, value);
 220     }
 221 }