summaryrefslogtreecommitdiffhomepage
path: root/doc/mdk.texi
blob: ade349a0da36ff39559b2b8adfb66c7cbda9a51a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename mdk.info
@settitle MIX Development Kit (mdk)
@finalout
@setchapternewpage odd
@c %**end of header

@include version.texi
@set JAO Jos@'e Antonio Ortega Ruiz
@footnotestyle separate

@ifinfo
This file documents the the @sc{mdk} utilities for developing
programs using Donald Knuth's MIX language.

Copyright (C) 2000, 2001 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end ifinfo

@titlepage
@title MDK
@subtitle MIX Development Kit
@subtitle Edition @value{EDITION}, for @sc{mdk} Version @value{VERSION}
@subtitle @value{UPDATED}
@author by @value{JAO}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage

@node Top, Introduction, (dir), (dir)

@ifinfo
This file documents the @sc{mdk} utilities to develop, run and debug
programs written in the MIXAL programming language.  MIXAL is an
assembler-like language for programming a virtual computer called
MIX. They were created by Donald Knuth in the first volume of @cite{The
Art of Computer Programming} (Addison Wesley, 1997).

@sc{mdk} was written by @value{JAO} and is released under the GNU
General Public license (@pxref{Copying}), so that users are free to share
and improve it.

@end ifinfo

@menu
* Introduction::                
* MIX and MIXAL tutorial::      Learn the innards of MIX and MIXAL.
* Getting started::             Basic usage of the @sc{mdk} tools.
* mixvm::                       Invoking the MIX virtual machine.
* mixasm::                      Invoking the MIXAL assembler.
* Copying::                     @sc{mdk} licensing terms.
* Problems::                    Reporting bugs.
* Concept Index::               Index of concepts.

@detailmenu
 --- The Detailed Node Listing ---

MIX and MIXAL tutorial

* The MIX computer::            Architecture and instruction set 
                                of the MIX computer.
* MIXAL::                       The MIX assembly language.

The MIX computer

* MIX architecture::            
* MIX instruction set::         

MIX instruction set

* Instruction structure::       
* Loading operators::           
* Storing operators::           
* Arithmetic operators::        
* Address transfer operators::  
* Comparison operators::        
* Jump operators::              
* Input-output operators::      
* Conversion operators::        
* Shift operators::             
* Miscellaneous operators::     
* Execution times::             

MIXAL

* Basic structure::             Writing basic MIXAL programs.
* MIXAL directives::            Assembler directives.
* Expressions::                 Evaluation of expressions.
* W-expressions::               Evaluation of w-expressions.
* Local symbols::               Special symbol table entries.
* Literal constants::           Specifying an immediate operand.

Getting started

* Writing a source file::       A sample MIXAL source file.
* Compiling::                   Using @code{mixasm} to compile source
                                files into binary format.
* Running the program::         Running and debugging your program.

Running the program

* Non-interactive mode::        Running your programs non-interactively.
* Interactive mode::            Running programs interactively.
* Debugging::                   Commands for debugging your programs.

@code{mixvm}, the MIX computer simulator

* Invocation::                  Options when invoking @code{mixvm}.
* Commands::                    Commands available in interactive mode.
* Devices::                     MIX block devices implementation.

Interactive commands 

* File commands::               Loading and executing programs.
* Debug commands::              Debugging programs.
* State commands::              Inspecting the virtual machine state.

@code{mixasm}, the MIXAL assembler

* Invoking @code{mixasm}::      @code{mixasm} options

@end detailmenu
@end menu

@node Introduction, MIX and MIXAL tutorial, Top, Top
@comment  node-name,  next,  previous,  up
@unnumbered Introduction
@cindex Introduction

In his book series @cite{The Art of Computer Programming} (published by
Addison Wesley), D. Knuth uses an imaginary computer, the MIX, and its
associated machine-code and assembly languages to ilustrate the
concepts and algorithms as they are presented. 

The MIX's architecture is a simplified version of those found in real
CISC CPUs, and the MIX assembly language (MIXAL) provides a set of
primitives that will be very familiar to any person with a minimum
experience in assembly programming. The MIX/MIXAL definition is powerful
and complete enough to provide a virtual development platform for
writing quite complex programs, and close enough to real computers to be
worth using when learning programming techniques. At any rate, if you
want to learn or improve your programming skills, a MIX development
environment would come in handy.

The @sc{mdk} package aims at providing such virtual development
environment on a GNU box. Thus, @sc{mdk} offers you a set of utilities
to simulate the MIX computer and to write, compile, run and debug MIXAL
programs. As of version @value{VERSION}, @sc{mdk} includes
the following programs:

@table @code
@item mixvm
MIX virtual machine. Emulation of the MIX computer.
@item mixasm
MIXAL assembler. Assembler which translates MIXAL source files into
programs that can be run (and debugged) by @code{mixvm}.
@end table 

@code{mixvm} implements a simulator of the MIX computer, giving you a
virtual machine for executing and debugging MIX programs. These binary
programs could be written by hand, but it is easier to produce them
compiling MIXAL source files, using the MIXAL assembler @code{mixasm}.

This manual gives you a tutorial of MIX and MIXAL, and a thorough
description of the use of the @sc{mdk} utilities.



@node MIX and MIXAL tutorial, Getting started, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter MIX and MIXAL tutorial
@cindex MIX
@cindex MIXAL

In the book series @cite{The Art of Computer Programming}, by D. Knuth,
a virtual computer, the MIX, is used by the author (together with the
set of binary instructions that the virtual CPU accepts) to illustrate
the algorithms and skills that every serious programmer should
master. Like any other real computer, there is a symbolic assembler
language that can be used to program the MIX: the MIX assembly language,
or MIXAL for short.  In the following subsections you will find a tutorial
on these topics, which will teach you the basics of the MIX architecture
and how to program a MIX computer using MIXAL.

@menu
* The MIX computer::            Architecture and instruction set 
                                of the MIX computer.
* MIXAL::                       The MIX assembly language.
@end menu

@node The MIX computer, MIXAL, MIX and MIXAL tutorial, MIX and MIXAL tutorial
@comment  node-name,  next,  previous,  up
@section The MIX computer

In this section, you will find a description of the MIX computer,
its components and instruction set.

@menu
* MIX architecture::            
* MIX instruction set::         
@end menu

@node MIX architecture, MIX instruction set, The MIX computer, The MIX computer
@comment  node-name,  next,  previous,  up
@subsection MIX architecture
@cindex byte
@cindex MIX byte
@cindex word
@cindex MIX word
@cindex MIX architecture
@cindex MIX computer
@cindex register
@cindex MIX register
@cindex field specification
@cindex fspec
@cindex instruction
@cindex MIX instruction
@cindex address
@cindex memory cell
@cindex cell
@cindex memory
@cindex index

The basic information storage unit in the MIX computer is the
@dfn{byte}, which stores positive values in the range 0-63 . Note that a
MIX byte can be then represented as 6 bits, instead of the common 8 bits
for a @emph{regular} byte. Unless otherwise stated, we shall use the
word @dfn{byte} to refer to a MIX 6-bit byte.

A MIX @dfn{word} is defined as a set of 5 bytes plus a sign. The bytes
within a word are numbered from 1 to 5, being byte number one the most
significant one. The sign is denoted by index 0. Graphically,

@example
 -----------------------------------------------
|   0   |   1   |   2   |   3   |   4   |   5   |
 -----------------------------------------------
|  +/-  | byte  | byte  | byte  | byte  | byte  |     
 -----------------------------------------------
@end example
@noindent
Sample MIX words are @samp{- 12 00 11 01 63} and @samp{+ 12 11 34 43
00}.

You can refer to subfields within a word using a @dfn{field
specification} or @dfn{fspec} of the form ``(@var{l}:@var{r})'', where
@var{l} denotes the first byte, and @var{r} the last byte of the
subfield.
When @var{l} is zero, the subfield includes the word's
sign. An fspec can also be represented as a single value @code{F}, given
by @code{F = 8*L + R} (thus the fspec @samp{(1:3)}, denoting the first
three bytes of a word, is represented by the integer 11).

The MIX computer stores information in @dfn{registers}, that can store
either a word or two bytes and sign (see below), and @dfn{memory cells},
each one containing a word. Specifically, the MIX computer has 4000
memory cells with addresses 0 to 3999 (i.e., two bytes are enough to
address a memory cell) and the following registers:

@cindex rA
@cindex rX
@cindex rJ
@cindex rIn
@cindex register

@table @asis
@item @code{rA}
A register. General purpose register holding a word. Usually its
contents serves as the operand of arithmetic and storing instructions.
@item @code{rX}
X register. General purpose register holding a word. Often it acts as an
extension or a replacement of @samp{rA}.
@item @code{rJ}
J (jump) register. This register stores positive two-byte values,
usually representing a jump address.
@item @code{rI1}, @code{rI2}, @code{rI3}, @code{rI4}, @code{rI5}, @code{rI6}
Index registers. These six registers can store a signed two-byte
value. Their contents is used as indexing values for the computation of
effective memory addresses.
@end table

@cindex @sc{ov}
@cindex @sc{cm}
@cindex @code{un}
@cindex overflow toggle
@cindex comparison indicator
@cindex input-output devices
@noindent
In addition, the MIX computer contains:

@itemize @minus
@item
An @dfn{overflow toggle} (a single bit with values @dfn{on} or
@dfn{off}). In this manual, this toggle is denoted @sc{ov}.
@item
A @dfn{comparison indicator} (having three values: @dfn{EQUAL},
@dfn{GREATER} or @dfn{LESS}). In this manual, this indicator is denoted
@sc{cm}, and its possible values are abbreviated as @dfn{E}, @dfn{G} and
@dfn{L}.
@item
Input-output block devices. Each device is labelled as @code{un}, where
@code{n} runs from 0 to 20. In Knuth's definition, @code{u0} through
@code{u7} are magnetic tape units, @code{u8} through @code{15} are disks
and drums, @code{u16} is a card reader, @code{u17} is a card writer,
@code{u18} is 
a line printer and, @code{u19} is a typewriter terminal, and @code{u20},
a paper tape. Our implementation maps these devices to disk files,
except for @code{u19}, which represents the standard output.
@end itemize

As noted above, the MIX computer communicates with the external world by
a set of input-output devices which can be ``connected'' to it. The
computer interchanges information using blocks of words whose length
depends on the device at hand (@pxref{Devices}). These words are
interpreted by the device either as binary information (for devices
0-16), or as representing printable characters (devices 17-20). In the
last case, each MIX byte is mapped onto a character according to the
following table:

