aboutsummaryrefslogtreecommitdiff
path: root/gcc/rtl.texi
blob: b15baab6c01b0802947bb0a8308cc74c5f6d9f40 (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
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
@c Copyright (C) 1988, 89, 92, 94, 97, 1998, 1999 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node RTL
@chapter RTL Representation
@cindex RTL representation
@cindex representation of RTL
@cindex Register Transfer Language (RTL)

Most of the work of the compiler is done on an intermediate representation
called register transfer language.  In this language, the instructions to be
output are described, pretty much one by one, in an algebraic form that
describes what the instruction does.

RTL is inspired by Lisp lists.  It has both an internal form, made up of
structures that point at other structures, and a textual form that is used
in the machine description and in printed debugging dumps.  The textual
form uses nested parentheses to indicate the pointers in the internal form.

@menu
* RTL Objects::       Expressions vs vectors vs strings vs integers.
* RTL Classes::       Categories of RTL expresion objects, and their structure.
* Accessors::         Macros to access expression operands or vector elts.
* Flags::             Other flags in an RTL expression.
* Machine Modes::     Describing the size and format of a datum.
* Constants::         Expressions with constant values.
* Regs and Memory::   Expressions representing register contents or memory.
* Arithmetic::        Expressions representing arithmetic on other expressions.
* Comparisons::       Expressions representing comparison of expressions.
* Bit Fields::        Expressions representing bitfields in memory or reg.
* Conversions::       Extending, truncating, floating or fixing.
* RTL Declarations::  Declaring volatility, constancy, etc.
* Side Effects::      Expressions for storing in registers, etc.
* Incdec::            Embedded side-effects for autoincrement addressing.
* Assembler::         Representing @code{asm} with operands.
* Insns::             Expression types for entire insns.
* Calls::             RTL representation of function call insns.
* Sharing::           Some expressions are unique; others *must* be copied.
* Reading RTL::       Reading textual RTL from a file.
@end menu

@node RTL Objects, RTL Classes, RTL, RTL
@section RTL Object Types
@cindex RTL object types

@cindex RTL integers
@cindex RTL strings
@cindex RTL vectors
@cindex RTL expression
@cindex RTX (See RTL)
RTL uses five kinds of objects: expressions, integers, wide integers,
strings and vectors.  Expressions are the most important ones.  An RTL
expression (``RTX'', for short) is a C structure, but it is usually
referred to with a pointer; a type that is given the typedef name
@code{rtx}.

An integer is simply an @code{int}; their written form uses decimal digits.
A wide integer is an integral object whose type is @code{HOST_WIDE_INT}
(@pxref{Config}); their written form uses decimal digits.

A string is a sequence of characters.  In core it is represented as a
@code{char *} in usual C fashion, and it is written in C syntax as well.
However, strings in RTL may never be null.  If you write an empty string in
a machine description, it is represented in core as a null pointer rather
than as a pointer to a null character.  In certain contexts, these null
pointers instead of strings are valid.  Within RTL code, strings are most
commonly found inside @code{symbol_ref} expressions, but they appear in
other contexts in the RTL expressions that make up machine descriptions.  

A vector contains an arbitrary number of pointers to expressions.  The
number of elements in the vector is explicitly present in the vector.
The written form of a vector consists of square brackets
(@samp{[@dots{}]}) surrounding the elements, in sequence and with
whitespace separating them.  Vectors of length zero are not created;
null pointers are used instead.

@cindex expression codes
@cindex codes, RTL expression
@findex GET_CODE
@findex PUT_CODE
Expressions are classified by @dfn{expression codes} (also called RTX
codes).  The expression code is a name defined in @file{rtl.def}, which is
also (in upper case) a C enumeration constant.  The possible expression
codes and their meanings are machine-independent.  The code of an RTX can
be extracted with the macro @code{GET_CODE (@var{x})} and altered with
@code{PUT_CODE (@var{x}, @var{newcode})}.

The expression code determines how many operands the expression contains,
and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
by looking at an operand what kind of object it is.  Instead, you must know
from its context---from the expression code of the containing expression.
For example, in an expression of code @code{subreg}, the first operand is
to be regarded as an expression and the second operand as an integer.  In
an expression of code @code{plus}, there are two operands, both of which
are to be regarded as expressions.  In a @code{symbol_ref} expression,
there is one operand, which is to be regarded as a string.

Expressions are written as parentheses containing the name of the
expression type, its flags and machine mode if any, and then the operands
of the expression (separated by spaces).

Expression code names in the @samp{md} file are written in lower case,
but when they appear in C code they are written in upper case.  In this
manual, they are shown as follows: @code{const_int}.

@cindex (nil)
@cindex nil
In a few contexts a null pointer is valid where an expression is normally
wanted.  The written form of this is @code{(nil)}.

@node RTL Classes, Accessors, RTL Objects, RTL
@section RTL Classes and Formats
@cindex RTL classes
@cindex classes of RTX codes
@cindex RTX codes, classes of
@findex GET_RTX_CLASS

The various expression codes are divided into several @dfn{classes},
which are represented by single characters.  You can determine the class
of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
Currently, @file{rtx.def} defines these classes:

@table @code
@item o
An RTX code that represents an actual object, such as a register
(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
Constants and basic transforms on objects (@code{ADDRESSOF},
@code{HIGH}, @code{LO_SUM}) are also included.  Note that @code{SUBREG}
and @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.

@item <
An RTX code for a comparison, such as @code{NE} or @code{LT}.

@item 1
An RTX code for a unary arithmetic operation, such as @code{NEG},
@code{NOT}, or @code{ABS}.  This category also includes value extension
(sign or zero) and conversions between integer and floating point.

@item c
An RTX code for a commutative binary operation, such as @code{PLUS} or
@code{AND}.  @code{NE} and @code{EQ} are comparisons, so they have class
@code{<}.

@item 2
An RTX code for a non-commutative binary operation, such as @code{MINUS},
@code{DIV}, or @code{ASHIFTRT}.

@item b
An RTX code for a bitfield operation.  Currently only
@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}.  These have three inputs
and are lvalues (so they can be used for insertion as well).  @xref{Bit
Fields}.

@item 3
An RTX code for other three input operations.  Currently only
@code{IF_THEN_ELSE}.

@item i
An RTX code for an entire instruction:  @code{INSN}, @code{JUMP_INSN}, and
@code{CALL_INSN}. @xref{Insns}.

@item m
An RTX code for something that matches in insns, such as
@code{MATCH_DUP}.  These only occur in machine descriptions.

@item x
All other RTX codes.  This category includes the remaining codes used
only in machine descriptions (@code{DEFINE_*}, etc.).  It also includes
all the codes describing side effects (@code{SET}, @code{USE},
@code{CLOBBER}, etc.) and the non-insns that may appear on an insn
chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
@end table

@cindex RTL format
For each expression type @file{rtl.def} specifies the number of
contained objects and their kinds, with four possibilities: @samp{e} for
expression (actually a pointer to an expression), @samp{i} for integer,
@samp{w} for wide integer, @samp{s} for string, and @samp{E} for vector
of expressions.  The sequence of letters for an expression code is
called its @dfn{format}.  For example, the format of @code{subreg} is
@samp{ei}.@refill

@cindex RTL format characters
A few other format characters are used occasionally:

@table @code
@item u
@samp{u} is equivalent to @samp{e} except that it is printed differently
in debugging dumps.  It is used for pointers to insns.

@item n
@samp{n} is equivalent to @samp{i} except that it is printed differently
in debugging dumps.  It is used for the line number or code number of a
@code{note} insn.

@item S
@samp{S} indicates a string which is optional.  In the RTL objects in
core, @samp{S} is equivalent to @samp{s}, but when the object is read,
from an @samp{md} file, the string value of this operand may be omitted.
An omitted string is taken to be the null string.

@item V
@samp{V} indicates a vector which is optional.  In the RTL objects in
core, @samp{V} is equivalent to @samp{E}, but when the object is read
from an @samp{md} file, the vector value of this operand may be omitted.
An omitted vector is effectively the same as a vector of no elements.

@item 0
@samp{0} means a slot whose contents do not fit any normal category.
@samp{0} slots are not printed at all in dumps, and are often used in
special ways by small parts of the compiler.
@end table

There are macros to get the number of operands and the format
of an expression code:

@table @code
@findex GET_RTX_LENGTH
@item GET_RTX_LENGTH (@var{code})
Number of operands of an RTX of code @var{code}.

@findex GET_RTX_FORMAT
@item GET_RTX_FORMAT (@var{code})
The format of an RTX of code @var{code}, as a C string.
@end table

Some classes of RTX codes always have the same format.  For example, it
is safe to assume that all comparison operations have format @code{ee}.

@table @code
@item 1
All codes of this class have format @code{e}.

@item <
@itemx c
@itemx 2
All codes of these classes have format @code{ee}.

@item b
@itemx 3
All codes of these classes have format @code{eee}.

@item i
All codes of this class have formats that begin with @code{iuueiee}.
@xref{Insns}.  Note that not all RTL objects linked onto an insn chain
are of class @code{i}.

@item o
@itemx m
@itemx x
You can make no assumptions about the format of these codes.
@end table

@node Accessors, Flags, RTL Classes, RTL
@section Access to Operands
@cindex accessors
@cindex access to operands
@cindex operand access

@findex XEXP
@findex XINT
@findex XWINT
@findex XSTR
Operands of expressions are accessed using the macros @code{XEXP},
@code{XINT}, @code{XWINT} and @code{XSTR}.  Each of these macros takes
two arguments: an expression-pointer (RTX) and an operand number
(counting from zero).  Thus,@refill

@example
XEXP (@var{x}, 2)
@end example

@noindent
accesses operand 2 of expression @var{x}, as an expression.

@example
XINT (@var{x}, 2)
@end example

@noindent
accesses the same operand as an integer.  @code{XSTR}, used in the same
fashion, would access it as a string.

Any operand can be accessed as an integer, as an expression or as a string.
You must choose the correct method of access for the kind of value actually
stored in the operand.  You would do this based on the expression code of
the containing expression.  That is also how you would know how many
operands there are.

For example, if @var{x} is a @code{subreg} expression, you know that it has
two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
and @code{XINT (@var{x}, 1)}.  If you did @code{XINT (@var{x}, 0)}, you
would get the address of the expression operand but cast as an integer;
that might occasionally be useful, but it would be cleaner to write
@code{(int) XEXP (@var{x}, 0)}.  @code{XEXP (@var{x}, 1)} would also
compile without error, and would return the second, integer operand cast as
an expression pointer, which would probably result in a crash when
accessed.  Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
but this will access memory past the end of the expression with
unpredictable results.@refill

Access to operands which are vectors is more complicated.  You can use the
macro @code{XVEC} to get the vector-pointer itself, or the macros
@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
vector.

@table @code
@findex XVEC
@item XVEC (@var{exp}, @var{idx})
Access the vector-pointer which is operand number @var{idx} in @var{exp}.

@findex XVECLEN
@item XVECLEN (@var{exp}, @var{idx})
Access the length (number of elements) in the vector which is
in operand number @var{idx} in @var{exp}.  This value is an @code{int}.

@findex XVECEXP
@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
Access element number @var{eltnum} in the vector which is
in operand number @var{idx} in @var{exp}.  This value is an RTX.

It is up to you to make sure that @var{eltnum} is not negative
and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
@end table

All the macros defined in this section expand into lvalues and therefore
can be used to assign the operands, lengths and vector elements as well as
to access them.

@node Flags, Machine Modes, Accessors, RTL
@section Flags in an RTL Expression
@cindex flags in RTL expression

RTL expressions contain several flags (one-bit bitfields) and other
values that are used in certain types of expression.  Most often they
are accessed with the following macros:

@table @code
@findex MEM_VOLATILE_P
@cindex @code{mem} and @samp{/v}
@cindex @code{volatil}, in @code{mem}
@cindex @samp{/v} in RTL dump
@item MEM_VOLATILE_P (@var{x})
In @code{mem} expressions, nonzero for volatile memory references.
Stored in the @code{volatil} field and printed as @samp{/v}.

@findex MEM_IN_STRUCT_P
@cindex @code{mem} and @samp{/s}
@cindex @code{in_struct}, in @code{mem}
@cindex @samp{/s} in RTL dump
@item MEM_IN_STRUCT_P (@var{x})
In @code{mem} expressions, nonzero for reference to an entire structure,
union or array, or to a component of one.  Zero for references to a
scalar variable or through a pointer to a scalar.  Stored in the
@code{in_struct} field and printed as @samp{/s}.  If both this flag and
MEM_SCALAR_P are clear, then we don't know whether this MEM is in a
structure or not.  Both flags should never be simultaneously set.

@findex MEM_SCALAR_P
@cindex @code{mem} and @samp{/f}
@cindex @code{frame_related}, in@code{mem}
@cindex @samp{/f} in RTL dump
@item MEM_SCALAR_P (@var{x})
In @code{mem} expressions, nonzero for reference to a scalar known not
to be a member of a structure, union, or array.  Zero for such
references and for indirections through pointers, even pointers pointing
to scalar types.  If both this flag and MEM_STRUCT_P are clear, then we
don't know whether this MEM is in a structure or not.  Both flags should
never be simultaneously set.

@findex MEM_ALIAS_SET
@item MEM_ALIAS_SET (@var{x})
In @code{mem} expressions, the alias set to which @var{x} belongs.  If
zero, @var{x} is not in any alias set, and may alias anything.  If
nonzero, @var{x} may only alias objects in the same alias set.  This
value is set (in a language-specific manner) by the front-end.  This
field is not a bit-field; it is in an integer, found as the second
argument to the @code{mem}.

@findex REG_LOOP_TEST_P
@cindex @code{reg} and @samp{/s}
@cindex @code{in_struct}, in @code{reg}
@item REG_LOOP_TEST_P
In @code{reg} expressions, nonzero if this register's entire life is
contained in the exit test code for some loop.  Stored in the
@code{in_struct} field and printed as @samp{/s}.

@findex REG_USERVAR_P 
@cindex @code{reg} and @samp{/v}
@cindex @code{volatil}, in @code{reg}
@item REG_USERVAR_P (@var{x})
In a @code{reg}, nonzero if it corresponds to a variable present in
the user's source code.  Zero for temporaries generated internally by
the compiler.  Stored in the @code{volatil} field and printed as
@samp{/v}.

@cindex @samp{/i} in RTL dump
@findex REG_FUNCTION_VALUE_P 
@cindex @code{reg} and @samp{/i}
@cindex @code{integrated}, in @code{reg}
@item REG_FUNCTION_VALUE_P (@var{x})
Nonzero in a @code{reg} if it is the place in which this function's
value is going to be returned.  (This happens only in a hard
register.)  Stored in the @code{integrated} field and printed as
@samp{/i}.

The same hard register may be used also for collecting the values of
functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
in this kind of use.

@findex SUBREG_PROMOTED_VAR_P
@cindex @code{subreg} and @samp{/s}
@cindex @code{in_struct}, in @code{subreg}
@item SUBREG_PROMOTED_VAR_P
Nonzero in a @code{subreg} if it was made when accessing an object that
was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
description macro (@pxref{Storage Layout}).  In this case, the mode of
the @code{subreg} is the declared mode of the object and the mode of
@code{SUBREG_REG} is the mode of the register that holds the object.
Promoted variables are always either sign- or zero-extended to the wider
mode on every assignment.  Stored in the @code{in_struct} field and
printed as @samp{/s}.

@findex SUBREG_PROMOTED_UNSIGNED_P
@cindex @code{subreg} and @samp{/u}
@cindex @code{unchanging}, in @code{subreg}
@item SUBREG_PROMOTED_UNSIGNED_P
Nonzero in a @code{subreg} that has @code{SUBREG_PROMOTED_VAR_P} nonzero
if the object being referenced is kept zero-extended and zero if it
is kept sign-extended.  Stored in the @code{unchanging} field and
printed as @samp{/u}.

@findex RTX_UNCHANGING_P 
@cindex @code{reg} and @samp{/u}
@cindex @code{mem} and @samp{/u}
@cindex @code{unchanging}, in @code{reg} and @code{mem}
@cindex @samp{/u} in RTL dump
@item RTX_UNCHANGING_P (@var{x})
Nonzero in a @code{reg} or @code{mem} if the value is not changed.
(This flag is not set for memory references via pointers to constants.
Such pointers only guarantee that the object will not be changed
explicitly by the current function.  The object might be changed by
other functions or by aliasing.)  Stored in the
@code{unchanging} field and printed as @samp{/u}.

@findex RTX_INTEGRATED_P 
@cindex @code{integrated}, in @code{insn}
@item RTX_INTEGRATED_P (@var{insn})
Nonzero in an insn if it resulted from an in-line function call.
Stored in the @code{integrated} field and printed as @samp{/i}.

@findex RTX_FRAME_RELATED_P
@item RTX_FRAME_RELATED_P (@var{x})
Nonzero in an insn or expression which is part of a function
prologue and sets the stack pointer, sets the frame pointer, or saves a 
register. This flag is required for exception handling support
on targets with RTL prologues.

@findex SYMBOL_REF_USED
@cindex @code{used}, in @code{symbol_ref}
@item SYMBOL_REF_USED (@var{x})
In a @code{symbol_ref}, indicates that @var{x} has been used.  This is
normally only used to ensure that @var{x} is only declared external
once.  Stored in the @code{used} field.

@findex SYMBOL_REF_FLAG
@cindex @code{symbol_ref} and @samp{/v}
@cindex @code{volatil}, in @code{symbol_ref}
@item SYMBOL_REF_FLAG (@var{x})
In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
Stored in the @code{volatil} field and printed as @samp{/v}.

@findex LABEL_OUTSIDE_LOOP_P
@cindex @code{label_ref} and @samp{/s}
@cindex @code{in_struct}, in @code{label_ref}
@item LABEL_OUTSIDE_LOOP_P
In @code{label_ref} expressions, nonzero if this is a reference to a
label that is outside the innermost loop containing the reference to the
label.  Stored in the @code{in_struct} field and printed as @samp{/s}.

@findex INSN_DELETED_P 
@cindex @code{volatil}, in @code{insn}
@item INSN_DELETED_P (@var{insn})
In an insn, nonzero if the insn has been deleted.  Stored in the
@code{volatil} field and printed as @samp{/v}.

@findex INSN_ANNULLED_BRANCH_P
@cindex @code{insn} and @samp{/u}
@cindex @code{unchanging}, in @code{insn}
@item INSN_ANNULLED_BRANCH_P (@var{insn})
In an @code{insn} in the delay slot of a branch insn, indicates that an
annulling branch should be used.  See the discussion under
@code{sequence} below.  Stored in the @code{unchanging} field and printed
as @samp{/u}.

@findex INSN_FROM_TARGET_P
@cindex @code{insn} and @samp{/s}
@cindex @code{in_struct}, in @code{insn}
@cindex @samp{/s} in RTL dump
@item INSN_FROM_TARGET_P (@var{insn})
In an @code{insn} in a delay slot of a branch, indicates that the insn
is from the target of the branch.  If the branch insn has
@code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
the branch is taken.  For annulled branches with
@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
branch is not taken.  When @code{INSN_ANNULLED_BRANCH_P} is not set,
this insn will always be executed.  Stored in the @code{in_struct}
field and printed as @samp{/s}.

@findex CONSTANT_POOL_ADDRESS_P 
@cindex @code{symbol_ref} and @samp{/u}
@cindex @code{unchanging}, in @code{symbol_ref}
@item CONSTANT_POOL_ADDRESS_P (@var{x})
Nonzero in a @code{symbol_ref} if it refers to part of the current
function's ``constants pool''.  These are addresses close to the
beginning of the function, and GNU CC assumes they can be addressed
directly (perhaps with the help of base registers).  Stored in the
@code{unchanging} field and printed as @samp{/u}.

@findex CONST_CALL_P
@cindex @code{call_insn} and @samp{/u}
@cindex @code{unchanging}, in @code{call_insn}
@item CONST_CALL_P (@var{x})
In a @code{call_insn}, indicates that the insn represents a call to a const
function.  Stored in the @code{unchanging} field and printed as @samp{/u}.

@findex LABEL_PRESERVE_P
@cindex @code{code_label} and @samp{/i}
@cindex @code{in_struct}, in @code{code_label}
@item LABEL_PRESERVE_P (@var{x})
In a @code{code_label}, indicates that the label can never be deleted.
Labels referenced by a non-local goto will have this bit set.  Stored
in the @code{in_struct} field and printed as @samp{/s}.

@findex SCHED_GROUP_P
@cindex @code{insn} and @samp{/i}
@cindex @code{in_struct}, in @code{insn}
@item SCHED_GROUP_P (@var{insn})
During instruction scheduling, in an insn, indicates that the previous insn
must be scheduled together with this insn.  This is used to ensure that
certain groups of instructions will not be split up by the instruction
scheduling pass, for example, @code{use} insns before a @code{call_insn} may
not be separated from the @code{call_insn}.  Stored in the @code{in_struct}
field and printed as @samp{/s}.
@end table

These are the fields which the above macros refer to:

@table @code
@findex used
@item used
Normally, this flag is used only momentarily, at the end of RTL
generation for a function, to count the number of times an expression
appears in insns.  Expressions that appear more than once are copied,
according to the rules for shared structure (@pxref{Sharing}).

In a @code{symbol_ref}, it indicates that an external declaration for
the symbol has already been written.

In a @code{reg}, it is used by the leaf register renumbering code to ensure
that each register is only renumbered once.

@findex volatil
@item volatil
This flag is used in @code{mem}, @code{symbol_ref} and @code{reg}
expressions and in insns.  In RTL dump files, it is printed as
@samp{/v}.

@cindex volatile memory references
In a @code{mem} expression, it is 1 if the memory reference is volatile.
Volatile memory references may not be deleted, reordered or combined.

In a @code{symbol_ref} expression, it is used for machine-specific 
purposes.

In a @code{reg} expression, it is 1 if the value is a user-level variable.
0 indicates an internal compiler temporary.

In an insn, 1 means the insn has been deleted.

@findex in_struct
@item in_struct
In @code{mem} expressions, it is 1 if the memory datum referred to is
all or part of a structure or array; 0 if it is (or might be) a scalar
variable.  A reference through a C pointer has 0 because the pointer
might point to a scalar variable.  This information allows the compiler
to determine something about possible cases of aliasing.

In an insn in the delay slot of a branch, 1 means that this insn is from
the target of the branch.

During instruction scheduling, in an insn, 1 means that this insn must be
scheduled as part of a group together with the previous insn.

In @code{reg} expressions, it is 1 if the register has its entire life
contained within the test expression of some loop.

In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
an object that has had its mode promoted from a wider mode.

In @code{label_ref} expressions, 1 means that the referenced label is
outside the innermost loop containing the insn in which the @code{label_ref}
was found.

In @code{code_label} expressions, it is 1 if the label may never be deleted.
This is used for labels which are the target of non-local gotos.

In an RTL dump, this flag is represented as @samp{/s}.

@findex unchanging
@item unchanging
In @code{reg} and @code{mem} expressions, 1 means
that the value of the expression never changes.

In @code{subreg} expressions, it is 1 if the @code{subreg} references an
unsigned object whose mode has been promoted to a wider mode.

In an insn, 1 means that this is an annulling branch.

In a @code{symbol_ref} expression, 1 means that this symbol addresses
something in the per-function constants pool.

In a @code{call_insn}, 1 means that this instruction is a call to a
const function.

In an RTL dump, this flag is represented as @samp{/u}.

@findex integrated
@item integrated
In some kinds of expressions, including insns, this flag means the
rtl was produced by procedure integration.

In a @code{reg} expression, this flag indicates the register
containing the value to be returned by the current function.  On
machines that pass parameters in registers, the same register number
may be used for parameters as well, but this flag is not set on such
uses.
@end table

@node Machine Modes, Constants, Flags, RTL
@section Machine Modes
@cindex machine modes

@findex enum machine_mode
A machine mode describes a size of data object and the representation used
for it.  In the C code, machine modes are represented by an enumeration
type, @code{enum machine_mode}, defined in @file{machmode.def}.  Each RTL
expression has room for a machine mode and so do certain kinds of tree
expressions (declarations and types, to be precise).

In debugging dumps and machine descriptions, the machine mode of an RTL
expression is written after the expression code with a colon to separate
them.  The letters @samp{mode} which appear at the end of each machine mode
name are omitted.  For example, @code{(reg:SI 38)} is a @code{reg}
expression with machine mode @code{SImode}.  If the mode is
@code{VOIDmode}, it is not written at all.

Here is a table of machine modes.  The term ``byte'' below refers to an
object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).

