| @@ -0,0 +1,97 @@ |
| | 1 | Dis Virtual Machine Tools for Python |
| | 2 | ==================================== |
| | 3 | |
| | 4 | Introduction |
| | 5 | ------------ |
| | 6 | |
| | 7 | This package contains Python modules for reading and writing files for the Dis |
| | 8 | virtual machine[1], used by the Inferno operating system[2]. Although the aim |
| | 9 | of these modules was to create a toolchain for producing .dis files, they are |
| | 10 | more useful for reading existing ones. |
| | 11 | |
| | 12 | Reading a .dis File |
| | 13 | ------------------- |
| | 14 | |
| | 15 | Sample .dis files are not provided, but you can compile the Limbo source code |
| | 16 | files from the Tests/Limbo directory to obtain simple .dis files to inspect. |
| | 17 | This is done using the limbo compiler supplied with Inferno. |
| | 18 | |
| | 19 | From within the package directory, or with the directory on the PYTHONPATH, |
| | 20 | you can run the Python interpreter and inspect the contents of an existing .dis |
| | 21 | file in the following way: |
| | 22 | |
| | 23 | import dis |
| | 24 | d = dis.Dis() |
| | 25 | d.read(open("/tmp/countmin.dis"), "countmin.dis") |
| | 26 | d.list() |
| | 27 | |
| | 28 | For the compiled version of the countmin.b file, the Python should produce |
| | 29 | output similar to the following: |
| | 30 | |
| | 31 | 0x0: load 0(mp), $0x0, 48(fp) |
| | 32 | 0x1: movw $0x0, 40(fp) |
| | 33 | 0x2: blew $0x7b, 40(fp), $0x5 |
| | 34 | 0x3: addw $0x1, 40(fp) |
| | 35 | 0x4: jmp $0x2 |
| | 36 | 0x5: ret |
| | 37 | |
| | 38 | entry 0x0, 1 |
| | 39 | desc $0x0, 8, "c0" |
| | 40 | desc $0x1, 56, "00c8" |
| | 41 | |
| | 42 | var @mp, 8 |
| | 43 | string @mp+0, "$Sys" |
| | 44 | |
| | 45 | module count |
| | 46 | |
| | 47 | link 0x0, 1, 0x4244b354, "init" |
| | 48 | |
| | 49 | ldts @ldt, 0 |
| | 50 | |
| | 51 | source "/tmp/countmin.b" |
| | 52 | |
| | 53 | The location of the source file when it was compiled by the limbo compiler will |
| | 54 | influence the value presented in the output of the list() method. |
| | 55 | |
| | 56 | Tests |
| | 57 | ----- |
| | 58 | |
| | 59 | Some tests that write .dis files are included in the Tests directory. These |
| | 60 | will try to create the corresponding .dis files to their equivalent Limbo |
| | 61 | programs. Ensure that the package directory is on the PYTHONPATH and run them |
| | 62 | in the following way: |
| | 63 | |
| | 64 | PYTHONPATH=. ./Tests/countmin.py /tmp/countmin.dis |
| | 65 | |
| | 66 | You should then be able to run them in the Inferno emulator and inspect them |
| | 67 | using the method described in the previous section. |
| | 68 | |
| | 69 | Authors and License |
| | 70 | ------------------- |
| | 71 | |
| | 72 | David Boddie <david@boddie.org.uk> |
| | 73 | |
| | 74 | Unless indicated otherwise, the contents of this package are licensed under the |
| | 75 | GNU General Public License version 3 (or later). |
| | 76 | |
| | 77 | Copyright (C) 2017 David Boddie <david@boddie.org.uk> |
| | 78 | |
| | 79 | This program is free software: you can redistribute it and/or modify |
| | 80 | it under the terms of the GNU General Public License as published by |
| | 81 | the Free Software Foundation, either version 3 of the License, or |
| | 82 | (at your option) any later version. |
| | 83 | |
| | 84 | This program is distributed in the hope that it will be useful, |
| | 85 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| | 86 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| | 87 | GNU General Public License for more details. |
| | 88 | |
| | 89 | You should have received a copy of the GNU General Public License |
| | 90 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
| | 91 | |
| | 92 | References |
| | 93 | ---------- |
| | 94 | |
| | 95 | [1] http://inferno-os.org/inferno/papers/dis.html |
| | 96 | [2] http://inferno-os.org |
| | 97 | [3] http://inferno-os.org/inferno/papers/limbo.html |