@multitable  {00} {C} {00} {C} {00} {C} {00} {C}
@item  00 @tab  @tab 01 @tab A @tab 02 @tab B @tab 03 @tab C
@item  04 @tab D @tab 05 @tab E @tab 06 @tab F @tab 07 @tab G
@item  08 @tab H @tab 09 @tab I @tab 10 @tab d @tab 11 @tab J
@item  12 @tab K @tab 13 @tab L @tab 14 @tab M @tab 15 @tab N
@item  16 @tab O @tab 17 @tab P @tab 18 @tab Q @tab 19 @tab R
@item  20 @tab s @tab 21 @tab p @tab 22 @tab S @tab 23 @tab T
@item  24 @tab U @tab 25 @tab V @tab 26 @tab W @tab 27 @tab X
@item  28 @tab Y @tab 29 @tab Z @tab 30 @tab 0 @tab 31 @tab 1 
@item  32 @tab 2 @tab 33 @tab 3 @tab 34 @tab 4 @tab 35 @tab 5
@item  36 @tab 6 @tab 37 @tab 7 @tab 38 @tab 8 @tab 39 @tab 9
@item  40 @tab . @tab 41 @tab , @tab 42 @tab ( @tab 43 @tab )
@item  44 @tab + @tab 45 @tab - @tab 46 @tab * @tab 47 @tab /
@item  48 @tab = @tab 49 @tab $ @tab 50 @tab < @tab 51 @tab >
@item  52 @tab @@ @tab 53 @tab ; @tab 54 @tab : @tab 55 @tab '
@end multitable
@noindent
The value 0 represents a whitespace. Lowercase letters (d, s, p)
correspond to symbols not representable as ASCII characters (uppercase
delta, sigma and gamma, respectively), and byte values 56-63 have no
associated character.

Finally, the MIX computer features a virtual CPU which controls the
above components, and which is able to execute a rich set of
instructions (constituting its machine language, similar to those
commonly found in real CPUs), including arithmetic, logical, storing,
comparison and jump instructions. Being a typical von Neumann computer,
the MIX CPU fetchs binary instructions from memory sequentially (unless
a jump instruction is found), and stores the address of the next
instruction to be executed in an internal register called @dfn{location
counter} (also known as program counter in other architectures).

The next section, @xref{MIX instruction set}, gives a complete description
of the available MIX binary instructions.

@node MIX instruction set,  , MIX architecture, The MIX computer
@comment  node-name,  next,  previous,  up
@subsection MIX instruction set
@cindex instruction set

The following subsections fully describe the instruction set of the MIX
computer. We begin with a description of the structure of binary
instructions and the notation used to refer to their subfields. The
remaininig subsections are devoted to describing the actual instructions
available to the MIX programmer.

@menu
* Instruction structure::       
* Loading operators::           
* Storing operators::           
* Arithmetic operators::        
* Address transfer operators::  
* Comparison operators::        
* Jump operators::              
* Input-output operators::      
* Conversion operators::        
* Shift operators::             
* Miscellaneous operators::     
* Execution times::             
@end menu

@node Instruction structure, Loading operators, MIX instruction set, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Instruction structure

MIX @dfn{instructions} are codified as words with the following subfield
structure:

@multitable @columnfractions .15 .20 .65
@item @emph{Subfield} @tab @emph{fspec} @tab @emph{Description}
@item ADDRESS @tab (0:2)
@tab The first two bytes plus sign are the @dfn{address} field. Combined
with the INDEX field, denotes the memory address to be used by the
instruction.
@item INDEX @tab (3:3)
@tab The third byte is the @dfn{index}, normally used for indexing the
address@footnote{The actual memory address the instruction refers to, is
obtained by adding to ADDRESS the value of the @samp{rI} register
denoted by INDEX.}.
@item MOD @tab (4:4)
@tab Byte four is used either as an operation code modifier or as a field
specification.
@item OPCODE @tab (5:5)
@tab The last (least significant) byte in the word denotes the operation
code.
@end multitable

@noindent
or, graphically,

@example
 ------------------------------------------------
|   0   |   1   |   2   |   3   |   4   |   5    |
 ------------------------------------------------
|        ADDRESS        | INDEX |  MOD  | OPCODE |     
 ------------------------------------------------
@end example

For a given instruction, @samp{M} stands for
the memory address obtained after indexing the ADDRESS subfield 
(using its INDEX byte), and @samp{V} is the contents of the
subfield indicated by MOD of the memory cell with address @samp{M}. For
instance, suppose that we have the following contents of MIX registers
and memory cells:

@example
[rI2] = + 00 63
[31] = - 10 11 00 11 22
@end example
@noindent
where @samp{[n]} denotes the contents of the nth memory cell and
@samp{[rI2]} the contents of register @samp{rI2}@footnote{In general,
@samp{[X]} will denote the contents of entity @samp{X}; thus, by
definition, @w{@samp{V = [M](MOD)}}.}.  Let us consider the binary
instruction @w{@samp{I = - 00 32 02 11 10}}. For this instruction we
have:

@example
ADDRESS = - 00 32 = -32
INDEX = 02 = 2
MOD = 11 = (1:3)
OPCODE = 10

M = ADDRESS + [rI2] = -32 + 63 = 31
V = [M](MOD) = (- 10 11 00 11 22)(1:3) = + 00 00 10 11 00
@end example

In the following subsections, we will assing to each MIX instruction a
mnemonic, or symbolic name. For instance, the mnemonic of @samp{OPCODE}
10 is @samp{LD2}. Thus we can rewrite the above instruction as

@example
LD2  -32,2(1:3)
@end example
@noindent
or, for a generic instruction:

@example
MNEMONIC  ADDRESS,INDEX(MOD)
@end example
@noindent
Some instructions are identified by both the OPCODE and the MOD
fields. In these cases, the MOD will not appear in the above symbolic
representation. Also when ADDRESS or INDEX are zero, they can be
omitted.  Finally, MOD defaults to (0:5) (meaning the
whole word).

@node Loading operators, Storing operators, Instruction structure, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Loading operators
@cindex loading operators

The following instructions are used to load memory contents into a
register.

@ftable @code
@item LDA
Put in rA the contents of cell no. M.
OPCODE = 8, MOD = fspec. @code{rA <- V}.
@item LDX
Put in rX the contents of cell no. M.
OPCODE = 15, MOD = fspec. @code{rX <- V}.
@item LDi
Put in rIi the contents of cell no. M.
OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}.
@item LDAN
Put in rA the negative contents of cell no. M.
OPCODE = 16, MOD = fspec. @code{rA <- -V}.
@item LDXN
Put in rX the negative contents of cell no. M.
OPCODE = 23, MOD = fspec. @code{rX <- -V}.
@item LDiN
Put in rIi the negative contents of cell no. M.
OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}.
@end ftable

In all the above load instructions the @samp{MOD} field selects the
bytes of the memory cell with address @samp{M} which are loaded into the
requisite register (indicated by the @samp{OPCODE}).  For instance, the
word @w{@samp{+ 00 13 01 27 11}} represents the instruction

@example
LD3    13,1(3:3)
 ^      ^ ^  ^
 |      | |  |
 |      | |   --- MOD = 27 = 3*8 + 7
 |      |  --- INDEX = 1
 |       --- ADDRESS = 00 13
  --- OPCODE = 11
@end example
Let us suppose that, prior to this instruction execution, the state of
the MIX computer is the following:

@example
[rI1] = - 00 01
[rI3] = + 24 12
[12] = - 01 02 03 04 05
@end example
@noindent
As, in this case, @w{@samp{M = 13 + [rI1] = 12}}, we have
@w{@samp{V = [M](3:3) = (- 01 02 03 04 05)(3:3) = + 00 00 00 00 03}}
(note that the specified subfield is left-padded with null bytes to
complete a word). Hence, the MIX state, after the instruction execution,
will be

@example
[rI1] = - 00 01
[rI3] = + 00 03
[12] = - 01 02 03 04 05
@end example

To further illustrate loading operators, the following table shows the
contents of @samp{rX} after different @samp{LDX} instructions:

@table @samp
@item LDX 12(0:0)     [rX] = - 00 00 00 00 00
@item LDX 12(0:1)     [rX] = - 00 00 00 00 01
@item LDX 12(3:5)     [rX] = + 00 00 03 04 05
@item LDX 12(3:4)     [rX] = + 00 00 00 03 04
@item LDX 12(0:5)     [rX] = - 01 02 03 04 05
@end table


@node Storing operators, Arithmetic operators, Loading operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Storing operators
@cindex storing operators

The following instructions are the inverse of the load
operations: they are used to store a subfield of a register
into a memory location. Here, MOD represents the subfield of the memory
cell that is to be overwritten with bytes from a register. These bytes
are taken beginning by the rightmost side of the register.

@ftable @code
@item STA
Store rA. OPCODE = 24, MOD = fspec. @code{V <- rA}.
@item STX
Store rX. OPCODE = 31, MOD = fspec. @code{V <- rX}.
@item STi
Store rIi. OPCODE = 24 + i, MOD = fspec. @code{V <- rIi}.
@item STJ
Store rJ. OPCODE = 32, MOD = fspec. @code{V <- rJ}.
@item STZ
Store zero. OPCODE = 33, MOD = fspec. @code{V <- 0}.
@end ftable

By way of example, consider the instruction @samp{STA 1200(2:3)}. It
causes the MIX to fetch bytes no. 4 and 5 of register A and copy them to
bytes 2 and 3 of memory cell no. 1200 (remember that, for these
instructions, MOD specifies a subfield of @emph{the memory
address}). The others bytes of the memory cell retain their
values. Thus, if prior to the instruction execution we have

@example
[1200] = - 20 21 22 23 24
[rA] = + 01 02 03 04 05
@end example
@noindent
we will end up with

@example
[1200] = - 20 04 05 23 24
[rA] = + 01 02 03 04 05
@end example

As a second example, @samp{ST2 1000(0)} will set the sign of
@samp{[1000]} to that of @samp{[rI2]}.

@node Arithmetic operators, Address transfer operators, Storing operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Arithmetic operators
@cindex arithmetic operators

The following instructions perform arithmetic operations between rA and
rX register and memory contents.