@table @code
@findex QImode
@item QImode
``Quarter-Integer'' mode represents a single byte treated as an integer.

@findex HImode
@item HImode
``Half-Integer'' mode represents a two-byte integer.

@findex PSImode
@item PSImode
``Partial Single Integer'' mode represents an integer which occupies
four bytes but which doesn't really use all four.  On some machines,
this is the right mode to use for pointers.

@findex SImode
@item SImode
``Single Integer'' mode represents a four-byte integer.

@findex PDImode
@item PDImode
``Partial Double Integer'' mode represents an integer which occupies
eight bytes but which doesn't really use all eight.  On some machines,
this is the right mode to use for certain pointers.

@findex DImode
@item DImode
``Double Integer'' mode represents an eight-byte integer.

@findex TImode
@item TImode
``Tetra Integer'' (?) mode represents a sixteen-byte integer.

@findex SFmode
@item SFmode
``Single Floating'' mode represents a single-precision (four byte) floating
point number.

@findex DFmode
@item DFmode
``Double Floating'' mode represents a double-precision (eight byte) floating
point number.

@findex XFmode
@item XFmode
``Extended Floating'' mode represents a triple-precision (twelve byte)
floating point number.  This mode is used for IEEE extended floating
point.  On some systems not all bits within these bytes will actually
be used.

@findex TFmode
@item TFmode
``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
floating point number.

@findex CCmode
@item CCmode
``Condition Code'' mode represents the value of a condition code, which
is a machine-specific set of bits used to represent the result of a
comparison operation.  Other machine-specific modes may also be used for
the condition code.  These modes are not used on machines that use
@code{cc0} (see @pxref{Condition Code}).

