1 /*
2  * sys-emu - A system emulator for tutorials
3  * Copyright (C) 2018 - 2019 osdevelopment-info
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU Affero General Public License as published by
7  * the Free Software Foundation, either version 3 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Affero General Public License for more details.
14  *
15  * You should have received a copy of the GNU Affero General Public License
16  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
17  */
18 package info.osdevelopment.sysemu.memory
19 
20 import scala.util.{Failure, Success, Try}
21 
22 /**
23   * A generic memory type. A memory type can address bytes up to a maximum of 2^64^ bytes.
24   */
25 trait Memory {
26 
27   /**
28     * Returns the size of the memory.
29     * @return the size of the memory
30     */
31   def size: Long
32 
33   /**
34     * Read a single `Byte` from the memory at the given address.
35     * @param address the `address` to read from
36     * @return a `Success` with the Byte read or a `Failure`
37     */
38   def readByte(address: Long): Try[Byte]
39 
40   /**
41     * Write a single `Byte` to the memory at the given address.
42     * @param address the `address` to write to
43     * @param value the `value` to write
44     * @return a `Success` when the byte was written successfully or a `Failure` otherwise
45     */
46   def writeByte(address: Long, value: Byte): Try[Unit]
47 
48   /**
49     * Read a `Short` from the memory at `address ... address + 1`. The value of `address` will be the least significant
50     * `Byte`.
51     * @param address the `address` to read from
52     * @return a `Success` with the `Short` read or a `Failure`
53     */
54   final def readShort(address: Long): Try[Short] = {
55     val bytes = List.range(0, 2).map(offs => readByte(address + offs))
56     val failures = bytes.filter(x => x.isFailure)
57     if (failures.isEmpty) {
58       Success((readSumBytes(bytes) & 0xffffL).asInstanceOf[Short])
59     } else {
60       failures.head.asInstanceOf[Failure[Short]]
61     }
62   }
63 
64   /**
65     * Write a `Short` to `address ... address + 1`. The least significant `Byte` will be written to `address`.
66     * @param address the `address` to write to
67     * @param value the `value` to write
68     * @return a `Success` when the short was written successfully or a `Failure` otherwise
69     */
70   final def writeShort(address: Long, value: Short): Try[Unit] = {
71     writeDivided(address, value, 2)
72   }
73 
74   /**
75     * Read an `Int` from the memory at `address ... address + 3`. The value of `address` will be the least significant
76     * `Byte`.
77     * @param address the `address` to read from
78     * @return a `Success` with the `Int` read or a `Failure`
79     */
80   final def readInt(address: Long): Try[Int] = {
81     val bytes = List.range(0, 4).map(offs => readByte(address + offs))
82     val failures = bytes.filter(x => x.isFailure)
83     if (failures.isEmpty) {
84       Success((readSumBytes(bytes) & 0xffffffffL).asInstanceOf[Int])
85     } else {
86       failures.head.asInstanceOf[Failure[Int]]
87     }
88   }
89 
90   /**
91     * Write an `Int` at `address ... address + 3`. The least significant `Byte` will be written to `address`.
92     * @param address the `address` to write to
93     * @param value the `value` to write
94     * @return a `Success` when the int was written successfully or a `Failure` otherwise
95     */
96   final def writeInt(address: Long, value: Int): Try[Unit] = {
97     writeDivided(address, value, 4)
98   }
99 
100   /**
101     * Read a `Long` from the memory at `address ... address + 7`. The value of `address` will be the least significant
102     * `Byte`.
103     * @param address the `address` to read from
104     * @return a `Success` with the `Long` read or a `Failure`
105     */
106   final def readLong(address: Long): Try[Long] = {
107     val bytes = List.range(0, 8).map(offs => readByte(address + offs))
108     val failures = bytes.filter(x => x.isFailure)
109     if (failures.isEmpty) {
110       Success(readSumBytes(bytes) & 0xffffffffffffffffL)
111     } else {
112       failures.head.asInstanceOf[Failure[Long]]
113     }
114   }
115 
116   /**
117     * Write a `Long` at `address ... address + 7`. The least significant `Byte` will be written to `address`.
118     * @param address the `address` to write to
119     * @param value the `value` to write
120     * @return a `Success` when the long was written successfully or a `Failure` otherwise
121     */
122   final def writeLong(address: Long, value: Long): Try[Unit] = {
123     writeDivided(address, value, 8)
124   }
125 
126   /**
127     * Write the `value` into the memory starting at `address` divided to `numberBytes` bytes.
128     * @param address the start address of the write
129     * @param value the value to write
130     * @param numberBytes the number of bytes to write
131     * @return a `Success` if no error occurred during the write, `Failure` otherwiese
132     */
133   private def writeDivided(address: Long, value: Long, numberBytes: Int): Try[Unit] = {
134     val offsets = List.range(0, numberBytes)
135     val result = offsets.map(offset => writeByte(address + offset, (value >> (offset * 8) & 0xff).asInstanceOf[Byte]))
136     val failures = result.filter(x => x.isFailure)
137     if (failures.isEmpty) {
138       Success((): Unit)
139     } else {
140       failures.head
141     }
142   }
143 
144   /**
145     * Sums up the bytes according. The first byte in the list is the least significant byte.
146     * @param bytes the bytes to sum up
147     * @return the combined bytes
148     */
149   private def readSumBytes(bytes: List[Try[Byte]]): Long = {
150     bytes.collect { case Success(b) => b.asInstanceOf[Long] & 0xff }
151         .zipWithIndex
152         .map { case (l, i) => l << (i * 8) }
153         .sum
154   }
155 
156 }