@ftable @code
@item ADD
Add and set OV if overflow. OPCODE = 1, MOD = fspec. 
@w{@code{rA <- rA +V}}.
@item SUB
Sub and set OV if overflow. OPCODE = 2, MOD = fspec.
@w{@code{rA <- rA - V}}.
@item MUL
Multiply V times rA and store the 10-bytes product in rAX.
OPCODE = 3, MOD = fspec. @w{@code{rAX <- rA x V}}.
@item DIV
rAX is considered a 10-bytes number, and it is divided by V.
OPCODE = 4, MOD = fspec. @w{@code{rA <- rAX / V}}, @code{rX} <- reminder.
@end ftable

In all the above instructions, @samp{[rA]} is one of the operands
of the binary arithmetic operation, the other being @samp{V} (that is,
the specified subfield of the memory cell with address @samp{M}), padded
with zero bytes on its left-side to complete a word. In multiplication
and division, the register @samp{X} comes into play as a right-extension
of the register @samp{A}, so that we are able to handle 10-byte numbers
whose more significant bytes are those of @samp{rA} (the sign of this
10-byte number is that of @samp{rA}: @samp{rX}'s sign is ignored).

Addition and substraction of MIX words can give rise to overflows, since
the result is stored in a register with room to only 5 bytes (plus
sign). When this occurs, the operation result modulo @w{1,073,741,823}
(the maximum value storable in a MIX word) is stored in @samp{rA}, and
the overflow toggle is set to TRUE.

@node Address transfer operators, Comparison operators, Arithmetic operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Address transfer operators
@cindex address transfer operators

In these instructions, @samp{M} (the address of the instruction after
indexing) is used as a number instead of as the address of a memory
cell.

@ftable @code
@item ENTA
Enter [rA]. OPCODE = 48, MOD = 2. @code{rA <- M}.
@item ENTX
Enter [rX]. OPCODE = 55, MOD = 2. @code{rX <- M}.
@item ENTi
Enter [rIi]. OPCODE = 48 + i, MOD = 2. @code{rIi <- M}.
@item ENNA
Enter negative [rA]. OPCODE = 48, MOD = 3. @code{rA <- -M}.
@item ENNX
Enter negative [rX]. OPCODE = 55, MOD = 3. @code{rX <- -M}.
@item ENNi
Enter negative [rIi]. OPCODE = 48 + i, MOD = 3. @code{rIi <- -M}.
@item INCA
Increase [rA]. OPCODE = 48, MOD = 0. @code{rA <- rA + M}.
@item INCX
Increase [rX]. OPCODE = 55, MOD = 0. @code{rX <- rX + M}.
@item INCi
Increase [rIi]. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi + M}.
@item DECA
Decrease [rA]. OPCODE = 48, MOD = 1. @code{rA <- rA - M}.
@item DECX
Decrease [rX]. OPCODE = 55, MOD = 0. @code{rX <- rX - M}.
@item DECi
Decrease [rIi]. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi - M}.
@end ftable

In the above instructions, the subfield @samp{ADDRESS} acts as an
immediate (indexed) operand, and allow us to set directly the contents
of the MIX registers without an indirection to the memory cells (in a
real CPU this would mean that they are faster that the previously
discussed instructions, whose operands are fetched from memory). So, if
you want to store in @samp{rA} the value -2000 (- 00 00 00 31 16), you
can use the binary instruction @w{+ 31 16 00 03 48}, or, symbolically,

@example
ENNA 2000
@end example
@noindent
Used in conjuction with the store operations (@samp{STA}, @samp{STX},
etc.), these instructions also allow you to set memory cells contents to
concrete values.

Note that in these address transfer operators, the @samp{MOD} field is
not a subfield specificator, but serves to define (together with
@samp{OPCODE}) the concrete operation to be performed.

@node Comparison operators, Jump operators, Address transfer operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Comparison operators
@cindex comparison operators

So far, we have learned how to move values around between the MIX
registers and its memory cells, and also how to perform arithmetic
operations using these values. But, in order to write non-trivial
programs, other functionalities are needed. One of the most common is
the ability to compare two values, which, combined with jumps, will
allow the execution of conditional statements.
The following instructions compare the value of a register with @samp{V}, and
set the @sc{cm} indicator to the result of the comparison (i.e. to
@samp{E}, @samp{G} or @samp{L}, equal, greater or lesser respectively).

@ftable @code
@item CMPA
Compare [rA] with V. OPCODE = 56, MOD = fspec.
@item CMPX
Compare [rX] with V. OPCODE = 63, MOD = fspec.
@item CMPi
Compare [rIi] with V. OPCODE = 56 + i, MOD = fspec.
@end ftable

As explained above, these instructions modify the value of the MIX
comparison indicator; but maybe you are asking yourself how do you use
this value: enter jump operators, in the next subsection.

@node Jump operators, Input-output operators, Comparison operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Jump operators
@cindex jump operators

The MIX computer has an internal register, called the @dfn{location
counter}, which stores the address of the next instruction to be fetched
and executed by the virtual CPU. You cannot directly modify the contents
of this internal register with a load instruction: after fetching the
current instruction from memory, it is automatically increased in one
unit by the MIX. However, the is a set of instructions (which we call
jump instructions) which can alter the contents of the location counter
provided some condition is met. When this occurs, the value of the next
instruction address that would have been fetched in the absence of the
jump is stored in @samp{rJ} (except for @code{JSJ}), and the location
counter is set to the value of @samp{M} (so that the next instruction is
fetched from this new address). Later on, you can return to the point
when the jump occurred reading the address stored in @samp{rJ}.

The MIX computer provides the following jump instructions:
With these instructions you force a jump to the specified address. Use
@samp{JSJ} if you do not care about the return address.

@ftable @code
@item JMP
Unconditional jump. OPCODE = 39, MOD = 0.
@item JSJ
Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1.
@end ftable

These instructions check the overflow toggle to decide whether to jump
or not.

@ftable @code
@item JOV
Jump if OV is set (and turn it off). OPCODE = 39, MOD = 2.
@item JNOV
Jump if OV is not set (and turn it off). OPCODE = 39, MOD = 3.
@end ftable

In the following instructions, the jump is conditioned to the contents of the
comparison flag:

@ftable @code
@item JL
Jump if @w{@code{[CM] = L}}. OPCODE = 39, MOD = 4.
@itemx JE
Jump if @w{@code{[CM] = E}}. OPCODE = 39, MOD = 5.
@itemx JG
Jump if @w{@code{[CM] = G}}. OPCODE = 39, MOD = 6.
@itemx JGE
Jump if @code{[CM]} does not equal @code{L}. OPCODE = 39, MOD = 7.
@itemx JNE
Jump if @code{[CM]} does not equal @code{E}. OPCODE = 39, MOD = 8.
@itemx JLE
Jump if @code{[CM]} does not equal @code{G}. OPCODE = 39, MOD = 9.
@end ftable

You can also jump conditioned to the value stored in the MIX registers,
using the following instructions:

@ftable @code
@item JAN
@itemx JAZ
@itemx JAP
@itemx JANN
@itemx JANZ
@itemx JANP
Jump if the contents of rA is, respectively, negative, zero, positive,
non-negative, non-zero or non-positive. 
OPCODE = 40, MOD = 0, 1, 2, 3, 4, 5.
@item JXN
@itemx JXZ
@itemx JXP
@itemx JXNN
@itemx JXNZ
@itemx JXNP
Jump if the contents of rX is, respectively, negative, zero, positive,
non-negative, non-zero or non-positive. 
OPCODE = 47, MOD = 0, 1, 2, 3, 4, 5.
@item JiN
@itemx JiZ
@itemx JiP
@itemx JiNN
@itemx JiNZ
@itemx JiNP
Jump if the contents of rIi is, respectively, negative, zero, positive,
non-negative, non-zero or non-positive. 
OPCODE = 40 + i, MOD = 0, 1, 2, 3, 4, 5.
@end ftable


@node Input-output operators, Conversion operators, Jump operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Input-output operators
@cindex input-output operators

As explained in previous sections (@pxref{MIX architecture}), the MIX
computer can interact with a series of block devices. To that end, you
have at your disposal the following instructions:

@ftable @code
@item IN
Transfer a block of words from the specified unit to memory, starting at
address M.
OPCODE = 36, MOD = I/O unit.
@item OUT
Transfer a block of words from memory (starting at address M) to the
specified unit.
OPCODE = 37, MOD = I/O unit.
@item IOC
Perfom a control operation (given by M) on the specified unit.
OPCODE = 35, MOD = I/O unit.
@item JRED
Jump to M if the specified unit is ready.
OPCODE = 38, MOD = I/O unit.
@item JBUS
Jump to M if the specified unit is busy.
OPCODE = 34, MOD = I/O unit.
@end ftable
@noindent
In all the above instructions, the @samp{MOD} subfile must be in the
range 0-20, since it denotes the operation's target device. The
@samp{IOC} instruction only makes sense for tape devices (@samp{MOD} =
0-7 or 20): it shifts the read/write pointer by the number of words
given by @samp{M} (if it equals zero, the tape is rewound)@footnote{In
Knuth's original definition, there are other control operations
available, but they do not make sense when implementing the block
devices as disk files (as we do in @sc{mdk} simulator). For the same
reason, @sc{mdk} devices are always ready, since all input-output
operations are performed using synchronous system calls.}.


@node Conversion operators, Shift operators, Input-output operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Conversion operators
@cindex conversion operators

The following instructions convert between numerical values and their
character representations.

@ftable @code
@item NUM
Convert rAX, assumed to contain a character representation of a number,
to its numerical value and store it in rA.
OPCODE = 5, MOD = 0.
@item CHAR
Convert the number stored in rA to a character representation and store
it in rAX.
OPCODE = 5, MOD = 1.
@end ftable
@noindent
Digits are represented in MIX by the range of values 30-39 (digits
9-0). Thus, if the contents of @samp{rA} and @samp{rX} is, for instance,