@findex BLKmode
@item BLKmode
``Block'' mode represents values that are aggregates to which none of
the other modes apply.  In RTL, only memory references can have this mode,
and only if they appear in string-move or vector instructions.  On machines
which have no such instructions, @code{BLKmode} will not appear in RTL.

@findex VOIDmode
@item VOIDmode
Void mode means the absence of a mode or an unspecified mode.
For example, RTL expressions of code @code{const_int} have mode
@code{VOIDmode} because they can be taken to have whatever mode the context
requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
the absence of any mode.

@findex SCmode
@findex DCmode
@findex XCmode
@findex TCmode
@item SCmode, DCmode, XCmode, TCmode
These modes stand for a complex number represented as a pair of floating
point values.  The floating point values are in @code{SFmode},
@code{DFmode}, @code{XFmode}, and @code{TFmode}, respectively.

@findex CQImode
@findex CHImode
@findex CSImode
@findex CDImode
@findex CTImode
@findex COImode
@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
These modes stand for a complex number represented as a pair of integer
values.  The integer values are in @code{QImode}, @code{HImode},
@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
respectively.
@end table

The machine description defines @code{Pmode} as a C macro which expands
into the machine mode used for addresses.  Normally this is the mode
whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.

The only modes which a machine description @i{must} support are
@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
The compiler will attempt to use @code{DImode} for 8-byte structures and
unions, but this can be prevented by overriding the definition of
@code{MAX_FIXED_MODE_SIZE}.  Alternatively, you can have the compiler
use @code{TImode} for 16-byte structures and unions.  Likewise, you can
arrange for the C type @code{short int} to avoid using @code{HImode}.

@cindex mode classes
Very few explicit references to machine modes remain in the compiler and
these few references will soon be removed.  Instead, the machine modes
are divided into mode classes.  These are represented by the enumeration
type @code{enum mode_class} defined in @file{machmode.h}.  The possible
mode classes are:

@table @code
@findex MODE_INT
@item MODE_INT
Integer modes.  By default these are @code{QImode}, @code{HImode},
@code{SImode}, @code{DImode}, and @code{TImode}.

@findex MODE_PARTIAL_INT
@item MODE_PARTIAL_INT
The ``partial integer'' modes, @code{PSImode} and @code{PDImode}.

@findex MODE_FLOAT
@item MODE_FLOAT
floating point modes.  By default these are @code{SFmode}, @code{DFmode},
@code{XFmode} and @code{TFmode}.

@findex MODE_COMPLEX_INT
@item MODE_COMPLEX_INT
Complex integer modes.  (These are not currently implemented).

@findex MODE_COMPLEX_FLOAT
@item MODE_COMPLEX_FLOAT
Complex floating point modes.  By default these are @code{SCmode},
@code{DCmode}, @code{XCmode}, and @code{TCmode}.

@findex MODE_FUNCTION
@item MODE_FUNCTION
Algol or Pascal function variables including a static chain.
(These are not currently implemented).

@findex MODE_CC
@item MODE_CC
Modes representing condition code values.  These are @code{CCmode} plus
any modes listed in the @code{EXTRA_CC_MODES} macro.  @xref{Jump Patterns},
also see @ref{Condition Code}.

@findex MODE_RANDOM
@item MODE_RANDOM
This is a catchall mode class for modes which don't fit into the above
classes.  Currently @code{VOIDmode} and @code{BLKmode} are in
@code{MODE_RANDOM}.
@end table

Here are some C macros that relate to machine modes:

@table @code
@findex GET_MODE
@item GET_MODE (@var{x})
Returns the machine mode of the RTX @var{x}.

@findex PUT_MODE
@item PUT_MODE (@var{x}, @var{newmode})
Alters the machine mode of the RTX @var{x} to be @var{newmode}.

@findex NUM_MACHINE_MODES
@item NUM_MACHINE_MODES
Stands for the number of machine modes available on the target
machine.  This is one greater than the largest numeric value of any
machine mode.

@findex GET_MODE_NAME
@item GET_MODE_NAME (@var{m})
Returns the name of mode @var{m} as a string.

@findex GET_MODE_CLASS
@item GET_MODE_CLASS (@var{m})
Returns the mode class of mode @var{m}.

@findex GET_MODE_WIDER_MODE
@item GET_MODE_WIDER_MODE (@var{m})
Returns the next wider natural mode.  For example, the expression
@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.

@findex GET_MODE_SIZE
@item GET_MODE_SIZE (@var{m})
Returns the size in bytes of a datum of mode @var{m}.

@findex GET_MODE_BITSIZE
@item GET_MODE_BITSIZE (@var{m})
Returns the size in bits of a datum of mode @var{m}.

@findex GET_MODE_MASK
@item GET_MODE_MASK (@var{m})
Returns a bitmask containing 1 for all bits in a word that fit within
mode @var{m}.  This macro can only be used for modes whose bitsize is
less than or equal to @code{HOST_BITS_PER_INT}.

@findex GET_MODE_ALIGNMENT
@item GET_MODE_ALIGNMENT (@var{m})
Return the required alignment, in bits, for an object of mode @var{m}.

@findex GET_MODE_UNIT_SIZE
@item GET_MODE_UNIT_SIZE (@var{m})
Returns the size in bytes of the subunits of a datum of mode @var{m}.
This is the same as @code{GET_MODE_SIZE} except in the case of complex
modes.  For them, the unit size is the size of the real or imaginary
part.

@findex GET_MODE_NUNITS
@item GET_MODE_NUNITS (@var{m})
Returns the number of units contained in a mode, i.e.,
@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.

@findex GET_CLASS_NARROWEST_MODE
@item GET_CLASS_NARROWEST_MODE (@var{c})
Returns the narrowest mode in mode class @var{c}.
@end table

@findex byte_mode
@findex word_mode
The global variables @code{byte_mode} and @code{word_mode} contain modes
whose classes are @code{MODE_INT} and whose bitsizes are either
@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively.  On 32-bit
machines, these are @code{QImode} and @code{SImode}, respectively.

@node Constants, Regs and Memory, Machine Modes, RTL
@section Constant Expression Types
@cindex RTL constants
@cindex RTL constant expression types

The simplest RTL expressions are those that represent constant values.

@table @code
@findex const_int
@item (const_int @var{i})
This type of expression represents the integer value @var{i}.  @var{i}
is customarily accessed with the macro @code{INTVAL} as in
@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.

@findex const0_rtx
@findex const1_rtx
@findex const2_rtx
@findex constm1_rtx
There is only one expression object for the integer value zero; it is
the value of the variable @code{const0_rtx}.  Likewise, the only
expression for integer value one is found in @code{const1_rtx}, the only
expression for integer value two is found in @code{const2_rtx}, and the
only expression for integer value negative one is found in
@code{constm1_rtx}.  Any attempt to create an expression of code
@code{const_int} and value zero, one, two or negative one will return
@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
@code{constm1_rtx} as appropriate.@refill

@findex const_true_rtx
Similarly, there is only one object for the integer whose value is
@code{STORE_FLAG_VALUE}.  It is found in @code{const_true_rtx}.  If
@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
@code{const1_rtx} will point to the same object.  If
@code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and
@code{constm1_rtx} will point to the same object.@refill

@findex const_double
@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
Represents either a floating-point constant of mode @var{m} or an
integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
bits but small enough to fit within twice that number of bits (GNU CC
does not provide a mechanism to represent even larger constants).  In
the latter case, @var{m} will be @code{VOIDmode}.

@findex CONST_DOUBLE_MEM
@findex CONST_DOUBLE_CHAIN
@var{addr} is used to contain the @code{mem} expression that corresponds
to the location in memory that at which the constant can be found.  If
it has not been allocated a memory location, but is on the chain of all
@code{const_double} expressions in this compilation (maintained using an
undisplayed field), @var{addr} contains @code{const0_rtx}.  If it is not
on the chain, @var{addr} contains @code{cc0_rtx}.  @var{addr} is
customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
chain field via @code{CONST_DOUBLE_CHAIN}.@refill

@findex CONST_DOUBLE_LOW
If @var{m} is @code{VOIDmode}, the bits of the value are stored in
@var{i0} and @var{i1}.  @var{i0} is customarily accessed with the macro
@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.

If the constant is floating point (regardless of its precision), then
the number of integers used to store the value depends on the size of
@code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}).  The integers
represent a floating point number, but not precisely in the target
machine's or host machine's floating point format.  To convert them to
the precise bit pattern used by the target machine, use the macro
@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).

@findex CONST0_RTX
@findex CONST1_RTX
@findex CONST2_RTX
The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
value 0 in mode @var{mode}.  If mode @var{mode} is of mode class
@code{MODE_INT}, it returns @code{const0_rtx}.  Otherwise, it returns a
@code{CONST_DOUBLE} expression in mode @var{mode}.  Similarly, the macro
@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
mode @var{mode} and similarly for @code{CONST2_RTX}.

@findex const_string
@item (const_string @var{str})
Represents a constant string with value @var{str}.  Currently this is
used only for insn attributes (@pxref{Insn Attributes}) since constant
strings in C are placed in memory.

@findex symbol_ref
@item (symbol_ref:@var{mode} @var{symbol})
Represents the value of an assembler label for data.  @var{symbol} is
a string that describes the name of the assembler label.  If it starts
with a @samp{*}, the label is the rest of @var{symbol} not including
the @samp{*}.  Otherwise, the label is @var{symbol}, usually prefixed
with @samp{_}.

The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
Usually that is the only mode for which a symbol is directly valid.

@findex label_ref
@item (label_ref @var{label})
Represents the value of an assembler label for code.  It contains one
operand, an expression, which must be a @code{code_label} that appears
in the instruction sequence to identify the place where the label
should go.

The reason for using a distinct expression type for code label
references is so that jump optimization can distinguish them.

@item (const:@var{m} @var{exp})
Represents a constant that is the result of an assembly-time
arithmetic computation.  The operand, @var{exp}, is an expression that
contains only constants (@code{const_int}, @code{symbol_ref} and
@code{label_ref} expressions) combined with @code{plus} and
@code{minus}.  However, not all combinations are valid, since the
assembler cannot do arbitrary arithmetic on relocatable symbols.

@var{m} should be @code{Pmode}.

@findex high
@item (high:@var{m} @var{exp})
Represents the high-order bits of @var{exp}, usually a
@code{symbol_ref}.  The number of bits is machine-dependent and is
normally the number of bits specified in an instruction that initializes
the high order bits of a register.  It is used with @code{lo_sum} to
represent the typical two-instruction sequence used in RISC machines to
reference a global memory location.

@var{m} should be @code{Pmode}.
@end table

@node Regs and Memory, Arithmetic, Constants, RTL
@section Registers and Memory
@cindex RTL register expressions
@cindex RTL memory expressions

Here are the RTL expression types for describing access to machine
registers and to main memory.

