+ * This interface provides methods that allow the context in which an item based device is + * created to copy data from and to the {@link net.minecraft.item.ItemStack} the device was + * created for. + *
+ * By default, no data is copied to and from the {@link net.minecraft.item.ItemStack}. Use
+ * these methods for storing data that should survive the item the device is based on being
+ * removed from the context (e.g. a computer) and being put back in some context.
+ */
public interface ItemDevice extends Device {
- void exportToItemStack(CompoundNBT nbt);
+ /**
+ * Export data that should be copied to the {@link net.minecraft.item.ItemStack}
+ * this device was created for to a tag that will be stored in the item.
+ *
+ * @param nbt the tag that will be written to the item.
+ */
+ default void exportToItemStack(final CompoundNBT nbt) {
+ }
- void importFromItemStack(CompoundNBT nbt);
+ /**
+ * Import data that is present on the {@link net.minecraft.item.ItemStack} this
+ * device was created for. The provided tag corresponds to the one presented to
+ * the {@link #exportToItemStack(CompoundNBT)} method.
+ *
+ * @param nbt the tag that was read from the item.
+ */
+ default void importFromItemStack(final CompoundNBT nbt) {
+ }
}
diff --git a/src/main/java/li/cil/oc2/api/bus/device/object/ObjectDevice.java b/src/main/java/li/cil/oc2/api/bus/device/object/ObjectDevice.java
index 47a79823..c196f8c0 100644
--- a/src/main/java/li/cil/oc2/api/bus/device/object/ObjectDevice.java
+++ b/src/main/java/li/cil/oc2/api/bus/device/object/ObjectDevice.java
@@ -63,6 +63,8 @@ public final class ObjectDevice implements RPCDevice {
this(object, emptyList());
}
+ ///////////////////////////////////////////////////////////////////
+
@Override
public List
+ * Allocated interrupts should be persisted and used in {@link #claimInterrupt(int)}
+ * when restoring from a saved state to ensure correct behaviour of the loaded virtual
+ * machine.
+ */
public interface InterruptAllocator {
+ /**
+ * Tries to reserve an interrupt with the specified index. The returned interrupt
+ * may differ from the one provided, if the interrupt has already been claimed by
+ * some other device. In this case, the result will be same as calling {@link #claimInterrupt()}.
+ *
+ * @param interrupt the interrupt to claim.
+ * @return the interrupt that was claimed, if any.
+ */
OptionalInt claimInterrupt(int interrupt);
+ /**
+ *
+ *
+ * @return the interrupt that was claimed, if any.
+ */
OptionalInt claimInterrupt();
}
diff --git a/src/main/java/li/cil/oc2/api/bus/device/vm/MemoryRangeAllocator.java b/src/main/java/li/cil/oc2/api/bus/device/vm/MemoryRangeAllocator.java
index 6cfe8382..02031715 100644
--- a/src/main/java/li/cil/oc2/api/bus/device/vm/MemoryRangeAllocator.java
+++ b/src/main/java/li/cil/oc2/api/bus/device/vm/MemoryRangeAllocator.java
@@ -4,8 +4,38 @@ import li.cil.sedna.api.device.MemoryMappedDevice;
import java.util.OptionalLong;
+/**
+ * Allows adding {@link MemoryMappedDevice}s to the memory map of a virtual machine
+ * during a {@link VMDevice#load(VMContext)} call.
+ *
+ * Allocated addresses should be persisted and used in {@link #claimMemoryRange(long, MemoryMappedDevice)}
+ * when restoring from a saved state to ensure correct behaviour of the loaded virtual
+ * machine.
+ */
public interface MemoryRangeAllocator {
+ /**
+ * Tries to add a {@link MemoryMappedDevice} to the memory map at the specified
+ * address. The returned address may differ from the address provided, if the
+ * device cannot fit into the memory map at the specified address. In this case,
+ * the result will be the same as calling {@link #claimMemoryRange(MemoryMappedDevice)}.
+ *
+ * @param address the address to add the specified device at.
+ * @param device the device to add at the specified address.
+ * @return the address the device was added at, if any.
+ */
OptionalLong claimMemoryRange(long address, MemoryMappedDevice device);
+ /**
+ * Tries to add a {@link MemoryMappedDevice} to the memory map at an address
+ * determined by the virtual machine. This may take into account the type of
+ * device being added. Typically, {@link li.cil.sedna.api.device.PhysicalMemory}
+ * devices will be allocated in a different memory region than regular devices.
+ *
+ * If the device could not fit into the memory map at all, this will return
+ * {@link OptionalLong#empty()}.
+ *
+ * @param device the device to add to the memory map.
+ * @return the address the device was added at, if any.
+ */
OptionalLong claimMemoryRange(MemoryMappedDevice device);
}
diff --git a/src/main/java/li/cil/oc2/common/bus/device/AbstractItemDevice.java b/src/main/java/li/cil/oc2/common/bus/device/AbstractItemDevice.java
index 92a0a8d3..cb640ba3 100644
--- a/src/main/java/li/cil/oc2/common/bus/device/AbstractItemDevice.java
+++ b/src/main/java/li/cil/oc2/common/bus/device/AbstractItemDevice.java
@@ -2,20 +2,9 @@ package li.cil.oc2.common.bus.device;
import li.cil.oc2.api.bus.device.ItemDevice;
import net.minecraft.item.ItemStack;
-import net.minecraft.nbt.CompoundNBT;
public abstract class AbstractItemDevice extends AbstractObjectDevice