@example
[rA] = + 30 30 31 32 33
[rX] = + 31 35 39 30 34
@end example
@noindent
the represented number is 0012315904, and @samp{NUM} will store this
value in @samp{rA} (i.e., we end up with @samp{[rA]} = @w{+ 0 46 62 52
0} = 12315904. @samp{CHAR} performs the inverse operation.

@node Shift operators, Miscellaneous operators, Conversion operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Shift operators
@cindex shift
@cindex shift operators

The following instructions perform byte-wise shifts of the contents of
@samp{rA} and @samp{rX}.

@ftable @code
@item SLA
@itemx SRA
@itemx SLAX
@itemx SRAX
@itemx SLC
@itemx SRC
Shift rA or rAX left, right, or rAX circularly left or right. M
specifies the number of bytes to be shifted.
OPCODE = 6, MOD = 0, 1, 2, 3, 4, 5.
@end ftable
@noindent
If we begin with, say, @samp{[rA]} = @w{- 01 02 03 04 05}, we would
have the following modifications to @samp{rA} contents when performing
the instructions on the left column:

@multitable {SLA 00} {[rA] = - 00 00 00 00 00}
@item SLA 2 @tab [rA] = - 03 04 05 00 00
@item SRA 1 @tab [rA] = - 00 01 02 03 04
@item SLC 3 @tab [rA] = - 04 05 01 02 03
@item SRC 24 @tab [rA] = - 05 01 02 03 04
@end multitable
@noindent
Note that the sign is unaffected by shift operations. On the other hand,
@samp{SLAX} and @samp{SRAX} treat @samp{rA} and @samp{rX} as a single
10-bytes register (ignoring again the signs), so that, if we begin with
@samp{[rA]} = @w{+ 01 02 03 04 05} and @samp{[rX]} = @w{- 06 07 08 09
10}, executing @samp{SLAX 3} would yield:

@example
[rA] = + 04 05 06 07 08  [rX] = - 09 10 00 00 00
@end example

@node Miscellaneous operators, Execution times, Shift operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Miscellaneous operators
@cindex miscellaneous operators

Finally, we list in the following table three miscellaneous MIX
instructions which do not fit in any of the previous subsections:

@ftable @code
@item MOVE
Move MOD words from M to the location stored in rI1.
OPCODE = 7, MOD = no. of bytes.
@item NOP
No operation. OPCODE = 0, MOD = 0.
@item HLT
Halt. Stops instruction fetching. OPCODE = 5, MOD = 2.
@end ftable
@noindent
The only effect of executing @samp{NOP} is increasing the location
counter, while @samp{HLT} usually marks program termination.

@node Execution times,  , Miscellaneous operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Execution times

@cindex exection time
@cindex time

When writing MIXAL programs (or any kind of programs, for that matter),
whe shall often be interested in their execution time. Loosely speaking,
we will interested in the answer to the question: how long takes a
program to execute? Of course, this execution time will be a function of
the input size, and the answer to our question is commonly given as the
asymptotic behaviour as a function of the input size. At any rate, to
compute this asymptotic behaviour, we need a measure of how long
execution of a single instruction takes in our (virtual) CPU. Therefore,
each MIX instruction will have an associated execution time, given in
arbitrary units (in a real computer, the value of this unit will depend
on the hardware configuration). When our MIX virtual machine executes
programs, it will give you the value of their execution time based upon
the execution time of each single instruction.

In the following table, the execution times (in the above mentioned
arbitrary units) of the MIX instructions are given.

@multitable {INSSSS} {01} {INSSSS} {01} {INSSSS} {01} {INSSSS} {01}
@item @code{NOP} @tab 1 @tab @code{ADD} @tab 2 @tab @code{SUB}
@tab 2 @tab @code{MUL} @tab 10
@item @code{DIV} @tab 12 @tab @code{NUM} @tab 10 @tab @code{CHAR}
@tab 10 @tab @code{HLT} @tab 10
@item @code{SLx} @tab 2 @tab @code{SRx} @tab 2 @tab @code{LDx}
@tab  2 @tab @code{STx} @tab 2 
@item @code{JBUS} @tab 1 @tab @code{IOC} @tab 1 @tab @code{IN}
@tab  1@tab @code{OUT} @tab 1
@item @code{JRED} @tab 1 @tab @code{Jx} @tab 1 @tab @code{INCx}
@tab  1 @tab @code{DECx} @tab 1 
@item @code{ENTx} @tab 1 @tab @code{ENNx} @tab 1 @tab @code{CMPx}
@tab  1 @tab @code{MOVE} @tab 1+F  
@end multitable

In the above table, 'F' stands for the number of blocks to be moved
(given by the @code{FSPEC} subfield of the instruction); @code{SLx} and
@code{SRx} are a short cut for the byte-shifting operations; @code{LDx}
denote all the loading operations; @code{STx} are the storing
operations; @code{Jx} stands for all the jump operations, and so on with
the rest of abbreviations.

@node MIXAL,  , The MIX computer, MIX and MIXAL tutorial
@comment  node-name,  next,  previous,  up
@section MIXAL
@cindex MIXAL
@cindex MIX assembly language
@cindex assembly

In the previous sections we have listed all the available MIX binary
instructions. As we have shown, each instruction is represented by a
word which is fetched from memory and executed by the MIX virtual
CPU. As is the case with real computers, the MIX knows how to decode
instructions in binary format (the so--called machine language), but a
human programmer would have a tough time if she were to write her
programs in machine language. Fortunately, the MIX computer can be
programmed using an assembly language, MIXAL, which provides a symbolic
way of writing the binary instructions understood by the imaginary MIX
computer. If you have used assembler languages before, you will find
MIXAL a very familiar language. MIXAL source files are translated
to machine language by a MIX assembler, which produces a binary file (the
actual MIX program) which can be directly loaded into the MIX memory and
subsequently executed.

In this section, we describe MIXAL, the MIX assembly language. The
implementation of the MIX assembler program and MIX computer simulator
provided by @sc{mdk} are described later on (@pxref{Getting started}).

@menu
* Basic structure::             Writing basic MIXAL programs.
* MIXAL directives::            Assembler directives.
* Expressions::                 Evaluation of expressions.
* W-expressions::               Evaluation of w-expressions.
* Local symbols::               Special symbol table entries.
* Literal constants::           Specifying an immediate operand.
@end menu

@node Basic structure, MIXAL directives, MIXAL, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Basic program structure

The MIX assembler reads MIXAL files line by line, producing, when
required, a binary instruction, which is associated to a predefined
memory address. To keep track of the current address, the assembler
maintains an internal location counter which is incremented each time an
instruction is compiled. In addition to MIX instructions, you can
include in MIXAL file assembly directives (or pseudoinstructions)
addressed at the assembler itself (for instance, telling it where the
program starts and ends, or to reposition the location counter; see below).

MIX instructions and assembler directives@footnote{We shall call them,
collectively, MIXAL instructions.} are written in MIXAL (one per
source file line) according to the following pattern:

@example
[LABEL]   MNEMONIC  [OPERAND]   [COMMENT]
@end example

@noindent
where @samp{OPERAND} is of the form

@example
[ADDRESS][,INDEX][(MOD)]
@end example

Items between square brackets are optional, and

@table @code
@item LABEL
Is an alphanumeric identifier (a @dfn{symbol}) which gets the current
value of the location counter, and can be used in subsequent
expressions.
@item MNEMONIC
Is a literal denoting the operation code of the instruction
(e.g. @code{LDA}, @code{STA}; see @pxref{MIX instruction set}) or an
assembly pseudoinstruction (e.g. @code{ORG}, @code{EQU}).
@item ADDRESS
Expression evaluating to the address subfield of the instruction.
@item INDEX
Expression evaluating to the index subfield of the instruction. It
defaults to 0 (i.e., no use of indexing) and can only be used when 
@code{ADDRESS} is present.
@item MOD
Expression evaluating to the mod subfield of the instruction. Its
default value, when omitted, depends on @code{OPCODE}.
@item COMMENT
Any number of spaces after the operand mark the beggining of a comment,
i.e. any text separated by white space from the operand is ignored by
the assembler (note that spaces are not allowed within the
@samp{OPERAND} field).
@end table

Note that spaces are @emph{not} allowed between the @code{ADDRESS},
@code{INDEX} and @code{MOD} fields if they are present. White space is
used to separate the label, operation code and operand parts of the
instruction@footnote{In fact, Knuth's definition of MIXAL restricts the
column number at which each of these instruction parts must start. The
MIXAL assembler included in @sc{mdk}, @code{mixasm}, does not impose
such restriction.}.

We have already listed the mnemonics associated will each MIX
instructions; sample MIXAL instructions representing MIX instructions
are:
@example
HERE     LDA  2000         HERE represents the current location counter
         LDX  HERE,2(1:3)  this is a comment
         JMP  1234
@end example

@node MIXAL directives, Expressions, Basic structure, MIXAL
@comment  node-name,  next,  previous,  up
@subsection MIXAL directives

MIXAL instructions can be either one of the MIX machine instructions
(@pxref{MIX instruction set}) or one of the following assembly
pseudoinstructions:

@ftable @code
@item ORIG
Sets the value of the memory address to which following instructions
will be allocated after compilation.
@item EQU
Used to define a symbol's value, e.g. @w{@code{SYM  EQU  2*200/3}}.
@item CON
The value of the given expression is copied directly into the current
memory address.
@item ALF
Takes as operand five characters, constituting the five bytes of a word
which is copied directly into the current memory address.
@item END
Marks the end of the program. Its operand gives the start address for
program execution.
@end ftable

The operand of @code{ORIG}, @code{EQU}, @code{CON} and @code{END} can be
any expression evaluating to a constant MIX word, i.e., either a simple
MIXAL expression (composed of numbers, symbols and binary operators,
@pxref{Expressions}) or a w-expression (@pxref{W-expressions}).

All MIXAL programs must contain an @code{END} directive, with a twofold
end: first, it marks the end of the assembler job, and, in the second
place, its (mandatory) operand indicates the start address for the
compiled program (that is, the address at which the virtual MIX machine
must begin fetching instructions after loading the program). It is also
very common (although not mandatory) to include at least an @code{ORIG}
directive to mark the initial value of the assembler's location counter
(remember that it stores the address associated with each compiled MIX
instruction). Thus, a minimal MIXAL program would be

@example
          ORIG  2000    set the initial compilation adress
          NOP           this instruction will be loaded at adress 2000
          HLT           and this one at address 2001
          END   2000    end of program; execution will start at address 2000
this line is not parsed by the assembler
@end example
@noindent
The assembler will generate two binary instructions (@code{NOP} (@w{+ 00
00 00 00 00}) and @code{HLT} (+ 00 00 02 05)), which will be loaded at
addresses 2000 and 2001. Execution of the program will begin at address
2000. Every MIXAL program should also include a @code{HLT} instruction,
which will mark the end of program execution (but not of program
compilation). 

The @code{EQU} directive allows the definition of symbolic names for
specific values. For instance, we could rewrite the above program as
follows:

@example
START     EQU   2000
          ORIG  START
          NOP
          HLT
          END   START
@end example
@noindent
which would give rise to the same compiled code. Symbolic constants (or
symbols, for short) can also be implicitly defined placing them in the
@code{LABEL} field of a MIXAL instruction: in this case, the assembler
assigns to the symbol the value of the location counter before compiling
the line. Hence, a third way of writing our trivial program is

@example
          ORIG  2000
START     NOP
          HLT
          END   START
@end example

The @code{CON} directive allows you to directly specify the contents of
the memory address pointed by the location counter. For instance, when
the assembler encounters the following code snippet

@example
          ORIG  1150
          CON   -1823473
@end example
@noindent
it will assign to the memory cell number 1150 the contents @w{- 00 06 61
11 49} (which corresponds to the decimal value -1823473). 

Finally, the @code{ALF} directive let's you specify the memory contents
as a set of five (quoted) characters, which are translated by the
assembler to their byte values, conforming in that way the binary word
that is to be stored in the corresponding memory cell. This directive
comes in handy when you need to store printable messages in a memory
address, as in the following example:

@example
          OUT  MSG       MSG is not yet defined here (future reference)
MSG       ALF  "THIS "   MSG gets defined here
          ALF  "IS A "
          ALF  "MESSA"
          ALF  "GE.  "
@end example
@noindent
The above snippet also shows the use of a @dfn{future reference}, that
is, the usage of a symbol (@code{MSG} in the example) prior of its actual
definition. The MIXAL assembler is able to handle future references
subject to some limitations which are described in the following section
(@pxref{Expressions}).

@cindex comments

Any line starting with an asterisk is treated as a comment and ignored
by the assembler.

@example
* This is a comment: this line is ignored.
    * This line is an error: * must be in column 1.
@end example

As noted in the previous section, comments can also be located after the
@code{MNEMONIC} field of an instruction, separated from it by white
space, as in

@example
LABEL     LDA   100  This is also a comment
@end example

@node Expressions, W-expressions, MIXAL directives, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Expressions
@cindex operator
@cindex binary operator
@cindex unary operator
The @code{ADDRESS}, @code{INDEX} and @code{MOD} fields of a MIXAL
instruction can be expressions, formed by numbers, identifiers and
binary operators (@code{+ - * / // :}). @code{+} and @code{-} can also
be used as unary operators. Order of evaluation is from left to right:
there is no other operator precedence rule, and parentheses cannot be
used for grouping. A stand-alone asterisk denotes the current memory
location; thus, for instance,

@example
     4+2**
@end example

@noindent
evaluates to 4 plus two times the current memory location. White space
is not allowed within expressions.

The special binary operator @code{:} has the same meaning as in fspecs,
i.e.,

@example
A:B = 8*A + B
@end example
@noindent
while @code{A//B} stands for the quotient of the ten-byte number @w{@code{A} 00
00 00 00 00} (that is, A right-padded with 5 null bytes or, what amounts
to the same, multiplied by 64 to the fifth power) divided by
@code{B}. Sample expressions are:

@example
18-8*3 = 30
14/3 = 4
1+3:11 = 4:11 = 43
1//64 = (01 00 00 00 00 00)/(00 00 00 01 00) = (01 00 00 00 00 00)
@end example
@noindent
Note that all MIXAL expressions evaluate to a MIX word (by definition).

All symbols appearing within an expression must be previously defined. Future
references are only allowed when appearing stand-alone (or modified by
an unary operator) in the @code{ADDRESS} part of a MIXAL instruction,
e.g.

@example
* OK: stand alone future reference 
         STA  -S1(1:5)
* ERROR: future reference in expression
         LDX  2-S1
S1       LD1  2000
@end example

@node W-expressions, Local symbols, Expressions, MIXAL
@comment  node-name,  next,  previous,  up
@subsection W-expressions
@cindex w-expressions

Besides expressions, as described above (@pxref{Expressions}), the MIXAL
assembler is able to handle the so called @dfn{w-expressions} as the
operands of the directives @code{ORIG}, @code{EQU}, @code{CON} and
@code{END} (@pxref{MIXAL directives}). The general form of a
w-expression is the following:

@example
     WEXP = EXP[(EXP)][,WEXP]
@end example
@noindent
where @code{EXP} stands for an expression and square brackets denote
optional items. Thus, a w-expression is made by a regular expression
followed by an optional expression between parenthesis, followed by any
number of similar constructs separated by commas. Sample w-expressions
are:

@example
2000
235(3)
S1+3(S2),3000
S1,S2(3:5),23
@end example

W-expressions are evaluated as follows. First, all expressions are
evaluated according to the rules given in the previous section. Thus, if
we start with, say, @samp{S1+2(2:4)} where @samp{S1} equals 265230, we
have @samp{265232(2:4)}. The expression between parenthesis must be a
valid f-spec, for it specifies the bytes to be taken from the preceding
word. In our example, we must take 3 bytes of the word @w{@samp{+ 00 01
00 48 16}} (which is 265232), and store them in positions 2, 3 and 4 of
the result, resulting in the new word @w{@samp{+ 00 00 48 16 00}} (i.e.,
the decimal value 197632). When we have two expressions separated with a
comma, we take, for each one, the subfield specified and compose the
word to obtain the result. For instance, in the w-expression

@example
1(1:2),66(4:5)
@end example
@noindent
we first take two bytes from 1 (00 and 01) and store them as bytes 1 and
2 of the result (obtaining @w{@samp{+ 00 01 00 00 00}}) and, afterwards,
take two bytes from 66 (01 and 02) and store them as bytes 4 and 5 of
the result, obtaining @w{@samp{+ 00 01 00 01 02}} (262210). The process
is repeated for each new comma-separated example. For instance:

@example
1(1:1),2(2:2),3(3:3),4(4:4) = 01 02 03 04 00
@end example

As stated before, w-expressions can only appear as the operands of MIXAL
directives taking a constant value (@code{ORIG}, @code{EQU}, @code{CON}
and @code{END}). Future references are @emph{not} allowed within
w-expressions (i.e., all symbols appearing in a w-expression must be
defined before they are used).

@node Local symbols, Literal constants, W-expressions, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Local symbols
@cindex local symbols

Besides user defined symbols, MIXAL programmers can use the so called
@dfn{local symbols}, which are symbols of the form @code{[1-9][HBF]}. A
local symbol @code{nB} refers to the address of the last previous
occurrence of @code{nH} as a label, while @code{nF} refers to the next
@code{nH} occurrence. Unlike user defined symbols, @code{nH} can appear
multiple times in the @code{LABEL} part of different MIXAL
instructions. The following code shows an instance of local symbols'
usage:

@example
* line 1
1H    LDA  100
* line 2: 1B refers to address of line 1, 3F refers to address of line 4
      STA  3F,2(1B//2)
* line 3: redefinition of 1H
1H    STZ
* line 4: 1B refers to address of line 3
3H    JMP  1B
@end example

Note that a @code{B} local symbol never refers to a definition in its
own line, that is, in the following program:

@example
		ORIG 1999
ST		NOP
3H		EQU 69
3H		ENTA 3B  local symbol 3B refers to 3H in previous line
		HLT
		END ST
@end example
@noindent
the contents of @samp{rA} is set to 69 and @emph{not} to 2001. An
specially tricky case occurs when using local symbols in conjunction
with @code{ORIG} pseudoinstructions. To wit@footnote{The author wants to
thank Philip E. King for pointing these two special cases of local
symbol usage to him.},

@example
		ORIG 1999 
ST		NOP
3H		CON 10
		ENT1 *
		LDA 3B
** rI1 is 2001, rA is 10.  So far so good!
3H		ORIG 3B+1000
** at this point 3H equals 2003
** and the location counter equals 3000.
		ENT2 *
		LDX 3B
** rI2 contains 3000, rX contains 2003.
		HLT
		END ST
@end example

@node Literal constants,  , Local symbols, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Literal constants
@cindex literal constants

MIXAL allows the introduction of @dfn{literal constants}, which are
automatically stored in memory addresses after the end of the program by
the assembler. Literal constants are denoted as @code{=wexp=}, where
@code{exp} is an w-expression (@pxref{W-expressions}). For instance, the
code

@example
L         EQU   10
          LDA   =20-L=
@end example

causes the assembler to add after the program's end an instruction with
contents 10, and to assemble the above code as the instruction @w{@code{
LDA a}}, where @code{a} stands for the address in which the value 10 is
stored. In other words, the compiled code is equivalent to the
following:

@example
L         EQU  10
          LDA  a
@dots{}
a         CON  20-L    
          END  start
@end example


@node Getting started, mixvm, MIX and MIXAL tutorial, Top
@comment  node-name,  next,  previous,  up
@chapter Getting started

In this chapter, you will find a sample code-compile-run-debug session
using the @sc{mdk} utilities. Familiarity with the MIX mythical computer
and its assembly language MIXAL (as described in Knuth's TAOCP) is
assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}. 

@menu
* Writing a source file::       A sample MIXAL source file.
* Compiling::                   Using @code{mixasm} to compile source
                                files into binary format.
* Running the program::         Running and debugging your program.
@end menu

@node Writing a source file, Compiling, Getting started, Getting started
@comment  node-name,  next,  previous,  up
@section Writing a source file
@cindex MIXAL
@cindex source file

MIXAL programs can be written as ASCII files with your editor of choice.
Here you have the mandatory @emph{hello world} as written in the MIXAL
assembly language:

@example
*                                                        (1)
* hello.mixal: say 'hello world' in MIXAL                (2)
*                                                        (3)
* label ins    operand     comment                       (4)
TERM    EQU    19          the MIX console device number (5)
        ORIG   1000        start address                 (6)
START   OUT    MSG(TERM)   output data at address MSG    (7)
        HLT                halt execution                (8)
MSG     ALF    "MIXAL"                                   (9)
        ALF    " HELL"                                   (10)
        ALF    "O WOR"                                   (11)
        ALF    "LD   "                                   (12)
        END    START       end of the program            (13)
@end example
         
@noindent MIXAL source files should have the extension @file{.mixal}
when used with the @sc{mdk} utilities. As you can see in the above
sample, each line in a MIXAL file can be divided into four fields
separated by an arbitrary amount of whitespace characters (blanks and or
tabs). While Knuth's definition of MIXAL each field must start at a
fixed pre-defined column number, the @sc{mdk} assembler loosens this
requirement and lets you format the file as you see fit. The only
restrictions retained are for comment lines (like 1-4) which must begin
with an asterisk (*) placed at column 1, and for the label field (see
below) which, if present, must also start at column 1. The four fields
in each non-comment line are:

@itemize @minus
@item
an optional label, which either refers to the current memory address (as
@code{START} and @code{MSG} in lines 7 and 9) or a defined symbol
(@code{TERM}) (if present, the label must always start at the first
column in its line, for the first whitespace in the line maks the
beginning of the second field),
@item
an operation mnemonic, which can represent either a MIX instruction
(@code{OUT} and @code{HLT} in lines 6 and 7 above), or an assembly
pseudoinstruction.
@item
an optional operand for the (pseudo)instruction, and
@item
an optional free text comment.
@end itemize

@noindent Lines 9-12 of the @file{hello.mixal} file above also show the
second (and last) difference between Knuth's MIXAL definition and ours:
the operand of the @code{ALF} pseudoinstruction (a word of five
characters) must be quoted with using ""@footnote{In Knuth's definition,
the operand always starts at a fixed column number, and the use of
quotation is therefore unnecessary. As @code{mixasm} releases this
requirement, marking the beginning and end of the @code{ALF} operand
disambiguates the parser's recognition of this operand when it includes
blanks}. 

The workings of this sample program should be straightforward if you are
familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or
@ref{MIX and MIXAL tutorial}, for a quick tutorial.

@node Compiling, Running the program, Writing a source file, Getting started
@comment  node-name,  next,  previous,  up
@section Compiling
@cindex compiling
@cindex binary programs
@cindex virtual machine
@cindex assembler
@cindex @code{mixasm}

A simulator of the MIX computer, called @code{mixvm} (MIX virtual
machine) is included in the @sc{mdk} tools. It is able to run binary
files containing MIX instructions written in their binary
representation. You can translate MIXAL source files into this binary
form using @code{mixasm}, the MIXAL assembler. So, in order to compile
the @file{hello.mixal} file, you can type the following 
command at your shell prompt:

@example
mixasm -g hello @key{RET}
@end example

If the source file contains no errors, this will produce a binary file
called @file{hello.mix} which can be loaded and run by the MIX virtual
machine. The @code{-g} flag tells the assembler to include debug
information in the executable file (for a complete description of all
the compilation options, see @ref{mixasm}.) Now, your are ready to run
your first MIX program, as described in the following section.


@node Running the program,  , Compiling, Getting started
@comment  node-name,  next,  previous,  up
@section Running the program
@cindex @code{mixvm}
@cindex non-interactive mode
@cindex interactive mode

MIX is a mythical computer, so it is no use ordering it from your
favorite hardware provider. @sc{mdk} provides a software simulator of
the computer, though. It is called @code{mixvm}, which stands for
@dfn{MIX virtual machine}. Using it, you can run your MIXAL programs,
after compiling them with @code{mixasm} into binary @file{.mix}
files. @code{mixvm} can be used either in @dfn{interactive} or
@dfn{non-interactive} mode. In the second case, @code{mixvm} will load
your program into memory, execute it (producing any output due to MIXAL
@code{OUT} instructions present in the program), and exit when it
encounters a @code{HLT} instruction. In interactive mode, you will enter
a shell prompt which allows you issuing commands to the running virtual
machine. This commands will permit you loading, running and debugging
programs, as well as inspecting the MIX computer state (register
contents, memory cells contents and so on).

@menu
* Non-interactive mode::        Running your programs non-interactively.
* Interactive mode::            Running programs interactively.
* Debugging::                   Commands for debugging your programs.
@end menu

@node Non-interactive mode, Interactive mode, Running the program, Running the program
@comment  node-name,  next,  previous,  up
@subsection Non-interactive mode
@cindex non-interactive mode

To make @code{mixvm} work in non-interactive mode, use the @code{-r}
flag. Thus, to run our @file{hello.mix} program, simply type

@example
mixvm -r hello @key{RET}
@end example

@noindent at your command prompt, and you will get the following output:

@example
MIXAL HELLO WORLD
** Execution time: 11
@end example

@noindent Since our hello world program uses MIX's device number 19 as
its output device (@pxref{Writing a source file}), the output is
redirected to the shell's standard output. Had you used any other MIX
output devices (disks, drums, line printer, etc.), @code{mixvm} would
have created a file named after the device used (e.g. @file{disk4.dev})
and written its output there. Note also that the virtual machine reports
the execution time of the program, according to the (virtual) time spent
in each of the binary instructions (@pxref{Execution times}).

Sometimes, you will prefer to store the results of your program in MIX
registers rather than writing them to a device. In such cases,
@code{mixvm}'s @code{-d} flag is your friend: it makes @code{mixvm} to
dump the contents of its registers and flags after executing the loaded
program. For instance, typing the following command at your shell's
prompt

@example
mixvm -d -r hello
@end example

@noindent you will obtain the following output:

@example
MIXAL HELLO WORLD
** Execution time: 11
rA: + 00 00 00 00 00 (0000000000)
rX: + 00 00 00 00 00 (0000000000)
rJ: + 00 00 (0000)
rI1: + 00 00 (0000)     rI2: + 00 00 (0000)     
rI3: + 00 00 (0000)     rI4: + 00 00 (0000)     
rI5: + 00 00 (0000)     rI6: + 00 00 (0000)     
Overflow: F
Cmp: E
@end example

@noindent which, in addition to the program's outputs and execution
time, gives you the contents of the MIX registers and the values of the
overflow toggle and comparison flag (admittedly, rather uninteresting in
our sample).

As you can see, running programs non-interactively has many
limitations. You cannot peek the virtual machine's memory contents, not
to mention stepping through your program's instructions or setting
breakpoints. Enter interactive mode.

@node Interactive mode, Debugging, Non-interactive mode, Running the program
@comment  node-name,  next,  previous,  up
@subsection Interactive mode
@cindex interactive mode

To enter the MIX virtual machine interactive mode, simply type

@example
mixvm @key{RET}
@end example

@noindent at your shell command prompt. This command enters the
@code{mixvm} command shell. You will be presented the following command
prompt:

@example
MIX >
@end example

@noindent The virtual machine is initialised and ready to accept your
commands. The @code{mixvm} command shell uses GNU's readline, so that
you have at your disposal command completion (using @key{TAB}) and
history functionality, as well as other line editing shortcuts common to
all utilities using this library (for a complete description of
readline's line editing usage, see @ref{Command Line
Editing,,,Readline}.)

Usually, the first thing you will want to do is loading a compiled MIX
program into memory. This is acomplished by the @code{load} command,
which takes as an argument the name of the @file{.mix} file to be
loaded. Thus, typing

@example
MIX > load hello @key{RET}
Program loaded. Start address: 3000
MIX >
@end example

@noindent will load @file{hello.mix} into the virtual machine's memory
and set the program counter to the address of the first instruction. You
can obtain the contents of the program counter using the command
@code{pc}:

@example
MIX > pc
Current address: 3000
MIX >
@end example

After loading it, you are ready to run the program, using, as you surely
have guessed, the @code{run} command:

@example
MIX > run
Running ...
MIXAL HELLO WORLD                                                     
... done
Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
MIX > 
@end example

@noindent Note that now the timing statistics are richer. You obtain the
elapsed execution time (i.e., the time spent executing instructions
since the last breakpoint), the total execution time for the program up
to now (which in our case coincides with the elapsed time, since there
were no breakpoints), and the total uptime for the virtual machine (you
can load and run more than one program in the same session). After
running the program, the program counter will point to the address after
the one containing the @code{HLT} instruction. In our case, asking the
value of the program counter after executing the program will give us

@example
MIX > pc
Current address: 3002
MIX >
@end example

@noindent You can check the contents of a memory cell giving its address
as an argument of the command @code{pmem}, like this

@example
MIX > pmem 3001
3001: + 00 00 00 02 05 (0000000133)
MIX >
@end example

@noindent
and convince yourself that address 3001 contains the binary
representation of the instruction @code{HLT}. An address range of the
form FROM-TO can also be used as the argument of @code{pmem}:

@example
MIX > pmem 3000-3006
3000: + 46 58 00 19 37 (0786957541)
3001: + 00 00 00 02 05 (0000000133)
3002: + 14 09 27 01 13 (0237350989)
3003: + 00 08 05 13 13 (0002118477)
3004: + 16 00 26 16 19 (0268542995)
3005: + 13 04 00 00 00 (0219152384)
3006: + 00 00 00 00 00 (0000000000)
MIX >
@end example

@noindent
In a similar manner, you can look at the contents of the MIX registers
and flags. For instance, to ask for the contents of the A register you
can type

@example
MIX > preg A
rA: + 00 00 00 00 00 (0000000000)
MIX >
@end example

@noindent
Use the comand @code{help} to obtain a list of all available commands,
and @code{help COMMAND} for help on a specific command, e.g.

@example
MIX > help run
run             Run loaded or given MIX code file. Usage: run [FILENAME]
MIX > 
@end example

@noindent
For a complete list of commands available at the MIX propmt,
@xref{mixvm}. In the following subsection, you will find a quick tour
over commands useful for debugging your programs.

@node Debugging,  , Interactive mode, Running the program
@comment  node-name,  next,  previous,  up
@subsection Debugging commands

The interactive mode of @code{mixvm} lets you step by step execution of
programs as well as breakpoint setting. Use @code{next} to step through
the program, running its instructions one by one. To run our
two-instruction @file{hello.mix} sample you can do the following:

@example
MIX > load hello
Program loaded. Start address: 3000
MIX > pc
Current address: 3000
MIX > next
MIXAL HELLO WORLD
Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
MIX > pc
Current address: 3001
MIX > next
End of program reached at address 3002
Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
MIX > pc
Current address: 3002
MIX > next
MIXAL HELLO WORLD
Elapsed time: 1 /Total program time: 1 (Total uptime: 12)
MIX > 
MIX > run
Running ...
... done
Elapsed time: 10 /Total program time: 11 (Total uptime: 22)
MIX > @end example
@noindent
(As an aside, the above sample also shows how the virtual machine
handles cummulative time statistics and automatic program restart).

You can set a breakpoint at a given address using the command
@code{sbpa} (set breakpoint at address). When a breakpoint is set,
@code{run} will stop before executing the instruction at the given
address. Typing @code{run} again will resume program execution. Coming
back to our hello world example, we would have:

@example
MIX > sbpa 3001
Breakpoint set at address 3001
MIX > run
Running ...
MIXAL HELLO WORLD                                                     
... stopped: breakpoint at line 8 (address 3001)
Elapsed time: 1 /Total program time: 1 (Total uptime: 23)
MIX > run
Running ...
... done
Elapsed time: 10 /Total program time: 11 (Total uptime: 33)
MIX >
@end example

@noindent
Note that, since we compiled @file{hello.mixal} with debug info enabled
(the @code{-g} flag of @code{mixasm}), the virtual machine is able to
tell us the line in the source file corresponding to the breakpoint we
are setting. As a matter of fact, you can directly set breakpoints at
source code lines using the command @code{sbp LINE_NO}, e.g.

@example
MIX > sbp 4
Breakpoint set at line 7
MIX > 
@end example

@noindent
@code{sbp} sets the breakpoint at the first meaningful source code line;
thus, in the above example we have requested a breakpoint at a line
which does not correspond to a MIX instruction and the breakpoint is set
at the first line containing a real instruction after the given one. To
unset breakpoints, use @code{cbpa ADDRESS} and @code{cbp LINE_NO}, or
@code{cabp} to remove all currently set breakpoints. 

MIXAL lets you define symbolic constants, either using the @code{EQU}
pseudoinstruction or starting an instruction line with a label (which
assigns to the label the value of the current memory address). Each
MIXAL program has, therefore, an associated symbol table which you can
inspect using the @code{psym} command. For our hello world sample, you
will obtain the following output:

@example
MIX > psym
START:  3000
TERM:  19
MSG:  3002
MIX > 
@end example

Other useful commands for debugging are @code{tron} (which turns on
tracing of executed intructions) and @code{weval} (which evaluates
w-expressions on the fly). For a complete description of all available
MIX commands, @xref{mixvm}.



@node mixvm, mixasm, Getting started, Top
@comment  node-name,  next,  previous,  up
@chapter @code{mixvm}, the MIX computer simulator

@cindex mixvm

This chapter describes @code{mixvm}, the MIX computer
simulator. @code{mixvm} is a command line interface programme which
simulates the MIX computer (@pxref{The MIX computer}). It is able
to run MIXAL programs (@pxref{MIXAL}) previously compiled with the MIX
assembler (@pxref{mixasm}). The simulator allows inspection of the MIX
computer components (registers, memory cells, comparison flag and overflow
toggle), step by step execution of MIX programmes, and breakpoint
setting to aid you in debugging your code. For a tutorial description of
@code{mixvm} usage, @xref{Running the program}.

@menu
* Invocation::                  Options when invoking @code{mixvm}.
* Commands::                    Commands available in interactive mode.
* Devices::                     MIX block devices implementation.
@end menu

@node Invocation, Commands, mixvm, mixvm
@comment  node-name,  next,  previous,  up
@section Invoking @code{mixvm}

@code{mixvm} can be invoked with the following command line options
(note, that, following GNU's conventions, we provide a long option name
for each available single letter switch):

@example
mixvm [-vhurd] [--version] [--help] [--usage] [--run] [--dump]
      [FILE[.mix]]
@end example

@noindent
The meaning of these options is as follows:

@defopt -v
@defoptx --version
Prints version and copyleft information and exits.
@end defopt

@defopt -h
@defoptx --help
@defoptx -u
@defoptx --usage
Prints a summary of available options and exits.
@end defopt

@defopt -r
@defoptx --run
Loads the specified @var{FILE} and executes it. After the program
execution, @code{mixvm} exits. @var{FILE} must be the name of a binary
@file{.mix} program compiled with @code{mixasm}. If your program does
not produce any output, use the @code{-d} flag (see below) to peek at
the virtual machine's state after execution.
@end defopt

@defopt -d
@defoptx --dump
This option must be used in conjuction with @code{-r}, and tells
@code{mixvm} to print the value of the virtual machine's registers,
comparison flag and overflow toggle after executing the program named
@var{FILE}. See @xref{Non-interactive mode}, for sample usage.
@end defopt

When run without the @code{-r} flag, @code{mixvm} enters its interactive
mode, showing you a prompt like this one:

@example
MIX >
@end example

@noindent
and waiting for your commands (@pxref{Commands}). If the
optional @var{FILE} argument is given, the file @file{FILE.mix} will be
loaded into the virtual machine memory before entering the interactive
mode. 

@node Commands, Devices, Invocation, mixvm
@comment  node-name,  next,  previous,  up
@section Interactive commands 

You can enter the interactive mode of the MIX virtual machine by simply
invoking @code{mixvm} without arguments. You will then presented a shell
prompt 

@example
MIX >
@end example

@noindent
which indicates that a new virtual machine has been initialised and is
ready to execute your commands. As we have already mentioned, this
command prompt offers you command line editing facilities which are
described in the Readline user's manual (chances are that you are
already familiar with these command line editing capabilities, as they
are present in many GNU utilities, e.g. the @code{bash} shell). As a
beginner, your best friend will be the @code{help} command, which shows
you a summary of all available MIX commands and their usage; its syntax
is as follows:

@deffn {@code{mixvm} command} help [command]
@deffnx {@code{mixvm} command} ? [command]
Prints a short description of the given @var{command} and its usage. If
@var{command} is omitted, all available commands are described.
@end deffn

@menu
* File commands::               Loading and executing programs.
* Debug commands::              Debugging programs.
* State commands::              Inspecting the virtual machine state.
@end menu

@node File commands, Debug commands, Commands, Commands
@comment  node-name,  next,  previous,  up
@subsection File commands

You have at your disposal a series of commands that let you load and
execute MIX executable files, as well as manipulate MIXAL source files:

@deffn {file command} load file[.mix]
This command loads a binary file, @var{file.mix} into the virtual
machine memory, and positions the program counter at the beginning of
the loaded program. This address is indicated in the MIXAL source file
as the operand of the @code{END} pseudoinstruction. Thus, if your
@file{sample.mixal} source file contains the line:

@example
     END 3000
@end example

@noindent
and you compile it with @code{mixasm} to produce the binary file
@file{sample.mix}, you will load it into the virtual machine as follows:

@example
MIX > load sample
Program loaded. Start address: 3000
MIX >
@end example

@end deffn

@deffn {file command} run [file[.mix]]
When executed without argument, this command initiates or resumes
execution of instructions from the current program counter
address. Therefore, issuing this command after a successful @code{load},
will run the loaded program until either a @code{HLT} instruction or a
breakpoint is found. If you provide a MIX filename as argument, the
given file will be loaded (as with @code{load} @var{file}) and
executed. If @code{run} is invoked again after program execution
completion (i.e., after the @code{HLT} instruction has been found in a
previous run), the program counter is repositioned and execution starts
again from the beginning. 
@end deffn

@deffn {file command} edit file[.mixal]
The source file @var{file.mixal} is edited using the editor defined in
the environment variable @var{MDK_EDITOR}. If this variable is not set,
the following ones are tried out in order: @var{X_EDITOR}, @var{EDITOR}
and @var{VISUAL}.
@end deffn

@deffn {file command} compile file[.mixal]
The source file @var{file.mixal} is compiled (with debug information
enabled) using @code{mixasm}.
@end deffn


@node Debug commands, State commands, File commands, Commands
@comment  node-name,  next,  previous,  up
@subsection Debug commands

Sequential execution of loaded programs can be interrupted using the
following debug commands:

@deffn {debug command} next [ins_number]
This command causes the virtual machine to fetch and execute  up to
@var{ins_number} instructions, beginning from the current program
counter position. Execution is interrupted either when the specified
number of instructions have been fetched or a breakpoint is found,
whatever happens first. If run without arguments, one instruction is
executed. 
@end deffn

@deffn {debug command} sbp line_number
Sets a breakpoint at the specified source file line number. If the line
specified corresponds to a command or to a MIXAL pseudoinstruction which
does not produce a MIX instruction in the binary file (such as
@code{ORIG} or @code{EQU}) the breakpoint is set at the first source
code line giving rise to a MIX instruction after the specified
one. Thus, for our sample @file{hello.mixal} file:

@example
*                                                        (1)
* hello.mixal: say 'hello world' in MIXAL                (2)
*                                                        (3)
* label ins    operand     comment                       (4)
TERM    EQU    19          the MIX console device number (5)
        ORIG   1000        start address                 (6)
START   OUT    MSG(TERM)   output data at address MSG    (7)
...
@end example

@noindent
trying to set a breakpoint at line 5, will produce the following result:

@example
MIX > sbp 5
Breakpoint set at line 7
MIX > 
@end example

@noindent
since line 7 is the first one compiled into a MIX instruction (at
address 3000). In order to @code{sbp} to work, the source file must be
compiled using the @code{-g} flags, which tells @code{mixasm} to include
debug information in the binary @file{.mix} file.
@end deffn

@deffn {debug command} spba address
Sets a breakpoint at the given memory @var{address}. The argument must
be a valid MIX memory address, i.e., it must belong into the range
@w{[0-3999]}. Note that no check is performed to verify that the
specified address is reachable during program execution. No debug
information is needed to set a breakpoint by address with @code{sbpa}.
@end deffn

@deffn {debug command} cbp line_no
Clears a (previously set) breakpoint at the given source file line.
@end deffn

@deffn {debug command} cbpa address
Clears a (previously set) breakpoint at the given memory address.
@end deffn

@deffn {debug command} cabp
Clears all currently set breakpoints.
@end deffn

@deffn {debug command} psym [symbol_name]
MIXAL programs can define symbolic constants, using either the
@code{EQU} pseudoinstruction or a label at the beginning of a
line. Thus, in the program fragment

@example
VAR     EQU  2168
        ORIG 4000
START   LDA  VAR
@end example

@noindent
the symbol @code{VAR} stands for the value 2168, while @code{START} is
assigned the value 4000. When MIXAL programs are compiled using the
@code{-g} flag (which tells @code{mixasm} to include debug information
in the binary @file{.mix} file), the symbol table can be consulted from
the @code{mixvm} command line using @code{psym} followed by the name of
the symbol whose contents you are interested in. When run without
arguments, @code{psym} will print all defined symbols and their values.
@end deffn

The virtual machine can also show you the instructions it is executing,
using the following commands:

@deffn {debug command} tron
@deffnx troff
@code{tron} enables instruction tracing. When tracing is enabled, each
time the virtual machine executes an instruction (due to your issuing a
@code{run} or @code{next} command), it is printed in its canonical form
(that is, with all expressions evaluated to their numerical values) and,
if the program was compiled with debug information, as it was originally
typed in the MIXAL source file. Instruction tracing is disable with the
@code{troff} command. A typical tracing session could be like this:

@example
MIX > tron
Instruction tracing has been turned ON.
MIX > next
3000: [OUT	3002,0(2:3)]	START	OUT	MSG(TERM)
MIXAL HELLO WORLD                                                     
Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
MIX > next
3001: [HLT	0,0]		HLT
End of program reached at address 3002
Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
MIX > troff
Instruction tracing has been turned OFF.
MIX > 
@end example
@noindent
The executed instruction, as it was translated, is shown between square
brackets after the memory address, and, following it, you can see the
actual MIXAL code that was compiled into the executed instruction.
@end deffn

@code{mixvm} is also able of evaluating w-expressions
(@pxref{W-expressions}) using the following command:

@deffn {debug command} weval WEXP
Evaluates the given w-expression, @var{WEXP}. The w-expression can
contain any currently defined symbol. For instance:

@example
MIX > psym START
+ 00 00 00 46 56 (0000003000)
MIX > weval START(0:1),START(3:4)
+ 56 00 46 56 00 (0939716096)
MIX >
@end example
@end deffn

New symbols can be defined using the @code{ssym} command:
@deffn {debug command} ssym SYM WEXP
Defines the symbol named @var{SYM} with the value resulting from
evaluating @var{WEXP}, an w-expression. The newly defined symbol can be
used in subsequent @code{weval} commands, as part of the expression to
be evaluated. E.g.,

@example
MIX > ssym S 2+23*START
+ 00 00 18 19 56 (0000075000)
MIX > psym S
+ 00 00 18 19 56 (0000075000)
MIX > weval S(3:4)
+ 00 00 19 56 00 (0000081408)
MIX > 
@end example
@end deffn

Finally, if you want to discover which is the decimal value of a MIX
word expressed as five bytes plus sign, you can use

@deffn {debug command} w2d WORD
Computes the decimal value of the given word. @var{WORD} must be
expressed as a sign (+/-) followed by five space-delimited, two-digit
decimal values representing the five bytes composing the word. The
reverse operation (showing the word representation of a decimal value)
can be accomplished with @code{weval}. For instance: 

@example
MIX > w2d - 01 00 00 02 02
-16777346
MIX > weval -16777346
- 01 00 00 02 02 (0016777346)
MIX > 
@end example
@end deffn

@node State commands,  , Debug commands, Commands
@comment  node-name,  next,  previous,  up
@subsection State commands

Inspection and modification of the virtual machine state (memory,
registers, overflow toggle and comparison flag contents) is accomplished
using the following commands:

@deffn {state command} pc
Prints the current value of the program counter, which stores the
address of the next instruction to be executed in a non-halted program.
@end deffn

@deffn {state command} preg [A | X | J | I[1-6]]
@deffnx {state command} pall
@deffnx {state command} sreg A | X | J | I[1-6] value
@code{preg} prints the contents of a given MIX register. For instance,
@w{@code{preg} @var{A}} will print the contents of the A-register. When
invoked without arguments, all registers shall be printed:

@example
MIX > preg
rA: - 00 00 00 00 35 (0000000035)
rX: + 00 00 00 15 40 (0000001000)
rJ: + 00 00 (0000)
rI1: + 00 00 (0000)	rI2: + 00 00 (0000)	
rI3: + 00 00 (0000)	rI4: + 00 00 (0000)	
rI5: + 00 00 (0000)	rI6: + 00 00 (0000)	
MIX > 
@end example

As you can see in the above sample, the contents is printed as the sign
plus the values of the MIX bytes stored in the register and, between
parenthesis, the decimal representation of its module.

@code{pall} prints the contents of all registers plus the comparison
flag and overflow toggle.

Finally, @code{sreg} Sets the contents of the given register to
@var{value}, expressed as a decimal constant. If @var{value} exceeds the
maximum value storable in the given register, @math{VALUE mod
MAXIMU_VALUE} is stored, e.g.

@example
MIX > sreg I1 1000
MIX > preg I1
rI1: + 15 40 (1000)	
MIX > sreg I1 1000000
MIX > preg I1
rI1: + 09 00 (0576)	
MIX > 
@end example

@end deffn


@deffn {state command} pflags
@deffnx {state command} scmp E | G | L
@deffnx {state command} sover F | T
@code{pflags} prints the value of the comparison flag and overflow
toggle of the virtual machine, e.g.

@example
MIX > pflags
Overflow: F
Cmp: E
MIX > 
@end example

@noindent
The values of the overflow toggle are either @var{F} (false) or @var{T}
(true), and, for the comparison flag, @var{E}, @var{G}, @var{L} (equal,
greater, lesser). @code{scmp} and @code{sover} are setters of the
comparison flag and overflow toggle values.
@end deffn

@deffn {state command} pmem from[-to]
@deffnx {state command} smem address value
@code{pmem} prints the contents of memory cells in the address range
@w{[@var{FROM}-@var{TO}]}. If the upper limit @var{to} is omitted, only
the contents of the memory cell with address @var{FROM} is printed, as
in

@example
MIX > pmem 3000
3000: + 46 58 00 19 37 (0786957541)
MIX >
@end example

The memory contents is displayed both as the set of five MIX bytes plus
sign composing the stored MIX word and, between parenthesis, the decimal
representation of the module of the stored value.

@code{smem} sets the content of the memory cell with address
@var{address} to @var{value}, expressed as a decimal constant.

@end deffn

Finally, you can use the @code{quit} command to exit @code{mixvm}.

@node Devices,  , Commands, mixvm
@comment  node-name,  next,  previous,  up
@section MIX block devices

The MIX computer comes equipped with a set of block devices for
input-output operations (@pxref{Input-output operators}). @code{mixvm}
implements these block devices as disk files, with the exception of
block device no. 19 (typewriter terminal) which is redirected to
standard output. When you request an output operation on any other
(output) device, a file named according to the following table will be
created in the current directory, and the specified MIX words will be
written to the file in binary form (for binary devices) or in ASCII (for
char devices). Files corresponding to input block devices should be
created and filled beforehand to be used by the MIX virtual machine (for
input-output devices this creation can be accomplished by a MIXAL
program writing to the device the required data, or, if you prefer, with
your favourite editor).

@multitable {the device name} {xx-xx} {filena[x-x].dev} {bin  i/o} 
@item @emph{Device}  @tab @emph{No.} @tab @emph{filename} @tab @emph{type}
@item Tape @tab 0-7 @tab @file{tape[0-7].dev} @tab bin i/o
@item Disks @tab 8-15 @tab @file{disk[0-7].dev} @tab bin i/o
@item Card reader @tab 16 @tab @file{cardrd.dev} @tab char in
@item Card writer @tab 17 @tab @file{cardwr.dev} @tab char out
@item Line printer @tab 18 @tab @file{printer.dev} @tab char out
@item Terminal @tab 19 @tab @code{stdout} @tab char out
@item Paper tape @tab 20 @tab @file{paper.dev} @tab char out
@end multitable



@node mixasm, Copying, mixvm, Top
@comment  node-name,  next,  previous,  up
@chapter @code{mixasm}, the MIXAL assembler
@cindex @code{mixasm}
@cindex MIXAL
@cindex assembler

MIX programs, as executed by @code{mixvm}, are composed of binary
instructions loaded into the virtual machine memory as MIX
words. Although you could write your MIX programs directly as a series
of words in binary format, you have at your disposal a more friendly
assembly language, MIXAL (@pxref{MIXAL}) which is compiled into binary
form by @code{mixasm}, the MIXAL assembler included in @sc{mdk}. In this
chapter, you will find a complete description of @code{mixasm} options.

@menu
* Invoking @code{mixasm}::      @code{mixasm} options
@end menu

@node Invoking @code{mixasm},  , mixasm, mixasm
@comment  node-name,  next,  previous,  up
@section Invoking @code{mixasm}

In its simplest form, @code{mixasm} is invoked with a single argument,
which is the name of the MIXAL file to be compiled, e.g.

@example
mixasm hello
@end example

@noindent
will compile either @file{hello} or @file{hello.mixal}, producing a
binary file named @file{hello.mix} if no errors are found.

In addition, @code{mixasm} can be invoked with the following command
line options (note, that, following GNU's conventions, we provide a long
option name for each available single letter switch):

@example
mixasm [-vhulg] [-o OUTPUT_FILE] [--version] [--help]
       [--usage] [--debug] [--output=OUTPUT_FILE] [--list[=LIST_FILE]] file
@end example

@noindent
The meaning of these options is as follows:

@defopt -v
@defoptx --version
Prints version and copyleft information and exits.
@end defopt

@defopt -h
@defoptx --help
@defoptx -u
@defoptx --usage
Prints a summary of available options and exits.
@end defopt

@defopt -g
@defoptx --debug
Includes debugging information in the compiled file, allowing breakpoint
setting at source level and symbol table inspection under @code{mixvm}.
@end defopt

@defopt -o output_file
@defoptx --output=output_file
By default, the given source file @var{file.mixal} is compiled into
@var{file.mix}. You can provide a different name for the output file
using this option.
@end defopt

@defopt -l
@defoptx --list[=list_file]
This option causes @code{mixasm} to produce, in addion to the
@file{.mix} file, an ASCII file containing a summary of the compilation
results. The file is named after the MIXAL source file, changing its
extension to @file{.mls} if no argument is provided; otherwise, the
listing file is named according to the argument.
@end defopt



@node Copying, Problems, mixasm, Top
@chapter Copying
@lowersections
@include gpl.texi
@raisesections

@node Problems, Concept Index, Copying, Top
@chapter Reporting Bugs
@cindex bugs
@cindex problems

If you find a bug in @sc{mdk} (or have questions, comments or suggestions
about it), please send electronic mail to @email{jaortega@@acm.org,
the author}. 

In your report, please include the version number, which you can find by
running @w{@samp{mixasm --version}}.  Also include in your message the
output that the program produced and the output you expected.

@node Concept Index,  , Problems, Top
@unnumbered Concept Index

@cindex tail recursion
@printindex cp

@c @node MIXAL instructions,  , Concept Index, Top
@comment  node-name,  next,  previous,  up
@c @unnumbered MIXAL instructions
@c @printindex fn

@shortcontents
@contents
@bye