@table @code
@findex reg
@cindex hard registers
@cindex pseudo registers
@item (reg:@var{m} @var{n})
For small values of the integer @var{n} (those that are less than
@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
register number @var{n}: a @dfn{hard register}.  For larger values of
@var{n}, it stands for a temporary value or @dfn{pseudo register}.
The compiler's strategy is to generate code assuming an unlimited
number of such pseudo registers, and later convert them into hard
registers or into memory references.

@var{m} is the machine mode of the reference.  It is necessary because
machines can generally refer to each register in more than one mode.
For example, a register may contain a full word but there may be
instructions to refer to it as a half word or as a single byte, as
well as instructions to refer to it as a floating point number of
various precisions.

Even for a register that the machine can access in only one mode,
the mode must always be specified.

The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
description, since the number of hard registers on the machine is an
invariant characteristic of the machine.  Note, however, that not
all of the machine registers must be general registers.  All the
machine registers that can be used for storage of data are given
hard register numbers, even those that can be used only in certain
instructions or can hold only certain types of data.

A hard register may be accessed in various modes throughout one
function, but each pseudo register is given a natural mode
and is accessed only in that mode.  When it is necessary to describe
an access to a pseudo register using a nonnatural mode, a @code{subreg}
expression is used.

A @code{reg} expression with a machine mode that specifies more than
one word of data may actually stand for several consecutive registers.
If in addition the register number specifies a hardware register, then
it actually represents several consecutive hardware registers starting
with the specified one.

Each pseudo register number used in a function's RTL code is
represented by a unique @code{reg} expression.

@findex FIRST_VIRTUAL_REGISTER
@findex LAST_VIRTUAL_REGISTER
Some pseudo register numbers, those within the range of
@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
appear during the RTL generation phase and are eliminated before the
optimization phases.  These represent locations in the stack frame that
cannot be determined until RTL generation for the function has been
completed.  The following virtual register numbers are defined:

@table @code
@findex VIRTUAL_INCOMING_ARGS_REGNUM
@item VIRTUAL_INCOMING_ARGS_REGNUM
This points to the first word of the incoming arguments passed on the
stack.  Normally these arguments are placed there by the caller, but the
callee may have pushed some arguments that were previously passed in
registers.

@cindex @code{FIRST_PARM_OFFSET} and virtual registers
@cindex @code{ARG_POINTER_REGNUM} and virtual registers
When RTL generation is complete, this virtual register is replaced
by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
value of @code{FIRST_PARM_OFFSET}.

@findex VIRTUAL_STACK_VARS_REGNUM
@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
@item VIRTUAL_STACK_VARS_REGNUM
If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately
above the first variable on the stack.  Otherwise, it points to the
first variable on the stack.

@cindex @code{STARTING_FRAME_OFFSET} and virtual registers
@cindex @code{FRAME_POINTER_REGNUM} and virtual registers
@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
register given by @code{FRAME_POINTER_REGNUM} and the value
@code{STARTING_FRAME_OFFSET}.

@findex VIRTUAL_STACK_DYNAMIC_REGNUM
@item VIRTUAL_STACK_DYNAMIC_REGNUM
This points to the location of dynamically allocated memory on the stack
immediately after the stack pointer has been adjusted by the amount of
memory desired.

@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
@cindex @code{STACK_POINTER_REGNUM} and virtual registers
This virtual register is replaced by the sum of the register given by
@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.

@findex VIRTUAL_OUTGOING_ARGS_REGNUM
@item VIRTUAL_OUTGOING_ARGS_REGNUM
This points to the location in the stack at which outgoing arguments
should be written when the stack is pre-pushed (arguments pushed using
push insns should always use @code{STACK_POINTER_REGNUM}).

@cindex @code{STACK_POINTER_OFFSET} and virtual registers
This virtual register is replaced by the sum of the register given by
@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
@end table

@findex subreg
@item (subreg:@var{m} @var{reg} @var{wordnum})
@code{subreg} expressions are used to refer to a register in a machine
mode other than its natural one, or to refer to one register of
a multi-word @code{reg} that actually refers to several registers.

Each pseudo-register has a natural mode.  If it is necessary to
operate on it in a different mode---for example, to perform a fullword
move instruction on a pseudo-register that contains a single
byte---the pseudo-register must be enclosed in a @code{subreg}.  In
such a case, @var{wordnum} is zero.

Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
case it is restricting consideration to only the bits of @var{reg} that
are in @var{m}.

Sometimes @var{m} is wider than the mode of @var{reg}.  These
@code{subreg} expressions are often called @dfn{paradoxical}.  They are
used in cases where we want to refer to an object in a wider mode but do
not care what value the additional bits have.  The reload pass ensures
that paradoxical references are only made to hard registers.

The other use of @code{subreg} is to extract the individual registers of
a multi-register value.  Machine modes such as @code{DImode} and
@code{TImode} can indicate values longer than a word, values which
usually require two or more consecutive registers.  To access one of the
registers, use a @code{subreg} with mode @code{SImode} and a
@var{wordnum} that says which register.

Storing in a non-paradoxical @code{subreg} has undefined results for
bits belonging to the same word as the @code{subreg}.  This laxity makes
it easier to generate efficient code for such instructions.  To
represent an instruction that preserves all the bits outside of those in
the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.

@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
that word number zero is the most significant part; otherwise, it is
the least significant part.

@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
@code{WORDS_BIG_ENDIAN}.
However, most parts of the compiler treat floating point values as if
they had the same endianness as integer values.  This works because
they handle them solely as a collection of integer values, with no
particular numerical value.  Only real.c and the runtime libraries
care about @code{FLOAT_WORDS_BIG_ENDIAN}.

@cindex combiner pass
@cindex reload pass
@cindex @code{subreg}, special reload handling
Between the combiner pass and the reload pass, it is possible to have a
paradoxical @code{subreg} which contains a @code{mem} instead of a
@code{reg} as its first operand.  After the reload pass, it is also
possible to have a non-paradoxical @code{subreg} which contains a
@code{mem}; this usually occurs when the @code{mem} is a stack slot
which replaced a pseudo register.

Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
using a @code{subreg}.  On some machines the most significant part of a
@code{DFmode} value does not have the same format as a single-precision
floating value.

It is also not valid to access a single word of a multi-word value in a
hard register when less registers can hold the value than would be
expected from its size.  For example, some 32-bit machines have
floating-point registers that can hold an entire @code{DFmode} value.
If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
would be invalid because there is no way to convert that reference to
a single machine register.  The reload pass prevents @code{subreg}
expressions such as these from being formed.

@findex SUBREG_REG
@findex SUBREG_WORD
The first operand of a @code{subreg} expression is customarily accessed 
with the @code{SUBREG_REG} macro and the second operand is customarily
accessed with the @code{SUBREG_WORD} macro.

@findex scratch
@cindex scratch operands
@item (scratch:@var{m})
This represents a scratch register that will be required for the
execution of a single instruction and not used subsequently.  It is
converted into a @code{reg} by either the local register allocator or
the reload pass.

@code{scratch} is usually present inside a @code{clobber} operation
(@pxref{Side Effects}).

@findex cc0
@cindex condition code register
@item (cc0)
This refers to the machine's condition code register.  It has no
operands and may not have a machine mode.  There are two ways to use it:

@itemize @bullet
@item
To stand for a complete set of condition code flags.  This is best on
most machines, where each comparison sets the entire series of flags.

With this technique, @code{(cc0)} may be validly used in only two
contexts: as the destination of an assignment (in test and compare
instructions) and in comparison operators comparing against zero
(@code{const_int} with value zero; that is to say, @code{const0_rtx}).

@item
To stand for a single flag that is the result of a single condition.
This is useful on machines that have only a single flag bit, and in
which comparison instructions must specify the condition to test.

With this technique, @code{(cc0)} may be validly used in only two
contexts: as the destination of an assignment (in test and compare
instructions) where the source is a comparison operator, and as the
first operand of @code{if_then_else} (in a conditional branch).
@end itemize

@findex cc0_rtx
There is only one expression object of code @code{cc0}; it is the
value of the variable @code{cc0_rtx}.  Any attempt to create an
expression of code @code{cc0} will return @code{cc0_rtx}.

Instructions can set the condition code implicitly.  On many machines,
nearly all instructions set the condition code based on the value that
they compute or store.  It is not necessary to record these actions
explicitly in the RTL because the machine description includes a
prescription for recognizing the instructions that do so (by means of
the macro @code{NOTICE_UPDATE_CC}).  @xref{Condition Code}.  Only
instructions whose sole purpose is to set the condition code, and
instructions that use the condition code, need mention @code{(cc0)}.

On some machines, the condition code register is given a register number
and a @code{reg} is used instead of @code{(cc0)}.  This is usually the
preferable approach if only a small subset of instructions modify the
condition code.  Other machines store condition codes in general
registers; in such cases a pseudo register should be used.

Some machines, such as the Sparc and RS/6000, have two sets of
arithmetic instructions, one that sets and one that does not set the
condition code.  This is best handled by normally generating the
instruction that does not set the condition code, and making a pattern
that both performs the arithmetic and sets the condition code register
(which would not be @code{(cc0)} in this case).  For examples, search
for @samp{addcc} and @samp{andcc} in @file{sparc.md}.

@findex pc
@item (pc)
@cindex program counter
This represents the machine's program counter.  It has no operands and
may not have a machine mode.  @code{(pc)} may be validly used only in
certain specific contexts in jump instructions.

@findex pc_rtx
There is only one expression object of code @code{pc}; it is the value
of the variable @code{pc_rtx}.  Any attempt to create an expression of
code @code{pc} will return @code{pc_rtx}.

All instructions that do not jump alter the program counter implicitly
by incrementing it, but there is no need to mention this in the RTL.

@findex mem
@item (mem:@var{m} @var{addr})
This RTX represents a reference to main memory at an address
represented by the expression @var{addr}.  @var{m} specifies how large
a unit of memory is accessed.

@findex addressof
@item (addressof:@var{m} @var{reg})
This RTX represents a request for the address of register @var{reg}.  Its mode
is always @code{Pmode}.  If there are any @code{addressof}
expressions left in the function after CSE, @var{reg} is forced into the
stack and the @code{addressof} expression is replaced with a @code{plus}
expression for the address of its stack slot.
@end table

@node Arithmetic, Comparisons, Regs and Memory, RTL
@section RTL Expressions for Arithmetic
@cindex arithmetic, in RTL
@cindex math, in RTL
@cindex RTL expressions for arithmetic

Unless otherwise specified, all the operands of arithmetic expressions
must be valid for mode @var{m}.  An operand is valid for mode @var{m}
if it has mode @var{m}, or if it is a @code{const_int} or
@code{const_double} and @var{m} is a mode of class @code{MODE_INT}.

For commutative binary operations, constants should be placed in the
second operand.

@table @code
@findex plus
@cindex RTL addition
@cindex RTL sum
@item (plus:@var{m} @var{x} @var{y})
Represents the sum of the values represented by @var{x} and @var{y}
carried out in machine mode @var{m}. 

@findex lo_sum
@item (lo_sum:@var{m} @var{x} @var{y})
Like @code{plus}, except that it represents that sum of @var{x} and the
low-order bits of @var{y}.  The number of low order bits is
machine-dependent but is normally the number of bits in a @code{Pmode}
item minus the number of bits set by the @code{high} code
(@pxref{Constants}).

@var{m} should be @code{Pmode}.

@findex minus
@cindex RTL subtraction
@cindex RTL difference
@item (minus:@var{m} @var{x} @var{y})
Like @code{plus} but represents subtraction.

@findex compare
@cindex RTL comparison
@item (compare:@var{m} @var{x} @var{y})
Represents the result of subtracting @var{y} from @var{x} for purposes
of comparison.  The result is computed without overflow, as if with
infinite precision.

Of course, machines can't really subtract with infinite precision.
However, they can pretend to do so when only the sign of the
result will be used, which is the case when the result is stored
in the condition code.   And that is the only way this kind of expression
may validly be used: as a value to be stored in the condition codes.

The mode @var{m} is not related to the modes of @var{x} and @var{y},
but instead is the mode of the condition code value.  If @code{(cc0)}
is used, it is @code{VOIDmode}.  Otherwise it is some mode in class
@code{MODE_CC}, often @code{CCmode}.  @xref{Condition Code}.

Normally, @var{x} and @var{y} must have the same mode.  Otherwise,
@code{compare} is valid only if the mode of @var{x} is in class
@code{MODE_INT} and @var{y} is a @code{const_int} or
@code{const_double} with mode @code{VOIDmode}.  The mode of @var{x}
determines what mode the comparison is to be done in; thus it must not
be @code{VOIDmode}.

If one of the operands is a constant, it should be placed in the
second operand and the comparison code adjusted as appropriate.  

A @code{compare} specifying two @code{VOIDmode} constants is not valid
since there is no way to know in what mode the comparison is to be
performed; the comparison must either be folded during the compilation
or the first operand must be loaded into a register while its mode is
still known.

@findex neg
@item (neg:@var{m} @var{x})
Represents the negation (subtraction from zero) of the value represented
by @var{x}, carried out in mode @var{m}.

@findex mult
@cindex multiplication
@cindex product
@item (mult:@var{m} @var{x} @var{y})
Represents the signed product of the values represented by @var{x} and
@var{y} carried out in machine mode @var{m}.

Some machines support a multiplication that generates a product wider
than the operands.  Write the pattern for this as

@example
(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
@end example

where @var{m} is wider than the modes of @var{x} and @var{y}, which need
not be the same.

Write patterns for unsigned widening multiplication similarly using
@code{zero_extend}.

@findex div
@cindex division
@cindex signed division
@cindex quotient
@item (div:@var{m} @var{x} @var{y})
Represents the quotient in signed division of @var{x} by @var{y},
carried out in machine mode @var{m}.  If @var{m} is a floating point
mode, it represents the exact quotient; otherwise, the integerized
quotient.

Some machines have division instructions in which the operands and
quotient widths are not all the same; you should represent 
such instructions using @code{truncate} and @code{sign_extend} as in,

@example
(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
@end example

@findex udiv
@cindex unsigned division
@cindex division
@item (udiv:@var{m} @var{x} @var{y})
Like @code{div} but represents unsigned division.

@findex mod
@findex umod
@cindex remainder
@cindex division
@item (mod:@var{m} @var{x} @var{y})
@itemx (umod:@var{m} @var{x} @var{y})
Like @code{div} and @code{udiv} but represent the remainder instead of
the quotient.

@findex smin
@findex smax
@cindex signed minimum
@cindex signed maximum
@item (smin:@var{m} @var{x} @var{y})
@itemx (smax:@var{m} @var{x} @var{y})
Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
@var{x} and @var{y}, interpreted as signed integers in mode @var{m}.

@findex umin
@findex umax
@cindex unsigned minimum and maximum
@item (umin:@var{m} @var{x} @var{y})
@itemx (umax:@var{m} @var{x} @var{y})
Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
integers.

@findex not
@cindex complement, bitwise
@cindex bitwise complement
@item (not:@var{m} @var{x})
Represents the bitwise complement of the value represented by @var{x},
carried out in mode @var{m}, which must be a fixed-point machine mode.

@findex and
@cindex logical-and, bitwise
@cindex bitwise logical-and
@item (and:@var{m} @var{x} @var{y})
Represents the bitwise logical-and of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}, which must be
a fixed-point machine mode.

@findex ior
@cindex inclusive-or, bitwise
@cindex bitwise inclusive-or
@item (ior:@var{m} @var{x} @var{y})
Represents the bitwise inclusive-or of the values represented by @var{x}
and @var{y}, carried out in machine mode @var{m}, which must be a
fixed-point mode.

@findex xor
@cindex exclusive-or, bitwise
@cindex bitwise exclusive-or
@item (xor:@var{m} @var{x} @var{y})
Represents the bitwise exclusive-or of the values represented by @var{x}
and @var{y}, carried out in machine mode @var{m}, which must be a
fixed-point mode.

@findex ashift
@cindex left shift
@cindex shift
@cindex arithmetic shift
@item (ashift:@var{m} @var{x} @var{c})
Represents the result of arithmetically shifting @var{x} left by @var{c}
places.  @var{x} have mode @var{m}, a fixed-point machine mode.  @var{c}
be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
mode is determined by the mode called for in the machine description
entry for the left-shift instruction.  For example, on the Vax, the mode
of @var{c} is @code{QImode} regardless of @var{m}.

@findex lshiftrt
@cindex right shift
@findex ashiftrt
@item (lshiftrt:@var{m} @var{x} @var{c})
@itemx (ashiftrt:@var{m} @var{x} @var{c})
Like @code{ashift} but for right shift.  Unlike the case for left shift,
these two operations are distinct.

@findex rotate
@cindex rotate 
@cindex left rotate
@findex rotatert
@cindex right rotate
@item (rotate:@var{m} @var{x} @var{c})
@itemx (rotatert:@var{m} @var{x} @var{c})
Similar but represent left and right rotate.  If @var{c} is a constant,
use @code{rotate}.

@findex abs
@cindex absolute value
@item (abs:@var{m} @var{x})
Represents the absolute value of @var{x}, computed in mode @var{m}.

@findex sqrt
@cindex square root
@item (sqrt:@var{m} @var{x})
Represents the square root of @var{x}, computed in mode @var{m}.
Most often @var{m} will be a floating point mode.

@findex ffs
@item (ffs:@var{m} @var{x})
Represents one plus the index of the least significant 1-bit in
@var{x}, represented as an integer of mode @var{m}.  (The value is
zero if @var{x} is zero.)  The mode of @var{x} need not be @var{m};
depending on the target machine, various mode combinations may be
valid.
@end table

@node Comparisons, Bit Fields, Arithmetic, RTL
@section Comparison Operations
@cindex RTL comparison operations

Comparison operators test a relation on two operands and are considered
to represent a machine-dependent nonzero value described by, but not
necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
if the relation holds, or zero if it does not.  The mode of the
comparison operation is independent of the mode of the data being
compared.  If the comparison operation is being tested (e.g., the first
operand of an @code{if_then_else}), the mode must be @code{VOIDmode}.
If the comparison operation is producing data to be stored in some
variable, the mode must be in class @code{MODE_INT}.  All comparison
operations producing data must use the same mode, which is
machine-specific.

@cindex condition codes
There are two ways that comparison operations may be used.  The
comparison operators may be used to compare the condition codes
@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.  Such
a construct actually refers to the result of the preceding instruction
in which the condition codes were set.  The instructing setting the
condition code must be adjacent to the instruction using the condition
code; only @code{note} insns may separate them.

Alternatively, a comparison operation may directly compare two data
objects.  The mode of the comparison is determined by the operands; they
must both be valid for a common machine mode.  A comparison with both
operands constant would be invalid as the machine mode could not be
deduced from it, but such a comparison should never exist in RTL due to
constant folding.

In the example above, if @code{(cc0)} were last set to
@code{(compare @var{x} @var{y})}, the comparison operation is
identical to @code{(eq @var{x} @var{y})}.  Usually only one style
of comparisons is supported on a particular machine, but the combine
pass will try to merge the operations to produce the @code{eq} shown
in case it exists in the context of the particular insn involved.

Inequality comparisons come in two flavors, signed and unsigned.  Thus,
there are distinct expression codes @code{gt} and @code{gtu} for signed and
unsigned greater-than.  These can produce different results for the same
pair of integer values: for example, 1 is signed greater-than -1 but not
unsigned greater-than, because -1 when regarded as unsigned is actually
@code{0xffffffff} which is greater than 1.

The signed comparisons are also used for floating point values.  Floating
point comparisons are distinguished by the machine modes of the operands.

@table @code
@findex eq
@cindex equal
@item (eq:@var{m} @var{x} @var{y})
1 if the values represented by @var{x} and @var{y} are equal,
otherwise 0.

@findex ne
@cindex not equal
@item (ne:@var{m} @var{x} @var{y})
1 if the values represented by @var{x} and @var{y} are not equal,
otherwise 0.

@findex gt
@cindex greater than
@item (gt:@var{m} @var{x} @var{y})
1 if the @var{x} is greater than @var{y}.  If they are fixed-point,
the comparison is done in a signed sense.

@findex gtu
@cindex greater than
@cindex unsigned greater than
@item (gtu:@var{m} @var{x} @var{y})
Like @code{gt} but does unsigned comparison, on fixed-point numbers only.

@findex lt
@cindex less than
@findex ltu
@cindex unsigned less than
@item (lt:@var{m} @var{x} @var{y})
@itemx (ltu:@var{m} @var{x} @var{y})
Like @code{gt} and @code{gtu} but test for ``less than''.

@findex ge
@cindex greater than
@findex geu
@cindex unsigned greater than
@item (ge:@var{m} @var{x} @var{y})
@itemx (geu:@var{m} @var{x} @var{y})
Like @code{gt} and @code{gtu} but test for ``greater than or equal''.

@findex le
@cindex less than or equal
@findex leu
@cindex unsigned less than
@item (le:@var{m} @var{x} @var{y})
@itemx (leu:@var{m} @var{x} @var{y})
Like @code{gt} and @code{gtu} but test for ``less than or equal''.

@findex if_then_else
@item (if_then_else @var{cond} @var{then} @var{else})
This is not a comparison operation but is listed here because it is
always used in conjunction with a comparison operation.  To be
precise, @var{cond} is a comparison expression.  This expression
represents a choice, according to @var{cond}, between the value
represented by @var{then} and the one represented by @var{else}.

On most machines, @code{if_then_else} expressions are valid only
to express conditional jumps.

@findex cond
@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
Similar to @code{if_then_else}, but more general.  Each of @var{test1},
@var{test2}, @dots{} is performed in turn.  The result of this expression is
the @var{value} corresponding to the first non-zero test, or @var{default} if
none of the tests are non-zero expressions.

This is currently not valid for instruction patterns and is supported only
for insn attributes.  @xref{Insn Attributes}.
@end table

@node Bit Fields, Conversions, Comparisons, RTL
@section Bit Fields
@cindex bit fields

Special expression codes exist to represent bitfield instructions.
These types of expressions are lvalues in RTL; they may appear
on the left side of an assignment, indicating insertion of a value
into the specified bit field.

@table @code
@findex sign_extract
@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
This represents a reference to a sign-extended bit field contained or
starting in @var{loc} (a memory or register reference).  The bit field
is @var{size} bits wide and starts at bit @var{pos}.  The compilation
option @code{BITS_BIG_ENDIAN} says which end of the memory unit
@var{pos} counts from.

If @var{loc} is in memory, its mode must be a single-byte integer mode.
If @var{loc} is in a register, the mode to use is specified by the
operand of the @code{insv} or @code{extv} pattern
(@pxref{Standard Names}) and is usually a full-word integer mode,
which is the default if none is specified.

The mode of @var{pos} is machine-specific and is also specified
in the @code{insv} or @code{extv} pattern.

The mode @var{m} is the same as the mode that would be used for
@var{loc} if it were a register.

@findex zero_extract
@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
Like @code{sign_extract} but refers to an unsigned or zero-extended
bit field.  The same sequence of bits are extracted, but they
are filled to an entire word with zeros instead of by sign-extension.
@end table

@node Conversions, RTL Declarations, Bit Fields, RTL
@section Conversions
@cindex conversions
@cindex machine mode conversions

All conversions between machine modes must be represented by
explicit conversion operations.  For example, an expression
which is the sum of a byte and a full word cannot be written as
@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
operation requires two operands of the same machine mode.
Therefore, the byte-sized operand is enclosed in a conversion
operation, as in

@example
(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
@end example

The conversion operation is not a mere placeholder, because there
may be more than one way of converting from a given starting mode
to the desired final mode.  The conversion operation code says how
to do it.

For all conversion operations, @var{x} must not be @code{VOIDmode}
because the mode in which to do the conversion would not be known.
The conversion must either be done at compile-time or @var{x}
must be placed into a register.

@table @code
@findex sign_extend
@item (sign_extend:@var{m} @var{x})
Represents the result of sign-extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode narrower than @var{m}.

@findex zero_extend
@item (zero_extend:@var{m} @var{x})
Represents the result of zero-extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode narrower than @var{m}.

@findex float_extend
@item (float_extend:@var{m} @var{x})
Represents the result of extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a floating point mode
and @var{x} a floating point value of a mode narrower than @var{m}.

@findex truncate
@item (truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode wider than @var{m}.

@findex float_truncate
@item (float_truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}.  @var{m} must be a floating point mode
and @var{x} a floating point value of a mode wider than @var{m}.

@findex float
@item (float:@var{m} @var{x})
Represents the result of converting fixed point value @var{x},
regarded as signed, to floating point mode @var{m}.

@findex unsigned_float
@item (unsigned_float:@var{m} @var{x})
Represents the result of converting fixed point value @var{x},
regarded as unsigned, to floating point mode @var{m}.

@findex fix
@item (fix:@var{m} @var{x})
When @var{m} is a fixed point mode, represents the result of
converting floating point value @var{x} to mode @var{m}, regarded as
signed.  How rounding is done is not specified, so this operation may
be used validly in compiling C code only for integer-valued operands.

@findex unsigned_fix
@item (unsigned_fix:@var{m} @var{x})
Represents the result of converting floating point value @var{x} to
fixed point mode @var{m}, regarded as unsigned.  How rounding is done
is not specified.

@findex fix
@item (fix:@var{m} @var{x})
When @var{m} is a floating point mode, represents the result of
converting floating point value @var{x} (valid for mode @var{m}) to an
integer, still represented in floating point mode @var{m}, by rounding
towards zero.
@end table

@node RTL Declarations, Side Effects, Conversions, RTL
@section Declarations
@cindex RTL declarations
@cindex declarations, RTL

Declaration expression codes do not represent arithmetic operations
but rather state assertions about their operands.

@table @code
@findex strict_low_part
@cindex @code{subreg}, in @code{strict_low_part}
@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
This expression code is used in only one context: as the destination operand of a
@code{set} expression.  In addition, the operand of this expression
must be a non-paradoxical @code{subreg} expression.

The presence of @code{strict_low_part} says that the part of the
register which is meaningful in mode @var{n}, but is not part of
mode @var{m}, is not to be altered.  Normally, an assignment to such
a subreg is allowed to have undefined effects on the rest of the
register when @var{m} is less than a word.
@end table

@node Side Effects, Incdec, RTL Declarations, RTL
@section Side Effect Expressions
@cindex RTL side effect expressions

The expression codes described so far represent values, not actions.
But machine instructions never produce values; they are meaningful
only for their side effects on the state of the machine.  Special
expression codes are used to represent side effects.

The body of an instruction is always one of these side effect codes;
the codes described above, which represent values, appear only as
the operands of these.

@table @code
@findex set
@item (set @var{lval} @var{x})
Represents the action of storing the value of @var{x} into the place
represented by @var{lval}.  @var{lval} must be an expression
representing a place that can be stored in: @code{reg} (or
@code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
@code{cc0}.@refill

If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
machine mode; then @var{x} must be valid for that mode.@refill

If @var{lval} is a @code{reg} whose machine mode is less than the full
width of the register, then it means that the part of the register
specified by the machine mode is given the specified value and the
rest of the register receives an undefined value.  Likewise, if
@var{lval} is a @code{subreg} whose machine mode is narrower than
the mode of the register, the rest of the register can be changed in
an undefined way.

If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
part of the register specified by the machine mode of the
@code{subreg} is given the value @var{x} and the rest of the register
is not changed.@refill

If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
be either a @code{compare} expression or a value that may have any mode.
The latter case represents a ``test'' instruction.  The expression
@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
Use the former expression to save space during the compilation.

@cindex jump instructions and @code{set}
@cindex @code{if_then_else} usage
If @var{lval} is @code{(pc)}, we have a jump instruction, and the
possibilities for @var{x} are very limited.  It may be a
@code{label_ref} expression (unconditional jump).  It may be an
@code{if_then_else} (conditional jump), in which case either the
second or the third operand must be @code{(pc)} (for the case which
does not jump) and the other of the two must be a @code{label_ref}
(for the case which does jump).  @var{x} may also be a @code{mem} or
@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
@code{mem}; these unusual patterns are used to represent jumps through
branch tables.@refill

If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
valid for the mode of @var{lval}.

@findex SET_DEST
@findex SET_SRC
@var{lval} is customarily accessed with the @code{SET_DEST} macro and 
@var{x} with the @code{SET_SRC} macro.

@findex return
@item (return)
As the sole expression in a pattern, represents a return from the
current function, on machines where this can be done with one
instruction, such as Vaxes.  On machines where a multi-instruction
``epilogue'' must be executed in order to return from the function,
returning is done by jumping to a label which precedes the epilogue, and
the @code{return} expression code is never used.

Inside an @code{if_then_else} expression, represents the value to be
placed in @code{pc} to return to the caller.

Note that an insn pattern of @code{(return)} is logically equivalent to
@code{(set (pc) (return))}, but the latter form is never used.

@findex call
@item (call @var{function} @var{nargs})
Represents a function call.  @var{function} is a @code{mem} expression
whose address is the address of the function to be called.
@var{nargs} is an expression which can be used for two purposes: on
some machines it represents the number of bytes of stack argument; on
others, it represents the number of argument registers.

Each machine has a standard machine mode which @var{function} must
have.  The machine description defines macro @code{FUNCTION_MODE} to
expand into the requisite mode name.  The purpose of this mode is to
specify what kind of addressing is allowed, on machines where the
allowed kinds of addressing depend on the machine mode being
addressed.

@findex clobber
@item (clobber @var{x})
Represents the storing or possible storing of an unpredictable,
undescribed value into @var{x}, which must be a @code{reg},
@code{scratch} or @code{mem} expression.

One place this is used is in string instructions that store standard
values into particular hard registers.  It may not be worth the
trouble to describe the values that are stored, but it is essential to
inform the compiler that the registers will be altered, lest it
attempt to keep data in them across the string instruction.

If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory
locations must be presumed clobbered.

Note that the machine description classifies certain hard registers as
``call-clobbered''.  All function call instructions are assumed by
default to clobber these registers, so there is no need to use
@code{clobber} expressions to indicate this fact.  Also, each function
call is assumed to have the potential to alter any memory location,
unless the function is declared @code{const}.

If the last group of expressions in a @code{parallel} are each a
@code{clobber} expression whose arguments are @code{reg} or
@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
phase can add the appropriate @code{clobber} expressions to an insn it
has constructed when doing so will cause a pattern to be matched.

This feature can be used, for example, on a machine that whose multiply
and add instructions don't use an MQ register but which has an
add-accumulate instruction that does clobber the MQ register.  Similarly,
a combined instruction might require a temporary register while the
constituent instructions might not.

When a @code{clobber} expression for a register appears inside a
@code{parallel} with other side effects, the register allocator
guarantees that the register is unoccupied both before and after that
insn.  However, the reload phase may allocate a register used for one of
the inputs unless the @samp{&} constraint is specified for the selected
alternative (@pxref{Modifiers}).  You can clobber either a specific hard
register, a pseudo register, or a @code{scratch} expression; in the
latter two cases, GNU CC will allocate a hard register that is available
there for use as a temporary.

For instructions that require a temporary register, you should use
@code{scratch} instead of a pseudo-register because this will allow the
combiner phase to add the @code{clobber} when required.  You do this by
coding (@code{clobber} (@code{match_scratch} @dots{})).  If you do
clobber a pseudo register, use one which appears nowhere else---generate
a new one each time.  Otherwise, you may confuse CSE.

There is one other known use for clobbering a pseudo register in a
@code{parallel}: when one of the input operands of the insn is also
clobbered by the insn.  In this case, using the same pseudo register in
the clobber and elsewhere in the insn produces the expected results.

@findex use
@item (use @var{x})
Represents the use of the value of @var{x}.  It indicates that the
value in @var{x} at this point in the program is needed, even though
it may not be apparent why this is so.  Therefore, the compiler will
not attempt to delete previous instructions whose only effect is to
store a value in @var{x}.  @var{x} must be a @code{reg} expression.

During the reload phase, an insn that has a @code{use} as pattern
can carry a reg_equal note.  These @code{use} insns will be deleted
before the reload phase exits.

During the delayed branch scheduling phase, @var{x} may be an insn.
This indicates that @var{x} previously was located at this place in the
code and its data dependencies need to be taken into account.  These
@code{use} insns will be deleted before the delayed branch scheduling
phase exits.

@findex parallel
@item (parallel [@var{x0} @var{x1} @dots{}])
Represents several side effects performed in parallel.  The square
brackets stand for a vector; the operand of @code{parallel} is a
vector of expressions.  @var{x0}, @var{x1} and so on are individual
side effect expressions---expressions of code @code{set}, @code{call},
@code{return}, @code{clobber} or @code{use}.@refill

``In parallel'' means that first all the values used in the individual
side-effects are computed, and second all the actual side-effects are
performed.  For example,

@example
(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
           (set (mem:SI (reg:SI 1)) (reg:SI 1))])
@end example

@noindent
says unambiguously that the values of hard register 1 and the memory
location addressed by it are interchanged.  In both places where
@code{(reg:SI 1)} appears as a memory address it refers to the value
in register 1 @emph{before} the execution of the insn.

It follows that it is @emph{incorrect} to use @code{parallel} and
expect the result of one @code{set} to be available for the next one.
For example, people sometimes attempt to represent a jump-if-zero
instruction this way:

@example
(parallel [(set (cc0) (reg:SI 34))
           (set (pc) (if_then_else
                        (eq (cc0) (const_int 0))
                        (label_ref @dots{})
                        (pc)))])
@end example

@noindent
But this is incorrect, because it says that the jump condition depends
on the condition code value @emph{before} this instruction, not on the
new value that is set by this instruction.

@cindex peephole optimization, RTL representation
Peephole optimization, which takes place together with final assembly
code output, can produce insns whose patterns consist of a @code{parallel}
whose elements are the operands needed to output the resulting
assembler code---often @code{reg}, @code{mem} or constant expressions.
This would not be well-formed RTL at any other stage in compilation,
but it is ok then because no further optimization remains to be done.
However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
any, must deal with such insns if you define any peephole optimizations.

@findex sequence
@item (sequence [@var{insns} @dots{}])
Represents a sequence of insns.  Each of the @var{insns} that appears
in the vector is suitable for appearing in the chain of insns, so it
must be an @code{insn}, @code{jump_insn}, @code{call_insn},
@code{code_label}, @code{barrier} or @code{note}.

A @code{sequence} RTX is never placed in an actual insn during RTL
generation.  It represents the sequence of insns that result from a
@code{define_expand} @emph{before} those insns are passed to
@code{emit_insn} to insert them in the chain of insns.  When actually
inserted, the individual sub-insns are separated out and the
@code{sequence} is forgotten.

After delay-slot scheduling is completed, an insn and all the insns that
reside in its delay slots are grouped together into a @code{sequence}.
The insn requiring the delay slot is the first insn in the vector;
subsequent insns are to be placed in the delay slot.

@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
indicate that a branch insn should be used that will conditionally annul
the effect of the insns in the delay slots.  In such a case,
@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
the branch and should be executed only if the branch is taken; otherwise
the insn should be executed only if the branch is not taken.
@xref{Delay Slots}.
@end table

These expression codes appear in place of a side effect, as the body of
an insn, though strictly speaking they do not always describe side
effects as such:

@table @code
@findex asm_input
@item (asm_input @var{s})
Represents literal assembler code as described by the string @var{s}.

@findex unspec
@findex unspec_volatile
@item (unspec [@var{operands} @dots{}] @var{index})
@itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
Represents a machine-specific operation on @var{operands}.  @var{index}
selects between multiple machine-specific operations.
@code{unspec_volatile} is used for volatile operations and operations
that may trap; @code{unspec} is used for other operations.

These codes may appear inside a @code{pattern} of an
insn, inside a @code{parallel}, or inside an expression.

@findex addr_vec
@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
Represents a table of jump addresses.  The vector elements @var{lr0},
etc., are @code{label_ref} expressions.  The mode @var{m} specifies
how much space is given to each address; normally @var{m} would be
@code{Pmode}.

@findex addr_diff_vec
@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
Represents a table of jump addresses expressed as offsets from
@var{base}.  The vector elements @var{lr0}, etc., are @code{label_ref}
expressions and so is @var{base}.  The mode @var{m} specifies how much
space is given to each address-difference.  @var{min} and @var{max}
are set up by branch shortening and hold a label with a minimum and a
maximum address, respectively.  @var{flags} indicates the relative
position of @var{base}, @var{min} and @var{max} to the cointaining insn
and of @var{min} and @var{max} to @var{base}.  See rtl.def for details.@refill
@end table

@node Incdec, Assembler, Side Effects, RTL
@section Embedded Side-Effects on Addresses
@cindex RTL preincrement
@cindex RTL postincrement
@cindex RTL predecrement
@cindex RTL postdecrement

Six special side-effect expression codes appear as memory addresses.

@table @code
@findex pre_dec
@item (pre_dec:@var{m} @var{x})
Represents the side effect of decrementing @var{x} by a standard
amount and represents also the value that @var{x} has after being
decremented.  @var{x} must be a @code{reg} or @code{mem}, but most
machines allow only a @code{reg}.  @var{m} must be the machine mode
for pointers on the machine in use.  The amount @var{x} is decremented
by is the length in bytes of the machine mode of the containing memory
reference of which this expression serves as the address.  Here is an
example of its use:@refill

@example
(mem:DF (pre_dec:SI (reg:SI 39)))
@end example

@noindent
This says to decrement pseudo register 39 by the length of a @code{DFmode}
value and use the result to address a @code{DFmode} value.

@findex pre_inc
@item (pre_inc:@var{m} @var{x})
Similar, but specifies incrementing @var{x} instead of decrementing it.

@findex post_dec
@item (post_dec:@var{m} @var{x})
Represents the same side effect as @code{pre_dec} but a different
value.  The value represented here is the value @var{x} has @i{before}
being decremented.

@findex post_inc
@item (post_inc:@var{m} @var{x})
Similar, but specifies incrementing @var{x} instead of decrementing it.

@findex post_modify
@item (post_modify:@var{m} @var{x} @var{y})

Represents the side effect of setting @var{x} to @var{y} and
represents @var{x} before @var{x} is modified.  @var{x} must be a
@code{reg} or @code{mem}, but most machines allow only a @code{reg}.
@var{m} must be the machine mode for pointers on the machine in use.
The amount @var{x} is decremented by is the length in bytes of the
machine mode of the containing memory reference of which this expression
serves as the address.  Note that this is not currently implemented.

The expression @var{y} must be one of three forms:
@table @code
@code{(plus:@var{m} @var{x} @var{z})},
@code{(minus:@var{m} @var{x} @var{z})}, or
@code{(plus:@var{m} @var{x} @var{i})},
@end table
where @var{z} is an index register and @var{i} is a constant.

Here is an example of its use:@refill

@example
(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) (reg:SI 48))))
@end example

This says to modify pseudo register 42 by adding the contents of pseudo
register 48 to it, after the use of what ever 42 points to.

@findex post_modify
@item (pre_modify:@var{m} @var{x} @var{expr})
Similar except side effects happen before the use.
@end table

These embedded side effect expressions must be used with care.  Instruction
patterns may not use them.  Until the @samp{flow} pass of the compiler,
they may occur only to represent pushes onto the stack.  The @samp{flow}
pass finds cases where registers are incremented or decremented in one
instruction and used as an address shortly before or after; these cases are
then transformed to use pre- or post-increment or -decrement.

If a register used as the operand of these expressions is used in
another address in an insn, the original value of the register is used.
Uses of the register outside of an address are not permitted within the
same insn as a use in an embedded side effect expression because such
insns behave differently on different machines and hence must be treated
as ambiguous and disallowed.

An instruction that can be represented with an embedded side effect
could also be represented using @code{parallel} containing an additional
@code{set} to describe how the address register is altered.  This is not
done because machines that allow these operations at all typically
allow them wherever a memory address is called for.  Describing them as
additional parallel stores would require doubling the number of entries
in the machine description.

@node Assembler, Insns, Incdec, RTL
@section Assembler Instructions as Expressions
@cindex assembler instructions in RTL

@cindex @code{asm_operands}, usage
The RTX code @code{asm_operands} represents a value produced by a
user-specified assembler instruction.  It is used to represent
an @code{asm} statement with arguments.  An @code{asm} statement with
a single output operand, like this:

@smallexample
asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
@end smallexample

@noindent
is represented using a single @code{asm_operands} RTX which represents
the value that is stored in @code{outputvar}:

@smallexample
(set @var{rtx-for-outputvar}
     (asm_operands "foo %1,%2,%0" "a" 0
                   [@var{rtx-for-addition-result} @var{rtx-for-*z}]
                   [(asm_input:@var{m1} "g")
                    (asm_input:@var{m2} "di")]))
@end smallexample

@noindent
Here the operands of the @code{asm_operands} RTX are the assembler
template string, the output-operand's constraint, the index-number of the
output operand among the output operands specified, a vector of input
operand RTX's, and a vector of input-operand modes and constraints.  The
mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
@code{*z}.

When an @code{asm} statement has multiple output values, its insn has
several such @code{set} RTX's inside of a @code{parallel}.  Each @code{set}
contains a @code{asm_operands}; all of these share the same assembler
template and vectors, but each contains the constraint for the respective
output operand.  They are also distinguished by the output-operand index
number, which is 0, 1, @dots{} for successive output operands.

@node Insns, Calls, Assembler, RTL
@section Insns
@cindex insns

The RTL representation of the code for a function is a doubly-linked
chain of objects called @dfn{insns}.  Insns are expressions with
special codes that are used for no other purpose.  Some insns are
actual instructions; others represent dispatch tables for @code{switch}
statements; others represent labels to jump to or various sorts of
declarative information.

In addition to its own specific data, each insn must have a unique
id-number that distinguishes it from all other insns in the current
function (after delayed branch scheduling, copies of an insn with the
same id-number may be present in multiple places in a function, but
these copies will always be identical and will only appear inside a
@code{sequence}), and chain pointers to the preceding and following
insns.  These three fields occupy the same position in every insn,
independent of the expression code of the insn.  They could be accessed
with @code{XEXP} and @code{XINT}, but instead three special macros are
always used:

@table @code
@findex INSN_UID
@item INSN_UID (@var{i})
Accesses the unique id of insn @var{i}.

@findex PREV_INSN
@item PREV_INSN (@var{i})
Accesses the chain pointer to the insn preceding @var{i}.
If @var{i} is the first insn, this is a null pointer.

@findex NEXT_INSN
@item NEXT_INSN (@var{i})
Accesses the chain pointer to the insn following @var{i}.
If @var{i} is the last insn, this is a null pointer.
@end table

@findex get_insns
@findex get_last_insn
The first insn in the chain is obtained by calling @code{get_insns}; the
last insn is the result of calling @code{get_last_insn}.  Within the
chain delimited by these insns, the @code{NEXT_INSN} and
@code{PREV_INSN} pointers must always correspond: if @var{insn} is not
the first insn,

@example
NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
@end example

@noindent
is always true and if @var{insn} is not the last insn,

@example
PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
@end example

@noindent
is always true.

After delay slot scheduling, some of the insns in the chain might be
@code{sequence} expressions, which contain a vector of insns.  The value
of @code{NEXT_INSN} in all but the last of these insns is the next insn
in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
which it is contained.  Similar rules apply for @code{PREV_INSN}.

This means that the above invariants are not necessarily true for insns
inside @code{sequence} expressions.  Specifically, if @var{insn} is the
first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
is the insn containing the @code{sequence} expression, as is the value
of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last
insn in the @code{sequence} expression.  You can use these expressions
to find the containing @code{sequence} expression.@refill

Every insn has one of the following six expression codes:

@table @code
@findex insn
@item insn
The expression code @code{insn} is used for instructions that do not jump
and do not do function calls.  @code{sequence} expressions are always
contained in insns with code @code{insn} even if one of those insns
should jump or do function calls.

Insns with code @code{insn} have four additional fields beyond the three
mandatory ones listed above.  These four are described in a table below.

@findex jump_insn
@item jump_insn
The expression code @code{jump_insn} is used for instructions that may
jump (or, more generally, may contain @code{label_ref} expressions).  If
there is an instruction to return from the current function, it is
recorded as a @code{jump_insn}.

@findex JUMP_LABEL
@code{jump_insn} insns have the same extra fields as @code{insn} insns,
accessed in the same way and in addition contain a field
@code{JUMP_LABEL} which is defined once jump optimization has completed.

For simple conditional and unconditional jumps, this field contains the
@code{code_label} to which this insn will (possibly conditionally)
branch.  In a more complex jump, @code{JUMP_LABEL} records one of the
labels that the insn refers to; the only way to find the others
is to scan the entire body of the insn.

Return insns count as jumps, but since they do not refer to any labels,
they have zero in the @code{JUMP_LABEL} field.

@findex call_insn
@item call_insn
The expression code @code{call_insn} is used for instructions that may do
function calls.  It is important to distinguish these instructions because
they imply that certain registers and memory locations may be altered
unpredictably.

@findex CALL_INSN_FUNCTION_USAGE
@code{call_insn} insns have the same extra fields as @code{insn} insns,
accessed in the same way and in addition contain a field
@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
@code{expr_list} expressions) containing @code{use} and @code{clobber}
expressions that denote hard registers used or clobbered by the called
function.  A register specified in a @code{clobber} in this list is
modified @emph{after} the execution of the @code{call_insn}, while a
register in a @code{clobber} in the body of the @code{call_insn} is
clobbered before the insn completes execution.  @code{clobber}
expressions in this list augment registers specified in
@code{CALL_USED_REGISTERS} (@pxref{Register Basics}).

@findex code_label
@findex CODE_LABEL_NUMBER
@item code_label
A @code{code_label} insn represents a label that a jump insn can jump
to.  It contains two special fields of data in addition to the three
standard ones.  @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
number}, a number that identifies this label uniquely among all the
labels in the compilation (not just in the current function).
Ultimately, the label is represented in the assembler output as an
assembler label, usually of the form @samp{L@var{n}} where @var{n} is
the label number.

When a @code{code_label} appears in an RTL expression, it normally
appears within a @code{label_ref} which represents the address of
the label, as a number.

@findex LABEL_NUSES
The field @code{LABEL_NUSES} is only defined once the jump optimization
phase is completed and contains the number of times this label is
referenced in the current function.

@findex barrier
@item barrier
Barriers are placed in the instruction stream when control cannot flow
past them.  They are placed after unconditional jump instructions to
indicate that the jumps are unconditional and after calls to
@code{volatile} functions, which do not return (e.g., @code{exit}).
They contain no information beyond the three standard fields.

@findex note
@findex NOTE_LINE_NUMBER
@findex NOTE_SOURCE_FILE
@item note
@code{note} insns are used to represent additional debugging and
declarative information.  They contain two nonstandard fields, an
integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
string accessed with @code{NOTE_SOURCE_FILE}.

If @code{NOTE_LINE_NUMBER} is positive, the note represents the
position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
that the line came from.  These notes control generation of line
number data in the assembler output.

Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
code with one of the following values (and @code{NOTE_SOURCE_FILE}
must contain a null pointer):

@table @code
@findex NOTE_INSN_DELETED
@item NOTE_INSN_DELETED
Such a note is completely ignorable.  Some passes of the compiler
delete insns by altering them into notes of this kind.

@findex NOTE_INSN_BLOCK_BEG
@findex NOTE_INSN_BLOCK_END
@item NOTE_INSN_BLOCK_BEG
@itemx NOTE_INSN_BLOCK_END
These types of notes indicate the position of the beginning and end
of a level of scoping of variable names.  They control the output
of debugging information.

@findex NOTE_INSN_EH_REGION_BEG
@findex NOTE_INSN_EH_REGION_END
@item NOTE_INSN_EH_REGION_BEG
@itemx NOTE_INSN_EH_REGION_END
These types of notes indicate the position of the beginning and end of a
level of scoping for exception handling.  @code{NOTE_BLOCK_NUMBER}
identifies which @code{CODE_LABEL} is associated with the given region.

@findex NOTE_INSN_LOOP_BEG
@findex NOTE_INSN_LOOP_END
@item NOTE_INSN_LOOP_BEG
@itemx NOTE_INSN_LOOP_END
These types of notes indicate the position of the beginning and end
of a @code{while} or @code{for} loop.  They enable the loop optimizer
to find loops quickly.

@findex NOTE_INSN_LOOP_CONT
@item NOTE_INSN_LOOP_CONT
Appears at the place in a loop that @code{continue} statements jump to.

@findex NOTE_INSN_LOOP_VTOP
@item NOTE_INSN_LOOP_VTOP
This note indicates the place in a loop where the exit test begins for
those loops in which the exit test has been duplicated.  This position
becomes another virtual start of the loop when considering loop
invariants. 

@findex NOTE_INSN_FUNCTION_END
@item NOTE_INSN_FUNCTION_END
Appears near the end of the function body, just before the label that
@code{return} statements jump to (on machine where a single instruction
does not suffice for returning).  This note may be deleted by jump
optimization.

@findex NOTE_INSN_SETJMP
@item NOTE_INSN_SETJMP
Appears following each call to @code{setjmp} or a related function.
@end table

These codes are printed symbolically when they appear in debugging dumps.
@end table

@cindex @code{TImode}, in @code{insn}
@cindex @code{HImode}, in @code{insn}
@cindex @code{QImode}, in @code{insn}
The machine mode of an insn is normally @code{VOIDmode}, but some
phases use the mode for various purposes. 

The common subexpression elimination pass sets the mode of an insn to
@code{QImode} when it is the first insn in a block that has already
been processed.

The second Haifa scheduling pass, for targets that can multiple issue,
sets the mode of an insn to @code{TImode} when it is believed that the
instruction begins an issue group.  That is, when the instruction 
cannot issue simultaneously with the previous.  This may be relied on
by later passes, in particular machine-dependant reorg.

Here is a table of the extra fields of @code{insn}, @code{jump_insn}
and @code{call_insn} insns:

@table @code
@findex PATTERN
@item PATTERN (@var{i})
An expression for the side effect performed by this insn.  This must be
one of the following codes: @code{set}, @code{call}, @code{use},
@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
@code{unspec_volatile}, @code{parallel}, or @code{sequence}.  If it is a @code{parallel},
each element of the @code{parallel} must be one these codes, except that
@code{parallel} expressions cannot be nested and @code{addr_vec} and
@code{addr_diff_vec} are not permitted inside a @code{parallel} expression.

@findex INSN_CODE
@item INSN_CODE (@var{i})
An integer that says which pattern in the machine description matches
this insn, or -1 if the matching has not yet been attempted.

Such matching is never attempted and this field remains -1 on an insn
whose pattern consists of a single @code{use}, @code{clobber},
@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.

@findex asm_noperands
Matching is also never attempted on insns that result from an @code{asm}
statement.  These contain at least one @code{asm_operands} expression.
The function @code{asm_noperands} returns a non-negative value for
such insns.

In the debugging output, this field is printed as a number followed by
a symbolic representation that locates the pattern in the @file{md}
file as some small positive or negative offset from a named pattern.

@findex LOG_LINKS
@item LOG_LINKS (@var{i})
A list (chain of @code{insn_list} expressions) giving information about
dependencies between instructions within a basic block.  Neither a jump
nor a label may come between the related insns.

@findex REG_NOTES
@item REG_NOTES (@var{i})
A list (chain of @code{expr_list} and @code{insn_list} expressions)
giving miscellaneous information about the insn.  It is often
information pertaining to the registers used in this insn.
@end table

The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
expressions.  Each of these has two operands: the first is an insn,
and the second is another @code{insn_list} expression (the next one in
the chain).  The last @code{insn_list} in the chain has a null pointer
as second operand.  The significant thing about the chain is which
insns appear in it (as first operands of @code{insn_list}
expressions).  Their order is not significant.

This list is originally set up by the flow analysis pass; it is a null
pointer until then.  Flow only adds links for those data dependencies
which can be used for instruction combination.  For each insn, the flow
analysis pass adds a link to insns which store into registers values
that are used for the first time in this insn.  The instruction
scheduling pass adds extra links so that every dependence will be
represented.  Links represent data dependencies, antidependencies and
output dependencies; the machine mode of the link distinguishes these
three types: antidependencies have mode @code{REG_DEP_ANTI}, output
dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
mode @code{VOIDmode}.

The @code{REG_NOTES} field of an insn is a chain similar to the
@code{LOG_LINKS} field but it includes @code{expr_list} expressions in
addition to @code{insn_list} expressions.  There are several kinds of
register notes, which are distinguished by the machine mode, which in a
register note is really understood as being an @code{enum reg_note}.
The first operand @var{op} of the note is data whose meaning depends on
the kind of note.

@findex REG_NOTE_KIND
@findex PUT_REG_NOTE_KIND
The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
register note.  Its counterpart, the macro @code{PUT_REG_NOTE_KIND
(@var{x}, @var{newkind})} sets the register note type of @var{x} to be
@var{newkind}.

Register notes are of three classes: They may say something about an
input to an insn, they may say something about an output of an insn, or
they may create a linkage between two insns.  There are also a set
of values that are only used in @code{LOG_LINKS}.

These register notes annotate inputs to an insn:

@table @code
@findex REG_DEAD 
@item REG_DEAD
The value in @var{op} dies in this insn; that is to say, altering the
value immediately after this insn would not affect the future behavior
of the program.  

This does not necessarily mean that the register @var{op} has no useful
value after this insn since it may also be an output of the insn.  In
such a case, however, a @code{REG_DEAD} note would be redundant and is
usually not present until after the reload pass, but no code relies on
this fact.

@findex REG_INC
@item REG_INC
The register @var{op} is incremented (or decremented; at this level
there is no distinction) by an embedded side effect inside this insn.
This means it appears in a @code{post_inc}, @code{pre_inc},
@code{post_dec} or @code{pre_dec} expression.

@findex REG_NONNEG
@item REG_NONNEG
The register @var{op} is known to have a nonnegative value when this
insn is reached.  This is used so that decrement and branch until zero
instructions, such as the m68k dbra, can be matched.

The @code{REG_NONNEG} note is added to insns only if the machine
description has a @samp{decrement_and_branch_until_zero} pattern.

@findex REG_NO_CONFLICT
@item REG_NO_CONFLICT
This insn does not cause a conflict between @var{op} and the item
being set by this insn even though it might appear that it does.
In other words, if the destination register and @var{op} could
otherwise be assigned the same register, this insn does not
prevent that assignment.

Insns with this note are usually part of a block that begins with a
@code{clobber} insn specifying a multi-word pseudo register (which will
be the output of the block), a group of insns that each set one word of
the value and have the @code{REG_NO_CONFLICT} note attached, and a final
insn that copies the output to itself with an attached @code{REG_EQUAL}
note giving the expression being computed.  This block is encapsulated
with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
last insns, respectively.

@findex REG_LABEL
@item REG_LABEL
This insn uses @var{op}, a @code{code_label}, but is not a
@code{jump_insn}.  The presence of this note allows jump optimization to
be aware that @var{op} is, in fact, being used.
@end table

The following notes describe attributes of outputs of an insn:

@table @code
@findex REG_EQUIV
@findex REG_EQUAL
@item REG_EQUIV
@itemx REG_EQUAL
This note is only valid on an insn that sets only one register and
indicates that that register will be equal to @var{op} at run time; the
scope of this equivalence differs between the two types of notes.  The
value which the insn explicitly copies into the register may look
different from @var{op}, but they will be equal at run time.  If the
output of the single @code{set} is a @code{strict_low_part} expression,
the note refers to the register that is contained in @code{SUBREG_REG}
of the @code{subreg} expression.
 
For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
the entire function, and could validly be replaced in all its
occurrences by @var{op}.  (``Validly'' here refers to the data flow of
the program; simple replacement may make some insns invalid.)  For
example, when a constant is loaded into a register that is never
assigned any other value, this kind of note is used.

When a parameter is copied into a pseudo-register at entry to a function,
a note of this kind records that the register is equivalent to the stack
slot where the parameter was passed.  Although in this case the register
may be set by other insns, it is still valid to replace the register
by the stack slot throughout the function.

A @code{REG_EQUIV} note is also used on an instruction which copies a
register parameter into a pseudo-register at entry to a function, if
there is a stack slot where that parameter could be stored.  Although
other insns may set the pseudo-register, it is valid for the compiler to
replace the pseudo-register by stack slot throughout the function,
provided the compiler ensures that the stack slot is properly
initialized by making the replacement in the initial copy instruction as
well.  This is used on machines for which the calling convention
allocates stack space for register parameters.  See
@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.

In the case of @code{REG_EQUAL}, the register that is set by this insn
will be equal to @var{op} at run time at the end of this insn but not
necessarily elsewhere in the function.  In this case, @var{op}
is typically an arithmetic expression.  For example, when a sequence of
insns such as a library call is used to perform an arithmetic operation,
this kind of note is attached to the insn that produces or copies the
final value.

These two notes are used in different ways by the compiler passes.
@code{REG_EQUAL} is used by passes prior to register allocation (such as
common subexpression elimination and loop optimization) to tell them how
to think of that value.  @code{REG_EQUIV} notes are used by register
allocation to indicate that there is an available substitute expression
(either a constant or a @code{mem} expression for the location of a
parameter on the stack) that may be used in place of a register if
insufficient registers are available.

Except for stack homes for parameters, which are indicated by a
@code{REG_EQUIV} note and are not useful to the early optimization
passes and pseudo registers that are equivalent to a memory location
throughout there entire life, which is not detected until later in
the compilation, all equivalences are initially indicated by an attached
@code{REG_EQUAL} note.  In the early stages of register allocation, a
@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
@var{op} is a constant and the insn represents the only set of its
destination register.

Thus, compiler passes prior to register allocation need only check for
@code{REG_EQUAL} notes and passes subsequent to register allocation
need only check for @code{REG_EQUIV} notes.

@findex REG_UNUSED
@item REG_UNUSED
The register @var{op} being set by this insn will not be used in a
subsequent insn.  This differs from a @code{REG_DEAD} note, which
indicates that the value in an input will not be used subsequently.
These two notes are independent; both may be present for the same
register.

@findex REG_WAS_0
@item REG_WAS_0
The single output of this insn contained zero before this insn.
@var{op} is the insn that set it to zero.  You can rely on this note if
it is present and @var{op} has not been deleted or turned into a @code{note};
its absence implies nothing.
@end table

These notes describe linkages between insns.  They occur in pairs: one
insn has one of a pair of notes that points to a second insn, which has
the inverse note pointing back to the first insn.

@table @code
@findex REG_RETVAL
@item REG_RETVAL
This insn copies the value of a multi-insn sequence (for example, a
library call), and @var{op} is the first insn of the sequence (for a
library call, the first insn that was generated to set up the arguments
for the library call).

Loop optimization uses this note to treat such a sequence as a single
operation for code motion purposes and flow analysis uses this note to
delete such sequences whose results are dead.

A @code{REG_EQUAL} note will also usually be attached to this insn to 
provide the expression being computed by the sequence.

These notes will be deleted after reload, since they are no longer
accurate or useful.

@findex REG_LIBCALL
@item REG_LIBCALL
This is the inverse of @code{REG_RETVAL}: it is placed on the first
insn of a multi-insn sequence, and it points to the last one.

These notes are deleted after reload, since they are no longer useful or 
accurate.

@findex REG_CC_SETTER
@findex REG_CC_USER
@item REG_CC_SETTER
@itemx REG_CC_USER
On machines that use @code{cc0}, the insns which set and use @code{cc0}
set and use @code{cc0} are adjacent.  However, when branch delay slot
filling is done, this may no longer be true.  In this case a
@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
be placed on the insn using @code{cc0} to point to the insn setting
@code{cc0}.@refill
@end table

These values are only used in the @code{LOG_LINKS} field, and indicate
the type of dependency that each link represents.  Links which indicate
a data dependence (a read after write dependence) do not use any code,
they simply have mode @code{VOIDmode}, and are printed without any
descriptive text.

@table @code
@findex REG_DEP_ANTI
@item REG_DEP_ANTI
This indicates an anti dependence (a write after read dependence).

@findex REG_DEP_OUTPUT
@item REG_DEP_OUTPUT
This indicates an output dependence (a write after write dependence).
@end table

These notes describe information gathered from gcov profile data.  They
are stored in the @code{REG_NOTES} field of an insn as an
@code{expr_list}.

@table @code
@findex REG_EXEC_COUNT
@item REG_EXEC_COUNT
This is used to indicate the number of times a basic block was executed
according to the profile data.  The note is attached to the first insn in
the basic block.

@findex REG_BR_PROB
@item REG_BR_PROB
This is used to specify the ratio of branches to non-branches of a
branch insn according to the profile data.  The value is stored as a
value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
probability that the branch will be taken.

@findex REG_BR_PRED
@item REG_BR_PRED
These notes are found in JUMP insns after delayed branch scheduling
has taken place.  They indicate both the direction and the likelyhood
of the JUMP.  The format is a bitmask of ATTR_FLAG_* values.

@findex REG_FRAME_RELATED_EXPR
@item REG_FRAME_RELATED_EXPR
This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
is used in place of the actual insn pattern.  This is done in cases where
the pattern is either complex or misleading.
@end table

For convenience, the machine mode in an @code{insn_list} or
@code{expr_list} is printed using these symbolic codes in debugging dumps.

@findex insn_list
@findex expr_list
The only difference between the expression codes @code{insn_list} and
@code{expr_list} is that the first operand of an @code{insn_list} is
assumed to be an insn and is printed in debugging dumps as the insn's
unique id; the first operand of an @code{expr_list} is printed in the
ordinary way as an expression.

@node Calls, Sharing, Insns, RTL
@section RTL Representation of Function-Call Insns
@cindex calling functions in RTL
@cindex RTL function-call insns
@cindex function-call insns

Insns that call subroutines have the RTL expression code @code{call_insn}.
These insns must satisfy special rules, and their bodies must use a special
RTL expression code, @code{call}.

@cindex @code{call} usage
A @code{call} expression has two operands, as follows:

@example
(call (mem:@var{fm} @var{addr}) @var{nbytes})
@end example

@noindent
Here @var{nbytes} is an operand that represents the number of bytes of
argument data being passed to the subroutine, @var{fm} is a machine mode
(which must equal as the definition of the @code{FUNCTION_MODE} macro in
the machine description) and @var{addr} represents the address of the
subroutine.

For a subroutine that returns no value, the @code{call} expression as
shown above is the entire body of the insn, except that the insn might
also contain @code{use} or @code{clobber} expressions.

@cindex @code{BLKmode}, and function return values
For a subroutine that returns a value whose mode is not @code{BLKmode},
the value is returned in a hard register.  If this register's number is
@var{r}, then the body of the call insn looks like this:

@example
(set (reg:@var{m} @var{r})
     (call (mem:@var{fm} @var{addr}) @var{nbytes}))
@end example

@noindent
This RTL expression makes it clear (to the optimizer passes) that the
appropriate register receives a useful value in this insn.

When a subroutine returns a @code{BLKmode} value, it is handled by
passing to the subroutine the address of a place to store the value.
So the call insn itself does not ``return'' any value, and it has the
same RTL form as a call that returns nothing.

On some machines, the call instruction itself clobbers some register,
for example to contain the return address.  @code{call_insn} insns
on these machines should have a body which is a @code{parallel}
that contains both the @code{call} expression and @code{clobber}
expressions that indicate which registers are destroyed.  Similarly,
if the call instruction requires some register other than the stack
pointer that is not explicitly mentioned it its RTL, a @code{use}
subexpression should mention that register.

Functions that are called are assumed to modify all registers listed in
the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
Basics}) and, with the exception of @code{const} functions and library
calls, to modify all of memory.

Insns containing just @code{use} expressions directly precede the
@code{call_insn} insn to indicate which registers contain inputs to the
function.  Similarly, if registers other than those in
@code{CALL_USED_REGISTERS} are clobbered by the called function, insns
containing a single @code{clobber} follow immediately after the call to
indicate which registers.

@node Sharing
@section Structure Sharing Assumptions
@cindex sharing of RTL components
@cindex RTL structure sharing assumptions

The compiler assumes that certain kinds of RTL expressions are unique;
there do not exist two distinct objects representing the same value.
In other cases, it makes an opposite assumption: that no RTL expression
object of a certain kind appears in more than one place in the
containing structure.

These assumptions refer to a single function; except for the RTL
objects that describe global variables and external functions,
and a few standard objects such as small integer constants,
no RTL objects are common to two functions.

@itemize @bullet
@cindex @code{reg}, RTL sharing
@item
Each pseudo-register has only a single @code{reg} object to represent it,
and therefore only a single machine mode.

@cindex symbolic label
@cindex @code{symbol_ref}, RTL sharing
@item
For any symbolic label, there is only one @code{symbol_ref} object
referring to it.

@cindex @code{const_int}, RTL sharing
@item
There is only one @code{const_int} expression with value 0, only
one with value 1, and only one with value @minus{}1.
Some other integer values are also stored uniquely.

@cindex @code{pc}, RTL sharing
@item
There is only one @code{pc} expression.

@cindex @code{cc0}, RTL sharing
@item
There is only one @code{cc0} expression.

@cindex @code{const_double}, RTL sharing
@item
There is only one @code{const_double} expression with value 0 for
each floating point mode.  Likewise for values 1 and 2.

@cindex @code{label_ref}, RTL sharing
@cindex @code{scratch}, RTL sharing
@item
No @code{label_ref} or @code{scratch} appears in more than one place in
the RTL structure; in other words, it is safe to do a tree-walk of all
the insns in the function and assume that each time a @code{label_ref}
or @code{scratch} is seen it is distinct from all others that are seen.

@cindex @code{mem}, RTL sharing
@item
Only one @code{mem} object is normally created for each static
variable or stack slot, so these objects are frequently shared in all
the places they appear.  However, separate but equal objects for these
variables are occasionally made.

@cindex @code{asm_operands}, RTL sharing
@item
When a single @code{asm} statement has multiple output operands, a
distinct @code{asm_operands} expression is made for each output operand.
However, these all share the vector which contains the sequence of input
operands.  This sharing is used later on to test whether two
@code{asm_operands} expressions come from the same statement, so all
optimizations must carefully preserve the sharing if they copy the
vector at all.

@item
No RTL object appears in more than one place in the RTL structure
except as described above.  Many passes of the compiler rely on this
by assuming that they can modify RTL objects in place without unwanted
side-effects on other insns.

@findex unshare_all_rtl
@item
During initial RTL generation, shared structure is freely introduced.
After all the RTL for a function has been generated, all shared
structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
after which the above rules are guaranteed to be followed.

@findex copy_rtx_if_shared
@item
During the combiner pass, shared structure within an insn can exist
temporarily.  However, the shared structure is copied before the
combiner is finished with the insn.  This is done by calling
@code{copy_rtx_if_shared}, which is a subroutine of
@code{unshare_all_rtl}.
@end itemize

@node Reading RTL
@section Reading RTL

To read an RTL object from a file, call @code{read_rtx}.  It takes one
argument, a stdio stream, and returns a single RTL object.

Reading RTL from a file is very slow.  This is not currently a
problem since reading RTL occurs only as part of building the
compiler.

People frequently have the idea of using RTL stored as text in a file as
an interface between a language front end and the bulk of GNU CC.  This
idea is not feasible.

GNU CC was designed to use RTL internally only.  Correct RTL for a given
program is very dependent on the particular target machine.  And the RTL
does not contain all the information about the program.

The proper way to interface GNU CC to a new language front end is with
the ``tree'' data structure.  There is no manual for this data
structure, but it is described in the files @file{tree.h} and
@file{tree.def}.