Unified · Split
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,661 @@ | ||
| 1 | +limbo .sbl 2.1 | |
| 2 | +Authproto | |
| 3 | +8 | |
| 4 | +authquery.b | |
| 5 | +sys.m | |
| 6 | +draw.m | |
| 7 | +keyring.m | |
| 8 | +bufio.m | |
| 9 | +sexprs.m | |
| 10 | +spki.m | |
| 11 | +authio.m | |
| 12 | +400 | |
| 13 | +55.1,11 0 | |
| 14 | +56.1,25 1 | |
| 15 | +57.1,28 2 | |
| 16 | +58.1,13 3 | |
| 17 | +1,13 3 | |
| 18 | +59.1,34 4 | |
| 19 | +60.1,15 5 | |
| 20 | +1,15 5 | |
| 21 | +61.8,11 6 | |
| 22 | +1,11 6 | |
| 23 | +66.6,40 7 | |
| 24 | +26,31 7 | |
| 25 | +33,39 7 | |
| 26 | +6,40 7 | |
| 27 | +6,40 7 | |
| 28 | +6,40 7 | |
| 29 | +68.9,26 8 | |
| 30 | +16,21 8 | |
| 31 | +23,25 8 | |
| 32 | +9,26 8 | |
| 33 | +9,26 8 | |
| 34 | +2,26 8 | |
| 35 | +70.9,26 9 | |
| 36 | +16,21 9 | |
| 37 | +23,25 9 | |
| 38 | +9,26 9 | |
| 39 | +9,26 9 | |
| 40 | +2,26 9 | |
| 41 | +72.9,23 10 | |
| 42 | +2,23 10 | |
| 43 | +78.32,67 11 | |
| 44 | +52,57 11 | |
| 45 | +59,66 11 | |
| 46 | +32,67 11 | |
| 47 | +32,67 11 | |
| 48 | +21,68 11 | |
| 49 | +21,68 11 | |
| 50 | +21,68 12 | |
| 51 | +21,68 11 | |
| 52 | +21,68 11 | |
| 53 | +2,6 11 | |
| 54 | +13,16 11 | |
| 55 | +13,16 13 | |
| 56 | +13,16 14 | |
| 57 | +13,16 15 | |
| 58 | +79.4,15 16 | |
| 59 | +19,29 16 | |
| 60 | +80.49,84 17 | |
| 61 | +69,74 17 | |
| 62 | +76,83 17 | |
| 63 | +49,84 17 | |
| 64 | +49,84 17 | |
| 65 | +8,90 17 | |
| 66 | +20,47 17 | |
| 67 | +20,47 17 | |
| 68 | +20,47 18 | |
| 69 | +86,89 17 | |
| 70 | +8,90 17 | |
| 71 | +8,90 17 | |
| 72 | +2,90 17 | |
| 73 | +82.12,23 19 | |
| 74 | +12,16 19 | |
| 75 | +12,23 19 | |
| 76 | +12,23 19 | |
| 77 | +2,24 19 | |
| 78 | +8,10 19 | |
| 79 | +8,10 19 | |
| 80 | +8,10 20 | |
| 81 | +2,24 19 | |
| 82 | +83.16,39 21 | |
| 83 | +26,38 21 | |
| 84 | +26,38 21 | |
| 85 | +26,38 21 | |
| 86 | +26,38 21 | |
| 87 | +35,37 21 | |
| 88 | +26,38 21 | |
| 89 | +26,38 22 | |
| 90 | +26,38 21 | |
| 91 | +26,38 21 | |
| 92 | +26,38 21 | |
| 93 | +16,39 21 | |
| 94 | +16,39 21 | |
| 95 | +16,39 21 | |
| 96 | +16,39 21 | |
| 97 | +16,39 21 | |
| 98 | +16,39 21 | |
| 99 | +16,39 21 | |
| 100 | +16,39 21 | |
| 101 | +16,39 21 | |
| 102 | +16,39 21 | |
| 103 | +16,39 21 | |
| 104 | +3,7 21 | |
| 105 | +9,12 21 | |
| 106 | +9,12 23 | |
| 107 | +9,12 24 | |
| 108 | +84.5,15 25 | |
| 109 | +85.10,38 26 | |
| 110 | +3,38 26 | |
| 111 | +86.5,16 27 | |
| 112 | +87.10,32 28 | |
| 113 | +3,32 28 | |
| 114 | +88.5,14 29 | |
| 115 | +5,9 29 | |
| 116 | +5,14 29 | |
| 117 | +5,14 29 | |
| 118 | +5,28 29 | |
| 119 | +5,6 30 | |
| 120 | +89.11,51 31 | |
| 121 | +24,27 31 | |
| 122 | +29,32 31 | |
| 123 | +34,37 31 | |
| 124 | +39,50 31 | |
| 125 | +39,43 31 | |
| 126 | +39,50 31 | |
| 127 | +39,50 31 | |
| 128 | +3,52 31 | |
| 129 | +3,5 31 | |
| 130 | +3,5 31 | |
| 131 | +3,5 32 | |
| 132 | +3,52 31 | |
| 133 | +90.10,13 33 | |
| 134 | +3,13 33 | |
| 135 | +92.16,34 34 | |
| 136 | +16,34 34 | |
| 137 | +16,34 34 | |
| 138 | +16,34 34 | |
| 139 | +16,34 34 | |
| 140 | +16,34 34 | |
| 141 | +16,34 34 | |
| 142 | +16,34 34 | |
| 143 | +16,34 34 | |
| 144 | +16,34 34 | |
| 145 | +16,17 35 | |
| 146 | +16,17 36 | |
| 147 | +16,34 34 | |
| 148 | +16,34 37 | |
| 149 | +16,34 34 | |
| 150 | +3,7 34 | |
| 151 | +9,12 34 | |
| 152 | +9,12 38 | |
| 153 | +9,12 39 | |
| 154 | +93.5,16 40 | |
| 155 | +94.10,36 41 | |
| 156 | +3,36 41 | |
| 157 | +100.16,39 42 | |
| 158 | +26,38 42 | |
| 159 | +26,38 42 | |
| 160 | +26,38 42 | |
| 161 | +26,38 42 | |
| 162 | +35,37 42 | |
| 163 | +26,38 42 | |
| 164 | +26,38 43 | |
| 165 | +26,38 42 | |
| 166 | +26,38 42 | |
| 167 | +26,38 42 | |
| 168 | +16,39 42 | |
| 169 | +16,39 42 | |
| 170 | +16,39 42 | |
| 171 | +16,39 42 | |
| 172 | +16,39 42 | |
| 173 | +16,39 42 | |
| 174 | +16,39 42 | |
| 175 | +16,39 42 | |
| 176 | +16,39 42 | |
| 177 | +16,39 42 | |
| 178 | +16,39 42 | |
| 179 | +101.4,14 44 | |
| 180 | +102.9,42 45 | |
| 181 | +2,42 45 | |
| 182 | +104.12,29 46 | |
| 183 | +24,28 46 | |
| 184 | +12,29 46 | |
| 185 | +12,29 46 | |
| 186 | +2,3 46 | |
| 187 | +5,8 46 | |
| 188 | +5,8 47 | |
| 189 | +5,8 48 | |
| 190 | +105.4,12 49 | |
| 191 | +106.9,37 50 | |
| 192 | +2,37 50 | |
| 193 | +107.7,30 51 | |
| 194 | +15,16 51 | |
| 195 | +7,30 51 | |
| 196 | +7,30 51 | |
| 197 | +7,30 51 | |
| 198 | +7,37 51 | |
| 199 | +7,8 52 | |
| 200 | +108.12,23 53 | |
| 201 | +12,16 53 | |
| 202 | +12,23 53 | |
| 203 | +12,23 53 | |
| 204 | +2,24 53 | |
| 205 | +8,10 53 | |
| 206 | +8,10 53 | |
| 207 | +8,10 54 | |
| 208 | +2,24 53 | |
| 209 | +109.16,39 55 | |
| 210 | +26,38 55 | |
| 211 | +26,38 55 | |
| 212 | +26,38 55 | |
| 213 | +26,38 55 | |
| 214 | +35,37 55 | |
| 215 | +26,38 55 | |
| 216 | +26,38 56 | |
| 217 | +26,38 55 | |
| 218 | +26,38 55 | |
| 219 | +26,38 55 | |
| 220 | +16,39 55 | |
| 221 | +16,39 55 | |
| 222 | +16,39 55 | |
| 223 | +16,39 55 | |
| 224 | +16,39 55 | |
| 225 | +16,39 55 | |
| 226 | +16,39 55 | |
| 227 | +16,39 55 | |
| 228 | +16,39 55 | |
| 229 | +16,39 55 | |
| 230 | +16,39 55 | |
| 231 | +110.5,15 57 | |
| 232 | +111.10,42 58 | |
| 233 | +3,42 58 | |
| 234 | +112.5,28 59 | |
| 235 | +12,13 59 | |
| 236 | +22,26 59 | |
| 237 | +5,28 59 | |
| 238 | +5,28 59 | |
| 239 | +5,28 59 | |
| 240 | +5,35 59 | |
| 241 | +5,6 60 | |
| 242 | +113.10,53 61 | |
| 243 | +3,53 61 | |
| 244 | +115.12,29 62 | |
| 245 | +12,22 62 | |
| 246 | +12,22 62 | |
| 247 | +12,22 62 | |
| 248 | +12,22 62 | |
| 249 | +12,22 62 | |
| 250 | +12,22 62 | |
| 251 | +12,22 62 | |
| 252 | +12,22 62 | |
| 253 | +12,22 62 | |
| 254 | +12,13 63 | |
| 255 | +12,13 64 | |
| 256 | +12,22 62 | |
| 257 | +12,22 65 | |
| 258 | +12,29 62 | |
| 259 | +12,29 62 | |
| 260 | +1,30 62 | |
| 261 | +7,9 62 | |
| 262 | +7,9 62 | |
| 263 | +7,9 66 | |
| 264 | +1,30 62 | |
| 265 | +116.1,22 67 | |
| 266 | +1,3 67 | |
| 267 | +9,21 67 | |
| 268 | +1,22 67 | |
| 269 | +117.8,11 68 | |
| 270 | +1,11 68 | |
| 271 | +133.7,14 69 | |
| 272 | +7,23 69 | |
| 273 | +134.2,33 70 | |
| 274 | +2,4 70 | |
| 275 | +11,14 70 | |
| 276 | +11,24 70 | |
| 277 | +26,32 70 | |
| 278 | +2,33 70 | |
| 279 | +2,33 70 | |
| 280 | +135.2,20 71 | |
| 281 | +2,20 71 | |
| 282 | +2,20 71 | |
| 283 | +137.1,23 72 | |
| 284 | +1,3 72 | |
| 285 | +10,13 72 | |
| 286 | +15,22 72 | |
| 287 | +1,23 72 | |
| 288 | +1,23 72 | |
| 289 | +138.0,1 73 | |
| 290 | +142.5,18 74 | |
| 291 | +5,9 74 | |
| 292 | +5,18 74 | |
| 293 | +5,18 74 | |
| 294 | +5,18 74 | |
| 295 | +143.10,13 75 | |
| 296 | +15,37 75 | |
| 297 | +2,38 75 | |
| 298 | +144.9,41 76 | |
| 299 | +19,23 76 | |
| 300 | +25,35 76 | |
| 301 | +25,29 76 | |
| 302 | +25,35 76 | |
| 303 | +25,35 76 | |
| 304 | +37,40 76 | |
| 305 | +9,41 76 | |
| 306 | +9,41 77 | |
| 307 | +43,46 76 | |
| 308 | +1,47 76 | |
| 309 | +149.4,18 78 | |
| 310 | +150.9,12 79 | |
| 311 | +2,12 79 | |
| 312 | +151.1,16 80 | |
| 313 | +152.1,21 81 | |
| 314 | +153.4,10 82 | |
| 315 | +4,5 82 | |
| 316 | +4,10 82 | |
| 317 | +4,10 82 | |
| 318 | +4,20 82 | |
| 319 | +4,5 83 | |
| 320 | +154.9,12 84 | |
| 321 | +2,12 84 | |
| 322 | +155.5,18 85 | |
| 323 | +10,11 85 | |
| 324 | +5,18 85 | |
| 325 | +5,18 85 | |
| 326 | +20,28 86 | |
| 327 | +156.5,16 87 | |
| 328 | +5,11 87 | |
| 329 | +5,16 87 | |
| 330 | +5,16 87 | |
| 331 | +5,27 87 | |
| 332 | +5,6 88 | |
| 333 | +31,44 87 | |
| 334 | +31,37 87 | |
| 335 | +31,44 87 | |
| 336 | +31,44 87 | |
| 337 | +31,51 87 | |
| 338 | +31,32 89 | |
| 339 | +157.22,35 90 | |
| 340 | +22,28 90 | |
| 341 | +22,35 90 | |
| 342 | +22,35 90 | |
| 343 | +18,36 90 | |
| 344 | +18,45 90 | |
| 345 | +18,45 90 | |
| 346 | +18,45 91 | |
| 347 | +18,45 90 | |
| 348 | +18,45 90 | |
| 349 | +14,45 90 | |
| 350 | +18,19 92 | |
| 351 | +3,46 90 | |
| 352 | +3,46 90 | |
| 353 | +3,46 90 | |
| 354 | +3,46 90 | |
| 355 | +155.30,38 93 | |
| 356 | +30,38 93 | |
| 357 | +158.8,34 94 | |
| 358 | +8,34 94 | |
| 359 | +8,34 94 | |
| 360 | +8,34 94 | |
| 361 | +13,23 94 | |
| 362 | +8,34 94 | |
| 363 | +30,33 94 | |
| 364 | +25,33 94 | |
| 365 | +8,34 94 | |
| 366 | +8,34 94 | |
| 367 | +8,9 95 | |
| 368 | +8,9 96 | |
| 369 | +8,34 94 | |
| 370 | +8,34 97 | |
| 371 | +1,34 94 | |
| 372 | +163.1,32 98 | |
| 373 | +164.8,11 99 | |
| 374 | +1,11 99 | |
| 375 | +179.13,22 100 | |
| 376 | +4,9 100 | |
| 377 | +4,22 100 | |
| 378 | +180.8,28 101 | |
| 379 | +16,20 101 | |
| 380 | +8,28 101 | |
| 381 | +8,28 101 | |
| 382 | +8,28 101 | |
| 383 | +8,35 101 | |
| 384 | +8,9 102 | |
| 385 | +39,46 101 | |
| 386 | +39,51 101 | |
| 387 | +181.3,24 103 | |
| 388 | +3,7 103 | |
| 389 | +17,23 103 | |
| 390 | +3,24 103 | |
| 391 | +3,24 103 | |
| 392 | +182.2,13 104 | |
| 393 | +183.2,11 105 | |
| 394 | +180.9,10 106 | |
| 395 | +185.1,8 107 | |
| 396 | +186.18,25 108 | |
| 397 | +18,25 108 | |
| 398 | +12,26 108 | |
| 399 | +8,26 108 | |
| 400 | +1,26 108 | |
| 401 | +191.4,16 109 | |
| 402 | +20,30 109 | |
| 403 | +192.9,11 110 | |
| 404 | +2,11 110 | |
| 405 | +193.1,8 111 | |
| 406 | +194.18,25 112 | |
| 407 | +18,25 112 | |
| 408 | +12,26 112 | |
| 409 | +8,26 112 | |
| 410 | +1,26 112 | |
| 411 | +199.8,17 113 | |
| 412 | +1,17 113 | |
| 413 | +16 | |
| 414 | +aSys->Dir 1:26.1,39.2 64 | |
| 415 | +11 | |
| 416 | +0:name:28.2,6 s | |
| 417 | +4:uid:29.2,5 s | |
| 418 | +8:gid:30.2,5 s | |
| 419 | +12:muid:31.2,6 s | |
| 420 | +16:qid:32.2,5 @1 | |
| 421 | + | |
| 422 | +32:mode:33.2,6 i | |
| 423 | +36:atime:34.2,7 i | |
| 424 | +40:mtime:35.2,7 i | |
| 425 | +48:length:36.2,8 B | |
| 426 | +56:dtype:37.2,7 i | |
| 427 | +60:dev:38.2,5 i | |
| 428 | +aSys->Qid 11.1,16.2 16 | |
| 429 | +3 | |
| 430 | +0:path:13.2,6 B | |
| 431 | +8:vers:14.2,6 i | |
| 432 | +12:qtype:15.2,7 i | |
| 433 | +aDraw->Chans 2:70.1,82.2 4 | |
| 434 | +1 | |
| 435 | +0:desc:72.2,6 i | |
| 436 | +aAuthio->Attr 7:6.1,12.2 12 | |
| 437 | +3 | |
| 438 | +0:tag:7.2,5 i | |
| 439 | +4:name:8.2,6 s | |
| 440 | +8:val:9.2,5 s | |
| 441 | +aAuthio->IO 45.1,58.2 8 | |
| 442 | +2 | |
| 443 | +0:f:46.2,3 R@5 | |
| 444 | + | |
| 445 | +4:rpc:47.2,5 R@9 | |
| 446 | + | |
| 447 | +aAuthio->Fid 24.1,35.2 32 | |
| 448 | +8 | |
| 449 | +0:fid:26.2,5 i | |
| 450 | +4:pid:27.2,5 i | |
| 451 | +8:err:28.2,5 s | |
| 452 | +12:attrs:29.2,7 LR@3 | |
| 453 | + | |
| 454 | +16:write:30.2,7 Ct8.2 | |
| 455 | +0:t0:18,31 Ab | |
| 456 | +4:t1:18,31 @6 | |
| 457 | + | |
| 458 | + | |
| 459 | +20:read:31.2,6 Ct8.2 | |
| 460 | +0:t0:17,20 i | |
| 461 | +4:t1:17,20 @7 | |
| 462 | + | |
| 463 | + | |
| 464 | +24:done:33.2,6 i | |
| 465 | +28:ai:34.2,4 R@8 | |
| 466 | + | |
| 467 | +Ct8.2 | |
| 468 | +0:t0:1:64.23,26 i | |
| 469 | +4:t1:23,26 s | |
| 470 | +Ct8.2 | |
| 471 | +0:t0:63.22,35 Ab | |
| 472 | +4:t1:22,35 s | |
| 473 | +aAuthio->Authinfo 7:61.1,66.2 16 | |
| 474 | +4 | |
| 475 | +0:cuid:62.2,6 s | |
| 476 | +4:suid:63.2,6 s | |
| 477 | +8:cap:64.2,5 s | |
| 478 | +12:secret:65.2,8 Ab | |
| 479 | +aAuthio->Rpc 37.1,43.2 20 | |
| 480 | +5 | |
| 481 | +0:r:38.2,3 R@5 | |
| 482 | + | |
| 483 | +4:cmd:39.2,5 i | |
| 484 | +8:arg:40.2,5 Ab | |
| 485 | +12:nbytes:41.2,8 i | |
| 486 | +16:rc:42.2,4 Ct8.2 | |
| 487 | +0:t0:15,28 Ab | |
| 488 | +4:t1:15,28 s | |
| 489 | + | |
| 490 | +pSexprs->Sexp 5:5.1,38.2 0 | |
| 491 | +0 | |
| 492 | +3 | |
| 493 | +String:7.2,8 12 | |
| 494 | +2 | |
| 495 | +4:s:8.3,4 s | |
| 496 | +8:hint:9.3,7 s | |
| 497 | +Binary:10.2,8 12 | |
| 498 | +2 | |
| 499 | +4:data:11.3,7 Ab | |
| 500 | +8:hint:12.3,7 s | |
| 501 | +List:13.2,6 8 | |
| 502 | +1 | |
| 503 | +4:l:14.3,4 LR@10 | |
| 504 | + | |
| 505 | +aQuery 0:27.0,36.1 12 | |
| 506 | +3 | |
| 507 | +0:e:28.1,2 R@10 | |
| 508 | + | |
| 509 | +4:certs:29.1,6 LR@10 | |
| 510 | + | |
| 511 | +8:gotcerts:30.1,9 LR@10 | |
| 512 | + | |
| 513 | +aRead 38.0,48.1 16 | |
| 514 | +4 | |
| 515 | +0:buf:39.1,4 Ab | |
| 516 | +4:ptr:40.1,4 i | |
| 517 | +8:off:41.1,4 i | |
| 518 | +12:io:42.1,3 R@4 | |
| 519 | + | |
| 520 | +pSexprs->Sexp 5:5.1,38.2 0 | |
| 521 | +0 | |
| 522 | +3 | |
| 523 | +String:7.2,8 12 | |
| 524 | +2 | |
| 525 | +4:s:8.3,4 s | |
| 526 | +8:hint:9.3,7 s | |
| 527 | +Binary:10.2,8 12 | |
| 528 | +2 | |
| 529 | +4:data:11.3,7 Ab | |
| 530 | +8:hint:12.3,7 s | |
| 531 | +List:13.2,6 8 | |
| 532 | +1 | |
| 533 | +4:l:14.3,4 LR@13 | |
| 534 | + | |
| 535 | +pSexprs->Sexp 5.1,38.2 0 | |
| 536 | +0 | |
| 537 | +3 | |
| 538 | +String:7.2,8 12 | |
| 539 | +2 | |
| 540 | +4:s:8.3,4 s | |
| 541 | +8:hint:9.3,7 s | |
| 542 | +Binary:10.2,8 12 | |
| 543 | +2 | |
| 544 | +4:data:11.3,7 Ab | |
| 545 | +8:hint:12.3,7 s | |
| 546 | +List:13.2,6 8 | |
| 547 | +1 | |
| 548 | +4:l:14.3,4 LR@14 | |
| 549 | + | |
| 550 | +pSexprs->Sexp 5.1,38.2 0 | |
| 551 | +0 | |
| 552 | +3 | |
| 553 | +String:7.2,8 12 | |
| 554 | +2 | |
| 555 | +4:s:8.3,4 s | |
| 556 | +8:hint:9.3,7 s | |
| 557 | +Binary:10.2,8 12 | |
| 558 | +2 | |
| 559 | +4:data:11.3,7 Ab | |
| 560 | +8:hint:12.3,7 s | |
| 561 | +List:13.2,6 8 | |
| 562 | +1 | |
| 563 | +4:l:14.3,4 LR@15 | |
| 564 | + | |
| 565 | +11 | |
| 566 | +0:init | |
| 567 | +1 | |
| 568 | +32:f:0:53.5,6 mAuthio | |
| 569 | +7:1.0,73.1 0 | |
| 570 | + | |
| 571 | +0 | |
| 572 | +s10:interaction | |
| 573 | +2 | |
| 574 | +32:attrs:0:64.12,17 LR@3 | |
| 575 | + | |
| 576 | +36:io:37,39 R@4 | |
| 577 | + | |
| 578 | +0 | |
| 579 | +s30:client | |
| 580 | +2 | |
| 581 | +32:attrs:76.7,12 LR@3 | |
| 582 | + | |
| 583 | +36:io:32,34 R@4 | |
| 584 | + | |
| 585 | +2 | |
| 586 | +40:sexp:78.2,6 R@10 | |
| 587 | + | |
| 588 | +44:err:13,16 s | |
| 589 | +s144:server | |
| 590 | +2 | |
| 591 | +32:attrs:98.7,12 LR@3 | |
| 592 | + | |
| 593 | +36:io:32,34 R@4 | |
| 594 | + | |
| 595 | +3 | |
| 596 | +40:sexp:100.2,6 R@14 | |
| 597 | + | |
| 598 | +44:err:8,11 s | |
| 599 | +48:q:103.1,2 R@11 | |
| 600 | + | |
| 601 | +s258:write | |
| 602 | +2 | |
| 603 | +32:io:131.6,8 R@4 | |
| 604 | + | |
| 605 | +36:buf:18,21 Ab | |
| 606 | +0 | |
| 607 | +n277:Query.parse | |
| 608 | +1 | |
| 609 | +32:sexp:140.12,16 R@10 | |
| 610 | + | |
| 611 | +0 | |
| 612 | +t8.2 | |
| 613 | +0:t0:30,39 R@11 | |
| 614 | + | |
| 615 | +4:t1:30,39 s | |
| 616 | +296:Query.neededcert | |
| 617 | +1 | |
| 618 | +32:q:147.17,18 R@11 | |
| 619 | + | |
| 620 | +2 | |
| 621 | +36:a:155.5,6 LR@10 | |
| 622 | + | |
| 623 | +40:c:151.1,2 R@10 | |
| 624 | + | |
| 625 | +R@10 | |
| 626 | +359:Query.addcert | |
| 627 | +2 | |
| 628 | +32:q:161.14,15 R@11 | |
| 629 | + | |
| 630 | +36:cert:33,37 R@10 | |
| 631 | + | |
| 632 | +0 | |
| 633 | +s362:Read.getb | |
| 634 | +1 | |
| 635 | +32:r:177.10,11 R@12 | |
| 636 | + | |
| 637 | +1 | |
| 638 | +36:buf:180.9,12 Ab | |
| 639 | +i388:Read.ungetb | |
| 640 | +1 | |
| 641 | +32:r:189.12,13 R@12 | |
| 642 | + | |
| 643 | +0 | |
| 644 | +i398:Read.offset | |
| 645 | +1 | |
| 646 | +32:r:197.12,13 R@12 | |
| 647 | + | |
| 648 | +0 | |
| 649 | +B4 | |
| 650 | +52:authio:15.1,7 mAuthio | |
| 651 | +7:1.0,73.1 0 | |
| 652 | + | |
| 653 | +116:sexprs:0:10.1,7 mSexprs | |
| 654 | +5:1.0,41.1 0 | |
| 655 | + | |
| 656 | +120:spki:0:13.1,5 mSPKI | |
| 657 | +6:26.0,211.1 0 | |
| 658 | + | |
| 659 | +124:sys:0:4.1,4 mSys | |
| 660 | +1:0,160.1 0 | |
| 661 | + | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,3 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | + | |
| 3 | +grid/register -a resource Camera -a name Y2K -a model 'Kodak DC260' -a 'Image resource' 1 {demo/camera/camera.dis -v 2 -p 0 -n Y2K -f /dis/demo/camera/tkinterface.dis -f /dis/demo/camera/readjpg.dis -f /dis/demo/camera/camload.bit -f /dis/demo/camera/camproc.bit} | |
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,20 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | +load std | |
| 3 | +autoload=std | |
| 4 | +ndb/cs | |
| 5 | + | |
| 6 | +chatroom=$1 | |
| 7 | + | |
| 8 | +fn ck { | |
| 9 | + or {$*} { | |
| 10 | + echo chatclient: exiting >[1=2] | |
| 11 | + raise error | |
| 12 | + } | |
| 13 | +} | |
| 14 | +user="{cat /dev/user} | |
| 15 | + | |
| 16 | +ck mount -A 'tcp!$registry!registry' /mnt/registry | |
| 17 | +ck /dis/grid/remotelogon wm/wm { | |
| 18 | + k = /usr/$user/keyring/default | |
| 19 | + grid/find -a resource chat -a pk `{getpk -s $k} Enter {demo/chat/chat /n/client} Shell {wm/sh} | |
| 20 | +} | |
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,50 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | +fn bindfs { | |
| 3 | + # this may be useful as a general purpose cmd | |
| 4 | + (mntpt dirs)=$* | |
| 5 | + memfs $mntpt | |
| 6 | + for d in $dirs { | |
| 7 | + parts=${split / $d} | |
| 8 | + fpath='' | |
| 9 | + for p in $parts { | |
| 10 | + fpath=$fpath^/^$p | |
| 11 | + if {! ftest -e $mntpt^$fpath} { | |
| 12 | + if {ftest -d $fpath} { | |
| 13 | + mkdir $mntpt^$fpath | |
| 14 | + } { | |
| 15 | + if {! ftest -e $fpath} { | |
| 16 | + echo $fpath does not exist >[1=2] | |
| 17 | + raise 'fail:errors' | |
| 18 | + } | |
| 19 | + } | |
| 20 | + } | |
| 21 | + } | |
| 22 | + if {! ftest -d $d} { | |
| 23 | + touch $mntpt/$d | |
| 24 | + } | |
| 25 | + bind $d $mntpt^$d | |
| 26 | + } | |
| 27 | +} | |
| 28 | + | |
| 29 | +fn x { | |
| 30 | + echo tcp!^$2 | |
| 31 | +} | |
| 32 | + | |
| 33 | +bindfs /tmp /dis /n/client /dev /prog | |
| 34 | +listen -A `{x `{ndb/csquery tcp!^`{cat /dev/sysname}^!rstyx}} { | |
| 35 | + @{ | |
| 36 | + load std | |
| 37 | + pctl forkns nodevs | |
| 38 | + bind /tmp / | |
| 39 | + runas rstyx {auxi/rstyxd} | |
| 40 | + }& | |
| 41 | + } | |
| 42 | + | |
| 43 | +while {} { | |
| 44 | + demo/cpupool/regpoll tcp!200.1.1.104!6676 up | |
| 45 | + echo Registering Rstyx service | |
| 46 | + mount -A 'tcp!200.1.1.104!6676' /mnt/registry | |
| 47 | + echo `{x `{ndb/csquery tcp!^`{cat /dev/sysname}^!rstyx}} proto styx auth none persist 1 resource '''Rstyx resource''' name `{cat /dev/sysname} > /mnt/registry/new | |
| 48 | + demo/cpupool/regpoll tcp!200.1.1.104!6676 down | |
| 49 | + echo Registry gone down | |
| 50 | +} | |
Binary file not shown.
| @@ -0,0 +1,17 @@ | ||
| 1 | +#!/dis/sh.dis | |
| 2 | +load std | |
| 3 | + | |
| 4 | +port=$1 | |
| 5 | +DIR=/dis/demo/lego | |
| 6 | +pctl forkns newpgrp | |
| 7 | + | |
| 8 | +cd $DIR | |
| 9 | +if { firmdl $port /dis/demo/lego/styx.srec } { | |
| 10 | + legolink $port | |
| 11 | + memfs /tmp | |
| 12 | + cd /tmp | |
| 13 | + mount -o -A /net/legolink /n/remote | |
| 14 | + $DIR/clockface /n/remote | |
| 15 | + echo reset > clockface | |
| 16 | + grid/register -a resource Robot -a name 'Lego Clock' {export /tmp} | |
| 17 | +} | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,329 @@ | ||
| 1 | +S00C0000737479782E7372656340 | |
| 2 | +S11880006DF06DF16DF26DF35E00967E6D736D726D716D7054AD | |
| 3 | +S118801570446F20796F7520627974652C207768656E20492057 | |
| 4 | +S10B802A6B6E6F636B3F0000F5 | |
| 5 | +S11880326DF60D761B870D621B8279014000790029F25E00965F | |
| 6 | +S1188047AC6B039A0A6F62FFFE1D23470819226B829A084012E9 | |
| 7 | +S118805C6B039A08790200091D234E060B036B839A086F61FF76 | |
| 8 | +S1188071FE6B819A0A6B039A08790200097900FFFF1D234F02CC | |
| 9 | +S11880860D100B876D7654706DF60D760D02790330026DF3790F | |
| 10 | +S118809B01301F79001FF25E0096BC0B87790027C85E0096D480 | |
| 11 | +S11880B06D7654706DF60D766DF40D047901300679001B625EB4 | |
| 12 | +S11880C50096DE0D405E00808E5E0080320D0046F86D746D7656 | |
| 13 | +S11880DA54706DF60D766DF40D041900684B473C0D1147380B7A | |
| 14 | +S11880EF040CBA8AD0AA09422E0CB8F00088D090FF1B01684BC7 | |
| 15 | +S118810447200D11471C0B040CBA8AD0AA0942120D0209220901 | |
| 16 | +S118811922092009000CBAF200092040D66D746D7654706DF617 | |
| 17 | +S118812E0D761B871B876DF46DF56FE0FFFE0D146FE0FFFC0DEA | |
| 18 | +S1188143444C16FA2D688A6F62FFFE0D230B036FE3FFFC170CE8 | |
| 19 | +S118815817040B040D444610FA306F63FFFC68BA0B036FE3FFC5 | |
| 20 | +S118816DFC404C790527101D454F407901000A0D505E0096EA0C | |
| 21 | +S11881820D051D454EF0402E0D510D405E0096EA0C8A8A306F7C | |
| 22 | +S118819763FFFC68BA0B036FE3FFFC0D510D405E0096FC0D0448 | |
| 23 | +S11881AC7901000A0D505E0096EA0D050D5546CE6F62FFFC6F38 | |
| 24 | +S11881C163FFFE19326FE2FFFC6F60FFFC6D756D740B870B87FD | |
| 25 | +S11881D66D7654706DF60D761B876DF46DF50D040D156FE2FF1B | |
| 26 | +S11881EBFE7900000A5E00972269846F8500026F62FFFE6F8241 | |
| 27 | +S118820000046F6200046F82000619226F8200086A0AA40A8AB5 | |
| 28 | +S1188215016A8AA40A6D756D740B876D7654706DF60D765E006D | |
| 29 | +S118822A979C6A0AA40A8AFF6A8AA40A6D7654706DF60D7669C5 | |
| 30 | +S118823F00790198885E008FD6790000016D7654706DF60D76C2 | |
| 31 | +S11882541B871B876DF46DF50D056FE1FFFE6FE2FFFC40266990 | |
| 32 | +S1188269546F61FFFC0D406F62FFFE5D200D00470E6F4200082A | |
| 33 | +S118827E69D20D405E0082244006790500080945695246D66DFD | |
| 34 | +S1188293756D740B870B876D7654706DF60D761B871B876DF426 | |
| 35 | +S11882A86DF56FE0FFFE6FE1FFFC19557904A3DC6F62FFFC6F1F | |
| 36 | +S11882BD61FFFE0D405E0082508C0E94000B05790200021D25D0 | |
| 37 | +S11882D24FE46D756D740B870B876D7654706DF60D7679030070 | |
| 38 | +S11882E70C19376DF46DF56FE2FFFE6F6400040D1147045A0077 | |
| 39 | +S11882FC83FE6E080002F00088F990FF6FE0FFFC6F65FFFC094E | |
| 40 | +S11883115509550955190509557902A3D009520D256F62FFFE7D | |
| 41 | +S118832646045A0083FE684BF300790200621D23470C79020088 | |
| 42 | +S118833B6C1D23470A5A0083FE79020060400219226FE2FFF8B1 | |
| 43 | +S11883500B046F63FFFE1B030D3346045A0083FE684AAA3E46D3 | |
| 44 | +S118836504FA014006AA3C460C18AA6EEAFFFB0B041B034006FB | |
| 45 | +S118837AFA016EEAFFFB0D3346045A0083FE7901823A0D50881D | |
| 46 | +S118838F0C900019226FE3FFF45E0082506F62FFFC8A00921091 | |
| 47 | +S11883A46FE2FFF66F61FFF6790019C45E0096DEFA0168DA6EE2 | |
| 48 | +S11883B96AFFF96EDA00016F63FFF40D310D405E0080DC6FD0B7 | |
| 49 | +S11883CE000A19226FD200026FD200046EDA0006FA016EDA0038 | |
| 50 | +S11883E3086E6AFFFB6EDA00096F61FFF6790019465E0096DEE7 | |
| 51 | +S11883F86F60FFFE40047900FFFF6D756D747903000C09376DED | |
| 52 | +S118840D7654706DF60D767903000619376DF46DF56FE0FFFE55 | |
| 53 | +S11884226FE1FFFC0D256F6400085E0090340D031D45443219C6 | |
| 54 | +S1188437546F6000041D0443046F6400046F62000609526FE243 | |
| 55 | +S118844C00060D300B800B000D426F6100066FE3FFFA5E0097D9 | |
| 56 | +S1188461AE6F63FFFA4002194468BC0D420C2A18226EBA0001DE | |
| 57 | +S118847618AA6EBA00020B840B046DF419226DF26F62FFFC6F2D | |
| 58 | +S118848B61FFFEF80F5E0090480B870B876D756D7479030006D4 | |
| 59 | +S11884A009376D7654706DF60D767903000C19376DF46DF56FEC | |
| 60 | +S11884B5E0FFF66FE1FFF40D257904FFF809646F6100060D4060 | |
| 61 | +S11884CA5E00812C6DF06DF46F6200046DF20D526F61FFF46F0B | |
| 62 | +S11884DF60FFF65E0084108F0697006D756D747903000C093786 | |
| 63 | +S11884F46D7654706DF60D766E0A0009471019116F0300046FFB | |
| 64 | +S118850902000A1D234514400E19116F0300046F02000A1D230B | |
| 65 | +S118851E4404790100010D106D7654706DF60D761B876DF46D67 | |
| 66 | +S1188533F56FE1FFFE0D256E0A0002F2008AF992FF0D240944BD | |
| 67 | +S118854809440944192409447902A3D009420D246E4A00084686 | |
| 68 | +S118855D067900FFFF404E0D405E0084F80D0047206F420004AA | |
| 69 | +S11885726DF26F6200066DF26F6200040D516F60FFFE5E00847A | |
| 70 | +S1188587A60B870B8740226F6200066DF26F6200040D516F6077 | |
| 71 | +S118859CFFFE5E0081DA6F42000C6F8200086FC0000C0B871974 | |
| 72 | +S11885B1006D756D740B876D7654706DF60D761B876DF46DF56A | |
| 73 | +S11885C67903A400683A4D045A008686EA7F68BA19440D4509E0 | |
| 74 | +S11885DB5509550955194509557902A3D009520D256E5A00086F | |
| 75 | +S11885F00D430B036FE3FFFE0CAA46045A0086768C0094100D32 | |
| 76 | +S1188605520D41790014C05E0096AC0D520D41790014C05E0077 | |
| 77 | +S118861A96AC0D520D41790014C05E0096AC0D520D4179001431 | |
| 78 | +S118862FC05E0096AC0D505E0084F80D00473840306F54000CD0 | |
| 79 | +S11886446F4200086FD2000C6F41000269406F5200046DF26F29 | |
| 80 | +S11886594200066DF26F4200045E0084A60D405E0082240B8741 | |
| 81 | +S118866E0B876F52000C46CA6F64FFFE790200021D244E045A4A | |
| 82 | +S11886830085D86D756D740B876D7654706DF60D766DF46DF5DC | |
| 83 | +S11886980D050D246F600004680BF300790200661D2347244E73 | |
| 84 | +S11886AD127902002D1D234750790200461D23472440327902CA | |
| 85 | +S11886C200721D23470E0B021D23470E4022790200014010794F | |
| 86 | +S11886D7020002400A7902000340047902000469926E0A000187 | |
| 87 | +S11886EC8AD0AA074304190040146E0A0001F2008AD092FF69F7 | |
| 88 | +S1188701C2FA0168DA790000016D756D746D7654706DF60D7696 | |
| 89 | +S11887167903001A19376DF46DF56FE2FFEE0D1147045A008818 | |
| 90 | +S118872B1A6EE9FFF26EE9FFF16EE9FFF06E0A0002AA054704D2 | |
| 91 | +S11887405A0087CC790200066F60FFEE1D2047045A00881A7939 | |
| 92 | +S118875504FFF409647905FFFA09657902FFF009626FE2FFECB1 | |
| 93 | +S118876A6F6300046DF30D420D516F60FFEC5E0086900B870D46 | |
| 94 | +S118877F0046045A00881A0D611B811B817900FFF109606F6252 | |
| 95 | +S118879400040B826DF21B826FE200047902FFF609625E00862B | |
| 96 | +S11887A9900B870D00476A0D611B817900FFF209606F63000424 | |
| 97 | +S11887BE0B830B836DF37902FFF809624044790200026F63FF77 | |
| 98 | +S11887D3EE1D2346426E0B0002F3001B837900FFF409606FE0A7 | |
| 99 | +S11887E8FFEA0D3209227905FFFA09650D5109217904FFF00943 | |
| 100 | +S11887FD640D4009306F6300046DF36F63FFEA09230D325E00BF | |
| 101 | +S118881286900B870D0046067900FFFF405019337904FFF40980 | |
| 102 | +S1188827647900FFF009606FE0FFE86F60FFE86C0A6FE0FFE86B | |
| 103 | +S118883C0CAA471E0D318900912069426DF2695279001A4E6F7B | |
| 104 | +S1188851E3FFE65E0096BC0B876F63FFE60B840B850B037902A5 | |
| 105 | +S118886600021D234FC66F60FFEE6D756D747903001A09376DE0 | |
| 106 | +S118887B7654706DF60D760D036B00A408400269000D00470896 | |
| 107 | +S11888906F0200021D3246F26D7654706DF60D761B876DF46DD8 | |
| 108 | +S11888A5F50D056FE1FFFE7900000E5E0097220D0446087900F0 | |
| 109 | +S11888BA02135E0080B418AA6ECA00046FC500026B02A4086948 | |
| 110 | +S11888CFC20D4088059000790200086F61FFFE5E0097AE6B8482 | |
| 111 | +S11888E4A4080D406D756D740B876D7654706DF60D766F03002E | |
| 112 | +S11888F9026F1200021D23470419004004790000016D765470D8 | |
| 113 | +S118890E6DF60D766DF40D04790088F20D415E00829E7903A419 | |
| 114 | +S118892308401269301D40460A690269B25E00979C400E0D0326 | |
| 115 | +S1188938693246EA790002325E0080B46D746D7654706DF60D24 | |
| 116 | +S118894D766DF46DF50D040D156F4200044608790002395E0090 | |
| 117 | +S118896280B46F440004401C6940790198DC5E0097D20D004703 | |
| 118 | +S11889770A0D5546040D40400C1B058C0A9400694246E0190064 | |
| 119 | +S118898C6D756D746D7654706DF60D761B876DF46DF50D056F9C | |
| 120 | +S11889A1E1FFFE6E5A000446226E5A0005AA0943087900024B1A | |
| 121 | +S11889B65E0080B46E5A0005F20009226F229A0C6F220004461A | |
| 122 | +S11889CB067900FFFF403E0D20690247360D0469406F61FFFEFC | |
| 123 | +S11889E05E0097D20D00461E6E4A00026EDA00056F4200041872 | |
| 124 | +S11889F5BB0D224702FB806EDB000879000001400A8C0A94007C | |
| 125 | +S1188A0A694246CC19006D756D740B876D7654706DF60D761B80 | |
| 126 | +S1188A1F876DF46DF56FE0FFFE0D157902007419110D505E00B2 | |
| 127 | +S1188A3498086F62FFFE69210D505E00981E0D50881C900079B6 | |
| 128 | +S1188A490400050D427901995E5E0097AE0D50883890000D42AC | |
| 129 | +S1188A5E7901995E5E0097AE6F63FFFE6E3A00026EDA00546F67 | |
| 130 | +S1188A73320004FBB60D224702FB6D6EDB005CFA016EDA005DDE | |
| 131 | +S1188A886F63FFFE6F32000418BB0D224702FB806EDB005F6D86 | |
| 132 | +S1188A9D756D740B876D7654706DF60D766DF46DF50D040D1555 | |
| 133 | +S1188AB26E4A000447067900FFFF40266E4A0005AA0943087991 | |
| 134 | +S1188AC700026B5E0080B46E4A0005F20009226F209A0C0D512A | |
| 135 | +S1188ADC5E008A1A790000016D756D746D7654706DF60D766E47 | |
| 136 | +S1188AF10A000446107369460C6E0A0008470A89FFA901420491 | |
| 137 | +S1188B061900400AFA016E8A0004790000016D7654706DF60D6B | |
| 138 | +S1188B1B767903000A19376DF46DF56FE0FFFE6FE1FFFC6FE24A | |
| 139 | +S1188B30FFFA6E0A0005AA094308790002875E0080B46F60FF56 | |
| 140 | +S1188B45FE6E0A0005F20009226F229A0C6FE2FFF86E0A000880 | |
| 141 | +S1188B5AEA8046045A008C3A6E0A00044720790100746F60008E | |
| 142 | +S1188B6F045E0098320D004610790100746F60FFFA5E00983280 | |
| 143 | +S1188B840D0047087900FFFF5A008C6C790100746F6000045E94 | |
| 144 | +S1188B990098446FE00004790100746F60FFFA5E0098446FE055 | |
| 145 | +S1188BAEFFFA5E0090346FE0FFF66F64FFF60B840B041955403B | |
| 146 | +S1188BC30C0D415E008A1A8C7494000B056F6200041D2544122C | |
| 147 | +S1188BD86F61FFFA09516F60FFF85E00894A0D0046DA0D5209D5 | |
| 148 | +S1188BED22092209221952092209220925095509556F63FFF685 | |
| 149 | +S1188C0268BD0D520C2A10021E226EBA000118AA6EBA00020B2D | |
| 150 | +S1188C17850B056DF519226DF26F63FFFE6F3200026F61FFFC76 | |
| 151 | +S1188C2CF80F5E00904819000B870B8740326F60FFF86F03000B | |
| 152 | +S1188C410647246F6200046DF26F60FFFA6DF06F60FFFE6F0213 | |
| 153 | +S1188C5600026F61FFFC6F60FFF85D300B870B8740047900FF05 | |
| 154 | +S1188C6BFF6D756D747903000A09376D7654706DF60D761B8739 | |
| 155 | +S1188C806DF46DF50D046FE1FFFE0D256E4A0008EA8046066EA4 | |
| 156 | +S1188C954A000446067900FFFF403C6E4A0005AA094308790005 | |
| 157 | +S1188CAA02B35E0080B46E4A0005F20009226F209A0C6F0200EA | |
| 158 | +S1188CBF0847166F6200046DF26F0300080D526F61FFFE5D30D0 | |
| 159 | +S1188CD40B8740047900FFFF6D756D740B876D7654706DF60DCE | |
| 160 | +S1188CE9761B876DF46DF56F63000446087900FFFF5A008DD243 | |
| 161 | +S1188CFE0D25194419116F6300040D5209326FE2FFFE40386806 | |
| 162 | +S1188D135BAB8846186F6200041B821D214CD4688B0B0018AACB | |
| 163 | +S1188D28688A0B000B8140180CBB46040B0440106F6200041BF1 | |
| 164 | +S1188D3D021D214CB4688B0B000B010B0519336F62FFFE1D2567 | |
| 165 | +S1188D52450479030001685A46040D3347B2790200011D2447F9 | |
| 166 | +S1188D67124E060D4447584038790200021D24471A402E6F62C7 | |
| 167 | +S1188D7C00041B021D214D045A008CF618AA688A0B000B014047 | |
| 168 | +S1188D91346F6200041B821D214D045A008CF618AA688A0B00F9 | |
| 169 | +S1188DA640186F6200041B821D214D045A008CF6FA88688A0B00 | |
| 170 | +S1188DBB000CCA8AFE688A0B000B8119440D3346045A008D12D8 | |
| 171 | +S1188DD00D106D756D740B876D7654706DF60D761B876DF46D1B | |
| 172 | +S1188DE5F50D040D2519226FE2FFFE0D55475E681AAA8847149E | |
| 173 | +S1188DFA68CA0B010B046F62FFFE0B026FE2FFFE1B0540E20B9D | |
| 174 | +S1188E0F016818F0000D00461468CA0B046F62FFFE0B026FE205 | |
| 175 | +S1188E24FFFE0B011B8540C40D030B836F62FFFE09326FE2FF91 | |
| 176 | +S1188E39FE0D321B030B011B854FAC188868C80B040D321B03E2 | |
| 177 | +S1188E4E4EF6409E6F60FFFE6D756D740B876D7654706DF60DB1 | |
| 178 | +S1188E63766DF46DF56A0CA40E47045A008F0079059F586B027F | |
| 179 | +S1188E78A4106DF20D527901009379009EC35E008CE66B80A429 | |
| 180 | +S1188E8D060B870D004C206B02A4100D5179009EC35E0097AEBF | |
| 181 | +S1188EA26B02A4106B82A40679029EC268AC0D23400879039E7E | |
| 182 | +S1188EB7C2FA0868BA6A0AA40A47047D3070206838F0006A0A0E | |
| 183 | +S1188ECCA40F4602C80168B86B00A4060D020B026B82A4066A77 | |
| 184 | +S1188EE10BA4076A8B9EC00C2A10021E226A8A9EC10B800B00FE | |
| 185 | +S1188EF66B80A406FA016A8AA40E6D756D746D7654706DF60D53 | |
| 186 | +S1188F0B766DF46DF55E008E606B02A4106B82A40C79059EC02E | |
| 187 | +S1188F206B04A406471A6DF46DF51922790117767900343E5E70 | |
| 188 | +S1188F350098560B870B870C8846E66D756D746D7654706DF684 | |
| 189 | +S1188F4A0D766B02A4106B03A40C1D32430E79009F580D3109F5 | |
| 190 | +S1188F5F0119325E0097AE6B02A40C6B03A41019230D326B8263 | |
| 191 | +S1188F74A41018AA6A8AA40E6D7654706DF60D766DF46DF50D6B | |
| 192 | +S1188F89246F6500046B03A41079029F5809320D2368B86EB98D | |
| 193 | +S1188F9E00010C1918116EB900020D44470E0B830B030D520D94 | |
| 194 | +S1188FB3410D305E0097AE6B02A4100B820B0209526B82A410CD | |
| 195 | +S1188FC818AA6A8AA40E6D756D746D7654706DF60D766DF46D0A | |
| 196 | +S1188FDDF50D156B04A41079029F5809420D24FA0368CA6EC8EE | |
| 197 | +S1188FF200010C0818006EC800020D505E009874790200401D62 | |
| 198 | +S1189007204F020D200B840B040D020D510D405E0097AE6B024A | |
| 199 | +S118901CA4108A4392006B82A41018AA6A8AA40E6D756D746DEF | |
| 200 | +S11890317654706DF60D766B00A41079029F5D09020D206D7655 | |
| 201 | +S118904654706DF60D766DF46DF56F6400046B03A41079059F8E | |
| 202 | +S118905B5809350D5368B86EB900010C1918116EB900026EBA1F | |
| 203 | +S118907000030C2A18226EBA00040D4447108B0593006F6200AC | |
| 204 | +S1189085060D410D305E0097AE6B02A4108A0592006F60000687 | |
| 205 | +S118909A09026B82A41018AA6A8AA40E6D756D746D7654706DD2 | |
| 206 | +S11890AFF60D7669021D12470419004004790000016D765470CC | |
| 207 | +S11890C46DF60D760D01790090AE5E00829E6D7654706DF60D53 | |
| 208 | +S11890D9767903000E19376DF46DF50D050D14790000021D049C | |
| 209 | +S11890EE4E08790003935E0080B46C5A6EEAFFFD6E5B00010C82 | |
| 210 | +S1189103B318BB685AF20014AB14236FE3FFFA1B841B040B858A | |
| 211 | +S11891186E6BFFFDF3000D33470A790200041D23470E40446DE0 | |
| 212 | +S118912DF319226F61FFFAF801402E790200021D244708790045 | |
| 213 | +S1189142039D5E0080B46E5800010C801888685AF20014A8146B | |
| 214 | +S1189157205E0090C419226DF26F61FFFAF8055E008F800B87CE | |
| 215 | +S118916C5A009496790200011D244E08790003A45E0080B46E33 | |
| 216 | +S11891815800010C801888685AF20014A814206FE0FFF81B84C7 | |
| 217 | +S11891960B855E00887E6FE0FFF46E6BFFFDF3008BFA93FF7932 | |
| 218 | +S11891AB0200161D2343045A00948E09336F3299DA592079024C | |
| 219 | +S11891C000381D244708790003AA5E0080B46F63FFF447087989 | |
| 220 | +S11891D50199635A0094567901988E6F60FFF85E00889C6FE009 | |
| 221 | +S11891EAFFF4790200086DF2880590006DF06F62FFF86F61FF86 | |
| 222 | +S11891FFFAF81D5A0094840D444708790003B65E0080B46F62A1 | |
| 223 | +S1189214FFF446087901996E5A0094566F60FFF45E00890E6E16 | |
| 224 | +S11892296BFFFDAB1446087901997A5A00945619226DF26DF2EE | |
| 225 | +S118923E6F62FFF86F61FFFAF8135A009484790200021D244704 | |
| 226 | +S118925308790003C45E0080B46E5C00010CC418CC685AF200F5 | |
| 227 | +S118926814AC14240D405E00887E6F62FFF446045A0092186EC4 | |
| 228 | +S118927D2A00044708790199875A0094560D0047045A0091D466 | |
| 229 | +S11892926F61FFF4890591000D405E00889C19226DF26DF26FAA | |
| 230 | +S11892A762FFF86F61FFFAF8075A0094847902001C1D244708F4 | |
| 231 | +S11892BC790003D35E0080B40D516F60FFF45E0089940D0046CA | |
| 232 | +S11892D108790199935A009456790200086DF26F63FFF48B055B | |
| 233 | +S11892E693006DF36F62FFF86F61FFFAF8095A0094840D4447E0 | |
| 234 | +S11892FB08790003DA5E0080B47904A3580D416F60FFF45E0084 | |
| 235 | +S11893108AA60D004608790199A05A009456790200746DF26D07 | |
| 236 | +S1189325F46F62FFF86F61FFFAF8175A009484790200211D244C | |
| 237 | +S118933A4708790003E25E0080B4790199AB5A0094567902005E | |
| 238 | +S118934F011D244708790003E65E0080B468596F60FFF45E009F | |
| 239 | +S11893648AEC0D004608790199B85A009456790200086DF26FBF | |
| 240 | +S118937960FFF4880590006DF06F62FFF86F61FFFAF80B5A0020 | |
| 241 | +S118938E94847902000A1D244708790003ED5E0080B46E5A00D6 | |
| 242 | +S11893A3010CA218AA6859F1006E5B00090CB318BB6E5800085C | |
| 243 | +S11893B8F000148B14036DF3149A14126F61FFFA6F60FFF45ED9 | |
| 244 | +S11893CD008B180B870D004D045A009496790199C35A00945656 | |
| 245 | +S11893E27902000A1D244E08790003F45E0080B46E5A00010C7F | |
| 246 | +S11893F7A218AA6FE2FFF6685AF2006F60FFF614A814206FE0FC | |
| 247 | +S118940CFFF66E5B00090CB318BB6E5A0008F20014AB14238DA9 | |
| 248 | +S11894210B95008CF594FF1D434710790003F96FE3FFF25E00B1 | |
| 249 | +S118943680B46F63FFF26DF50D326F61FFF66F60FFF45E008C14 | |
| 250 | +S118944B7A0B870D004C0E790199CE6F60FFFA5E008FD64036B3 | |
| 251 | +S11894606EE8FFFE0C0810001E006EE8FFFF790200026DF20D21 | |
| 252 | +S1189475621B826DF26F62FFF86F61FFFAF8115E0090480B871E | |
| 253 | +S118948A0B874008790004045E0080B46D756D747903000E0986 | |
| 254 | +S118949F376D7654706DF60D766DF46DF50D04684BF3007902FB | |
| 255 | +S11894B400451D23470C7902004D1D2347045A009548790200C2 | |
| 256 | +S11894C9051D214708790004125E0080B479039A28683DF500FF | |
| 257 | +S11894DE6A0A9A290CA218AA14AD14250D5209326E4B00036E10 | |
| 258 | +S11894F3AB000118BB6A0AA40F4602FB016A8BA40F5E008F4899 | |
| 259 | +S1189508790200011D254F326A0A9A2AEA08471E79019A2B79C4 | |
| 260 | +S118951D049AC00D521B020D405E008DDC0D050D510D405E002C | |
| 261 | +S118953290D6400C79009A2B0D511B015E0090D65E008F0840BD | |
| 262 | +S1189547087900042C5E0080B46D756D746D7654706DF60D7678 | |
| 263 | +S118955C7903005219376DF45E00970E7900FFB0096079020068 | |
| 264 | +S11895714019115E0098087902A4007901FFB6096179003B9A73 | |
| 265 | +S11895865E0096AC790029645E0096D4790014985E0096D479F8 | |
| 266 | +S118959B0200016DF26DF27902FFB609627901FFB4096179004B | |
| 267 | +S11895B030D05E0098560B870B87790230026DF2192279013041 | |
| 268 | +S11895C51F79001FF25E0096BC0B877901300779001B625E009D | |
| 269 | +S11895DA96DE790027C85E0096D419446DF479029A2879011748 | |
| 270 | +S11895EF717900327C5E0096BC0B876A8CA40F6B84A4066B8458 | |
| 271 | +S1189604A4106A8CA40E405C19227901FFAF0961790034265E57 | |
| 272 | +S11896190096AC6E6AFFAFF2000CAA473E18AA6EEAFFAE790201 | |
| 273 | +S118962EFFAE09626DF2790200107901FFF00961790033B05E94 | |
| 274 | +S11896430096BC0B876E69FFAEF1006B029A200B026B829A20DA | |
| 275 | +S11896581B017900FFF009605E0094A45E0085BC5E0080320DBA | |
| 276 | +S114966D00469C19006D747903005209376D76547057 | |
| 277 | +S118967E6DF60D7679029A207903A4121D32470A188868A80B2B | |
| 278 | +S1189693021D3246F85E009558FA016A8AFFCC6B0200005D2040 | |
| 279 | +S10796A86D76547013 | |
| 280 | +S11396AC6DF66DF20D165D000D600B876D765470C2 | |
| 281 | +S11896BC6DF66F7300046DF36DF20D165D000D600B870B876D0F | |
| 282 | +S10696D176547058 | |
| 283 | +S10D96D46DF65D000D606D765470B4 | |
| 284 | +S10F96DE6DF60D165D000D606D76547085 | |
| 285 | +S11596EA6DF56DF60D060D155F520D606D766D755470C9 | |
| 286 | +S11596FC6DF56DF60D060D155F500D606D766D755470B9 | |
| 287 | +S118970E6DF60D767903A4127902EF00193269B26D7654706D46 | |
| 288 | +S1189723F60D766DF46DF50D040B04ECFE0B841D04455C79001D | |
| 289 | +S1189738A4120D01404C69024D4209217902EEFF1D2142144068 | |
| 290 | +S118974D0E690209326982691209211D51420469134CEE6903E9 | |
| 291 | +S11897621D4345220D428A0692001D23450A0D02094219436908 | |
| 292 | +S1189777A369846902C28069820B804010E27F09210D107905B0 | |
| 293 | +S118978CEEFF1D5043AC19006D756D746D7654706DF60D766FA3 | |
| 294 | +S11097A102FFFEE27F6F82FFFE6D765470C2 | |
| 295 | +S11897AE6DF60D766DF40D140D010D0309231D31470A6C4A6833 | |
| 296 | +S11297C38A0B001D3046F60D106D746D765470D0 | |
| 297 | +S11897D26DF60D76401C680B681A1CAB430679000001401E1C43 | |
| 298 | +S11897E7AB44067900FFFF40140B000B01680A46E0681A19005F | |
| 299 | +S10F97FC0CAA47047900FFFF6D7654703E | |
| 300 | +S11898086DF60D760D0309231D3047066CB91D3046FA6D7654A2 | |
| 301 | +S104981D70D6 | |
| 302 | +S117981E6DF60D760D036C1A68BA0B030CAA46F66D765470ED | |
| 303 | +S11598326DF56DF60D060D155F4C0D606D766D75547085 | |
| 304 | +S11598446DF56DF60D060D155F4E0D606D766D75547071 | |
| 305 | +S11898566DF66F7300066DF36F7300066DF36DF20D165D000D1A | |
| 306 | +S10C986B608F0697006D765470BD | |
| 307 | +S11798746DF60D76193340020B036C0A46FA0D306D765470C0 | |
| 308 | +S1189888726573657400000000800000000098DC000099120005 | |
| 309 | +S118989D00000098DA020000000000871298D803000000000032 | |
| 310 | +S11898B2871298D6040000000000871298D20500000000008703 | |
| 311 | +S11898C712000000000000000000003031320032003100300050 | |
| 312 | +S11898DC2E2E000098DC000099120000000098DA0700000085FA | |
| 313 | +S11898F12A82E098D808000000852A82E098D609000000852A23 | |
| 314 | +S118990682E00000000000000000000098DC0000994800000091 | |
| 315 | +S118991B0099410100989600000000993A060098E000000000D9 | |
| 316 | +S11899300000000000000000000073656E736F72006D6F746FC5 | |
| 317 | +S1189945720000995C00009912000000000000000000000000F7 | |
| 318 | +S118995A00002F006C65676F0066696420696E20757365006E19 | |
| 319 | +S118996F6F2073756368206669640063616E27742072656D6FAA | |
| 320 | +S118998476650063616E277420636C6F6E65006E6F20737563A9 | |
| 321 | +S118999968206E616D650063616E277420737461740063616EB1 | |
| 322 | +S11899AE2774206372656174650063616E2774206F70656E00D2 | |
| 323 | +S11899C363616E277420726561640063616E277420777269744F | |
| 324 | +S11899D86500924C948E92B4948E934C948E9334948E93909408 | |
| 325 | +S11899ED8E93E2948E9206948E9206948E92F8948E948E948ED8 | |
| 326 | +S1099A02948E948E91BEC7 | |
| 327 | +S1189A080000FFFF9948991C98A098AA98B498BE992698EA98BC | |
| 328 | +S1069A1DF498FEB8 | |
| 329 | +S90380007C | |
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,7 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | +load std | |
| 3 | +if {~ $#* 0} { | |
| 4 | + echo usage: runns path0 path1 ... pathn | |
| 5 | + raise usage | |
| 6 | +} | |
| 7 | +grid/register -a resource Namespace 'grid/srv/ns '^$"* | grid/srv/monitor 1 'Namespace' | |
Binary file not shown.
| @@ -0,0 +1,17 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | + | |
| 3 | +mount -A {auxi/odbcmnt -a tcp!200.1.1.113} /mnt/odbc | |
| 4 | + | |
| 5 | +fn splitrun { | |
| 6 | + if {! ~ $#* 0} { | |
| 7 | + (hd tl) = $* | |
| 8 | + echo Registering $hd | |
| 9 | + grid/register -a resource ODBC -a name $hd '{export /mnt/odbc/'^$hd^'}' | |
| 10 | + splitrun $tl | |
| 11 | + } | |
| 12 | +} | |
| 13 | + | |
| 14 | +cd /mnt/odbc | |
| 15 | +sources=`{ls} | |
| 16 | +splitrun $sources | |
| 17 | + | |
Binary file not shown.
| @@ -0,0 +1,44 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | +load std | |
| 3 | +autoload=std | |
| 4 | +ndb/cs | |
| 5 | + | |
| 6 | +fn ck { | |
| 7 | + or {$*} { | |
| 8 | + echo spreeclient: exiting >[1=2] | |
| 9 | + raise error | |
| 10 | + } | |
| 11 | +} | |
| 12 | +user="{cat /dev/user} | |
| 13 | + | |
| 14 | +fn notice { | |
| 15 | + or {~ $#* 1} { | |
| 16 | + echo usage: notice arg >[1=2] | |
| 17 | + raise usage | |
| 18 | + } | |
| 19 | + t := $* | |
| 20 | + run /lib/sh/win | |
| 21 | + tkwin Notice { | |
| 22 | + x text .t -yscrollcommand {.s set} | |
| 23 | + x scrollbar .s -orient vertical -command {.t yview} | |
| 24 | + x pack .s -side left -fill y | |
| 25 | + x pack .t -side top -fill both -expand 1 | |
| 26 | + x .t insert 1.0 ${tkquote $t} | |
| 27 | + tk onscreen $wid | |
| 28 | + chan c; {} ${recv c} | |
| 29 | + } | |
| 30 | +} | |
| 31 | + | |
| 32 | +ck mount -A 'tcp!$registry!registry' /mnt/registry | |
| 33 | +ck /dis/grid/remotelogon wm/wm { | |
| 34 | + k = /usr/$user/keyring/default | |
| 35 | + addrs=`{ndb/regquery resource spree auth.signer `{getpk -s $k}} | |
| 36 | + if{~ $#addrs 0} { | |
| 37 | + notice 'No spree servers found' | |
| 38 | + } | |
| 39 | + if {mount ${hd $addrs} /n/remote} { | |
| 40 | + spree/joinsession 0 | |
| 41 | + } { | |
| 42 | + notice 'Cannot access spree server' | |
| 43 | + } | |
| 44 | +} | |
| @@ -0,0 +1,7 @@ | ||
| 1 | +#!/dis/sh.dis | |
| 2 | +load std | |
| 3 | +pctl forkns | |
| 4 | +memfs /tmp | |
| 5 | +cp /dis/wm/whiteboard.dis /tmp | |
| 6 | +/dis/auxi/wbsrv /tmp $2 | |
| 7 | +grid/register -a resource Whiteboard -a size 600x400 -a name $1 {export /tmp} | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,67 @@ | ||
| 1 | +#!/dis/sh | |
| 2 | + | |
| 3 | + | |
| 4 | +load std | |
| 5 | +autoload=std | |
| 6 | +pctl forkns newpgrp | |
| 7 | +echo -n 62.254.170.99 > /dev/sysname | |
| 8 | + | |
| 9 | +# from /dis/svc/auth (except -n option) | |
| 10 | +fn auth { | |
| 11 | + or {ftest -e /net/dns} {ftest -e /env/emuhost} {ndb/dns} | |
| 12 | + or {ftest -e /net/cs} {ndb/cs} | |
| 13 | + # svc/registry # unclear if we should | |
| 14 | + or {ftest -f /keydb/signerkey} {echo 'auth: need to use createsignerkey(8)' >[1=2]; exit nosignerkey} | |
| 15 | + or {ftest -f /keydb/keys} {echo 'auth: need to create /keydb/keys' >[1=2]; exit nokeys} | |
| 16 | + nopt := () | |
| 17 | + if{ftest -r /tmp/gamepasswd} { | |
| 18 | + nopt=-n /tmp/gamepasswd | |
| 19 | + } | |
| 20 | + and {auth/keyfs $nopt} { | |
| 21 | + listen -v -t -A 'tcp!*!inflogin' {auth/logind&} | |
| 22 | + listen -v -t -A 'tcp!*!infkey' {auth/keysrv&} | |
| 23 | + listen -v -t -A 'tcp!*!infsigner' {auth/signer&} | |
| 24 | + listen -v -t -A 'tcp!*!infcsigner' {auth/countersigner&} | |
| 25 | + } | |
| 26 | +} | |
| 27 | + | |
| 28 | +fn ck { | |
| 29 | + or {$*} { | |
| 30 | + echo signer startup failed >[1=2] | |
| 31 | + rm -f /mnt/registry/tcp!doppio!inflogin | |
| 32 | + kill -g ${pid} | |
| 33 | + raise error | |
| 34 | + } | |
| 35 | +} | |
| 36 | + | |
| 37 | +fn register { | |
| 38 | + { | |
| 39 | + or {echo $*} { | |
| 40 | + echo spreesrv: register $* failed >[1=2] | |
| 41 | + } | |
| 42 | + sleep 2000000 | |
| 43 | + } $* > /mnt/registry/new & | |
| 44 | +} | |
| 45 | +sysname="{cat /dev/sysname} | |
| 46 | + | |
| 47 | +ck ndb/cs | |
| 48 | +ck mount -A 'tcp!$registry!registry' /mnt/registry | |
| 49 | + | |
| 50 | +@ { | |
| 51 | + pctl forkns | |
| 52 | + ck listen -f /usr/i4e/keyring/spree tcp!$sysname!1234 { | |
| 53 | + if {~ $user spree} { | |
| 54 | + export /lib/spreearchive & | |
| 55 | + } | |
| 56 | + } | |
| 57 | +} | |
| 58 | + | |
| 59 | +# start auth services and announce them in the registry. | |
| 60 | +ck bind /keydb/gamesignerkey /keydb/signerkey | |
| 61 | +ck bind /keydb/gamekeys /keydb/keys | |
| 62 | +ck auth | |
| 63 | +pk=`{getpk /keydb/signerkey} | |
| 64 | +ck register tcp!$sysname!inflogin resource login pk $pk | |
| 65 | +ck register tcp!$sysname!infkey resource infkey pk $pk | |
| 66 | + | |
| 67 | +ck grid/register -a resource createuser -a signer $pk { grid/usercreatesrv } | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,9 @@ | ||
| 1 | +#!/dis/sh.dis -n | |
| 2 | +load std | |
| 3 | +if {~ $emuhost Nt} { | |
| 4 | + # spec | |
| 5 | +} {~ $emuhost Plan9} { | |
| 6 | + # different? | |
| 7 | +} { | |
| 8 | + # the unix systems | |
| 9 | +} | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,13 @@ | ||
| 1 | +#!/dis/sh.dis -n | |
| 2 | +load std | |
| 3 | +or {ftest -e /net/dns} {ftest -e /env/emuhost} {ndb/dns} | |
| 4 | +or {ftest -e /net/cs} {ndb/cs} | |
| 5 | +or {ftest -f /keydb/signerkey} {echo 'auth: need to use createsignerkey(8)' >[1=2]; exit nosignerkey} | |
| 6 | +or {ftest -f /keydb/keys} {echo 'auth: need to create /keydb/keys' >[1=2]; exit nokeys} | |
| 7 | +and {auth/keyfs} { | |
| 8 | + listen -v -t -A 'tcp!*!inflogin' {auth/logind&} | |
| 9 | + listen -v -t -A 'tcp!*!infkey' {auth/keysrv&} | |
| 10 | + listen -v -t -A 'tcp!*!infsigner' {auth/signer&} | |
| 11 | + listen -v -t -A 'tcp!*!infcsigner' {auth/countersigner&} | |
| 12 | +} | |
| 13 | +# run svc/registry separately if desired | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,6 @@ | ||
| 1 | +#!/dis/sh.dis -n | |
| 2 | +load std | |
| 3 | +or {ftest -e /net/dns} {ftest -e /env/emuhost} {ndb/dns} | |
| 4 | +or {ftest -e /net/cs} {ndb/cs} | |
| 5 | +svc/registry | |
| 6 | +svc/styx | |
| @@ -0,0 +1,8 @@ | ||
| 1 | +#!/dis/sh.dis -n | |
| 2 | +load std | |
| 3 | +or {ftest -f /mnt/registry/new} { | |
| 4 | + db=() | |
| 5 | + and {ftest -f /lib/ndb/registry} {db=(-f /lib/ndb/registry)} | |
| 6 | + mount -A -c {ndb/registry $db} /mnt/registry | |
| 7 | +} | |
| 8 | +listen -v 'tcp!*!registry' {export /mnt/registry&} # -n? | |
| @@ -0,0 +1,4 @@ | ||
| 1 | +#!/dis/sh.dis -n | |
| 2 | +load std | |
| 3 | +listen 'tcp!*!rstyx' {runas $user auxi/rstyxd&} | |
| 4 | +#and {ftest -d /net/il} {listen 'il!*!rstyx' {runas $user auxi/rstyxd&}} | |
| @@ -0,0 +1,4 @@ | ||
| 1 | +#!/dis/sh.dis -n | |
| 2 | +load std | |
| 3 | +listen -v 'tcp!*!styx' {export /&} # -n? | |
| 4 | +#and {ftest -d /net/il} {listen -v 'il!*!styx' {export /&}} # -n? | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,941 @@ | ||
| 1 | +.TL | |
| 2 | +Inferno 3rd Edition \- June 2001 Revision | |
| 3 | +.br | |
| 4 | +Release Notes and Errata | |
| 5 | +.AI | |
| 6 | +Vita Nuova | |
| 7 | +support@vitanuova.com | |
| 8 | +.br | |
| 9 | +18 June 2001 | |
| 10 | +.SP 4 | |
| 11 | +.NH 1 | |
| 12 | +Installation | |
| 13 | +.LP | |
| 14 | +If you have a previous version of Inferno installed, this one must not | |
| 15 | +be installed over it. | |
| 16 | +If you have a Lucent Inferno 2.3 release from 1999 or earlier, you | |
| 17 | +should make a completely new installation from this CD. | |
| 18 | +If you have installed the Vita Nuova `Binary and Limited Source' CD you | |
| 19 | +should also make a new installation from this CD. | |
| 20 | +If you have previously installed the Vita Nuova Full Source CD from July 2000, | |
| 21 | +see the section `Updating the July 2000 release' at the end of this document. | |
| 22 | +(You could also make a fresh installation in a new directory, or remove the old | |
| 23 | +release and install this one if there are no files you wish to keep.) | |
| 24 | +.LP | |
| 25 | +Follow the installation instructions in ``Installation of the Inferno Software'' | |
| 26 | +at the end of Volume 2. | |
| 27 | +The printed copy has several mistakes: | |
| 28 | +.IP \(bu | |
| 29 | +Page 327 notes that on Unix | |
| 30 | +if the installation is done as user | |
| 31 | +.CW root | |
| 32 | +but a user | |
| 33 | +.CW inferno | |
| 34 | +exists the files will be owned by | |
| 35 | +.CW inferno . | |
| 36 | +They are not. | |
| 37 | +Indeed, on Unix there is no reason to install the package as | |
| 38 | +the super-user | |
| 39 | +.CW root . | |
| 40 | +Do the installation as the user, perhaps | |
| 41 | +.CW inferno , | |
| 42 | +that is to own the files. | |
| 43 | +.IP \(bu | |
| 44 | +It refers on page 327 | |
| 45 | +to the Windows installation program as | |
| 46 | +.CW Nt-386.exe . | |
| 47 | +The correct name is used on the next | |
| 48 | +page in the actual instructions, namely | |
| 49 | +.CW \einstall\esetup.exe . | |
| 50 | +.IP \(bu | |
| 51 | +The Windows | |
| 52 | +.CW setup.exe | |
| 53 | +will offer to create the target installation directory if it does not exist. | |
| 54 | +On all other systems, you must first create the directory yourself. | |
| 55 | +.IP \(bu | |
| 56 | +Solaris and some other commercial Unix systems | |
| 57 | +do not read the `Joliet' format section of the CD, | |
| 58 | +which uses Unicode names, and | |
| 59 | +they | |
| 60 | +force the names in the non-Joliet portion on the CD to lower case, sometimes | |
| 61 | +with hyphens converted to underscores. | |
| 62 | +The installation script on Solaris is therefore | |
| 63 | +.CW install/solaris_sparc.sh . | |
| 64 | +The installation script itself works despite this. | |
| 65 | +Alternatively, if the CD is mounted with the option | |
| 66 | +.CW nomaplcase | |
| 67 | +the system will not force the names to lower case | |
| 68 | +and all names will appear as we intended | |
| 69 | +(see the Solaris manual entry for | |
| 70 | +.I mount_hsfs ). | |
| 71 | +Future CDs will use Rock Ridge format as well as Joliet to avoid the problem. | |
| 72 | +(We attempted that this time | |
| 73 | +but ran into trouble on Windows systems because of an error in the CD writing program.) | |
| 74 | +Linux and FreeBSD show the names we intended. | |
| 75 | +.LP | |
| 76 | +When installing on Windows NT or Windows 2000, the installation program determines | |
| 77 | +if the current user belongs to the | |
| 78 | +.CW Administrators | |
| 79 | +group. | |
| 80 | +If so, the Start Menu entry is created in the | |
| 81 | +.CW "All Users" | |
| 82 | +profile, otherwise it is created in the user's private profile. | |
| 83 | +On Windows 95 and Windows 98, if the user has a private profile the | |
| 84 | +Start Menu entry is created there, | |
| 85 | +otherwise it is created in the main system Start Menu. | |
| 86 | +Furthermore, | |
| 87 | +.CW setup.exe | |
| 88 | +looks for | |
| 89 | +.CW "Start Menu" | |
| 90 | +to install the shortcut, but that name is locale-dependent, | |
| 91 | +and thus the shortcut will not be installed correctly in non-English locales, | |
| 92 | +although Inferno itself will be installed successfully. | |
| 93 | +.LP | |
| 94 | +When the installation completes normally, | |
| 95 | +it prints ``installation complete'', but on some platforms it can then print | |
| 96 | +``Killed: ...'' followed by the command line used in the installation shell script. | |
| 97 | +Provided it has said ``installation complete'' and there were no errors noted | |
| 98 | +prior to that, the installation has succeeded. | |
| 99 | +The ``Killed'' message results from the installation software | |
| 100 | +running inside the Inferno environment having shut down that environment. | |
| 101 | +It does not mean that installation failed. | |
| 102 | +.LP | |
| 103 | +If an installation does fail, for instance by running out of space, | |
| 104 | +delete everything in the target directory before retrying the installation. | |
| 105 | +Also see the ``Known Problems'' section below. | |
| 106 | +.NH 1 | |
| 107 | +CD Number | |
| 108 | +.LP | |
| 109 | +There is a set of six unique numbers on the back of the CD case. | |
| 110 | +You should keep the case or record the numbers: | |
| 111 | +they identify your subscription, and you will need them | |
| 112 | +to gain access to subscriber's services we provide electronically. | |
| 113 | +(They are randomly generated and usable in a 6/49 lottery!) | |
| 114 | +.NH 1 | |
| 115 | +Hosted Operating System versions | |
| 116 | +.LP | |
| 117 | +The software was compiled on the operating system versions listed below. | |
| 118 | +UNIX systems show the output from | |
| 119 | +.CW "uname -a" | |
| 120 | +and the version of the C compiler, | |
| 121 | +if known. | |
| 122 | +See the section | |
| 123 | +.I "Known problems" | |
| 124 | +below for a list of known problems for any given release. | |
| 125 | +.TS | |
| 126 | +center; | |
| 127 | +lf(B) lf(R)w(4i) . | |
| 128 | +Windows Nt Windows NT4.0 SP4 | |
| 129 | +Linux T{ | |
| 130 | +Linux vespa 2.2.9-19mdk #1 Wed May 19 19:53:00 GMT 1999 i586 ... | |
| 131 | +.br | |
| 132 | +(gcc-2.91.66) | |
| 133 | +T} | |
| 134 | +Solaris T{ | |
| 135 | +SunOS pazzo 5.6 Generic_105181-03 sun4u sparc SUNW,Ultra-5_10 | |
| 136 | +.br | |
| 137 | +(gcc 2.95) | |
| 138 | +T} | |
| 139 | +FreeBSD 4.x T{ | |
| 140 | +FreeBSD outside 4.0-RELEASE FreeBSD 4.0-RELEASE #0: ... i386 | |
| 141 | +.br | |
| 142 | +(gcc 2.95.2) | |
| 143 | +T} | |
| 144 | +HP/UX T{ | |
| 145 | +HP-UX hpserv1 B.10.20 A 9000/715 2013314861 ... | |
| 146 | +.br | |
| 147 | +(c89) | |
| 148 | +T} | |
| 149 | +IRIX 5.3 T{ | |
| 150 | +IRIX invece 5.3 11091812 IP22 mips | |
| 151 | +.br | |
| 152 | +(MIPS cc) | |
| 153 | +T} | |
| 154 | +Plan9/x86 Third Edition, updates to 5th June 2001 | |
| 155 | +.TE | |
| 156 | +.LP | |
| 157 | +The Windows version has also been tested and | |
| 158 | +used extensively on the following variants: | |
| 159 | +.DS | |
| 160 | +.ft B | |
| 161 | +Windows '95 | |
| 162 | +Windows '98 | |
| 163 | +Windows Me | |
| 164 | +.ft R | |
| 165 | +.DE | |
| 166 | +We have also installed and run the system under Windows 2000, both | |
| 167 | +client and server, but there is a problem with the cursor under Windows 2000 client (see below). | |
| 168 | +.LP | |
| 169 | +Inferno source code is included for the following, but they have neither been | |
| 170 | +built nor tested: | |
| 171 | +.DS | |
| 172 | +.ft B | |
| 173 | +Plan 9 (mips, sparc, power) | |
| 174 | +Solaris/386 | |
| 175 | +Unixware v 2.3 | |
| 176 | +.ft R | |
| 177 | +.DE | |
| 178 | +.NH 1 | |
| 179 | +Known problems | |
| 180 | +.LP | |
| 181 | +See | |
| 182 | +.CW www.vitanuova.com/inferno/ | |
| 183 | +for current pointers to information about Inferno. | |
| 184 | +You should particularly check the Frequently Asked Questions at | |
| 185 | +.P1 | |
| 186 | +www.vitanuova.com/inferno/faq.html | |
| 187 | +.P2 | |
| 188 | +and the current Bugs list at | |
| 189 | +.P1 | |
| 190 | +www.vitanuova.com/inferno/bugs.html | |
| 191 | +.P2 | |
| 192 | +The Subscriber area will include online updates after 6 July 2001. | |
| 193 | +.LP | |
| 194 | +Now, the bad news: | |
| 195 | +.IP \(bu | |
| 196 | +The Windows NT installation program will create a Start Menu shortcut that invokes | |
| 197 | +.I emu | |
| 198 | +with a | |
| 199 | +.CW "-g800x600" | |
| 200 | +argument. The | |
| 201 | +.I emu | |
| 202 | +display will be incorrect if the screen width available is less than 800 pixels and is not a multiple | |
| 203 | +of four. The problem can be seen if the PC is configured with a resolution of 800x600 pixels | |
| 204 | +and the Microsoft Office shortcut bar is active. The simplest fix is to change the | |
| 205 | +.I emu | |
| 206 | +shortcut to use a | |
| 207 | +.CW "-g788x600" | |
| 208 | +argument instead. | |
| 209 | +.IP \(bu | |
| 210 | +As mentioned above, the Windows NT installation program looks only for | |
| 211 | +.CW "Start Menu" | |
| 212 | +not the locale-dependent name. | |
| 213 | +.IP \(bu | |
| 214 | +Changing the cursor image does not work under Windows 2000 Client; | |
| 215 | +this mainly affects | |
| 216 | +.I acme , | |
| 217 | +which changes the cursor when rearranging or resizing frames. | |
| 218 | +.IP \(bu | |
| 219 | +The HP version of hosted Inferno was generated by HP/UX version B.10.20. | |
| 220 | +On the HP platform, | |
| 221 | +.CW emu | |
| 222 | +can currently only be run in interpreted mode; the compiled mode (ie, | |
| 223 | +.CW -c1 | |
| 224 | +option) | |
| 225 | +will fault. | |
| 226 | +.IP \(bu | |
| 227 | +Some Inferno calls return error strings provided by Windows, without modification. | |
| 228 | +They can be obscure: | |
| 229 | +for instance, ``windows error 10049'' is produced by network calls | |
| 230 | +that attempt to use symbolic names when | |
| 231 | +.I cs (8) | |
| 232 | +has not been started. | |
| 233 | +.IP \(bu | |
| 234 | +On all systems, the mapping from Inferno names and permissions to the underlying | |
| 235 | +operating system's names and permissions needs more work, particularly on Windows. | |
| 236 | +Common problems include: | |
| 237 | +.RS | |
| 238 | +.IP \- | |
| 239 | +File names in the Inferno environment cannot be longer than 27 bytes. | |
| 240 | +.IP \- | |
| 241 | +.I Ftpfs | |
| 242 | +cannot access files with long names or names containing spaces. | |
| 243 | +.IP \- | |
| 244 | +The contents of | |
| 245 | +.CW /dev/user | |
| 246 | +on Windows will contain the Windows user name, which can contain spaces. | |
| 247 | +.IP \- | |
| 248 | +Files created inside the Inferno hierarchy by host system applications | |
| 249 | +can sometimes have odd permissions when accessed within Inferno. | |
| 250 | +.IP \- | |
| 251 | +Readonly files and open files cannot be removed under Windows. | |
| 252 | +.LP | |
| 253 | +In general, the mapping between Inferno users and groups and Windows/Nt users and groups | |
| 254 | +is systematic, as described in | |
| 255 | +.I sys-stat (2): | |
| 256 | +.QS | |
| 257 | +.I Emu | |
| 258 | +attempts to maintain a limited but consistent map | |
| 259 | +between Inferno and NT worlds, specifically between Inferno | |
| 260 | +names and NT security IDs. | |
| 261 | +Special NT group `Everyone' | |
| 262 | +represents `other' for file permissions. The Inferno uid is | |
| 263 | +the file owner under NT; the Inferno gid reported is the | |
| 264 | +first user in the file's ACL that is neither the owner nor | |
| 265 | +Everyone; failing that, the gid is the file's owner. | |
| 266 | +.QE | |
| 267 | +.LP | |
| 268 | +The effects of this mapping are sometimes peculiar: for instance, something that | |
| 269 | +is thought of as a user appears as the group name in | |
| 270 | +.I ls , | |
| 271 | +and vice-versa. | |
| 272 | +Either the implementation or the mapping might need to be rethought. | |
| 273 | +.RE | |
| 274 | +.IP \(bu | |
| 275 | +.I bufio (2) | |
| 276 | +maintains an internal list of files open for output, | |
| 277 | +to support its little-used | |
| 278 | +.CW flush -all | |
| 279 | +operation. | |
| 280 | +Unfortunately, that means that if several processes | |
| 281 | +use the same Bufio module instance (the result of a single | |
| 282 | +.CW load ) | |
| 283 | +concurrently for output to different files, they must separately interlock the open, create and close calls. | |
| 284 | +.IP \(bu | |
| 285 | +The file | |
| 286 | +.CW utils/5l/thumb.c | |
| 287 | +contains comments in the C++ style, which (reasonably enough) are not accepted by the | |
| 288 | +ANSI C compiler on the HP/UX system we used, and thus the current | |
| 289 | +.CW 5l | |
| 290 | +is not compiled for HP/UX; they will be changed to ANSI C comments by | |
| 291 | +one of the online updates. | |
| 292 | +.NH 1 | |
| 293 | +Contents | |
| 294 | +.LP | |
| 295 | +This revision offers the following, compared to the July 2000 release. | |
| 296 | +.SH | |
| 297 | +.I "Repairs and changes" | |
| 298 | +.IP \(bu | |
| 299 | +Many bug fixes and improvements appear throughout. | |
| 300 | +Many commands have been revised to print usage and diagnostic consistently, and give reliable exit status for | |
| 301 | +.CW sh . | |
| 302 | +.IP \(bu | |
| 303 | +The shell | |
| 304 | +.CW sh | |
| 305 | +has repairs and several visible changes: | |
| 306 | +.I sh-expr (1) | |
| 307 | +implements a | |
| 308 | +.CW % | |
| 309 | +operator for remainder; | |
| 310 | +a new | |
| 311 | +.CW @ | |
| 312 | +operator creates a sub-shell to execute a command, allowing the calling shell to be insulated | |
| 313 | +by | |
| 314 | +.CW pctl | |
| 315 | +(see | |
| 316 | +.I sh-std (1)) | |
| 317 | +from changes to name space and environment; | |
| 318 | +environment variables are stored in printable form; | |
| 319 | +a newline is allowed after a caret; | |
| 320 | +and everyone's favourite change, the colon character | |
| 321 | +.CW : ' ` | |
| 322 | +is no longer reserved in argument words | |
| 323 | +(allowing URLs to be given without quoting). | |
| 324 | +.IP \(bu | |
| 325 | +Inferno's Acme has been revised to match the version in Plan 9 (Third Edition). | |
| 326 | +In particular, the | |
| 327 | +.CW Edit | |
| 328 | +built-in has been added, allowing the use of structural regular expressions | |
| 329 | +and the | |
| 330 | +.CW sam | |
| 331 | +command language for efficient editing within | |
| 332 | +Acme, | |
| 333 | +replacing the | |
| 334 | +.CW /acme/edit | |
| 335 | +suite of commands. | |
| 336 | +The Acme panes have acquired a similar touch of colour. | |
| 337 | +.IP \(bu | |
| 338 | +Charon has also had many fixes and improvements, particularly to | |
| 339 | +Javascript extraction, frames and layout code. | |
| 340 | +Sometimes the `fix' requires making Charon mimic the interpretation of incorrect HTML | |
| 341 | +of other browsers. | |
| 342 | +The PNG image format is now supported. | |
| 343 | +Cookies are enabled by default (too many sites use them); | |
| 344 | +parsing and production of the cookie file has been repaired. | |
| 345 | +The progress bar is more compact. | |
| 346 | +Support for longer SSL keys is enabled by default. | |
| 347 | +.IP \(bu | |
| 348 | +The software installation commands | |
| 349 | +.CW install/* | |
| 350 | +have been extensively revised, | |
| 351 | +and documented by | |
| 352 | +.I archfs (4) | |
| 353 | +and | |
| 354 | +.I create (8). | |
| 355 | +They are based (though not entirely) on Russ Cox's update | |
| 356 | +package for Plan 9. | |
| 357 | +.IP \(bu | |
| 358 | +.I format (8) | |
| 359 | +can format an ordinary file, for instance to prepare flash partition | |
| 360 | +contents in a hosted environment for a native Inferno device. | |
| 361 | +.IP \(bu | |
| 362 | +.CW mount | |
| 363 | +allows the certificate file to be named directly. | |
| 364 | +.IP \(bu | |
| 365 | +.CW ns | |
| 366 | +correctly quotes the fields in its output. | |
| 367 | +.IP \(bu | |
| 368 | +.CW /services/server/config | |
| 369 | +no longer gives the unauthenticated | |
| 370 | +.CW nobody ') (` | |
| 371 | +option to | |
| 372 | +.I styx (8); | |
| 373 | +some unused entries have also been deleted. | |
| 374 | +.IP \(bu | |
| 375 | +.I srv (8) | |
| 376 | +passes all arguments to servers it spawns, including the command name. | |
| 377 | +It also ensures each server has its own process group, file descriptors | |
| 378 | +and name space. | |
| 379 | +.IP \(bu | |
| 380 | +.I stack (1) | |
| 381 | +has a new | |
| 382 | +.CW -p | |
| 383 | +option to add names to the source file search list. | |
| 384 | +.IP \(bu | |
| 385 | +.I deflate (2) | |
| 386 | +correctly detects end-of-file; | |
| 387 | +.I inflate (2) | |
| 388 | +correctly decodes the combined compressed code-length tables | |
| 389 | +.IP \(bu | |
| 390 | +Tk's handling of objects in canvases is better: | |
| 391 | +raise and lower work properly; stipple is implemented. | |
| 392 | +.IP \(bu | |
| 393 | +Tk now knows that a window pops up when resized, and adjusts | |
| 394 | +the z-order accordingly. | |
| 395 | +.IP \(bu | |
| 396 | +Tk's scroller always expands the fraction of a | |
| 397 | +.CW moveto | |
| 398 | +when it evaluates the scrolling command. | |
| 399 | +.SH | |
| 400 | +.I "New commands and modules" | |
| 401 | +.IP \(bu | |
| 402 | +.I ftpfs (4) | |
| 403 | +provides a way to make a remote FTP site visible in the Inferno name space | |
| 404 | +(it was documented in the printed manual but not previously included with the system). | |
| 405 | +.IP \(bu | |
| 406 | +.I listen (1) | |
| 407 | +provides a convenient way to listen for incoming calls to one or more Inferno services, | |
| 408 | +with optional use of | |
| 409 | +.I ssl (3) | |
| 410 | +for authentication and encryption. | |
| 411 | +This can replace the clumsy use of | |
| 412 | +.I srv (8). | |
| 413 | +.IP \(bu | |
| 414 | +.I dial | |
| 415 | +(see | |
| 416 | +.I listen (1)) | |
| 417 | +is the complement of | |
| 418 | +.I listen ; | |
| 419 | +it dials a service, with optional authentication and encryption. | |
| 420 | +.IP \(bu | |
| 421 | +.I lockfs (4) | |
| 422 | +enforces multiple reader, exclusive writer access to the contents of a name space. | |
| 423 | +.IP \(bu | |
| 424 | +The device | |
| 425 | +.I prof (3) | |
| 426 | +serves a name space for controlling the profiling of Limbo modules, | |
| 427 | +and retrieving the resulting data. | |
| 428 | +The module | |
| 429 | +.I profile (2) | |
| 430 | +offers a convenient interface, relating the profiling data to the source code. | |
| 431 | +Finally, | |
| 432 | +.I prof (1) | |
| 433 | +is the command line interface to enable profiling and display the results. | |
| 434 | +.IP \(bu | |
| 435 | +.CW uuencode | |
| 436 | +and | |
| 437 | +.CW uudecode | |
| 438 | +interpret a format used to encode binary data printably on Usenet and in mail messages; | |
| 439 | +see | |
| 440 | +.I uuencode (1). | |
| 441 | +.IP \(bu | |
| 442 | +.I Read (1) | |
| 443 | +writes to standard output the result of a single | |
| 444 | +.I sys-read (2) | |
| 445 | +of a given number of bytes from standard input, | |
| 446 | +with optional seek offset. | |
| 447 | +(See | |
| 448 | +.I getlines | |
| 449 | +in | |
| 450 | +.I sh-std (1) | |
| 451 | +for a way to read a line from standard input.) | |
| 452 | +.IP \(bu | |
| 453 | +.I Tcs (1) | |
| 454 | +uses | |
| 455 | +.I convcs (2) | |
| 456 | +to offer character set conversion on files. | |
| 457 | +.IP \(bu | |
| 458 | +.I wm-misc (1) | |
| 459 | +mentions | |
| 460 | +.CW wm/mand , | |
| 461 | +a browser for fractals, | |
| 462 | +and | |
| 463 | +.CW wm/polyhedra , | |
| 464 | +a polyhedra viewer | |
| 465 | +.IP \(bu | |
| 466 | +.I cfg (2) | |
| 467 | +provides a module to read configuration files. | |
| 468 | +.IP \(bu | |
| 469 | +.I dividers (2) | |
| 470 | +provides user-draggable dividing lines to separate Tk widgets, | |
| 471 | +allowing screen space to be allocated to widgets by dragging a dividing line. | |
| 472 | +.IP \(bu | |
| 473 | +.I imagefile (2) | |
| 474 | +offers support for reading PNG image files | |
| 475 | +.SH | |
| 476 | +.I "Interface changes and extensions" | |
| 477 | +.IP \(bu | |
| 478 | +.CW Url | |
| 479 | +.CW /module/url.m ) ( | |
| 480 | +now requires an | |
| 481 | +.CW init | |
| 482 | +function to be invoked before other functions in the module | |
| 483 | +.IP \(bu | |
| 484 | +.I convcs (2) | |
| 485 | +has changed its interface significantly (see the manual page); | |
| 486 | +it also offers support for UTF-7. | |
| 487 | +Even the module name has changed, to | |
| 488 | +.CW Convcs | |
| 489 | +(from | |
| 490 | +.CW ConvCS ). | |
| 491 | +.IP \(bu | |
| 492 | +.I plumber (8) | |
| 493 | +now returns an error to a message's sender if it cannot be plumbed, | |
| 494 | +as was previously documented; | |
| 495 | +it handles | |
| 496 | +.CW ^ | |
| 497 | +correctly in regular expressions | |
| 498 | +.IP \(bu | |
| 499 | +.I readdir (2) | |
| 500 | +returns all file names in union directories | |
| 501 | +.IP \(bu | |
| 502 | +.I string (2)'s | |
| 503 | +quoting and unquoting functions are correct and more efficient | |
| 504 | +.IP \(bu | |
| 505 | +.I styxlib (2) | |
| 506 | +forces an internal process into a new empty name space to | |
| 507 | +allow detection of the last unmount of the served space by a file server | |
| 508 | +.IP \(bu | |
| 509 | +.I translate (2) | |
| 510 | +supports writing Unicode characters in hexadecimal using Limbo's \f5\eu\fP\fIXXXX\fP | |
| 511 | +syntax | |
| 512 | +.IP \(bu | |
| 513 | +.I workdir (2) | |
| 514 | +returns a better guess at the current directory on native Inferno | |
| 515 | +(hosted implementation will be supported in the next update) | |
| 516 | +.IP \(bu | |
| 517 | +.I cs (8) | |
| 518 | +keeps a cache of recent translations; | |
| 519 | +.I ipsrv (8) | |
| 520 | +uses UDP/IP by default, not TCP/IP, for domain name lookup | |
| 521 | +.IP \(bu | |
| 522 | +.I httpd (8) | |
| 523 | +can now be said to work as documented | |
| 524 | +.IP \(bu | |
| 525 | +.I wm-sh (1) | |
| 526 | +provides a new control file | |
| 527 | +.CW /chan/shctl | |
| 528 | +to allow it to be kept informed | |
| 529 | +of the current directory (and | |
| 530 | +.CW /lib/wmsetup | |
| 531 | +defines a Shell function to do that) | |
| 532 | +and to implement buttons below the title bar, | |
| 533 | +as with | |
| 534 | +.I mash-tk (1). | |
| 535 | +.IP \(bu | |
| 536 | +A collection of playing card images has been added in | |
| 537 | +.CW /icons/cards . | |
| 538 | +.IP \(bu | |
| 539 | +.CW /lib/wmsetup | |
| 540 | +defines a | |
| 541 | +.CW cd | |
| 542 | +function to keep | |
| 543 | +.CW wm/sh | |
| 544 | +informed of the current directory; | |
| 545 | +the | |
| 546 | +.CW Web | |
| 547 | +menu item is now called | |
| 548 | +.CW Charon ; | |
| 549 | +a new | |
| 550 | +.CW Manual | |
| 551 | +entry invokes | |
| 552 | +.I wm-man (1); | |
| 553 | +and the game | |
| 554 | +.CW Tetris | |
| 555 | +has been added to the | |
| 556 | +.CW Misc | |
| 557 | +submenu. | |
| 558 | +.IP \(bu | |
| 559 | +The manual pages | |
| 560 | +.I draw-font (2), | |
| 561 | +.I draw-image (2), | |
| 562 | +and | |
| 563 | +.I draw-screen (2) | |
| 564 | +now document | |
| 565 | +.CW display | |
| 566 | +and | |
| 567 | +.CW screen | |
| 568 | +members of various data structures. | |
| 569 | +.IP \(bu | |
| 570 | +.I security-auth (2) | |
| 571 | +and | |
| 572 | +.I security-login (2) | |
| 573 | +note that | |
| 574 | +.CW keyring.m | |
| 575 | +must be included. | |
| 576 | +.IP \(bu | |
| 577 | +In | |
| 578 | +.I sh (2), | |
| 579 | +the function | |
| 580 | +.CW exec | |
| 581 | +has been renamed | |
| 582 | +.CW run , | |
| 583 | +to reflect more accurately what it does. | |
| 584 | +.IP \(bu | |
| 585 | +In | |
| 586 | +.I sys-pctl (2), | |
| 587 | +the type of the second parameter to | |
| 588 | +.CW Sys->pctl | |
| 589 | +is actually | |
| 590 | +.CW "list of int" | |
| 591 | +not | |
| 592 | +.CW "list of ref Sys->FD" . | |
| 593 | +.IP \(bu | |
| 594 | +.I ssl (3) | |
| 595 | +documents the new | |
| 596 | +.CW encalg | |
| 597 | +and | |
| 598 | +.CW hashalg | |
| 599 | +files, which list the supported algorithms. | |
| 600 | +.IP \(bu | |
| 601 | +.I canvas (9) | |
| 602 | +describes the new | |
| 603 | +.CW -winding | |
| 604 | +option | |
| 605 | +.IP \(bu | |
| 606 | +.CW /services/cs/services | |
| 607 | +lists the Software Download Server port | |
| 608 | +and removes others that are obsolete. | |
| 609 | +.IP \(bu | |
| 610 | +.CW /services/server/config | |
| 611 | +no longer gives the unauthenticated | |
| 612 | +.CW nobody ') (` | |
| 613 | +option to | |
| 614 | +.I styx (8); | |
| 615 | +some unused entries have also been deleted. | |
| 616 | +.SH | |
| 617 | +.I "Limbo compiler" | |
| 618 | +.IP \(bu | |
| 619 | +The Limbo compiler correctly clears reference values (eg, | |
| 620 | +.CW list , | |
| 621 | +.CW ref | |
| 622 | +and | |
| 623 | +.CW array ) | |
| 624 | +when they go out of scope when necessary (eg, in loops), causing the storage to be reclaimed, | |
| 625 | +and the values to be correctly | |
| 626 | +.CW nil | |
| 627 | +when the scope is next entered. | |
| 628 | +.IP \(bu | |
| 629 | +A bug that caused temporaries sometimes to be reused too early has been fixed. | |
| 630 | +.IP \(bu | |
| 631 | +The compile-time evaluation of floating-point | |
| 632 | +.CW > | |
| 633 | +does not calculate | |
| 634 | +.CW >= | |
| 635 | +instead. | |
| 636 | +.IP \(bu | |
| 637 | +A little context has been added to `syntax error' messages. | |
| 638 | +.SH | |
| 639 | +.I "Compilers and architectures" | |
| 640 | +.IP \(bu | |
| 641 | +The system now supports the Thumb variant of the ARM architecture, | |
| 642 | +including full interworking of Thumb code and 32-bit ARM code; | |
| 643 | +there is a Thumb JIT compiler for the virtual machine, and support for | |
| 644 | +Thumb mode in the disassembler and debugger. | |
| 645 | +The Thumb compiler is | |
| 646 | +.CW tc ; | |
| 647 | +the existing ARM linker | |
| 648 | +.CW 5l | |
| 649 | +links both ARM and Thumb code. | |
| 650 | +.IP \(bu | |
| 651 | +A bug in | |
| 652 | +.CW 5l | |
| 653 | +has been fixed that could very occasionally place a literal pool inside a case table. | |
| 654 | +.IP \(bu | |
| 655 | +The compilers find include files correctly under Nt. | |
| 656 | +.SH | |
| 657 | +.I "Hosted and Native Inferno" | |
| 658 | +.IP \(bu | |
| 659 | +.I Emu | |
| 660 | +has the following fixes and improvements: | |
| 661 | +.RS | |
| 662 | +.IP \- | |
| 663 | +support for logging of memory pool usage | |
| 664 | +.IP \- | |
| 665 | +FreeBSD support uses | |
| 666 | +.I rfork | |
| 667 | +not | |
| 668 | +.I pthreads . | |
| 669 | +.IP \- | |
| 670 | +Linux support no longer relies on being able to set the TSS register. | |
| 671 | +.IP \- | |
| 672 | +A memory leak when a kernel process exits has been fixed. | |
| 673 | +.IP \- | |
| 674 | +A start has been made on tidying up the audio support; the | |
| 675 | +.CW svp.c | |
| 676 | +file has gone and platforms that do not currently support audio | |
| 677 | +no longer must include a stub driver. | |
| 678 | +.IP \- | |
| 679 | +The Linux and | |
| 680 | +FreeBSD ports use an alternative implementation of Inferno graphics | |
| 681 | +under X11 that should allow the program to run under 16-bit graphics and higher. | |
| 682 | +.RE | |
| 683 | +.IP \(bu | |
| 684 | +For the native kernels only: | |
| 685 | +.RS | |
| 686 | +.IP \- | |
| 687 | +The native kernel implements Rob Pike's `lexical names' (as in Plan 9), which helps | |
| 688 | +provide more sensible data to | |
| 689 | +.I workdir (2). | |
| 690 | +The hosted Inferno implementation of lexical names will appear in a future update. | |
| 691 | +Note that | |
| 692 | +.CW /os/port/ns.c | |
| 693 | +no longer exists, and native kernel configuration files should no longer mention | |
| 694 | +.CW ns | |
| 695 | +in the | |
| 696 | +.CW port | |
| 697 | +section. | |
| 698 | +Drivers that serve a directory hierarchy might need to support the | |
| 699 | +.CW DEVDOTDOT | |
| 700 | +value for the table index in their | |
| 701 | +.CW devgen | |
| 702 | +function. | |
| 703 | +.IP \- | |
| 704 | +.CW os/ip/bootp.c | |
| 705 | +will correctly time out if there is no response. | |
| 706 | +.CW os/ip/ihbootp.c | |
| 707 | +will now work with an RFC1084 BOOTP server. | |
| 708 | +Note that both are likely to be replaced in future by | |
| 709 | +Limbo applications that do BOOTP and DHCP. | |
| 710 | +.IP \- | |
| 711 | +.CW os/pc/cga.c | |
| 712 | +provides a replacement for | |
| 713 | +.CW screen.c | |
| 714 | +for use when only a simple CGA console is needed or possible. | |
| 715 | +.IP \- | |
| 716 | +The file descriptor array is correctly freed when the file descriptor | |
| 717 | +group is closed, fixing a memory leak. | |
| 718 | +.IP \- | |
| 719 | +A few files that were left off the July 2000 CD have been included this time. | |
| 720 | +.IP \- | |
| 721 | +ARM/Thumb kernels have been implemented; those implementations | |
| 722 | +are not included in this update because the hardware is specialised but ask if you could use them. | |
| 723 | +.RE | |
| 724 | +.LP | |
| 725 | +The remaining points are common to both hosted and native Inferno: | |
| 726 | +.IP \(bu | |
| 727 | +A write on closed pipe does not produce an exception if the process has been killed. | |
| 728 | +.IP \(bu | |
| 729 | +.I Devbwrite | |
| 730 | +will not lose memory if an error is raised by the device driver (eg, interrupt). | |
| 731 | +.IP \(bu | |
| 732 | +.I ssl (3) | |
| 733 | +has | |
| 734 | +.CW encalg | |
| 735 | +and | |
| 736 | +.CW hashalg | |
| 737 | +files | |
| 738 | +.IP \(bu | |
| 739 | +.I Kfs (3) | |
| 740 | +offers | |
| 741 | +.CW readonly | |
| 742 | +and | |
| 743 | +.CW readwrite | |
| 744 | +commands, and an | |
| 745 | +.CW ro | |
| 746 | +(readonly) | |
| 747 | +option to the | |
| 748 | +.CW init | |
| 749 | +request. | |
| 750 | +.IP \(bu | |
| 751 | +.I Srv (3) | |
| 752 | +rejects attempts to create an unusable name containing a `/'. | |
| 753 | +.IP \(bu | |
| 754 | +The | |
| 755 | +.CW NODEVS | |
| 756 | +flag of | |
| 757 | +.I sys-pctl (2) | |
| 758 | +is correctly copied when the name space is duplicated. | |
| 759 | +.\" the following is only in the 386 version | |
| 760 | +.\" .IP \(bu | |
| 761 | +.\" .I Prog (3) | |
| 762 | +.\" can optionally give the correct Dis pc for the debugger even for compiled modules; if | |
| 763 | +.\" .CW cflag | |
| 764 | +.\" (or | |
| 765 | +.\" .CW -c | |
| 766 | +.\" option for | |
| 767 | +.\" .I emu ) | |
| 768 | +.\" is 2 not 1, a mapping table is retained after JIT compilation. | |
| 769 | +.SH | |
| 770 | +.I "SA1100 native" | |
| 771 | +.IP \(bu | |
| 772 | +A new | |
| 773 | +.CW archether | |
| 774 | +function in | |
| 775 | +.CW arch*.c | |
| 776 | +(when required) | |
| 777 | +is invoked by | |
| 778 | +.CW devether.c | |
| 779 | +to discover the configuration of Ethernet devices. | |
| 780 | +.IP \(bu | |
| 781 | +.CW devuart.c | |
| 782 | +supports the use of XON/XOFF; | |
| 783 | +the first line of the | |
| 784 | +.CW stat | |
| 785 | +file gives the current UART settings; | |
| 786 | +it no longer panics if an overrun occurs; | |
| 787 | +and | |
| 788 | +.CW setlength | |
| 789 | +accesses the correct structures. | |
| 790 | +.IP \(bu | |
| 791 | +The CS8900 driver | |
| 792 | +.CW ether8900.c | |
| 793 | +is more general, supporting the I/O port interface as well as the memory interface. | |
| 794 | +.IP \(bu | |
| 795 | +Obsolete definitions have been removed from several include files | |
| 796 | +(eg, | |
| 797 | +.CW io.h ) | |
| 798 | +and obsolete (typically #ifdef'd code) has been removed from source files. | |
| 799 | +.NH 1 | |
| 800 | +IDEA™ | |
| 801 | +.LP | |
| 802 | +The software includes an implementation of the IDEA encryption algorithm, | |
| 803 | +for non-commercial use. | |
| 804 | +IDEA was patented by Ascom-Tech AG (European patent EP 0 482 154 B1, US patent number | |
| 805 | +US005214703, and patent filed in Japan). | |
| 806 | +At time of writing, there was no licence fee required for noncommercial use. | |
| 807 | +If you intend to use IDEA encryption commercially with Inferno, you should consult | |
| 808 | +.CW http://www.it-sec.com/idea_lic_policy.html | |
| 809 | +for the current licensing policy of iT_SEC Systec Ltd, which currently holds the patents and trademark. | |
| 810 | +Note that IDEA is not required for | |
| 811 | +successful use of Inferno. | |
| 812 | +It is not by default enabled by | |
| 813 | +.I rstyxd (8), | |
| 814 | +and otherwise is used only by SSL3 (for the browser), in | |
| 815 | +.CW /appl/lib/crypt/ssl3.b , | |
| 816 | +where it can be disabled. | |
| 817 | +.NH 1 | |
| 818 | +Updating the July 2000 Full Source release | |
| 819 | +.LP | |
| 820 | +A set of update packages for the July 2000 release is provided in the directory | |
| 821 | +.CW /updates | |
| 822 | +on this June 2001 CD. | |
| 823 | +You should install the updates as the host operating system user who owns the Inferno files and directories | |
| 824 | +on your system. | |
| 825 | +You might like to take a backup copy of the existing tree, just in case. | |
| 826 | +Do the following to update the installation. | |
| 827 | +(Next time we hope to provide a more automated scheme. | |
| 828 | +You might check | |
| 829 | +.CW www.vitanuova.com/inferno/ | |
| 830 | +to see if there are any more recent instructions.) | |
| 831 | +.IP 1. | |
| 832 | +Copy the directory | |
| 833 | +.CW updates | |
| 834 | +and its subdirectories from the CD to a directory | |
| 835 | +.CW updates | |
| 836 | +in the root of your existing Inferno hierarchy. | |
| 837 | +Make sure there is sufficient space in the file system holding that hierarchy. | |
| 838 | +If all platform files are copied and installed, about 45 Mbytes will be needed | |
| 839 | +to hold the compressed update packages in | |
| 840 | +.CW updates , | |
| 841 | +with a further | |
| 842 | +35 Mbytes needed for an temporary uncompressed copy | |
| 843 | +of the largest package, and allow 10 Mbytes for new additional material, giving | |
| 844 | +90 Mbytes in all. | |
| 845 | +The | |
| 846 | +.CW updates | |
| 847 | +directory can be removed after installation. | |
| 848 | +.IP 2. | |
| 849 | +Start the existing Inferno | |
| 850 | +.I emu ; | |
| 851 | +it will be quicker if you use the | |
| 852 | +.CW -c1 | |
| 853 | +option to force compiled mode. | |
| 854 | +It is best to use only the Inferno console; do not start the window system, since | |
| 855 | +the updates will change files in the running system. | |
| 856 | +On the other hand, it is a good idea to make the window in the host | |
| 857 | +operating system a scrolling one, so that you can scroll back to | |
| 858 | +see any errors. | |
| 859 | +All following commands are run in the Inferno environment. | |
| 860 | +.IP 3. | |
| 861 | +Change to the directory | |
| 862 | +.CW updates | |
| 863 | +and load the standard Inferno shell module: | |
| 864 | +.RS | |
| 865 | +.P1 | |
| 866 | +cd /updates | |
| 867 | +load std | |
| 868 | +.P2 | |
| 869 | +.RE | |
| 870 | +.NE 1i | |
| 871 | +.IP 4. | |
| 872 | +Unpack the updated installation software: | |
| 873 | +.RS | |
| 874 | +.P1 | |
| 875 | +gunzip <install.tgz | {cd /; gettar} | |
| 876 | +.P2 | |
| 877 | +.RE | |
| 878 | +.IP 5. | |
| 879 | +Update the installed Inferno, source and utility source directories | |
| 880 | +using the script | |
| 881 | +.CW applybase : | |
| 882 | +.RS | |
| 883 | +.P1 | |
| 884 | +sh ./applybase | |
| 885 | +.P2 | |
| 886 | +.LP | |
| 887 | +That script updates the | |
| 888 | +.CW inferno , | |
| 889 | +.CW src | |
| 890 | +and | |
| 891 | +.CW utils | |
| 892 | +packages. | |
| 893 | +You will see one warning: | |
| 894 | +.P1 | |
| 895 | +skipping /dis/install/inst.dis: locally modified | |
| 896 | +.P2 | |
| 897 | +because that file was updated by step 4. | |
| 898 | +You might see other warnings if you have modified any other files from the original release. | |
| 899 | +.RE | |
| 900 | +.IP 6. | |
| 901 | +Update one or more platform specific files for your platform(s). | |
| 902 | +The directories are named after the platforms: | |
| 903 | +.CW Solaris | |
| 904 | +for Solaris, | |
| 905 | +.CW Plan9 | |
| 906 | +for Plan 9, | |
| 907 | +.CW Nt | |
| 908 | +for all Windows systems, | |
| 909 | +and so on. | |
| 910 | +For each | |
| 911 | +.I platform | |
| 912 | +that you run, do: | |
| 913 | +.RS | |
| 914 | +.P1 | |
| 915 | +for (a in \fIplatform\fP/*) {install/inst -v -t $a} | |
| 916 | +.P2 | |
| 917 | +.RE | |
| 918 | +.IP 7. | |
| 919 | +Quit | |
| 920 | +.I emu . | |
| 921 | +The new version of | |
| 922 | +.I emu | |
| 923 | +will be called | |
| 924 | +.CW emu.new | |
| 925 | +in the platform-specific directory | |
| 926 | +(eg, | |
| 927 | +.CW Solaris/sparc/bin/emu.new ). | |
| 928 | +Rename the old | |
| 929 | +.CW emu | |
| 930 | +file as | |
| 931 | +.CW emu.old , | |
| 932 | +then rename the new | |
| 933 | +.CW emu.new | |
| 934 | +as | |
| 935 | +.CW emu | |
| 936 | +on Plan 9 and Unix systems, | |
| 937 | +or | |
| 938 | +.CW emu.exe | |
| 939 | +on Windows. | |
| 940 | +When run, it should announce itself as | |
| 941 | +``Inferno Third Edition (18 Jun 2001)''. | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,2519 @@ | ||
| 1 | +.am DS | |
| 2 | +.ft I | |
| 3 | +.. | |
| 4 | +.am DE | |
| 5 | +.ft R | |
| 6 | +.. | |
| 7 | +.ta 1i 2.3i 4.5i (optional to set tabs) | |
| 8 | +.TL | |
| 9 | +Acid Reference Manual | |
| 10 | +.AU | |
| 11 | +Phil Winterbottom | |
| 12 | +philw@plan9.bell-labs.com | |
| 13 | +.FS | |
| 14 | +\l'1i' | |
| 15 | +.br | |
| 16 | +Previously appeared with minor differences as the | |
| 17 | +``Acid Manual'' in | |
| 18 | +.I "Plan 9 Programmer's Manual, Volume 2 (Second Edition)". | |
| 19 | +.FE | |
| 20 | +.SH | |
| 21 | +Introduction | |
| 22 | +.PP | |
| 23 | +Acid is a general purpose, source level symbolic debugger. | |
| 24 | +The debugger is built around a simple command language. | |
| 25 | +The command language, distinct from the language of the program being debugged, | |
| 26 | +provides a flexible user interface that allows the debugger | |
| 27 | +interface to be customized for a specific application or architecture. | |
| 28 | +Moreover, it provides an opportunity to write test and | |
| 29 | +verification code independently of a program's source code. | |
| 30 | +Acid is able to debug multiple | |
| 31 | +processes provided they share a common set of symbols, such as the processes in | |
| 32 | +a threaded program. | |
| 33 | +.PP | |
| 34 | +Like other language-based solutions, Acid presents a poor user interface but | |
| 35 | +provides a powerful debugging tool. | |
| 36 | +Application of Acid to hard problems is best approached by writing functions off-line | |
| 37 | +(perhaps loading them with the | |
| 38 | +.CW include | |
| 39 | +function or using the support provided by | |
| 40 | +.I acme (1)), | |
| 41 | +rather than by trying to type intricate Acid operations | |
| 42 | +at the interactive prompt. | |
| 43 | +.PP | |
| 44 | +Acid allows the execution of a program to be controlled by operating on its | |
| 45 | +state while it is stopped and by monitoring and controlling its execution | |
| 46 | +when it is running. Each program action that causes a change | |
| 47 | +of execution state is reflected by the execution | |
| 48 | +of an Acid function, which may be user defined. | |
| 49 | +A library of default functions provides the functionality of a normal debugger. | |
| 50 | +.PP | |
| 51 | +On Plan 9, a process is controlled by writing messages to a control file in the | |
| 52 | +.I proc (3) | |
| 53 | +file system. Each control message has a corresponding Acid function, which | |
| 54 | +sends the message to the process. These functions take a process id | |
| 55 | +.I pid ) ( | |
| 56 | +as an | |
| 57 | +argument. The memory and text file of the program may be manipulated using | |
| 58 | +the indirection operators. The symbol table, including source cross reference, | |
| 59 | +is available to an Acid program. The combination allows complex operations | |
| 60 | +to be performed both in terms of control flow and data manipulation. | |
| 61 | +.SH | |
| 62 | +Input format and \f(CWwhatis\fP | |
| 63 | +.PP | |
| 64 | +Comments start with | |
| 65 | +.CW // | |
| 66 | +and continue to the end of the line. | |
| 67 | +Input is a series of statements and expressions separated by semicolons. | |
| 68 | +At the top level of the interpreter, the builtin function | |
| 69 | +.CW print | |
| 70 | +is called automatically to display the result of all expressions except function calls. | |
| 71 | +A unary | |
| 72 | +.CW + | |
| 73 | +may be used as a shorthand to force the result of a function call to be printed. | |
| 74 | +.PP | |
| 75 | +Also at the top level, newlines are treated as semicolons | |
| 76 | +by the parser, so semicolons are unnecessary when evaluating expressions. | |
| 77 | +.PP | |
| 78 | +When Acid starts, it loads the default program modules, | |
| 79 | +enters interactive mode, and prints a prompt. In this state Acid accepts | |
| 80 | +either function definitions or statements to be evaluated. | |
| 81 | +In this interactive mode | |
| 82 | +statements are evaluated immediately, while function definitions are | |
| 83 | +stored for later invocation. | |
| 84 | +.PP | |
| 85 | +The | |
| 86 | +.CW whatis | |
| 87 | +operator can be used to report the state of identifiers known to the interpreter. | |
| 88 | +With no argument, | |
| 89 | +.CW whatis | |
| 90 | +reports the name of all defined Acid functions; when supplied with an identifier | |
| 91 | +as an argument it reports any variable, function, or type definition | |
| 92 | +associated with the identifier. | |
| 93 | +Because of the way the interpreter handles semicolons, | |
| 94 | +the result of a | |
| 95 | +.CW whatis | |
| 96 | +statement can be returned directly to Acid without adding semicolons. | |
| 97 | +A syntax error or interrupt returns Acid to the normal evaluation | |
| 98 | +mode; any partially evaluated definitions are lost. | |
| 99 | +.SH | |
| 100 | +Using the Library Functions | |
| 101 | +.PP | |
| 102 | +After loading the program binary, Acid loads the portable and architecture-specific | |
| 103 | +library functions that form the standard debugging environment. | |
| 104 | +These files are Acid source code and are human-readable. | |
| 105 | +The following example uses the standard debugging library to show how | |
| 106 | +language and program interact: | |
| 107 | +.P1 | |
| 108 | +% acid /bin/ls | |
| 109 | +/bin/ls:mips plan 9 executable | |
| 110 | + | |
| 111 | +/sys/lib/acid/port | |
| 112 | +/sys/lib/acid/mips | |
| 113 | +acid: new() | |
| 114 | +75721: system call _main ADD $-0x14,R29 | |
| 115 | +75721: breakpoint main+0x4 MOVW R31,0x0(R29) | |
| 116 | +acid: bpset(ls) | |
| 117 | +acid: cont() | |
| 118 | +75721: breakpoint ls ADD $-0x16c8,R29 | |
| 119 | +acid: stk() | |
| 120 | +At pc:0x0000141c:ls /sys/src/cmd/ls.c:87 | |
| 121 | +ls(s=0x0000004d,multi=0x00000000) /sys/src/cmd/ls.c:87 | |
| 122 | + called from main+0xf4 /sys/src/cmd/ls.c:79 | |
| 123 | +main(argc=0x00000000,argv=0x7ffffff0) /sys/src/cmd/ls.c:48 | |
| 124 | + called from _main+0x20 /sys/src/libc/mips/main9.s:10 | |
| 125 | +acid: PC | |
| 126 | +0xc0000f60 | |
| 127 | +acid: *PC | |
| 128 | +0x0000141c | |
| 129 | +acid: ls | |
| 130 | +0x0000141c | |
| 131 | +.P2 | |
| 132 | +The function | |
| 133 | +.CW new() | |
| 134 | +creates a new process and stops it at the first instruction. | |
| 135 | +This change in state is reported by a call to the | |
| 136 | +Acid function | |
| 137 | +.CW stopped , | |
| 138 | +which is called by the interpreter whenever the debugged program stops. | |
| 139 | +.CW Stopped | |
| 140 | +prints the status line giving the pid, the reason the program stopped | |
| 141 | +and the address and instruction at the current PC. | |
| 142 | +The function | |
| 143 | +.CW bpset | |
| 144 | +makes an entry in the breakpoint table and plants a breakpoint in memory. | |
| 145 | +The | |
| 146 | +.CW cont | |
| 147 | +function continues the process, allowing it to run until some condition | |
| 148 | +causes it to stop. In this case the program hits the breakpoint placed on | |
| 149 | +the function | |
| 150 | +.CW ls | |
| 151 | +in the C program. Once again the | |
| 152 | +.CW stopped | |
| 153 | +routine is called to print the status of the program. The function | |
| 154 | +.CW stk | |
| 155 | +prints a C stack trace of the current process. It is implemented using | |
| 156 | +a builtin Acid function that returns the stack trace as a list; the code | |
| 157 | +that formats the information is all written in Acid. | |
| 158 | +The Acid variable | |
| 159 | +.CW PC | |
| 160 | +holds the address of the | |
| 161 | +cell where the current value of the processor register | |
| 162 | +.CW PC | |
| 163 | +is stored. By indirecting through | |
| 164 | +the value of | |
| 165 | +.CW PC | |
| 166 | +the address where the program is stopped can be found. | |
| 167 | +All of the processor registers are available by the same mechanism. | |
| 168 | +.SH | |
| 169 | +Types | |
| 170 | +.PP | |
| 171 | +An Acid variable has one of four types: | |
| 172 | +.I integer , | |
| 173 | +.I float , | |
| 174 | +.I list , | |
| 175 | +or | |
| 176 | +.I string . | |
| 177 | +The type of a variable is inferred from the type of the right-hand | |
| 178 | +side of the assignment expression which last set its value. | |
| 179 | +Referencing a variable that has not yet | |
| 180 | +been assigned draws a "used but not set" error. Many of the operators may | |
| 181 | +be applied to more than | |
| 182 | +one type; for these operators the action of the operator is determined by | |
| 183 | +the types of its operands. The action of each operator is defined in the | |
| 184 | +.I Expressions | |
| 185 | +section of this manual. | |
| 186 | +.SH | |
| 187 | +Variables | |
| 188 | +.PP | |
| 189 | +Acid has three kinds of variables: variables defined by the symbol table | |
| 190 | +of the debugged program, variables that are defined and maintained | |
| 191 | +by the interpreter as the debugged program changes state, and variables | |
| 192 | +defined and used by Acid programs. | |
| 193 | +.PP | |
| 194 | +Some examples of variables maintained by the interpreter are the register | |
| 195 | +pointers listed by name in the Acid list variable | |
| 196 | +.CW registers , | |
| 197 | +and the symbol table listed by name and contents in the Acid variable | |
| 198 | +.CW symbols . | |
| 199 | +.PP | |
| 200 | +The variable | |
| 201 | +.CW pid | |
| 202 | +is updated by the interpreter to select the most recently created process | |
| 203 | +or the process selected by the | |
| 204 | +.CW setproc | |
| 205 | +builtin function. | |
| 206 | +.SH 1 | |
| 207 | +Formats | |
| 208 | +.PP | |
| 209 | +In addition to a type, variables have formats. The format is a code | |
| 210 | +letter that determines the printing style and the effect of some of the | |
| 211 | +operators on that variable. The format codes are derived from the format | |
| 212 | +letters used by | |
| 213 | +.I db (1). | |
| 214 | +By default, symbol table variables and numeric constants | |
| 215 | +are assigned the format code | |
| 216 | +.CW X , | |
| 217 | +which specifies 32-bit hexadecimal. | |
| 218 | +Printing a variable with this code yields the output | |
| 219 | +.CW 0x00123456 . | |
| 220 | +The format code of a variable may be changed from the default by using the | |
| 221 | +builtin function | |
| 222 | +.CW fmt . | |
| 223 | +This function takes two arguments, an expression and a format code. After | |
| 224 | +the expression is evaluated the new format code is attached to the result | |
| 225 | +and forms the return value from | |
| 226 | +.CW fmt . | |
| 227 | +The backslash operator is a short form of | |
| 228 | +.CW fmt . | |
| 229 | +The format supplied by the backslash operator must be the format character | |
| 230 | +rather than an expression. | |
| 231 | +If the result is assigned to a variable the new format code is maintained | |
| 232 | +in the variable. For example: | |
| 233 | +.P1 | |
| 234 | +acid: x=10 | |
| 235 | +acid: print(x) | |
| 236 | +0x0000000a | |
| 237 | +acid: x = fmt(x, 'D') | |
| 238 | +acid: print(x, fmt(x, 'X')) | |
| 239 | +10 0x0000000a | |
| 240 | +acid: x | |
| 241 | +10 | |
| 242 | +acid: x\eo | |
| 243 | +12 | |
| 244 | +.P2 | |
| 245 | +The supported format characters are: | |
| 246 | +.RS | |
| 247 | +.IP \f(CWo\fP | |
| 248 | +Print two-byte integer in octal. | |
| 249 | +.IP \f(CWO\fP | |
| 250 | +Print four-byte integer in octal. | |
| 251 | +.IP \f(CWq\fP | |
| 252 | +Print two-byte integer in signed octal. | |
| 253 | +.IP \f(CWQ\fP | |
| 254 | +Print four-byte integer in signed octal. | |
| 255 | +.IP \f(CWB\fP | |
| 256 | +Print four-byte integer in binary. | |
| 257 | +.IP \f(CWd\fP | |
| 258 | +Print two-byte integer in signed decimal. | |
| 259 | +.IP \f(CWD\fP | |
| 260 | +Print four-byte integer in signed decimal. | |
| 261 | +.IP \f(CWY\fP | |
| 262 | +Print eight-byte integer in signed decimal. | |
| 263 | +.IP \f(CWx\fP | |
| 264 | +Print two-byte integer in hexadecimal. | |
| 265 | +.IP \f(CWX\fP | |
| 266 | +Print four-byte integer in hexadecimal. | |
| 267 | +.IP \f(CWu\fP | |
| 268 | +Print two-byte integer in unsigned decimal. | |
| 269 | +.IP \f(CWU\fP | |
| 270 | +Print four-byte integer in unsigned decimal. | |
| 271 | +.IP \f(CWZ\fP | |
| 272 | +Print eight-byte integer in unsigned decimal. | |
| 273 | +.IP \f(CWf\fP | |
| 274 | +Print single-precision floating point number. | |
| 275 | +.IP \f(CWF\fP | |
| 276 | +Print double-precision floating point number. | |
| 277 | +.IP \f(CWg\fP | |
| 278 | +Print a single precision floating point number in string format. | |
| 279 | +.IP \f(CWG\fP | |
| 280 | +Print a double precision floating point number in string format. | |
| 281 | +.IP \f(CWb\fP | |
| 282 | +Print byte in hexadecimal. | |
| 283 | +.IP \f(CWc\fP | |
| 284 | +Print byte as an ASCII character. | |
| 285 | +.IP \f(CWC\fP | |
| 286 | +Like | |
| 287 | +.CW c , | |
| 288 | +with | |
| 289 | +printable ASCII characters represented normally and | |
| 290 | +others printed in the form \f(CW\ex\fInn\fR. | |
| 291 | +.IP \f(CWs\fP | |
| 292 | +Interpret the addressed bytes as UTF characters | |
| 293 | +and print successive characters until a zero byte is reached. | |
| 294 | +.IP \f(CWr\fP | |
| 295 | +Print a two-byte integer as a rune. | |
| 296 | +.IP \f(CWR\fP | |
| 297 | +Print successive two-byte integers as runes | |
| 298 | +until a zero rune is reached. | |
| 299 | +.IP \f(CWY\fP | |
| 300 | +Print successive eight-byte integers in hexadecimal. | |
| 301 | +.IP \f(CWi\fP | |
| 302 | +Print as machine instructions. | |
| 303 | +.IP \f(CWI\fP | |
| 304 | +As | |
| 305 | +.CW i | |
| 306 | +above, but print the machine instructions in | |
| 307 | +an alternate form if possible: | |
| 308 | +.CW sunsparc | |
| 309 | +and | |
| 310 | +.CW mipsco | |
| 311 | +reproduce the manufacturers' syntax. | |
| 312 | +.IP \f(CWa\fP | |
| 313 | +Print the value in symbolic form. | |
| 314 | +.RE | |
| 315 | +.SH | |
| 316 | +Complex types | |
| 317 | +.PP | |
| 318 | +Acid permits the definition of the layout of memory. | |
| 319 | +The usual method is to use the | |
| 320 | +.CW -a | |
| 321 | +flag of the compilers to produce Acid-language descriptions of data structures (see | |
| 322 | +.I 2c (1)) | |
| 323 | +although such definitions can be typed interactively. | |
| 324 | +The keywords | |
| 325 | +.CW complex , | |
| 326 | +.CW adt , | |
| 327 | +.CW aggr , | |
| 328 | +and | |
| 329 | +.CW union | |
| 330 | +are all equivalent; the compiler uses the synonyms to document the declarations. | |
| 331 | +A complex type is described as a set of members, each containing a format letter, | |
| 332 | +an offset in the structure, and a name. For example, the C structure | |
| 333 | +.P1 | |
| 334 | +struct List { | |
| 335 | + int type; | |
| 336 | + struct List *next; | |
| 337 | +}; | |
| 338 | +.P2 | |
| 339 | +is described by the Acid statement | |
| 340 | +.P1 | |
| 341 | +complex List { | |
| 342 | + 'D' 0 type; | |
| 343 | + 'X' 4 next; | |
| 344 | +}; | |
| 345 | +.P2 | |
| 346 | +.SH | |
| 347 | +Scope | |
| 348 | +.PP | |
| 349 | +Variables are global unless they are either parameters to functions | |
| 350 | +or are declared as | |
| 351 | +.CW local | |
| 352 | +in a function body. Parameters and local variables are available only in | |
| 353 | +the body of the function in which they are instantiated. | |
| 354 | +Variables are dynamically bound: if a function declares a local variable | |
| 355 | +with the same name as a global variable, the global variable will be hidden | |
| 356 | +whenever the function is executing. | |
| 357 | +For example, if a function | |
| 358 | +.CW f | |
| 359 | +has a local called | |
| 360 | +.CW main , | |
| 361 | +any function called below | |
| 362 | +.CW f | |
| 363 | +will see the local version of | |
| 364 | +.CW main , | |
| 365 | +not the external symbol. | |
| 366 | +.SH 1 | |
| 367 | +Addressing | |
| 368 | +.PP | |
| 369 | +Since the symbol table specifies addresses, | |
| 370 | +to access the value of program variables | |
| 371 | +an extra level of indirection | |
| 372 | +is required relative to the source code. | |
| 373 | +For consistency, the registers are maintained as pointers as well; Acid variables with the names | |
| 374 | +of processor registers point to cells holding the saved registers. | |
| 375 | +.PP | |
| 376 | +The location in a file or memory image associated with | |
| 377 | +an address is calculated from a map | |
| 378 | +associated with the file. | |
| 379 | +Each map contains one or more quadruples (\c | |
| 380 | +.I t , | |
| 381 | +.I b , | |
| 382 | +.I e , | |
| 383 | +.I f \|), | |
| 384 | +defining a segment named | |
| 385 | +.I t | |
| 386 | +(usually | |
| 387 | +.CW text , | |
| 388 | +.CW data , | |
| 389 | +.CW regs , | |
| 390 | +or | |
| 391 | +.CW fpregs ) | |
| 392 | +mapping addresses in the range | |
| 393 | +.I b | |
| 394 | +through | |
| 395 | +.I e | |
| 396 | +to the part of the file | |
| 397 | +beginning at | |
| 398 | +offset | |
| 399 | +.I f . | |
| 400 | +The memory model of a Plan 9 process assumes | |
| 401 | +that segments are disjoint. There | |
| 402 | +can be more than one segment of a given type (e.g., a process | |
| 403 | +may have more than one text segment) but segments | |
| 404 | +may not overlap. | |
| 405 | +An address | |
| 406 | +.I a | |
| 407 | +is translated | |
| 408 | +to a file address | |
| 409 | +by finding a segment | |
| 410 | +for which | |
| 411 | +.I b | |
| 412 | ++ | |
| 413 | +.I a | |
| 414 | +< | |
| 415 | +.I e ; | |
| 416 | +the location in the file | |
| 417 | +is then | |
| 418 | +.I address | |
| 419 | ++ | |
| 420 | +.I f | |
| 421 | +\- | |
| 422 | +.I b . | |
| 423 | +.PP | |
| 424 | +Usually, | |
| 425 | +the text and initialized data of a program | |
| 426 | +are mapped by segments called | |
| 427 | +.CW text | |
| 428 | +and | |
| 429 | +.CW data . | |
| 430 | +Since a program file does not contain bss, stack, or register data, | |
| 431 | +these data are | |
| 432 | +not mapped by the data segment. | |
| 433 | +The text segment is mapped similarly in the memory image of | |
| 434 | +a normal (i.e., non-kernel) process. | |
| 435 | +However, the segment called | |
| 436 | +.CW *data | |
| 437 | +maps memory from the beginning to the end of the program's data space. | |
| 438 | +This region contains the program's static data, the bss, the | |
| 439 | +heap and the stack. A segment | |
| 440 | +called | |
| 441 | +.CW *regs | |
| 442 | +maps the registers; | |
| 443 | +.CW *fpregs | |
| 444 | +maps the floating point registers (if they exist). | |
| 445 | +.PP | |
| 446 | +Sometimes it is useful to define a map with a single segment | |
| 447 | +mapping the region from 0 to 0xFFFFFFFF; such a map | |
| 448 | +allows the entire file to be examined | |
| 449 | +without address translation. The builtin function | |
| 450 | +.CW map | |
| 451 | +examines and modifies Acid's map for a process. | |
| 452 | +.SH 1 | |
| 453 | +Name Conflicts | |
| 454 | +.PP | |
| 455 | +Name conflicts between keywords in the Acid language, symbols in the program, | |
| 456 | +and previously defined functions are resolved when the interpreter starts up. | |
| 457 | +Each name is made unique by prefixing enough | |
| 458 | +.CW $ | |
| 459 | +characters to the front of the name to make it unique. Acid reports | |
| 460 | +a list of each name change at startup. The report looks like this: | |
| 461 | +.P1 | |
| 462 | +/bin/sam: mips plan 9 executable | |
| 463 | +/lib/acid/port | |
| 464 | +/lib/acid/mips | |
| 465 | +Symbol renames: | |
| 466 | + append=$append T/0xa4e40 | |
| 467 | +acid: | |
| 468 | +.P2 | |
| 469 | +The symbol | |
| 470 | +.CW append | |
| 471 | +is both a keyword and a text symbol in the program. The message reports | |
| 472 | +that the text symbol is now named | |
| 473 | +.CW $append . | |
| 474 | +.SH | |
| 475 | +Expressions | |
| 476 | +.PP | |
| 477 | +Operators have the same | |
| 478 | +binding and precedence as in C. | |
| 479 | +For operators of equal precedence, expressions are evaluated from left to right. | |
| 480 | +.SH 1 | |
| 481 | +Boolean expressions | |
| 482 | +.PP | |
| 483 | +If an expression is evaluated for a boolean condition the test | |
| 484 | +performed depends on the type of the result. If the result is of | |
| 485 | +.I integer | |
| 486 | +or | |
| 487 | +.I floating | |
| 488 | +type the result is true if the value is non-zero. If the expression is a | |
| 489 | +.I list | |
| 490 | +the result is true if there are any members in the list. | |
| 491 | +If the expression is a | |
| 492 | +.I string | |
| 493 | +the result is true if there are any characters in the string. | |
| 494 | +.DS | |
| 495 | + primary-expression: | |
| 496 | + identifier | |
| 497 | + identifier \f(CW:\fP identifier | |
| 498 | + constant | |
| 499 | + \f(CW(\fP expression \f(CW)\fP | |
| 500 | + \f(CW{\fP elist \f(CW}\fP | |
| 501 | + | |
| 502 | + elist: | |
| 503 | + expression | |
| 504 | + elist , expression | |
| 505 | +.DE | |
| 506 | +An identifier may be any legal Acid variable. The colon operator returns the | |
| 507 | +address of parameters or local variables in the current stack of a program. | |
| 508 | +For example: | |
| 509 | +.P1 | |
| 510 | +*main:argc | |
| 511 | +.P2 | |
| 512 | +prints the number of arguments passed into main. Local variables and parameters | |
| 513 | +can only be referenced after the frame has been established. It may be necessary to | |
| 514 | +step a program over the first few instructions of a breakpointed function to properly set | |
| 515 | +the frame. | |
| 516 | +.PP | |
| 517 | +Constants follow the same lexical rules as C. | |
| 518 | +A list of expressions delimited by braces forms a list constructor. | |
| 519 | +A new list is produced by evaluating each expression when the constructor is executed. | |
| 520 | +The empty list is formed from | |
| 521 | +.CW {} . | |
| 522 | +.P1 | |
| 523 | +acid: x = 10 | |
| 524 | +acid: l = { 1, x, 2\eD } | |
| 525 | +acid: x = 20 | |
| 526 | +acid: l | |
| 527 | +{0x00000001 , 0x0000000a , 2 } | |
| 528 | +.P2 | |
| 529 | +.SH 1 | |
| 530 | +Lists | |
| 531 | +.PP | |
| 532 | +Several operators manipulate lists. | |
| 533 | +.DS | |
| 534 | + list-expression: | |
| 535 | + primary-expression | |
| 536 | + \f(CWhead\fP primary-expression | |
| 537 | + \f(CWtail\fP primary-expression | |
| 538 | + \f(CWappend\fP expression \f(CW,\fP primary-expression | |
| 539 | + \f(CWdelete\fP expression \f(CW,\fP primary-expression | |
| 540 | +.DE | |
| 541 | +The | |
| 542 | +.I primary-expression | |
| 543 | +for | |
| 544 | +.CW head | |
| 545 | +and | |
| 546 | +.CW tail | |
| 547 | +must yield a value of type | |
| 548 | +.I list . | |
| 549 | +If there are no elements in the list the value of | |
| 550 | +.CW head | |
| 551 | +or | |
| 552 | +.CW tail | |
| 553 | +will be the empty list. Otherwise | |
| 554 | +.CW head | |
| 555 | +evaluates to the first element of the list and | |
| 556 | +.CW tail | |
| 557 | +evaluates to the rest. | |
| 558 | +.P1 | |
| 559 | +acid: head {} | |
| 560 | +{} | |
| 561 | +acid: head {1, 2, 3, 4} | |
| 562 | +0x00000001 | |
| 563 | +acid: tail {1, 2, 3, 4} | |
| 564 | +{0x00000002 , 0x00000003 , 0x00000004 } | |
| 565 | +.P2 | |
| 566 | +The first operand of | |
| 567 | +.CW append | |
| 568 | +and | |
| 569 | +.CW delete | |
| 570 | +must be an expression that yields a | |
| 571 | +.I list . | |
| 572 | +.CW Append | |
| 573 | +places the result of evaluating | |
| 574 | +.I primary-expression | |
| 575 | +at the end of the list. | |
| 576 | +The | |
| 577 | +.I primary-expression | |
| 578 | +supplied to | |
| 579 | +.CW delete | |
| 580 | +must evaluate to an integer; | |
| 581 | +.CW delete | |
| 582 | +removes the | |
| 583 | +.I n 'th | |
| 584 | +item from the list, where | |
| 585 | +.I n | |
| 586 | +is integral value of | |
| 587 | +.I primary-expression. | |
| 588 | +List indices are zero-based. | |
| 589 | +.P1 | |
| 590 | + acid: append {1, 2}, 3 | |
| 591 | + {0x00000001 , 0x00000002 , 0x00000003 } | |
| 592 | + acid: delete {1, 2, 3}, 1 | |
| 593 | + {0x00000001 , 0x00000003 } | |
| 594 | +.P2 | |
| 595 | +.PP | |
| 596 | +Assigning a list to a variable copies a reference to the list; if a list variable | |
| 597 | +is copied it still points at the same list. To copy a list, the elements must | |
| 598 | +be copied piecewise using | |
| 599 | +.CW head | |
| 600 | +and | |
| 601 | +.CW append . | |
| 602 | +.SH 1 | |
| 603 | +Operators | |
| 604 | +.PP | |
| 605 | +.DS | |
| 606 | + postfix-expression: | |
| 607 | + list-expression | |
| 608 | + postfix-expression \f(CW[\fP expression \f(CW]\fP | |
| 609 | + postfix-expression \f(CW(\fP argument-list \f(CW)\fP | |
| 610 | + postfix-expression \f(CW.\fP tag | |
| 611 | + postfix-expression \f(CW->\fP tag | |
| 612 | + postfix-expression \f(CW++\fP | |
| 613 | + postfix-expression \f(CW--\fP | |
| 614 | + | |
| 615 | + argument-list: | |
| 616 | + expression | |
| 617 | + argument-list , expression | |
| 618 | +.DE | |
| 619 | +The | |
| 620 | +.CW [ | |
| 621 | +.I expression | |
| 622 | +.CW ] | |
| 623 | +operator performs indexing. | |
| 624 | +The indexing expression must result in an expression of | |
| 625 | +.I integer | |
| 626 | +type, say | |
| 627 | +.I n . | |
| 628 | +The operation depends on the type of | |
| 629 | +.I postfix-expression . | |
| 630 | +If the | |
| 631 | +.I postfix-expression | |
| 632 | +yields an | |
| 633 | +.I integer | |
| 634 | +it is assumed to be the base address of an array in the memory image. | |
| 635 | +The index offsets into this array; the size of the array members is | |
| 636 | +determined by the format associated with the | |
| 637 | +.I postfix-expression . | |
| 638 | +If the | |
| 639 | +.I postfix-expression | |
| 640 | +yields a | |
| 641 | +.I string | |
| 642 | +the index operator fetches the | |
| 643 | +.I n 'th | |
| 644 | +character | |
| 645 | +of the string. If the index points beyond the end | |
| 646 | +of the string, a zero is returned. | |
| 647 | +If the | |
| 648 | +.I postfix-expression | |
| 649 | +yields a | |
| 650 | +.I list | |
| 651 | +then the indexing operation returns the | |
| 652 | +.I n 'th | |
| 653 | +item of the list. | |
| 654 | +If the list contains less than | |
| 655 | +.I n | |
| 656 | +items the empty list | |
| 657 | +.CW {} | |
| 658 | +is returned. | |
| 659 | +.PP | |
| 660 | +The | |
| 661 | +.CW ++ | |
| 662 | +and | |
| 663 | +.CW -- | |
| 664 | +operators increment and decrement integer variables. | |
| 665 | +The amount of increment or decrement depends on the format code. These postfix | |
| 666 | +operators return the value of the variable before the increment or decrement | |
| 667 | +has taken place. | |
| 668 | +.DS | |
| 669 | + unary-expression: | |
| 670 | + postfix-expression | |
| 671 | + \f(CW++\fP unary-expression | |
| 672 | + \f(CW--\fP unary-expression | |
| 673 | + | |
| 674 | + unary-operator: one of | |
| 675 | + \f(CW*\fP \f(CW@\fP \f(CW+\fP \f(CW-\fP ~ \f(CW!\fP | |
| 676 | +.DE | |
| 677 | +The operators | |
| 678 | +.CW * | |
| 679 | +and | |
| 680 | +.CW @ | |
| 681 | +are the indirection operators. | |
| 682 | +.CW @ | |
| 683 | +references a value from the text file of the program being debugged. | |
| 684 | +The size of the value depends on the format code. The | |
| 685 | +.CW * | |
| 686 | +operator fetches a value from the memory image of a process. If either | |
| 687 | +operator appears on the left-hand side of an assignment statement, either the file | |
| 688 | +or memory will be written. The file can only be modified when Acid is invoked | |
| 689 | +with the | |
| 690 | +.CW -w | |
| 691 | +option. | |
| 692 | +The prefix | |
| 693 | +.CW ++ | |
| 694 | +and | |
| 695 | +.CW -- | |
| 696 | +operators perform the same operation as their postfix counterparts but | |
| 697 | +return the value after the increment or decrement has been performed. Since the | |
| 698 | +.CW ++ | |
| 699 | +and | |
| 700 | +.CW * | |
| 701 | +operators fetch and increment the correct amount for the specified format, | |
| 702 | +the following function prints correct machine instructions on a machine with | |
| 703 | +variable length instructions, such as the 68020 or 386: | |
| 704 | +.P1 | |
| 705 | + defn asm(addr) | |
| 706 | + { | |
| 707 | + addr = fmt(addr, 'i'); | |
| 708 | + loop 1, 10 do | |
| 709 | + print(*addr++, "\en"); | |
| 710 | + } | |
| 711 | +.P2 | |
| 712 | +The operators | |
| 713 | +.CW ~ | |
| 714 | +and | |
| 715 | +.CW ! | |
| 716 | +perform bitwise and logical negation respectively. Their operands must be of | |
| 717 | +.I integer | |
| 718 | +type. | |
| 719 | +.DS | |
| 720 | + cast-expression: | |
| 721 | + unary-expression | |
| 722 | + unary-expression \f(CW\e\fP format-char | |
| 723 | + \f(CW(\fP complex-name \f(CW)\fP unary-expression | |
| 724 | +.DE | |
| 725 | +A unary expression may be preceded by a cast. The cast has the effect of | |
| 726 | +associating the value of | |
| 727 | +.I unary-expression | |
| 728 | +with a complex type structure. | |
| 729 | +The result may then be dereferenced using the | |
| 730 | +.CW . | |
| 731 | +and | |
| 732 | +.CW -> | |
| 733 | +operators. | |
| 734 | +.PP | |
| 735 | +An Acid variable may be associated with a complex type | |
| 736 | +to enable accessing the type's members: | |
| 737 | +.P1 | |
| 738 | +acid: complex List { | |
| 739 | + 'D' 0 type; | |
| 740 | + 'X' 4 next; | |
| 741 | +}; | |
| 742 | +acid: complex List lhead | |
| 743 | +acid: lhead.type | |
| 744 | +10 | |
| 745 | +acid: lhead = ((List)lhead).next | |
| 746 | +acid: lhead.type | |
| 747 | +-46 | |
| 748 | +.P2 | |
| 749 | +Note that the | |
| 750 | +.CW next | |
| 751 | +field cannot be given a complex type automatically. | |
| 752 | +.PP | |
| 753 | +When entered at the top level of the interpreter, | |
| 754 | +an expression of complex type | |
| 755 | +is treated specially. | |
| 756 | +If the type is called | |
| 757 | +.CW T | |
| 758 | +and an Acid function also called | |
| 759 | +.CW T | |
| 760 | +exists, | |
| 761 | +then that function will be called with the expression as its argument. | |
| 762 | +The compiler options | |
| 763 | +.CW -a | |
| 764 | +and | |
| 765 | +.CW -aa | |
| 766 | +will generate Acid source code defining such complex types and functions; see | |
| 767 | +.I 2c (1). | |
| 768 | +.PP | |
| 769 | +A | |
| 770 | +.I unary-expression | |
| 771 | +may be qualified with a format specifier using the | |
| 772 | +.CW \e | |
| 773 | +operator. This has the same effect as passing the expression to the | |
| 774 | +.CW fmt | |
| 775 | +builtin function. | |
| 776 | +.DS | |
| 777 | + multiplicative-expression: | |
| 778 | + cast-expression | |
| 779 | + multiplicative-expression \f(CW*\fP multiplicative-expression | |
| 780 | + multiplicative-expression \f(CW/\fP multiplicative-expression | |
| 781 | + multiplicative-expression \f(CW%\fP multiplicative-expression | |
| 782 | +.DE | |
| 783 | +These operate on | |
| 784 | +.I integer | |
| 785 | +and | |
| 786 | +.I float | |
| 787 | +types and perform the expected operations: | |
| 788 | +.CW * | |
| 789 | +multiplication, | |
| 790 | +.CW / | |
| 791 | +division, | |
| 792 | +.CW % | |
| 793 | +modulus. | |
| 794 | +.DS | |
| 795 | + additive-expression: | |
| 796 | + multiplicative-expression | |
| 797 | + additive-expression \f(CW+\fP multiplicative-expression | |
| 798 | + additive-expression \f(CW-\fP multiplicative-expression | |
| 799 | +.DE | |
| 800 | +These operators perform as expected for | |
| 801 | +.I integer | |
| 802 | +and | |
| 803 | +.I float | |
| 804 | +operands. | |
| 805 | +Unlike in C, | |
| 806 | +.CW + | |
| 807 | +and | |
| 808 | +.CW - | |
| 809 | +do not scale the addition based on the format of the expression. | |
| 810 | +This means that | |
| 811 | +.CW i=i+1 | |
| 812 | +will always add 1 but | |
| 813 | +.CW i++ | |
| 814 | +will add the size corresponding to the format stored with | |
| 815 | +.CW i . | |
| 816 | +If both operands are of either | |
| 817 | +.I string | |
| 818 | +or | |
| 819 | +.I list | |
| 820 | +type then addition is defined as concatenation. | |
| 821 | +Adding a string and an integer is treated as concatenation | |
| 822 | +with the Unicode character corresponding to the integer. | |
| 823 | +Subtraction is undefined for strings and lists. | |
| 824 | +.DS | |
| 825 | + shift-expression: | |
| 826 | + additive-expression | |
| 827 | + shift-expression \f(CW<<\fP additive-expression | |
| 828 | + shift-expression \f(CW>>\fP additive-expression | |
| 829 | +.DE | |
| 830 | +The | |
| 831 | +.CW >> | |
| 832 | +and | |
| 833 | +.CW << | |
| 834 | +operators perform bitwise right and left shifts respectively. Both | |
| 835 | +require operands of | |
| 836 | +.I integer | |
| 837 | +type. | |
| 838 | +.DS | |
| 839 | + relational-expression: | |
| 840 | + relational-expression \f(CW<\fP shift-expression | |
| 841 | + relational-expression \f(CW>\fP shift-expression | |
| 842 | + relational-expression \f(CW<=\fP shift-expression | |
| 843 | + relational-expression \f(CW>=\fP shift-expression | |
| 844 | + | |
| 845 | + equality-expression: | |
| 846 | + relational-expression | |
| 847 | + relational-expression \f(CW==\fP equality-expression | |
| 848 | + relational-expression \f(CW!=\fP equality-expression | |
| 849 | +.DE | |
| 850 | +The comparison operators are | |
| 851 | +.CW < | |
| 852 | +(less than), | |
| 853 | +.CW > | |
| 854 | +(greater than), | |
| 855 | +.CW <= | |
| 856 | +(less than or equal to), | |
| 857 | +.CW >= | |
| 858 | +(greater than or equal to), | |
| 859 | +.CW == | |
| 860 | +(equal to) and | |
| 861 | +.CW != | |
| 862 | +(not equal to). The result of a comparison is 0 | |
| 863 | +if the condition is false, otherwise 1. The relational operators can only be | |
| 864 | +applied to operands of | |
| 865 | +.I integer | |
| 866 | +and | |
| 867 | +.I float | |
| 868 | +type. The equality operators apply to all types. Comparing mixed types is legal. | |
| 869 | +Mixed integer and float compare on the integral value. Other mixtures are always unequal. | |
| 870 | +Two lists are equal if they | |
| 871 | +have the same number of members and a pairwise comparison of the members results | |
| 872 | +in equality. | |
| 873 | +.DS | |
| 874 | + AND-expression: | |
| 875 | + equality-expression | |
| 876 | + AND-expression \f(CW&\fP equality-expression | |
| 877 | + | |
| 878 | + XOR-expression: | |
| 879 | + AND-expression | |
| 880 | + XOR-expression \f(CW^\fP AND-expression | |
| 881 | + | |
| 882 | + OR-expression: | |
| 883 | + XOR-expression | |
| 884 | + OR-expression \f(CW|\fP XOR-expression | |
| 885 | +.DE | |
| 886 | +These operators perform bitwise logical operations and apply only to the | |
| 887 | +.I integer | |
| 888 | +type. | |
| 889 | +The operators are | |
| 890 | +.CW & | |
| 891 | +(logical and), | |
| 892 | +.CW ^ | |
| 893 | +(exclusive or) and | |
| 894 | +.CW | | |
| 895 | +(inclusive or). | |
| 896 | +.DS | |
| 897 | + logical-AND-expression: | |
| 898 | + OR-expression | |
| 899 | + logical-AND-expression \f(CW&&\fP OR-expression | |
| 900 | + | |
| 901 | + logical-OR-expression: | |
| 902 | + logical-AND-expression | |
| 903 | + logical-OR-expression \f(CW||\fP logical-AND-expression | |
| 904 | +.DE | |
| 905 | +The | |
| 906 | +.CW && | |
| 907 | +operator returns 1 if both of its operands evaluate to boolean true, otherwise 0. | |
| 908 | +The | |
| 909 | +.CW || | |
| 910 | +operator returns 1 if either of its operands evaluates to boolean true, | |
| 911 | +otherwise 0. | |
| 912 | +.SH | |
| 913 | +Statements | |
| 914 | +.PP | |
| 915 | +.DS | |
| 916 | + \f(CWif\fP expression \f(CWthen\fP statement \f(CWelse\fP statement | |
| 917 | + \f(CWif\fP expression \f(CWthen\fP statement | |
| 918 | +.DE | |
| 919 | +The | |
| 920 | +.I expression | |
| 921 | +is evaluated as a boolean. If its value is true the statement after | |
| 922 | +the | |
| 923 | +.CW then | |
| 924 | +is executed, otherwise the statement after the | |
| 925 | +.CW else | |
| 926 | +is executed. The | |
| 927 | +.CW else | |
| 928 | +portion may be omitted. | |
| 929 | +.DS | |
| 930 | + \f(CWwhile\fP expression \f(CWdo\fP statement | |
| 931 | +.DE | |
| 932 | +In a while loop, the | |
| 933 | +.I statement | |
| 934 | +is executed while the boolean | |
| 935 | +.I expression | |
| 936 | +evaluates | |
| 937 | +true. | |
| 938 | +.DS | |
| 939 | + \f(CWloop\fP startexpr, endexpr \f(CWdo\fP statement | |
| 940 | +.DE | |
| 941 | +The two expressions | |
| 942 | +.I startexpr | |
| 943 | +and | |
| 944 | +.I endexpr | |
| 945 | +are evaluated prior to loop entry. | |
| 946 | +.I Statement | |
| 947 | +is evaluated while the value of | |
| 948 | +.I startexpr | |
| 949 | +is less than or equal to | |
| 950 | +.I endexpr . | |
| 951 | +Both expressions must yield | |
| 952 | +.I integer | |
| 953 | +values. The value of | |
| 954 | +.I startexpr | |
| 955 | +is | |
| 956 | +incremented by one for each loop iteration. | |
| 957 | +Note that there is no explicit loop variable; the | |
| 958 | +.I expressions | |
| 959 | +are just values. | |
| 960 | +.DS | |
| 961 | + \f(CWreturn\fP expression | |
| 962 | +.DE | |
| 963 | +.CW return | |
| 964 | +terminates execution of the current function and returns to its caller. | |
| 965 | +The value of the function is given by expression. Since | |
| 966 | +.CW return | |
| 967 | +requires an argument, nil-valued functions should return the empty list | |
| 968 | +.CW {} . | |
| 969 | +.DS | |
| 970 | + \f(CWlocal\fP variable | |
| 971 | +.DE | |
| 972 | +The | |
| 973 | +.CW local | |
| 974 | +statement creates a local instance of | |
| 975 | +.I variable , | |
| 976 | +which exists for the duration | |
| 977 | +of the instance of the function in which it is declared. Binding is dynamic: the local variable, | |
| 978 | +rather than the previous value of | |
| 979 | +.I variable , | |
| 980 | +is visible to called functions. | |
| 981 | +After a return from the current function the previous value of | |
| 982 | +.I variable | |
| 983 | +is | |
| 984 | +restored. | |
| 985 | +.PP | |
| 986 | +If Acid is interrupted, the values of all local variables are lost, | |
| 987 | +as if the function returned. | |
| 988 | +.DS | |
| 989 | + \f(CWdefn\fP function-name \f(CW(\fP parameter-list \f(CW)\fP body | |
| 990 | + | |
| 991 | + parameter-list: | |
| 992 | + variable | |
| 993 | + parameter-list , variable | |
| 994 | + | |
| 995 | + body: | |
| 996 | + \f(CW{\fP statement \f(CW}\fP | |
| 997 | +.DE | |
| 998 | +Functions are introduced by the | |
| 999 | +.CW defn | |
| 1000 | +statement. The definition of parameter names suppresses any variables | |
| 1001 | +of the same name until the function returns. The body of a function is a list | |
| 1002 | +of statements enclosed by braces. | |
| 1003 | +.SH | |
| 1004 | +Code variables | |
| 1005 | +.PP | |
| 1006 | +Acid permits the delayed evaluation of a parameter to a function. The parameter | |
| 1007 | +may then be evaluated at any time with the | |
| 1008 | +.CW eval | |
| 1009 | +operator. Such parameters are called | |
| 1010 | +.I "code variables | |
| 1011 | +and are defined by prefixing their name with an asterisk in their declaration. | |
| 1012 | +.PP | |
| 1013 | +For example, this function wraps up an expression for later evaluation: | |
| 1014 | +.P1 | |
| 1015 | +acid: defn code(*e) { return e; } | |
| 1016 | +acid: x = code(v+atoi("100")\eD) | |
| 1017 | +acid: print(x) | |
| 1018 | +(v+atoi("100"))\eD; | |
| 1019 | +acid: eval x | |
| 1020 | +<stdin>:5: (error) v used but not set | |
| 1021 | +acid: v=5 | |
| 1022 | +acid: eval x | |
| 1023 | +105 | |
| 1024 | +.P2 | |
| 1025 | +.SH | |
| 1026 | +Source Code Management | |
| 1027 | +.PP | |
| 1028 | +Acid provides the means to examine source code. Source code is | |
| 1029 | +represented by lists of strings. Builtin functions provide mapping | |
| 1030 | +from address to lines and vice-versa. The default debugging environment | |
| 1031 | +has the means to load and display source files. | |
| 1032 | +.SH | |
| 1033 | +Builtin Functions | |
| 1034 | +.PP | |
| 1035 | +The Acid interpreter has a number of builtin functions, which cannot be redefined. | |
| 1036 | +These functions perform machine- or operating system-specific functions such as | |
| 1037 | +symbol table and process management. | |
| 1038 | +The following section presents a description of each builtin function. | |
| 1039 | +The notation | |
| 1040 | +.CW {} | |
| 1041 | +is used to denote the empty list, which is the default value of a function that | |
| 1042 | +does not execute a | |
| 1043 | +.CW return | |
| 1044 | +statement. | |
| 1045 | +The type and number of parameters for each function are specified in the | |
| 1046 | +description; where a parameter can be of any type it is specified as type | |
| 1047 | +.I item . | |
| 1048 | +.de Ip | |
| 1049 | +.KS | |
| 1050 | +.LP | |
| 1051 | +.tl '\f2\\$1\fP\ \ \f(CW\\$2(\f2\\$3\f(CW)\f1''\\$4' | |
| 1052 | +.IP | |
| 1053 | +.. | |
| 1054 | +.de Ex | |
| 1055 | +.KE | |
| 1056 | +.KS | |
| 1057 | +.IP | |
| 1058 | +.ft CW | |
| 1059 | +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n | |
| 1060 | +.nf | |
| 1061 | +.in +4n | |
| 1062 | +.br | |
| 1063 | +.. | |
| 1064 | +.de Ee | |
| 1065 | +.fi | |
| 1066 | +.ft 1 | |
| 1067 | +.br | |
| 1068 | +.KE | |
| 1069 | +.. | |
| 1070 | +.\" | |
| 1071 | +.\" | |
| 1072 | +.\" | |
| 1073 | +.Ip integer access string "Check if a file can be read | |
| 1074 | +.CW Access | |
| 1075 | +returns the integer 1 if the file name in | |
| 1076 | +.I string | |
| 1077 | +can be read by the builtin functions | |
| 1078 | +.CW file , | |
| 1079 | +.CW readfile , | |
| 1080 | +or | |
| 1081 | +.CW include , | |
| 1082 | +otherwise 0. A typical use of this function is to follow | |
| 1083 | +a search path looking for a source file; it is used by | |
| 1084 | +.CW findsrc . | |
| 1085 | +.Ex | |
| 1086 | +if access("main.c") then | |
| 1087 | + return file("main.c"); | |
| 1088 | +.Ee | |
| 1089 | +.\" | |
| 1090 | +.\" | |
| 1091 | +.\" | |
| 1092 | +.Ip float atof string "Convert a string to float | |
| 1093 | +.CW atof | |
| 1094 | +converts the string supplied as its argument into a floating point | |
| 1095 | +number. The function accepts strings in the same format as the C | |
| 1096 | +function of the same name. The value returned has the format code | |
| 1097 | +.CW f . | |
| 1098 | +.CW atof | |
| 1099 | +returns the value 0.0 if it is unable to perform the conversion. | |
| 1100 | +.Ex | |
| 1101 | +acid: +atof("10.4e6") | |
| 1102 | +1.04e+07 | |
| 1103 | +.Ee | |
| 1104 | +.\" | |
| 1105 | +.\" | |
| 1106 | +.\" | |
| 1107 | +.Ip integer atoi string "Convert a string to an integer | |
| 1108 | +.CW atoi | |
| 1109 | +converts the argument | |
| 1110 | +.i string | |
| 1111 | +to an integer value. | |
| 1112 | +The function accepts strings in the same format as the C function of the | |
| 1113 | +same name. The value returned has the format code | |
| 1114 | +.CW D . | |
| 1115 | +.CW atoi | |
| 1116 | +returns the integer 0 if it is unable to perform a conversion. | |
| 1117 | +.Ex | |
| 1118 | +acid: +atoi("-1255") | |
| 1119 | +-1255 | |
| 1120 | +.Ee | |
| 1121 | +.\" | |
| 1122 | +.\" | |
| 1123 | +.\" | |
| 1124 | +.Ip \f(CW{}\fP error string "Generate an interpreter error | |
| 1125 | +.CW error | |
| 1126 | +generates an error message and returns the interpreter to interactive | |
| 1127 | +mode. If an Acid program is running, it is aborted. | |
| 1128 | +Processes being debugged are not affected. The values of all local variables are lost. | |
| 1129 | +.CW error | |
| 1130 | +is commonly used to stop the debugger when some interesting condition arises | |
| 1131 | +in the debugged program. | |
| 1132 | +.Ex | |
| 1133 | +while 1 do { | |
| 1134 | + step(); | |
| 1135 | + if *main != @main then | |
| 1136 | + error("memory corrupted"); | |
| 1137 | +} | |
| 1138 | +.Ee | |
| 1139 | +.\" | |
| 1140 | +.\" | |
| 1141 | +.\" | |
| 1142 | +.Ip list file string "Read the contents of a file into a list | |
| 1143 | +.CW file | |
| 1144 | +reads the contents of the file specified by | |
| 1145 | +.I string | |
| 1146 | +into a list. | |
| 1147 | +Each element in the list is a string corresponding to a line in the file. | |
| 1148 | +.CW file | |
| 1149 | +breaks lines at the newline character, but the newline | |
| 1150 | +characters are not returned as part each string. | |
| 1151 | +.CW file | |
| 1152 | +returns the empty list if it encounters an error opening or reading the data. | |
| 1153 | +.Ex | |
| 1154 | +acid: print(file("main.c")[0]) | |
| 1155 | +#include <u.h> | |
| 1156 | +.Ee | |
| 1157 | +.\" | |
| 1158 | +.\" | |
| 1159 | +.\" | |
| 1160 | +.Ip integer filepc string "Convert source address to text address | |
| 1161 | +.CW filepc | |
| 1162 | +interprets its | |
| 1163 | +.I string | |
| 1164 | +argument as a source file address in the form of a file name and line offset. | |
| 1165 | +.CW filepc | |
| 1166 | +uses the symbol table to map the source address into a text address | |
| 1167 | +in the debugged program. The | |
| 1168 | +.I integer | |
| 1169 | +return value has the format | |
| 1170 | +.CW X . | |
| 1171 | +.CW filepc | |
| 1172 | +returns an address of -1 if the source address is invalid. | |
| 1173 | +The source file address uses the same format as | |
| 1174 | +.I acme (1). | |
| 1175 | +This function is commonly used to set breakpoints from the source text. | |
| 1176 | +.Ex | |
| 1177 | +acid: bpset(filepc("main:10")) | |
| 1178 | +acid: bptab() | |
| 1179 | + 0x00001020 usage ADD $-0xc,R29 | |
| 1180 | +.Ee | |
| 1181 | +.\" | |
| 1182 | +.\" | |
| 1183 | +.\" | |
| 1184 | +.Ip item fmt item,fmt "Set print, \f(CW@\fP and \f(CW*\fP formats | |
| 1185 | +.CW fmt | |
| 1186 | +evaluates the expression | |
| 1187 | +.I item | |
| 1188 | +and sets the format of the result to | |
| 1189 | +.I fmt . | |
| 1190 | +The format of a value determines how it will be printed and | |
| 1191 | +what kind of object will be fetched by the | |
| 1192 | +.CW * | |
| 1193 | +and | |
| 1194 | +.CW @ | |
| 1195 | +operators. The | |
| 1196 | +.CW \e | |
| 1197 | +operator is a short-hand form of the | |
| 1198 | +.CW fmt | |
| 1199 | +builtin function. The | |
| 1200 | +.CW fmt | |
| 1201 | +function leaves the format of the | |
| 1202 | +.I item | |
| 1203 | +unchanged. | |
| 1204 | +.Ex | |
| 1205 | +acid: main=fmt(main, 'i') // as instructions | |
| 1206 | +acid: print(main\eX, "\et", *main) | |
| 1207 | +0x00001020 ADD $-64,R29 | |
| 1208 | +.Ee | |
| 1209 | +.\" | |
| 1210 | +.\" | |
| 1211 | +.\" | |
| 1212 | +.Ip list fnbound integer "Find start and end address of a function | |
| 1213 | +.CW fnbound | |
| 1214 | +interprets its | |
| 1215 | +.I integer | |
| 1216 | +argument as an address in the text of the debugged program. | |
| 1217 | +.CW fnbound | |
| 1218 | +returns a list containing two integers corresponding to | |
| 1219 | +the start and end addresses of the function containing the supplied address. | |
| 1220 | +If the | |
| 1221 | +.I integer | |
| 1222 | +address is not in the text segment of the program then the empty list is returned. | |
| 1223 | +.CW fnbound | |
| 1224 | +is used by | |
| 1225 | +.CW next | |
| 1226 | +to detect stepping into new functions. | |
| 1227 | +.Ex | |
| 1228 | +acid: print(fnbound(main)) | |
| 1229 | +{0x00001050, 0x000014b8} | |
| 1230 | +.Ee | |
| 1231 | +.\" | |
| 1232 | +.\" | |
| 1233 | +.\" | |
| 1234 | +.Ip \f(CW{}\fP follow integer "Compute follow set | |
| 1235 | +The follow set is defined as the set of program counter values that could result | |
| 1236 | +from executing an instruction. | |
| 1237 | +.CW follow | |
| 1238 | +interprets its | |
| 1239 | +.I integer | |
| 1240 | +argument as a text address, decodes the instruction at | |
| 1241 | +that address and, with the current register set, builds a list of possible | |
| 1242 | +next program counter values. If the instruction at the specified address | |
| 1243 | +cannot be decoded | |
| 1244 | +.CW follow | |
| 1245 | +raises an error. | |
| 1246 | +.CW follow | |
| 1247 | +is used to plant breakpoints on | |
| 1248 | +all potential paths of execution. The following code fragment | |
| 1249 | +plants breakpoints on top of all potential following instructions. | |
| 1250 | +.Ex | |
| 1251 | +lst = follow(*PC); | |
| 1252 | +while lst do | |
| 1253 | +{ | |
| 1254 | + *head lst = bpinst; | |
| 1255 | + lst = tail lst; | |
| 1256 | +} | |
| 1257 | +.Ee | |
| 1258 | +.\" | |
| 1259 | +.\" | |
| 1260 | +.\" | |
| 1261 | +.Ip \f(CW{}\fP include string "Take input from a new file | |
| 1262 | +.CW include | |
| 1263 | +opens the file specified by | |
| 1264 | +.I string | |
| 1265 | +and uses its contents as command input to the interpreter. | |
| 1266 | +The interpreter restores input to its previous source when it encounters | |
| 1267 | +either an end of file or an error. | |
| 1268 | +.CW include | |
| 1269 | +can be used to incrementally load symbol table information without | |
| 1270 | +leaving the interpreter. | |
| 1271 | +.Ex | |
| 1272 | +acid: include("/sys/src/cmd/acme/syms") | |
| 1273 | +.Ee | |
| 1274 | +.\" | |
| 1275 | +.\" | |
| 1276 | +.\" | |
| 1277 | +.Ip \f(CW{}\fP interpret string "Take input from a string | |
| 1278 | +.CW interpret | |
| 1279 | +evaluates the | |
| 1280 | +.I string | |
| 1281 | +expression and uses its result as command input for the interpreter. | |
| 1282 | +The interpreter restores input to its previous source when it encounters | |
| 1283 | +either the end of string or an error. The | |
| 1284 | +.CW interpret | |
| 1285 | +function allows Acid programs to write Acid code for later evaluation. | |
| 1286 | +.Ex | |
| 1287 | +acid: interpret("main+10;") | |
| 1288 | +0x0000102a | |
| 1289 | +.Ee | |
| 1290 | +.\" | |
| 1291 | +.\" | |
| 1292 | +.\" | |
| 1293 | +.Ip string itoa integer "Convert integer to string | |
| 1294 | +.CW itoa | |
| 1295 | +takes an integer argument and converts it into an ASCII string | |
| 1296 | +in the | |
| 1297 | +.CW D | |
| 1298 | +format. This function is commonly used to build | |
| 1299 | +.CW rc | |
| 1300 | +command lines. | |
| 1301 | +.Ex | |
| 1302 | +acid: rc("cat /proc/"+itoa(pid)+"/segment") | |
| 1303 | +Stack 7fc00000 80000000 1 | |
| 1304 | +Data 00001000 00009000 1 | |
| 1305 | +Data 00009000 0000a000 1 | |
| 1306 | +Bss 0000a000 0000c000 1 | |
| 1307 | +.Ee | |
| 1308 | +.\" | |
| 1309 | +.\" | |
| 1310 | +.\" | |
| 1311 | +.Ip \f(CW{}\fP kill integer "Kill a process | |
| 1312 | +.CW kill | |
| 1313 | +writes a kill control message into the control file of the process | |
| 1314 | +specified by the | |
| 1315 | +.I integer | |
| 1316 | +pid. | |
| 1317 | +If the process was previously installed by | |
| 1318 | +.CW setproc | |
| 1319 | +it will be removed from the list of active processes. | |
| 1320 | +If the | |
| 1321 | +.I integer | |
| 1322 | +has the same value as | |
| 1323 | +.CW pid , | |
| 1324 | +then | |
| 1325 | +.CW pid | |
| 1326 | +will be set to 0. | |
| 1327 | +To continue debugging, a new process must be selected using | |
| 1328 | +.CW setproc . | |
| 1329 | +For example, to kill all the active processes: | |
| 1330 | +.Ex | |
| 1331 | +while proclist do { | |
| 1332 | + kill(head proclist); | |
| 1333 | + proclist = tail proclist; | |
| 1334 | +} | |
| 1335 | +.Ee | |
| 1336 | +.\" | |
| 1337 | +.\" | |
| 1338 | +.\" | |
| 1339 | +.Ip list map list "Set or retrieve process memory map | |
| 1340 | +.CW map | |
| 1341 | +either retrieves all the mappings associated with a process or sets a single | |
| 1342 | +map entry to a new value. | |
| 1343 | +If the | |
| 1344 | +.I list | |
| 1345 | +argument is omitted then | |
| 1346 | +.CW map | |
| 1347 | +returns a list of lists. Each sublist has four values and describes a | |
| 1348 | +single region of contiguous addresses in the | |
| 1349 | +memory or file image of the debugged program. The first entry is the name of the | |
| 1350 | +mapping. If the name begins with | |
| 1351 | +.CW * | |
| 1352 | +it denotes a map into the memory of an active process. | |
| 1353 | +The second and third values specify the base and end | |
| 1354 | +address of the region and the fourth number specifies the offset in the file | |
| 1355 | +corresponding to the first location of the region. | |
| 1356 | +A map entry may be set by supplying a list in the same format as the sublist | |
| 1357 | +described above. The name of the mapping must match a region already defined | |
| 1358 | +by the current map. | |
| 1359 | +Maps are set automatically for Plan 9 processes and some kernels; they may | |
| 1360 | +need to be set by hand for other kernels and programs that run on bare hardware. | |
| 1361 | +.Ex | |
| 1362 | +acid: map({"text", _start, end, 0x30}) | |
| 1363 | +.Ee | |
| 1364 | +.\" | |
| 1365 | +.\" | |
| 1366 | +.\" | |
| 1367 | +.Ip integer match item,list "Search list for matching value | |
| 1368 | +.CW match | |
| 1369 | +compares each item in | |
| 1370 | +.I list | |
| 1371 | +using the equality operator | |
| 1372 | +.CW == | |
| 1373 | +with | |
| 1374 | +.I item . | |
| 1375 | +The | |
| 1376 | +.I item | |
| 1377 | +can be of any type. If the match succeeds the result is the integer index | |
| 1378 | +of the matching value, otherwise -1. | |
| 1379 | +.Ex | |
| 1380 | +acid: list={8,9,10,11} | |
| 1381 | +acid: print(list[match(10, list)]\eD) | |
| 1382 | +10 | |
| 1383 | +.Ee | |
| 1384 | +.\" | |
| 1385 | +.\" | |
| 1386 | +.\" | |
| 1387 | +.Ip \f(CW{}\fP newproc string "Create a new process | |
| 1388 | +.CW newproc | |
| 1389 | +starts a new process with an argument vector constructed from | |
| 1390 | +.I string . | |
| 1391 | +The argument vector excludes the name of the program to execute and | |
| 1392 | +each argument in | |
| 1393 | +.I string | |
| 1394 | +must be space separated. A new process can accept no more | |
| 1395 | +than 512 arguments. The internal variable | |
| 1396 | +.CW pid | |
| 1397 | +is set to the pid of the newly created process. The new pid | |
| 1398 | +is also appended to the list of active processes stored in the variable | |
| 1399 | +.CW proclist . | |
| 1400 | +The new process is created then halted at the first instruction, causing | |
| 1401 | +the debugger to call | |
| 1402 | +.CW stopped . | |
| 1403 | +The library functions | |
| 1404 | +.CW new | |
| 1405 | +and | |
| 1406 | +.CW win | |
| 1407 | +should be used to start processes when using the standard debugging | |
| 1408 | +environment. | |
| 1409 | +.Ex | |
| 1410 | +acid: newproc("-l .") | |
| 1411 | +56720: system call _main ADD $-0x14,R29 | |
| 1412 | +.Ee | |
| 1413 | +.\" | |
| 1414 | +.\" | |
| 1415 | +.\" | |
| 1416 | +.Ip string pcfile integer "Convert text address to source file name | |
| 1417 | +.CW pcfile | |
| 1418 | +interprets its | |
| 1419 | +.I integer | |
| 1420 | +argument as a text address in the debugged program. The address and symbol table | |
| 1421 | +are used to generate a string containing the name of the source file | |
| 1422 | +corresponding to the text address. If the address does not lie within the | |
| 1423 | +program the string | |
| 1424 | +.CW ?file? | |
| 1425 | +is returned. | |
| 1426 | +.Ex | |
| 1427 | +acid: print("Now at ", pcfile(*PC), ":", pcline(*PC)) | |
| 1428 | +Now at ls.c:46 | |
| 1429 | +.Ee | |
| 1430 | +.\" | |
| 1431 | +.\" | |
| 1432 | +.\" | |
| 1433 | +.Ip integer pcline integer "Convert text address to source line number | |
| 1434 | +.CW pcline | |
| 1435 | +interprets its | |
| 1436 | +.I integer | |
| 1437 | +argument as a text address in the debugged program. The address and symbol table | |
| 1438 | +are used to generate an integer containing the line number in the source file | |
| 1439 | +corresponding to the text address. If the address does not lie within the | |
| 1440 | +program the integer 0 is returned. | |
| 1441 | +.Ex | |
| 1442 | +acid: +file("main.c")[pcline(main)] | |
| 1443 | +main(int argc, char *argv[]) | |
| 1444 | +.Ee | |
| 1445 | +.\" | |
| 1446 | +.\" | |
| 1447 | +.\" | |
| 1448 | +.Ip \f(CW{}\fP print item,item,... "Print expressions | |
| 1449 | +.CW print | |
| 1450 | +evaluates each | |
| 1451 | +.I item | |
| 1452 | +supplied in its argument list and prints it to standard output. Each | |
| 1453 | +argument will be printed according to its associated format character. | |
| 1454 | +When the interpreter is executing, output is buffered and flushed every | |
| 1455 | +5000 statements or when the interpreter returns to interactive mode. | |
| 1456 | +.CW print | |
| 1457 | +accepts a maximum of 512 arguments. | |
| 1458 | +.Ex | |
| 1459 | +acid: print(10, "decimal ", 10\eD, "octal ", 10\eo) | |
| 1460 | +0x0000000a decimal 10 octal 000000000012 | |
| 1461 | +acid: print({1, 2, 3}) | |
| 1462 | +{0x00000001 , 0x00000002 , 0x00000003 } | |
| 1463 | +acid: print(main, main\ea, "\et", @main\ei) | |
| 1464 | +0x00001020 main ADD $-64,R29 | |
| 1465 | +.Ee | |
| 1466 | +.\" | |
| 1467 | +.\" | |
| 1468 | +.\" | |
| 1469 | +.Ip \f(CW{}\fP printto string,item,item,... "Print expressions to file | |
| 1470 | +.CW printto | |
| 1471 | +offers a limited form of output redirection. The first | |
| 1472 | +.I string | |
| 1473 | +argument is used as the path name of a new file to create. | |
| 1474 | +Each | |
| 1475 | +.I item | |
| 1476 | +is then evaluated and printed to the newly created file. When all items | |
| 1477 | +have been printed the file is closed. | |
| 1478 | +.CW printto | |
| 1479 | +accepts a maximum of 512 arguments. | |
| 1480 | +.Ex | |
| 1481 | +acid: printto("/env/foo", "hello") | |
| 1482 | +acid: rc("echo -n $foo") | |
| 1483 | +hello | |
| 1484 | +.Ee | |
| 1485 | +.\" | |
| 1486 | +.\" | |
| 1487 | +.\" | |
| 1488 | +.Ip string rc string "Execute a shell command | |
| 1489 | +.CW rc | |
| 1490 | +evaluates | |
| 1491 | +.I string | |
| 1492 | +to form a shell command. A new command interpreter is started | |
| 1493 | +to execute the command. The Acid interpreter blocks until the command | |
| 1494 | +completes. The return value is the empty string | |
| 1495 | +if the command succeeds, otherwise the exit status of the failed command. | |
| 1496 | +.Ex | |
| 1497 | +acid: rc("B "+itoa(-pcline(addr))+" "+pcfile(addr)); | |
| 1498 | +.Ee | |
| 1499 | +.\" | |
| 1500 | +.\" | |
| 1501 | +.\" | |
| 1502 | +.Ip string readfile string "Read file contents into a string | |
| 1503 | +.CW readfile | |
| 1504 | +takes the contents of the file specified by | |
| 1505 | +.I string | |
| 1506 | +and returns its contents as a new string. | |
| 1507 | +If | |
| 1508 | +.CW readfile | |
| 1509 | +encounters a zero byte in the file, it terminates. | |
| 1510 | +If | |
| 1511 | +.CW readfile | |
| 1512 | +encounters an error opening or reading the file then the empty list | |
| 1513 | +is returned. | |
| 1514 | +.CW readfile | |
| 1515 | +can be used to read the contents of device files whose lines are not | |
| 1516 | +terminated with newline characters. | |
| 1517 | +.Ex | |
| 1518 | +acid: ""+readfile("/dev/label") | |
| 1519 | +helix | |
| 1520 | +.Ee | |
| 1521 | +.\" | |
| 1522 | +.\" | |
| 1523 | +.\" | |
| 1524 | +.Ip string reason integer "Print cause of program stoppage | |
| 1525 | +.CW reason | |
| 1526 | +uses machine-dependent information to generate a string explaining | |
| 1527 | +why a process has stopped. The | |
| 1528 | +.I integer | |
| 1529 | +argument is the value of an architecture dependent status register, | |
| 1530 | +for example | |
| 1531 | +.CW CAUSE | |
| 1532 | +on the MIPS. | |
| 1533 | +.Ex | |
| 1534 | +acid: print(reason(*CAUSE)) | |
| 1535 | +system call | |
| 1536 | +.Ee | |
| 1537 | +.\" | |
| 1538 | +.\" | |
| 1539 | +.\" | |
| 1540 | +.Ip integer regexp pattern,string "Regular expression match | |
| 1541 | +.CW regexp | |
| 1542 | +matches the | |
| 1543 | +.I pattern | |
| 1544 | +string supplied as its first argument with the | |
| 1545 | +.I string | |
| 1546 | +supplied as its second. | |
| 1547 | +If the pattern matches the result is the value 1, otherwise 0. | |
| 1548 | +.Ex | |
| 1549 | +acid: print(regexp(".*bar", "foobar")) | |
| 1550 | +1 | |
| 1551 | +.Ee | |
| 1552 | +.\" | |
| 1553 | +.\" | |
| 1554 | +.\" | |
| 1555 | +.Ip \f(CW{}\fP setproc integer "Set debugger focus | |
| 1556 | +.CW setproc | |
| 1557 | +selects the default process used for memory and control operations. It effectively | |
| 1558 | +shifts the focus of control between processes. The | |
| 1559 | +.I integer | |
| 1560 | +argument specifies the pid of the process to look at. | |
| 1561 | +The variable | |
| 1562 | +.CW pid | |
| 1563 | +is set to the pid of the selected process. If the process is being | |
| 1564 | +selected for the first time its pid is added to the list of active | |
| 1565 | +processes | |
| 1566 | +.CW proclist . | |
| 1567 | +.Ex | |
| 1568 | +acid: setproc(68382) | |
| 1569 | +acid: procs() | |
| 1570 | +>68382: Stopped at main+0x4 setproc(68382) | |
| 1571 | +.Ee | |
| 1572 | +.\" | |
| 1573 | +.\" | |
| 1574 | +.\" | |
| 1575 | +.Ip \f(CW{}\fP start integer "Restart execution | |
| 1576 | +.CW start | |
| 1577 | +writes a | |
| 1578 | +.CW start | |
| 1579 | +message to the control file of the process specified by the pid | |
| 1580 | +supplied as its | |
| 1581 | +.I integer | |
| 1582 | +argument. | |
| 1583 | +.CW start | |
| 1584 | +draws an error if the process is not in the | |
| 1585 | +.CW Stopped | |
| 1586 | +state. | |
| 1587 | +.Ex | |
| 1588 | +acid: start(68382) | |
| 1589 | +acid: procs() | |
| 1590 | +>68382: Running at main+0x4 setproc(68382) | |
| 1591 | +.Ee | |
| 1592 | +.\" | |
| 1593 | +.\" | |
| 1594 | +.\" | |
| 1595 | +.Ip \f(CW{}\fP startstop integer "Restart execution, block until stopped | |
| 1596 | +.CW startstop | |
| 1597 | +performs the same actions as a call to | |
| 1598 | +.CW start | |
| 1599 | +followed by a call to | |
| 1600 | +.CW stop . | |
| 1601 | +The | |
| 1602 | +.I integer | |
| 1603 | +argument specifies the pid of the process to control. The process | |
| 1604 | +must be in the | |
| 1605 | +.CW Stopped | |
| 1606 | +state. | |
| 1607 | +Execution is restarted, the debugger then waits for the process to | |
| 1608 | +return to the | |
| 1609 | +.CW Stopped | |
| 1610 | +state. A process will stop if a startstop message has been written to its control | |
| 1611 | +file and any of the following conditions becomes true: the process executes or returns from | |
| 1612 | +a system call, the process generates a trap or the process receives a note. | |
| 1613 | +.CW startstop | |
| 1614 | +is used to implement single stepping. | |
| 1615 | +.Ex | |
| 1616 | +acid: startstop(pid) | |
| 1617 | +75374: breakpoint ls ADD $-0x16c8,R29 | |
| 1618 | +.Ee | |
| 1619 | +.\" | |
| 1620 | +.\" | |
| 1621 | +.\" | |
| 1622 | +.Ip string status integer "Return process state | |
| 1623 | +.CW status | |
| 1624 | +uses the pid supplied by its | |
| 1625 | +.I integer | |
| 1626 | +argument to generate a string describing the state of the process. | |
| 1627 | +The string corresponds to the state returned by the | |
| 1628 | +sixth column of the | |
| 1629 | +.I ps (1) | |
| 1630 | +command. | |
| 1631 | +A process must be in the | |
| 1632 | +.CW Stopped | |
| 1633 | +state to modify its memory or registers. | |
| 1634 | +.Ex | |
| 1635 | +acid: ""+status(pid) | |
| 1636 | +Stopped | |
| 1637 | +.Ee | |
| 1638 | +.\" | |
| 1639 | +.\" | |
| 1640 | +.\" | |
| 1641 | +.Ip \f(CW{}\fP stop integer "Wait for a process to stop | |
| 1642 | +.CW stop | |
| 1643 | +writes a | |
| 1644 | +.CW stop | |
| 1645 | +message to the control file of the process specified by the | |
| 1646 | +pid supplied as its | |
| 1647 | +.I integer | |
| 1648 | +argument. | |
| 1649 | +The interpreter blocks until the debugged process enters the | |
| 1650 | +.CW Stopped | |
| 1651 | +state. | |
| 1652 | +A process will stop if a stop message has been written to its control | |
| 1653 | +file and any of the following conditions becomes true: the process executes or returns from | |
| 1654 | +a system call, the process generates a trap, the process is scheduled or the | |
| 1655 | +process receives a note. | |
| 1656 | +.CW stop | |
| 1657 | +is used to wait for a process to halt before planting a breakpoint since Plan 9 | |
| 1658 | +only allows a process's memory to be written while it is in the | |
| 1659 | +.CW Stopped | |
| 1660 | +state. | |
| 1661 | +.Ex | |
| 1662 | +defn bpset(addr) { | |
| 1663 | + if (status(pid)!="Stopped") then { | |
| 1664 | + print("Waiting...\en"); | |
| 1665 | + stop(pid); | |
| 1666 | + } | |
| 1667 | + ... | |
| 1668 | +} | |
| 1669 | +.Ee | |
| 1670 | +.\" | |
| 1671 | +.\" | |
| 1672 | +.\" | |
| 1673 | +.Ip list strace pc,sp,linkreg "Stack trace | |
| 1674 | +.CW strace | |
| 1675 | +generates a list of lists corresponding to procedures called by the debugged | |
| 1676 | +program. Each sublist describes a single stack frame in the active process. | |
| 1677 | +The first element is an | |
| 1678 | +.I integer | |
| 1679 | +of format | |
| 1680 | +.CW X | |
| 1681 | +specifying the address of the called function. The second element is the value | |
| 1682 | +of the program counter when the function was called. The third and fourth elements | |
| 1683 | +contain lists of parameter and automatic variables respectively. | |
| 1684 | +Each element of these lists | |
| 1685 | +contains a string with the name of the variable and an | |
| 1686 | +.I integer | |
| 1687 | +value of format | |
| 1688 | +.CW X | |
| 1689 | +containing the current value of the variable. | |
| 1690 | +The arguments to | |
| 1691 | +.CW strace | |
| 1692 | +are the current value of the program counter, the current value of the | |
| 1693 | +stack pointer, and the address of the link register. All three parameters | |
| 1694 | +must be integers. | |
| 1695 | +The setting of | |
| 1696 | +.I linkreg | |
| 1697 | +is architecture dependent. On the MIPS linkreg is set to the address of saved | |
| 1698 | +.CW R31 , | |
| 1699 | +on the SPARC to the address of saved | |
| 1700 | +.CW R15 . | |
| 1701 | +For the other architectures | |
| 1702 | +.I linkreg | |
| 1703 | +is not used, but must point to valid memory. | |
| 1704 | +.Ex | |
| 1705 | +acid: print(strace(*PC, *SP, linkreg)) | |
| 1706 | +{{0x0000141c, 0xc0000f74, | |
| 1707 | +{{"s", 0x0000004d}, {"multi", 0x00000000}}, | |
| 1708 | +{{"db", 0x00000000}, {"fd", 0x000010a4}, | |
| 1709 | +{"n", 0x00000001}, {"i", 0x00009824}}}} | |
| 1710 | +.Ee | |
| 1711 | +.\" | |
| 1712 | +.\" | |
| 1713 | +.\" | |
| 1714 | +.Ip \f(CW{}\fP waitstop integer "Wait for a process to stop | |
| 1715 | +.CW waitstop | |
| 1716 | +writes a waitstop message to the control file of the process specified by the | |
| 1717 | +pid supplied as its | |
| 1718 | +.I integer | |
| 1719 | +argument. | |
| 1720 | +The interpreter will remain blocked until the debugged process enters the | |
| 1721 | +.CW Stopped | |
| 1722 | +state. | |
| 1723 | +A process will stop if a waitstop message has been written to its control | |
| 1724 | +file and any of the following conditions becomes true: the process generates a trap | |
| 1725 | +or receives a note. Unlike | |
| 1726 | +.CW stop , | |
| 1727 | +the | |
| 1728 | +.CW waitstop | |
| 1729 | +function is passive; it does not itself cause the program to stop. | |
| 1730 | +.Ex | |
| 1731 | +acid: waitstop(pid) | |
| 1732 | +75374: breakpoint ls ADD $-0x16c8,R29 | |
| 1733 | +.Ee | |
| 1734 | +.\" | |
| 1735 | +.\" | |
| 1736 | +.\" | |
| 1737 | +.SH | |
| 1738 | +Library Functions | |
| 1739 | +.PP | |
| 1740 | +A standard debugging environment is provided by modules automatically | |
| 1741 | +loaded when | |
| 1742 | +Acid is started. | |
| 1743 | +These modules are located in the directory | |
| 1744 | +.CW /sys/lib/acid . | |
| 1745 | +These functions may be overridden, personalized, or added to by code defined in | |
| 1746 | +.CW $home/lib/acid . | |
| 1747 | +The implementation of these functions can be examined using the | |
| 1748 | +.CW whatis | |
| 1749 | +operator and then modified during debugging sessions. | |
| 1750 | +.\" | |
| 1751 | +.\" | |
| 1752 | +.\" | |
| 1753 | +.Ip \f(CW{}\fP Bsrc integer "Load text editor with source | |
| 1754 | +.CW Bsrc | |
| 1755 | +interprets the | |
| 1756 | +.I integer | |
| 1757 | +argument as a text address. The text address is used to produce a pathname | |
| 1758 | +and line number suitable for the external | |
| 1759 | +.CW B | |
| 1760 | +command | |
| 1761 | +of the text editor | |
| 1762 | +(eg, | |
| 1763 | +.I acme (1)). | |
| 1764 | +.CW Bsrc | |
| 1765 | +builds a shell | |
| 1766 | +command to invoke | |
| 1767 | +.CW B , | |
| 1768 | +which either selects an existing source file or loads a new source file into | |
| 1769 | +the editor. | |
| 1770 | +The line of source corresponding to the text address is then selected. | |
| 1771 | +In the following example | |
| 1772 | +.CW stopped | |
| 1773 | +is redefined so that | |
| 1774 | +the editor | |
| 1775 | +follows and displays the source line currently being executed. | |
| 1776 | +.Ex | |
| 1777 | +defn stopped(pid) { | |
| 1778 | + pstop(pid); | |
| 1779 | + Bsrc(*PC); | |
| 1780 | +} | |
| 1781 | +.Ee | |
| 1782 | +.\" | |
| 1783 | +.\" | |
| 1784 | +.\" | |
| 1785 | +.Ip \f(CW{}\fP Fpr "" "Display double precision floating registers | |
| 1786 | +For machines equipped with floating point, | |
| 1787 | +.CW Fpr | |
| 1788 | +displays the contents of the floating point registers as double precision | |
| 1789 | +values. | |
| 1790 | +.Ex | |
| 1791 | +acid: Fpr() | |
| 1792 | +F0 0. F2 0. | |
| 1793 | +F4 0. F6 0. | |
| 1794 | +F8 0. F10 0. | |
| 1795 | +\&... | |
| 1796 | +.Ee | |
| 1797 | +.\" | |
| 1798 | +.\" | |
| 1799 | +.\" | |
| 1800 | +.Ip \f(CW{}\fP Ureg integer "Display contents of Ureg structure | |
| 1801 | +.CW Ureg | |
| 1802 | +interprets the integer passed as its first argument as the address of a | |
| 1803 | +kernel | |
| 1804 | +.CW Ureg | |
| 1805 | +structure. Each element of the structure is retrieved and printed. | |
| 1806 | +The size and contents of the | |
| 1807 | +.CW Ureg | |
| 1808 | +structure are architecture dependent. | |
| 1809 | +This function can be used to decode the first argument passed to a | |
| 1810 | +.I notify (2) | |
| 1811 | +function after a process has received a note. | |
| 1812 | +.Ex | |
| 1813 | +acid: Ureg(*notehandler:ur) | |
| 1814 | + status 0x3000f000 | |
| 1815 | + pc 0x1020 | |
| 1816 | + sp 0x7ffffe00 | |
| 1817 | + cause 0x00004002 | |
| 1818 | +\&... | |
| 1819 | +.Ee | |
| 1820 | +.\" | |
| 1821 | +.\" | |
| 1822 | +.\" | |
| 1823 | +.Ip \f(CW{}\fP acidinit "" "Interpreter startup | |
| 1824 | +.CW acidinit | |
| 1825 | +is called by the interpreter after all | |
| 1826 | +modules have been loaded at initialization time. | |
| 1827 | +It is used to set up machine specific variables and the default source path. | |
| 1828 | +.CW acidinit | |
| 1829 | +should not be called by user code. | |
| 1830 | +.KE | |
| 1831 | +.\" | |
| 1832 | +.\" | |
| 1833 | +.\" | |
| 1834 | +.Ip \f(CW{}\fP addsrcdir string "Add element to source search path | |
| 1835 | +.CW addsrcdir | |
| 1836 | +interprets its string argument as a new directory | |
| 1837 | +.CW findsrc | |
| 1838 | +should search when looking for source code files. | |
| 1839 | +.CW addsrcdir | |
| 1840 | +draws an error if the directory is already in the source search path. The search | |
| 1841 | +path may be examined by looking at the variable | |
| 1842 | +.CW srcpath . | |
| 1843 | +.Ex | |
| 1844 | +acid: rc("9fs fornax") | |
| 1845 | +acid: addsrcpath("/n/fornax/sys/src/cmd") | |
| 1846 | +.Ee | |
| 1847 | +.\" | |
| 1848 | +.\" | |
| 1849 | +.\" | |
| 1850 | +.Ip \f(CW{}\fP asm integer "Disassemble machine instructions | |
| 1851 | +.CW asm | |
| 1852 | +interprets its integer argument as a text address from which to disassemble | |
| 1853 | +machine instructions. | |
| 1854 | +.CW asm | |
| 1855 | +prints the instruction address in symbolic and hexadecimal form, then prints | |
| 1856 | +the instructions with addressing modes. Up to twenty instructions will | |
| 1857 | +be disassembled. | |
| 1858 | +.CW asm | |
| 1859 | +stops disassembling when it reaches the end of the current function. | |
| 1860 | +Instructions are read from the file image using the | |
| 1861 | +.CW @ | |
| 1862 | +operator. | |
| 1863 | +.Ex | |
| 1864 | +acid: asm(main) | |
| 1865 | +main 0x00001020 ADD $-0x64,R29 | |
| 1866 | +main+0x4 0x00001024 MOVW R31,0x0(R29) | |
| 1867 | +main+0x8 0x00001028 MOVW R1,argc+4(FP) | |
| 1868 | +main+0xc 0x0000102c MOVW $bin(SB),R1 | |
| 1869 | +.Ee | |
| 1870 | +.\" | |
| 1871 | +.\" | |
| 1872 | +.\" | |
| 1873 | +.Ip \f(CW{}\fP bpdel integer "Delete breakpoint | |
| 1874 | +.CW bpdel | |
| 1875 | +removes a previously set breakpoint from memory. | |
| 1876 | +The | |
| 1877 | +.I integer | |
| 1878 | +supplied as its argument must be the address of a previously set breakpoint. | |
| 1879 | +The breakpoint address is deleted from the active breakpoint list | |
| 1880 | +.CW bplist , | |
| 1881 | +then the original instruction is copied from the file image to the memory | |
| 1882 | +image so that the breakpoint is removed. | |
| 1883 | +.Ex | |
| 1884 | +acid: bpdel(main+4) | |
| 1885 | +.Ee | |
| 1886 | +.\" | |
| 1887 | +.\" | |
| 1888 | +.\" | |
| 1889 | +.Ip \f(CW{}\fP bpset integer "Set a breakpoint | |
| 1890 | +.CW bpset | |
| 1891 | +places a breakpoint instruction at the address specified | |
| 1892 | +by its | |
| 1893 | +.I integer | |
| 1894 | +argument, which must be in the text segment. | |
| 1895 | +.CW bpset | |
| 1896 | +draws an error if a breakpoint has already been set at the specified address. | |
| 1897 | +A list of current breakpoints is maintained in the variable | |
| 1898 | +.CW bplist . | |
| 1899 | +Unlike in | |
| 1900 | +.I db (1), | |
| 1901 | +breakpoints are left in memory even when a process is stopped, and | |
| 1902 | +the process must exist, perhaps by being | |
| 1903 | +created by either | |
| 1904 | +.CW new | |
| 1905 | +or | |
| 1906 | +.CW win , | |
| 1907 | +in order to place a breakpoint. | |
| 1908 | +.CW Db "" ( | |
| 1909 | +accepts breakpoint commands before the process is started.) | |
| 1910 | +On the | |
| 1911 | +MIPS and SPARC architectures, | |
| 1912 | +breakpoints at function entry points should be set 4 bytes into the function | |
| 1913 | +because the | |
| 1914 | +instruction scheduler may fill | |
| 1915 | +.CW JAL | |
| 1916 | +branch delay slots with the first instruction of the function. | |
| 1917 | +.Ex | |
| 1918 | +acid: bpset(main+4) | |
| 1919 | +.Ee | |
| 1920 | +.\" | |
| 1921 | +.\" | |
| 1922 | +.\" | |
| 1923 | +.Ip \f(CW{}\fP bptab "" "List active breakpoints | |
| 1924 | +.CW bptab | |
| 1925 | +prints a list of currently installed breakpoints. The list contains the | |
| 1926 | +breakpoint address in symbolic and hexadecimal form as well as the instruction | |
| 1927 | +the breakpoint replaced. Breakpoints are not maintained across process creation | |
| 1928 | +using | |
| 1929 | +.CW new | |
| 1930 | +and | |
| 1931 | +.CW win . | |
| 1932 | +They are maintained across a fork, but care must be taken to keep control of | |
| 1933 | +the child process. | |
| 1934 | +.Ex | |
| 1935 | +acid: bpset(ls+4) | |
| 1936 | +acid: bptab() | |
| 1937 | + 0x00001420 ls+0x4 MOVW R31,0x0(R29) | |
| 1938 | +.Ee | |
| 1939 | +.\" | |
| 1940 | +.\" | |
| 1941 | +.\" | |
| 1942 | +.Ip \f(CW{}\fP casm "" "Continue disassembly | |
| 1943 | +.CW casm | |
| 1944 | +continues to disassemble instructions from where the last | |
| 1945 | +.CW asm | |
| 1946 | +or | |
| 1947 | +.CW casm | |
| 1948 | +command stopped. Like | |
| 1949 | +.CW asm , | |
| 1950 | +this command stops disassembling at function boundaries. | |
| 1951 | +.Ex | |
| 1952 | +acid: casm() | |
| 1953 | +main+0x10 0x00001030 MOVW $0x1,R3 | |
| 1954 | +main+0x14 0x00001034 MOVW R3,0x8(R29) | |
| 1955 | +main+0x18 0x00001038 MOVW $0x1,R5 | |
| 1956 | +main+0x1c 0x0000103c JAL Binit(SB) | |
| 1957 | +.Ee | |
| 1958 | +.\" | |
| 1959 | +.\" | |
| 1960 | +.\" | |
| 1961 | +.Ip \f(CW{}\fP cont "" "Continue program execution | |
| 1962 | +.CW cont | |
| 1963 | +restarts execution of the currently active process. | |
| 1964 | +If the process is stopped on a breakpoint, the breakpoint is first removed, | |
| 1965 | +the program is single stepped, the breakpoint is replaced and the program | |
| 1966 | +is then set executing. This may cause | |
| 1967 | +.CW stopped() | |
| 1968 | +to be called twice. | |
| 1969 | +.CW cont | |
| 1970 | +causes the interpreter to block until the process enters the | |
| 1971 | +.CW Stopped | |
| 1972 | +state. | |
| 1973 | +.Ex | |
| 1974 | +acid: cont() | |
| 1975 | +95197: breakpoint ls+0x4 MOVW R31,0x0(R29) | |
| 1976 | +.Ee | |
| 1977 | +.\" | |
| 1978 | +.\" | |
| 1979 | +.\" | |
| 1980 | +.Ip \f(CW{}\fP dump integer,integer,string "Formatted memory dump | |
| 1981 | +.CW dump | |
| 1982 | +interprets its first argument as an address, its second argument as a | |
| 1983 | +count and its third as a format string. | |
| 1984 | +.CW dump | |
| 1985 | +fetches an object from memory at the current address and prints it according | |
| 1986 | +to the format. The address is incremented by the number of bytes specified by | |
| 1987 | +the format and the process is repeated count times. The format string is any | |
| 1988 | +combination of format characters, each preceded by an optional count. | |
| 1989 | +For each object, | |
| 1990 | +.CW dump | |
| 1991 | +prints the address in hexadecimal, a colon, the object and then a newline. | |
| 1992 | +.CW dump | |
| 1993 | +uses | |
| 1994 | +.CW mem | |
| 1995 | +to fetch each object. | |
| 1996 | +.Ex | |
| 1997 | +acid: dump(main+35, 4, "X2bi") | |
| 1998 | +0x00001043: 0x0c8fa700 108 143 lwc2 r0,0x528f(R4) | |
| 1999 | +0x0000104d: 0xa9006811 0 0 swc3 r0,0x0(R24) | |
| 2000 | +0x00001057: 0x2724e800 4 37 ADD $-0x51,R23,R31 | |
| 2001 | +0x00001061: 0xa200688d 6 0 NOOP | |
| 2002 | +0x0000106b: 0x2710c000 7 0 BREAK | |
| 2003 | +.Ee | |
| 2004 | +.\" | |
| 2005 | +.\" | |
| 2006 | +.\" | |
| 2007 | +.Ip \f(CW{}\fP findsrc string "Use source path to load source file | |
| 2008 | +.CW findsrc | |
| 2009 | +interprets its | |
| 2010 | +.I string | |
| 2011 | +argument as a source file. Each directory in the source path is searched | |
| 2012 | +in turn for the file. If the file is found, the source text is loaded using | |
| 2013 | +.CW file | |
| 2014 | +and stored in the list of active source files called | |
| 2015 | +.CW srctext . | |
| 2016 | +The name of the file is added to the source file name list | |
| 2017 | +.CW srcfiles . | |
| 2018 | +Users are unlikely to call | |
| 2019 | +.CW findsrc | |
| 2020 | +from the command line, but may use it from scripts to preload source files | |
| 2021 | +for a debugging session. This function is used by | |
| 2022 | +.CW src | |
| 2023 | +and | |
| 2024 | +.CW line | |
| 2025 | +to locate and load source code. The default search path for the MIPS | |
| 2026 | +is | |
| 2027 | +.CW ./ , | |
| 2028 | +.CW /sys/src/libc/port , | |
| 2029 | +.CW /sys/src/libc/9sys , | |
| 2030 | +.CW /sys/src/libc/mips . | |
| 2031 | +.Ex | |
| 2032 | +acid: findsrc(pcfile(main)); | |
| 2033 | +.Ee | |
| 2034 | +.\" | |
| 2035 | +.\" | |
| 2036 | +.\" | |
| 2037 | +.Ip \f(CW{}\fP fpr "" "Display single precision floating registers | |
| 2038 | +For machines equipped with floating point, | |
| 2039 | +.CW fpr | |
| 2040 | +displays the contents of the floating point registers as single precision | |
| 2041 | +values. When the interpreter stores or manipulates floating point values | |
| 2042 | +it converts into double precision values. | |
| 2043 | +.Ex | |
| 2044 | +acid: fpr() | |
| 2045 | +F0 0. F1 0. | |
| 2046 | +F2 0. F3 0. | |
| 2047 | +F4 0. F5 0. | |
| 2048 | +\&... | |
| 2049 | +.Ee | |
| 2050 | +.\" | |
| 2051 | +.\" | |
| 2052 | +.\" | |
| 2053 | +.Ip \f(CW{}\fP func "" "Step while in function | |
| 2054 | +.CW func | |
| 2055 | +single steps the active process until it leaves the current function | |
| 2056 | +by either calling another function or returning to its caller. | |
| 2057 | +.CW func | |
| 2058 | +will execute a single instruction after leaving the current function. | |
| 2059 | +.Ex | |
| 2060 | +acid: func() | |
| 2061 | +95197: breakpoint ls+0x8 MOVW R1,R8 | |
| 2062 | +95197: breakpoint ls+0xc MOVW R8,R1 | |
| 2063 | +95197: breakpoint ls+0x10 MOVW R8,s+4(FP) | |
| 2064 | +95197: breakpoint ls+0x14 MOVW $0x2f,R5 | |
| 2065 | +95197: breakpoint ls+0x18 JAL utfrrune(SB) | |
| 2066 | +95197: breakpoint utfrrune ADD $-0x18,R29 | |
| 2067 | +.Ee | |
| 2068 | +.\" | |
| 2069 | +.\" | |
| 2070 | +.\" | |
| 2071 | +.Ip \f(CW{}\fP gpr "" "Display general purpose registers | |
| 2072 | +.CW gpr | |
| 2073 | +prints the values of the general purpose processor registers. | |
| 2074 | +.Ex | |
| 2075 | +acid: gpr() | |
| 2076 | +R1 0x00009562 R2 0x000010a4 R3 0x00005d08 | |
| 2077 | +R4 0x0000000a R5 0x0000002f R6 0x00000008 | |
| 2078 | +\&... | |
| 2079 | +.Ee | |
| 2080 | +.\" | |
| 2081 | +.\" | |
| 2082 | +.\" | |
| 2083 | +.Ip \f(CW{}\fP labstk integer "Print stack trace from label | |
| 2084 | +.CW labstk | |
| 2085 | +performs a stack trace from a Plan 9 | |
| 2086 | +.I label. | |
| 2087 | +The kernel | |
| 2088 | +and C compilers store continuations in a common format. Since the | |
| 2089 | +compilers all use caller save conventions a continuation may be saved by | |
| 2090 | +storing a | |
| 2091 | +.CW PC | |
| 2092 | +and | |
| 2093 | +.CW SP | |
| 2094 | +pair. This data structure is called a label and is used by the | |
| 2095 | +C function | |
| 2096 | +.CW longjmp | |
| 2097 | +and the kernel to schedule threads and processes. | |
| 2098 | +.CW labstk | |
| 2099 | +interprets its | |
| 2100 | +.I integer | |
| 2101 | +argument as the address of a label and produces a stack trace for | |
| 2102 | +the thread of execution. The value of the function | |
| 2103 | +.CW ALEF_tid | |
| 2104 | +is a suitable argument for | |
| 2105 | +.CW labstk . | |
| 2106 | +.Ex | |
| 2107 | +acid: labstk(*mousetid) | |
| 2108 | +At pc:0x00021a70:Rendez_Sleep+0x178 rendez.l:44 | |
| 2109 | +Rendez_Sleep(r=0xcd7d8,bool=0xcd7e0,t=0x0) rendez.l:5 | |
| 2110 | + called from ALEF_rcvmem+0x198 recvmem.l:45 | |
| 2111 | +ALEF_rcvmem(c=0x000cd764,l=0x00000010) recvmem.l:6 | |
| 2112 | +\&... | |
| 2113 | +.Ee | |
| 2114 | +.\" | |
| 2115 | +.\" | |
| 2116 | +.\" | |
| 2117 | +.Ip \f(CW{}\fP lstk "" "Stack trace with local variables | |
| 2118 | +.CW lstk | |
| 2119 | +produces a long format stack trace. | |
| 2120 | +The stack trace includes each function in the stack, | |
| 2121 | +where it was called from, and the value of the parameters and automatic | |
| 2122 | +variables for each function. | |
| 2123 | +.CW lstk | |
| 2124 | +displays the value rather than the address of each variable and all | |
| 2125 | +variables are assumed to be an integer in format | |
| 2126 | +.CW X . | |
| 2127 | +To print a variable in its correct format use the | |
| 2128 | +.CW : | |
| 2129 | +operator to find the address and apply the appropriate format before indirection | |
| 2130 | +with the | |
| 2131 | +.CW * | |
| 2132 | +operator. It may be necessary to single step a couple of instructions into | |
| 2133 | +a function to get a correct stack trace because the frame pointer adjustment | |
| 2134 | +instruction may get scheduled down into the body of the function. | |
| 2135 | +.Ex | |
| 2136 | +acid: lstk() | |
| 2137 | +At pc:0x00001024:main+0x4 ls.c:48 | |
| 2138 | +main(argc=0x00000001,argv=0x7fffefec) ls.c:48 | |
| 2139 | + called from _main+0x20 main9.s:10 | |
| 2140 | + _argc=0x00000000 | |
| 2141 | + _args=0x00000000 | |
| 2142 | + fd=0x00000000 | |
| 2143 | + buf=0x00000000 | |
| 2144 | + i=0x00000000 | |
| 2145 | +.Ee | |
| 2146 | +.\" | |
| 2147 | +.\" | |
| 2148 | +.\" | |
| 2149 | +.Ip \f(CW{}\fP mem integer,string "Print memory object | |
| 2150 | +.CW mem | |
| 2151 | +interprets its first | |
| 2152 | +.I integer | |
| 2153 | +argument as the address of an object to be printed according to the | |
| 2154 | +format supplied in its second | |
| 2155 | +.I string | |
| 2156 | +argument. | |
| 2157 | +The format string can be any combination of format characters, each preceded | |
| 2158 | +by an optional count. | |
| 2159 | +.Ex | |
| 2160 | +acid: mem(bdata+0x326, "2c2Xb") | |
| 2161 | +P = 0xa94bc464 0x3e5ae44d 19 | |
| 2162 | +.Ee | |
| 2163 | +.\" | |
| 2164 | +.\" | |
| 2165 | +.\" | |
| 2166 | +.Ip \f(CW{}\fP new "" "Create new process | |
| 2167 | +.CW new | |
| 2168 | +starts a new copy of the debugged program. The new program is started | |
| 2169 | +with the program arguments set by the variable | |
| 2170 | +.CW progargs . | |
| 2171 | +The new program is stopped in the second instruction of | |
| 2172 | +.CW main . | |
| 2173 | +The breakpoint list is reinitialized. | |
| 2174 | +.CW new | |
| 2175 | +may be used several times to instantiate several copies of a program | |
| 2176 | +simultaneously. The user can rotate between the copies using | |
| 2177 | +.CW setproc . | |
| 2178 | +.Ex | |
| 2179 | +acid: progargs="-l" | |
| 2180 | +acid: new() | |
| 2181 | +60: external interrupt _main ADD $-0x14,R29 | |
| 2182 | +60: breakpoint main+0x4 MOVW R31,0x0(R29) | |
| 2183 | +.Ee | |
| 2184 | +.\" | |
| 2185 | +.\" | |
| 2186 | +.\" | |
| 2187 | +.Ip \f(CW{}\fP next "" "Step through language statement | |
| 2188 | +.CW next | |
| 2189 | +steps through a single language level statement without tracing down | |
| 2190 | +through each statement in a called function. For each statement, | |
| 2191 | +.CW next | |
| 2192 | +prints the machine instructions executed as part of the statement. After | |
| 2193 | +the statement has executed, source lines around the current program | |
| 2194 | +counter are displayed. | |
| 2195 | +.Ex | |
| 2196 | +acid: next() | |
| 2197 | +60: breakpoint Binit+0x4 MOVW R31,0x0(R29) | |
| 2198 | +60: breakpoint Binit+0x8 MOVW f+8(FP),R4 | |
| 2199 | +binit.c:93 | |
| 2200 | + 88 | |
| 2201 | + 89 int | |
| 2202 | + 90 Binit(Biobuf *bp, int f, int mode) | |
| 2203 | + 91 { | |
| 2204 | +>92 return Binits(bp, f, mode, bp->b, BSIZE); | |
| 2205 | + 93 } | |
| 2206 | +.Ee | |
| 2207 | +.\" | |
| 2208 | +.\" | |
| 2209 | +.\" | |
| 2210 | +.Ip \f(CW{}\fP notestk integer "Stack trace after receiving a note | |
| 2211 | +.CW notestk | |
| 2212 | +interprets its | |
| 2213 | +.I integer | |
| 2214 | +argument as the address of a | |
| 2215 | +.CW Ureg | |
| 2216 | +structure passed by the kernel to a | |
| 2217 | +.I notify (2) | |
| 2218 | +function during note processing. | |
| 2219 | +.CW notestk | |
| 2220 | +uses the | |
| 2221 | +.CW PC , | |
| 2222 | +.CW SP , | |
| 2223 | +and link register from the | |
| 2224 | +.CW Ureg | |
| 2225 | +to print a stack trace corresponding to the point in the program where the note | |
| 2226 | +was received. | |
| 2227 | +To get a valid stack trace on the MIPS and SPARC architectures from a notify | |
| 2228 | +routine, the program must stop in a new function called from the notify routine | |
| 2229 | +so that the link register is valid and the notify routine's parameters are | |
| 2230 | +addressable. | |
| 2231 | +.Ex | |
| 2232 | +acid: notestk(*notify:ur) | |
| 2233 | +Note pc:0x00001024:main+0x4 ls.c:48 | |
| 2234 | +main(argc=0x00000001,argv=0x7fffefec) ls.c:48 | |
| 2235 | + called from _main+0x20 main9.s:10 | |
| 2236 | + _argc=0x00000000 | |
| 2237 | + _args=0x00000000 | |
| 2238 | +.Ee | |
| 2239 | +.\" | |
| 2240 | +.\" | |
| 2241 | +.\" | |
| 2242 | +.Ip \f(CW{}\fP pfl integer "Print source file and line | |
| 2243 | +.CW pfl | |
| 2244 | +interprets its argument as a text address and uses it to print | |
| 2245 | +the source file and line number corresponding to the address. The output | |
| 2246 | +has the same format as file addresses in | |
| 2247 | +.I acme (1). | |
| 2248 | +.Ex | |
| 2249 | +acid: pfl(main) | |
| 2250 | +ls.c:48 | |
| 2251 | +.Ee | |
| 2252 | +.\" | |
| 2253 | +.\" | |
| 2254 | +.\" | |
| 2255 | +.Ip \f(CW{}\fP procs "" "Print active process list | |
| 2256 | +.CW procs | |
| 2257 | +prints a list of active process attached to the debugger. Each process | |
| 2258 | +produces a single line of output giving the pid, process state, the address | |
| 2259 | +the process is currently executing, and the | |
| 2260 | +.CW setproc | |
| 2261 | +command required to make that process current. | |
| 2262 | +The current process is marked in the first column with a | |
| 2263 | +.CW > | |
| 2264 | +character. The debugger maintains a list of processes in the variable | |
| 2265 | +.CW proclist . | |
| 2266 | +.Ex | |
| 2267 | +acid: procs() | |
| 2268 | +>62: Stopped at main+0x4 setproc(62) | |
| 2269 | + 60: Stopped at Binit+0x8 setproc(60) | |
| 2270 | +.Ee | |
| 2271 | +.\" | |
| 2272 | +.\" | |
| 2273 | +.\" | |
| 2274 | +.Ip \f(CW{}\fP pstop integer "Print reason process stopped | |
| 2275 | +.CW pstop | |
| 2276 | +prints the status of the process specified by the | |
| 2277 | +.I integer | |
| 2278 | +pid supplied as its argument. | |
| 2279 | +.CW pstop | |
| 2280 | +is usually called from | |
| 2281 | +.CW stopped | |
| 2282 | +every time a process enters the | |
| 2283 | +.CW Stopped | |
| 2284 | +state. | |
| 2285 | +.Ex | |
| 2286 | +acid: pstop(62) | |
| 2287 | +0x0000003e: breakpoint main+0x4 MOVW R31,0x0(R29) | |
| 2288 | +.Ee | |
| 2289 | +.\" | |
| 2290 | +.\" | |
| 2291 | +.\" | |
| 2292 | +.Ip \f(CW{}\fP regs "" "Print registers | |
| 2293 | +.CW regs | |
| 2294 | +prints the contents of both the general and special purpose registers. | |
| 2295 | +.CW regs | |
| 2296 | +calls | |
| 2297 | +.CW spr | |
| 2298 | +then | |
| 2299 | +.CW gpr | |
| 2300 | +to display the contents of the registers. | |
| 2301 | +.KE | |
| 2302 | +.\" | |
| 2303 | +.\" | |
| 2304 | +.\" | |
| 2305 | +.Ip \f(CW{}\fP source "" "Summarize source data base | |
| 2306 | +.CW source | |
| 2307 | +prints the directory search path followed by a list of currently loaded | |
| 2308 | +source files. The source management functions | |
| 2309 | +.CW src | |
| 2310 | +and | |
| 2311 | +.CW findsrc | |
| 2312 | +use the search path to locate and load source files. Source files are | |
| 2313 | +loaded incrementally into a source data base during debugging. A list | |
| 2314 | +of loaded files is stored in the variable | |
| 2315 | +.CW srcfiles | |
| 2316 | +and the contents of each source file in the variable | |
| 2317 | +.CW srctext . | |
| 2318 | +.Ex | |
| 2319 | +acid: source() | |
| 2320 | +/n/bootes/sys/src/libbio/ | |
| 2321 | +./ | |
| 2322 | +/sys/src/libc/port/ | |
| 2323 | +/sys/src/libc/9sys/ | |
| 2324 | +/sys/src/libc/mips/ | |
| 2325 | + binit.c | |
| 2326 | +.Ee | |
| 2327 | +.\" | |
| 2328 | +.\" | |
| 2329 | +.\" | |
| 2330 | +.Ip \f(CW{}\fP spr "" "Print special purpose registers | |
| 2331 | +.CW spr | |
| 2332 | +prints the contents of the processor control and memory management | |
| 2333 | +registers. Where possible, the contents of the registers are decoded | |
| 2334 | +to provide extra information; for example the | |
| 2335 | +.CW CAUSE | |
| 2336 | +register on the MIPS is | |
| 2337 | +printed both in hexadecimal and using the | |
| 2338 | +.CW reason | |
| 2339 | +function. | |
| 2340 | +.Ex | |
| 2341 | +acid: spr() | |
| 2342 | +PC 0x00001024 main+0x4 ls.c:48 | |
| 2343 | +SP 0x7fffef68 LINK 0x00006264 _main+0x28 main9.s:12 | |
| 2344 | +STATUS 0x0000ff33 CAUSE 0x00000024 breakpoint | |
| 2345 | +TLBVIR 0x000000d3 BADVADR 0x00001020 | |
| 2346 | +HI 0x00000004 LO 0x00001ff7 | |
| 2347 | +.Ee | |
| 2348 | +.\" | |
| 2349 | +.\" | |
| 2350 | +.\" | |
| 2351 | +.Ip \f(CW{}\fP src integer "Print lines of source | |
| 2352 | +.CW src | |
| 2353 | +interprets its | |
| 2354 | +.I integer | |
| 2355 | +argument as a text address and uses this address to print 5 lines | |
| 2356 | +of source before and after the address. The current line is marked with a | |
| 2357 | +.CW > | |
| 2358 | +character. | |
| 2359 | +.CW src | |
| 2360 | +uses the source search path maintained by | |
| 2361 | +.CW source | |
| 2362 | +and | |
| 2363 | +.CW addsrcdir | |
| 2364 | +to locate the required source files. | |
| 2365 | +.Ex | |
| 2366 | +acid: src(*PC) | |
| 2367 | +ls.c:47 | |
| 2368 | + 42 Biobuf bin; | |
| 2369 | + 43 | |
| 2370 | + 44 #define HUNK 50 | |
| 2371 | + 45 | |
| 2372 | + 46 void | |
| 2373 | +>47 main(int argc, char *argv[]) | |
| 2374 | + 48 { | |
| 2375 | + 49 int i, fd; | |
| 2376 | + 50 char buf[64]; | |
| 2377 | + 51 | |
| 2378 | + 52 Binit(&bin, 1, OWRITE); | |
| 2379 | +.Ee | |
| 2380 | +.\" | |
| 2381 | +.\" | |
| 2382 | +.\" | |
| 2383 | +.Ip \f(CW{}\fP step "" "Single step process | |
| 2384 | +.CW step | |
| 2385 | +causes the debugged process to execute a single machine level instruction. | |
| 2386 | +If the program is stopped on a breakpoint set by | |
| 2387 | +.CW bpset | |
| 2388 | +it is first removed, the single step executed, and the breakpoint replaced. | |
| 2389 | +.CW step | |
| 2390 | +uses | |
| 2391 | +.CW follow | |
| 2392 | +to predict the address of the program counter after the current instruction | |
| 2393 | +has been executed. A breakpoint is placed at each of these predicted addresses | |
| 2394 | +and the process is started. When the process stops the breakpoints are removed. | |
| 2395 | +.Ex | |
| 2396 | +acid: step() | |
| 2397 | +62: breakpoint main+0x8 MOVW R1,argc+4(FP) | |
| 2398 | +.Ee | |
| 2399 | +.\" | |
| 2400 | +.\" | |
| 2401 | +.\" | |
| 2402 | +.Ip \f(CW{}\fP stk "" "Stack trace | |
| 2403 | +.CW stk | |
| 2404 | +produces a short format stack trace. The stack trace includes each function | |
| 2405 | +in the stack, where it was called from, and the value of the parameters. | |
| 2406 | +The short format omits the values of automatic variables. | |
| 2407 | +Parameters are assumed to be integer values in the format | |
| 2408 | +.CW X ; | |
| 2409 | +to print a parameter in the correct format use the | |
| 2410 | +.CW : | |
| 2411 | +to obtain its address, apply the correct format, and use the | |
| 2412 | +.CW * | |
| 2413 | +indirection operator to find its value. | |
| 2414 | +It may be necessary to single step a couple of instructions into | |
| 2415 | +a function to get a correct stack trace because the frame pointer adjustment | |
| 2416 | +instruction may get scheduled down into the body of the function. | |
| 2417 | +.Ex | |
| 2418 | +acid: stk() | |
| 2419 | +At pc:0x00001028:main+0x8 ls.c:48 | |
| 2420 | +main(argc=0x00000002,argv=0x7fffefe4) ls.c:48 | |
| 2421 | + called from _main+0x20 main9.s:10 | |
| 2422 | +.Ee | |
| 2423 | +.\" | |
| 2424 | +.\" | |
| 2425 | +.\" | |
| 2426 | +.Ip \f(CW{}\fP stmnt "" "Execute a single statement | |
| 2427 | +.CW stmnt | |
| 2428 | +executes a single language level statement. | |
| 2429 | +.CW stmnt | |
| 2430 | +displays each machine level instruction as it is executed. When the executed | |
| 2431 | +statement is completed the source for the next statement is displayed. | |
| 2432 | +Unlike | |
| 2433 | +.CW next , | |
| 2434 | +the | |
| 2435 | +.CW stmnt | |
| 2436 | +function will trace down through function calls. | |
| 2437 | +.Ex | |
| 2438 | +acid: stmnt() | |
| 2439 | +62: breakpoint main+0x18 MOVW R5,0xc(R29) | |
| 2440 | +62: breakpoint main+0x1c JAL Binit(SB) | |
| 2441 | +62: breakpoint Binit ADD $-0x18,R29 | |
| 2442 | +binit.c:91 | |
| 2443 | + 89 int | |
| 2444 | + 90 Binit(Biobuf *bp, int f, int mode) | |
| 2445 | +>91 { | |
| 2446 | +.Ee | |
| 2447 | +.\" | |
| 2448 | +.\" | |
| 2449 | +.\" | |
| 2450 | +.Ip \f(CW{}\fP stopped integer "Report status of stopped process | |
| 2451 | +.CW stopped | |
| 2452 | +is called automatically by the interpreter | |
| 2453 | +every time a process enters the | |
| 2454 | +.CW Stopped | |
| 2455 | +state, such as when it hits a breakpoint. | |
| 2456 | +The pid is passed as the | |
| 2457 | +.I integer | |
| 2458 | +argument. The default implementation just calls | |
| 2459 | +.CW pstop , | |
| 2460 | +but the function may be changed to provide more information or perform fine control | |
| 2461 | +of execution. Note that | |
| 2462 | +.CW stopped | |
| 2463 | +should return; for example, calling | |
| 2464 | +.CW step | |
| 2465 | +in | |
| 2466 | +.CW stopped | |
| 2467 | +will recur until the interpreter runs out of stack space. | |
| 2468 | +.Ex | |
| 2469 | +acid: defn stopped(pid) { | |
| 2470 | + if *lflag != 0 then error("lflag modified"); | |
| 2471 | + } | |
| 2472 | +acid: progargs = "-l" | |
| 2473 | +acid: new(); | |
| 2474 | +acid: while 1 do step(); | |
| 2475 | +<stdin>:7: (error) lflag modified | |
| 2476 | +acid: stk() | |
| 2477 | +At pc:0x00001220:main+0x200 ls.c:54 | |
| 2478 | +main(argc=0x00000001,argv=0x7fffffe8) ls.c:48 | |
| 2479 | + called from _main+0x20 main9.s:10 | |
| 2480 | +.Ee | |
| 2481 | +.\" | |
| 2482 | +.\" | |
| 2483 | +.\" | |
| 2484 | +.Ip \f(CW{}\fP symbols string "Search symbol table | |
| 2485 | +.CW symbols | |
| 2486 | +uses the regular expression supplied by | |
| 2487 | +.I string | |
| 2488 | +to search the symbol table for symbols whose name matches the | |
| 2489 | +regular expression. | |
| 2490 | +.Ex | |
| 2491 | +acid: symbols("main") | |
| 2492 | +main T 0x00001020 | |
| 2493 | +_main T 0x0000623c | |
| 2494 | +.Ee | |
| 2495 | +.\" | |
| 2496 | +.\" | |
| 2497 | +.\" | |
| 2498 | +.Ip \f(CW{}\fP win "" "Start new process in a window | |
| 2499 | +.CW win | |
| 2500 | +performs exactly the same function as | |
| 2501 | +.CW new | |
| 2502 | +but uses the window system to create a new window for the debugged process. | |
| 2503 | +The variable | |
| 2504 | +.CW progargs | |
| 2505 | +supplies arguments to the new process. | |
| 2506 | +The environment variable | |
| 2507 | +.CW $8½srv | |
| 2508 | +must be set to allow the interpreter to locate the mount channel for the | |
| 2509 | +window system. | |
| 2510 | +The window is created in the top left corner of the screen and is | |
| 2511 | +400x600 pixels in size. The | |
| 2512 | +.CW win | |
| 2513 | +function may be modified to alter the geometry. | |
| 2514 | +The window system will not be able to deliver notes in the new window | |
| 2515 | +since the pid of the created process is not passed when the server is | |
| 2516 | +mounted to create a new window. | |
| 2517 | +.Ex | |
| 2518 | +acid: win() | |
| 2519 | +.Ee | |
Binary file not shown.
| @@ -0,0 +1,1327 @@ | ||
| 1 | +.TL | |
| 2 | +Acid: A Debugger Built From A Language | |
| 3 | +.AU | |
| 4 | +.I "Phil Winterbottom" | |
| 5 | +.AI | |
| 6 | +.I "Lucent Technologies Inc" | |
| 7 | +.AB | |
| 8 | +.FS | |
| 9 | +\l'1i' | |
| 10 | +.br | |
| 11 | +Originally appeared in | |
| 12 | +.I | |
| 13 | +Proc. of the Winter 1994 USENIX Conf., | |
| 14 | +.R | |
| 15 | +pp. 211-222, | |
| 16 | +San Francisco, CA; | |
| 17 | +and subsequently in the | |
| 18 | +.I "Plan 9 Programmer's Manual, Volume 2 (Second Edition)" . | |
| 19 | +.FE | |
| 20 | +Acid is an unusual source-level symbolic debugger for Plan 9. It is implemented | |
| 21 | +as a language interpreter with specialized primitives that provide | |
| 22 | +debugger support. Programs written in the language manipulate | |
| 23 | +one or more target processes; variables in the language represent the | |
| 24 | +symbols, state, and resources of those processes. | |
| 25 | +This structure allows complex | |
| 26 | +interaction between the debugger and the target program and | |
| 27 | +provides a convenient method of parameterizing differences between | |
| 28 | +machine architectures. | |
| 29 | +Although some effort is required to learn | |
| 30 | +the debugging language, the richness and flexibility of the | |
| 31 | +debugging environment encourages new ways of reasoning about the way | |
| 32 | +programs run and the conditions under which they fail. | |
| 33 | +.AE | |
| 34 | +.NH | |
| 35 | +Introduction | |
| 36 | +.PP | |
| 37 | +The size and complexity | |
| 38 | +of programs have increased in proportion to processor speed and memory but | |
| 39 | +the interface between debugger and programmer has changed little. | |
| 40 | +Graphical user interfaces have eased some of the tedious | |
| 41 | +aspects of the interaction. A graphical interface is a convenient | |
| 42 | +means for navigating through source and data structures but provides | |
| 43 | +little benefit for process control. | |
| 44 | +The introduction of a new concurrent language, Alef [Win93], emphasized the | |
| 45 | +inadequacies of the existing Plan 9 [Pike90] debugger | |
| 46 | +.I db , | |
| 47 | +a distant relative of | |
| 48 | +.I adb , | |
| 49 | +and made it clear that a new debugger was required. | |
| 50 | +.PP | |
| 51 | +Current debuggers like | |
| 52 | +.I dbx , | |
| 53 | +.I sdb , | |
| 54 | +and | |
| 55 | +.I gdb | |
| 56 | +are limited to answering only the questions their authors | |
| 57 | +envisage. As a result, they supply a plethora | |
| 58 | +of specialized commands, each attempting to anticipate | |
| 59 | +a specific question a user may ask. | |
| 60 | +When a debugging situation arises that is beyond the scope | |
| 61 | +of the command set, the tool is useless. | |
| 62 | +Further, | |
| 63 | +it is often tedious or impossible to reproduce an anomalous state | |
| 64 | +of the program, especially when | |
| 65 | +the state is embedded in the program's data structures. | |
| 66 | +.PP | |
| 67 | +Acid applies some ideas found in CAD software used for | |
| 68 | +hardware test and simulation. | |
| 69 | +It is based on the notion that the state and resources of a program | |
| 70 | +are best represented and manipulated by a language. The state and resources, | |
| 71 | +such as memory, registers, variables, type information and source code | |
| 72 | +are represented by variables in the language. | |
| 73 | +Expressions provide a computation mechanism and control | |
| 74 | +statements allow repetitive or selective interpretation based | |
| 75 | +on the result of expression evaluation. | |
| 76 | +The heart of the Acid debugger is an interpreter for a small typeless | |
| 77 | +language whose operators mirror the operations | |
| 78 | +of C and Alef, which in turn correspond well to the basic operations of | |
| 79 | +the machine. The interpreter itself knows nothing of the underlying | |
| 80 | +hardware; it deals with the program state and resources | |
| 81 | +in the abstract. | |
| 82 | +Fundamental routines to control | |
| 83 | +processes, read files, and interface to the system are implemented | |
| 84 | +as builtin functions available to the interpreter. | |
| 85 | +The actual debugger functionality is coded | |
| 86 | +in Acid; commands are implemented as Acid functions. | |
| 87 | +.PP | |
| 88 | +This language-based approach has several advantages. | |
| 89 | +Most importantly, programs written in Acid, including most of the | |
| 90 | +debugger itself, are inherently portable. | |
| 91 | +Furthermore, Acid avoids the limitations other debuggers impose when | |
| 92 | +debugging parallel programs. Instead of embedding a fixed | |
| 93 | +process model in the debugger, Acid allows the | |
| 94 | +programmer to adapt the debugger to handle an | |
| 95 | +arbitrary process partitioning or program structure. | |
| 96 | +The ability to | |
| 97 | +interact dynamically with an executing process provides clear advantages | |
| 98 | +over debuggers constrained to probe a static image. | |
| 99 | +Finally, the Acid language is a powerful vehicle for expressing | |
| 100 | +assertions about logic, process state, and the contents of data structures. | |
| 101 | +When combined with dynamic interaction it allows a | |
| 102 | +limited form of automated program verification without requiring | |
| 103 | +modification or recompilation of the source code. | |
| 104 | +The language is also an | |
| 105 | +excellent vehicle for preserving a test suite for later regression testing. | |
| 106 | +.PP | |
| 107 | +The debugger may be customized by its users; standard | |
| 108 | +functions may be modified or extended to suit a particular application | |
| 109 | +or preference. | |
| 110 | +For example, the kernel developers in our group require a | |
| 111 | +command set supporting assembler-level debugging while the application | |
| 112 | +programmers prefer source-level functionality. | |
| 113 | +Although the default library is biased toward assembler-level debugging, | |
| 114 | +it is easily modified to provide a convenient source-level interface. | |
| 115 | +The debugger itself does not change; the user combines primitives | |
| 116 | +and existing Acid functions in different ways to | |
| 117 | +implement the desired interface. | |
| 118 | +.NH | |
| 119 | +Related Work | |
| 120 | +.PP | |
| 121 | +DUEL [Gol93], an extension to | |
| 122 | +.I gdb | |
| 123 | +[Stal91], proposes using a high level expression evaluator to solve | |
| 124 | +some of these problems. The evaluator provides iterators to loop over data | |
| 125 | +structures and conditionals to control evaluation of expressions. | |
| 126 | +The author shows that complex state queries can be formulated | |
| 127 | +by combining concise expressions but this only addresses part of the problem. | |
| 128 | +A program is a dynamic entity; questions asked when the program is in | |
| 129 | +a static state are meaningful only after the program has been `caught' in | |
| 130 | +that state. The framework for manipulating the program is still as | |
| 131 | +primitive as the underlying debugger. While DUEL provides a means to | |
| 132 | +probe data structures it entirely neglects the most beneficial aspect | |
| 133 | +of debugging languages: the ability to control processes. Acid is structured | |
| 134 | +around a thread of control that passes between the interpreter and the | |
| 135 | +target program. | |
| 136 | +.PP | |
| 137 | +The NeD debugger [May92] is a set of extensions to TCL [Ous90] that provide | |
| 138 | +debugging primitives. The resulting language, NeDtcl, is used to implement | |
| 139 | +a portable interface between a conventional debugger, pdb [May90], and | |
| 140 | +a server that executes NeDtcl programs operating on the target program. | |
| 141 | +Execution of the NeDtcl programs implements the debugging primitives | |
| 142 | +that pdb expects. | |
| 143 | +NeD is targeted at multi-process debugging across a network, | |
| 144 | +and proves the flexibility of a language as a means of | |
| 145 | +communication between debugging tools. Whereas NeD provides an interface | |
| 146 | +between a conventional debugger and the process it debugs, Acid is the | |
| 147 | +debugger itself. While NeD has some of the ideas | |
| 148 | +found in Acid it is targeted toward a different purpose. Acid seeks to | |
| 149 | +integrate the manipulation of a program's resources into the debugger | |
| 150 | +while NeD provides a flexible interconnect between components of | |
| 151 | +the debugging environment. The choice of TCL is appropriate for its use | |
| 152 | +in NeD but is not suitable for Acid. Acid relies on the coupling of the type | |
| 153 | +system with expression evaluation, which are the root of its design, | |
| 154 | +to provide the debugging primitives. | |
| 155 | +.PP | |
| 156 | +Dalek [Ols90] is an event based language extension to gdb. State transitions | |
| 157 | +in the target program cause events to be queued for processing by the | |
| 158 | +debugging language. | |
| 159 | +.PP | |
| 160 | +Acid has many of the advantages of same process or | |
| 161 | +.I local | |
| 162 | +.I agent | |
| 163 | +debuggers, like Parasight [Aral], without the need for dynamic linking or | |
| 164 | +shared memory. | |
| 165 | +Acid improves on the ideas of these other systems by completely integrating | |
| 166 | +all aspects of the debugging process into the language environment. Of | |
| 167 | +particular importance is the relationship between Acid variables, | |
| 168 | +program symbols, source code, registers and type information. This | |
| 169 | +integration is made possible by the design of the Acid language. | |
| 170 | +.PP | |
| 171 | +Interpreted languages such as Lisp and Smalltalk are able to provide | |
| 172 | +richer debugging environments through more complete information than | |
| 173 | +their compiled counterparts. Acid is a means to gather and represent | |
| 174 | +similar information about compiled programs through cooperation | |
| 175 | +with the compilation tools and library implementers. | |
| 176 | +.NH | |
| 177 | +Acid the Language | |
| 178 | +.PP | |
| 179 | +Acid is a small interpreted language targeted to its debugging task. | |
| 180 | +It focuses on representing program state and addressing data rather than | |
| 181 | +expressing complex computations. Program state is | |
| 182 | +.I addressable | |
| 183 | +from an Acid program. | |
| 184 | +In addition to parsing and executing expressions and providing | |
| 185 | +an architecture-independent interface to the target process, | |
| 186 | +the interpreter supplies a mark-and-scan garbage collector | |
| 187 | +to manage storage. | |
| 188 | +.PP | |
| 189 | +Every Acid session begins with the loading of the Acid libraries. | |
| 190 | +These libraries contain functions, written in Acid, that provide | |
| 191 | +a standard debugging environment including breakpoint management, | |
| 192 | +stepping by instruction or statement, stack tracing, and | |
| 193 | +access to variables, memory, and registers. | |
| 194 | +The library contains 600 lines of Acid code and provides | |
| 195 | +functionality similar to | |
| 196 | +.I dbx . | |
| 197 | +Following the loading of the system library, Acid loads | |
| 198 | +user-specified libraries; this load sequence allows the | |
| 199 | +user to augment or override the standard commands | |
| 200 | +to customize the debugging environment. When all libraries | |
| 201 | +are loaded, Acid issues an interactive prompt and begins | |
| 202 | +evaluating expressions entered by the user. The Acid `commands' | |
| 203 | +are actually invocations of builtin primitives or previously defined | |
| 204 | +Acid functions. Acid evaluates each expression as it is entered and | |
| 205 | +prints the result. | |
| 206 | +.NH | |
| 207 | +Types and Variables | |
| 208 | +.PP | |
| 209 | +Acid variables are of four basic types: | |
| 210 | +.I integer , | |
| 211 | +.I string , | |
| 212 | +.I float , | |
| 213 | +and | |
| 214 | +.I list . | |
| 215 | +The type of a variable is inferred by the type of the right-hand side of | |
| 216 | +an assignment expression. | |
| 217 | +Many of the operators can be applied to more than | |
| 218 | +one type; for these operators the action of the operator is determined | |
| 219 | +by the type of its operands. | |
| 220 | +For example, | |
| 221 | +the | |
| 222 | +.CW + | |
| 223 | +operator adds | |
| 224 | +.I integer | |
| 225 | +and | |
| 226 | +.I float | |
| 227 | +operands, and concatenates | |
| 228 | +.I string | |
| 229 | +and | |
| 230 | +.I list | |
| 231 | +operands. | |
| 232 | +Lists are the only complex type in Acid; there are no arrays, structures | |
| 233 | +or pointers. Operators provide | |
| 234 | +.CW head , | |
| 235 | +.CW tail , | |
| 236 | +.CW append | |
| 237 | +and | |
| 238 | +.CW delete | |
| 239 | +operations. | |
| 240 | +Lists can also be indexed like arrays. | |
| 241 | +.PP | |
| 242 | +Acid has two levels of scope: global and local. | |
| 243 | +Function parameters and variables declared in a function body | |
| 244 | +using the | |
| 245 | +.CW local | |
| 246 | +keyword are created at entry to the function and | |
| 247 | +exist for the lifetime of a function. | |
| 248 | +Global variables are created by assignment and need not be declared. | |
| 249 | +All variables and functions in the program | |
| 250 | +being debugged are entered in the Acid symbol table as global | |
| 251 | +variables during Acid initialization. | |
| 252 | +Conflicting variable names are resolved by prefixing enough `$' characters | |
| 253 | +to make them unique. | |
| 254 | +Syntactically, Acid variables and target program | |
| 255 | +symbols are referenced identically. | |
| 256 | +However, the variables are managed differently in the Acid | |
| 257 | +symbol table and the user must be aware of this distinction. | |
| 258 | +The value of an Acid variable is stored in the symbol | |
| 259 | +table; a reference returns the value. | |
| 260 | +The symbol table entry for a variable or function in the target | |
| 261 | +program contains the address of that symbol in the image | |
| 262 | +of the program. Thus, the value of a program variable is | |
| 263 | +accessed by indirect reference through the Acid | |
| 264 | +variable that has the same name; the value of an Acid variable is the | |
| 265 | +address of the corresponding program variable. | |
| 266 | +.NH | |
| 267 | +Control Flow | |
| 268 | +.PP | |
| 269 | +The | |
| 270 | +.CW while | |
| 271 | +and | |
| 272 | +.CW loop | |
| 273 | +statements implement looping. | |
| 274 | +The former | |
| 275 | +is similar to the same statement in C. | |
| 276 | +The latter evaluates starting and ending expressions yielding | |
| 277 | +integers and iterates while an incrementing loop index | |
| 278 | +is within the bounds of those expressions. | |
| 279 | +.P1 | |
| 280 | +acid: i = 0; loop 1,5 do print(i=i+1) | |
| 281 | +0x00000001 | |
| 282 | +0x00000002 | |
| 283 | +0x00000003 | |
| 284 | +0x00000004 | |
| 285 | +0x00000005 | |
| 286 | +acid: | |
| 287 | +.P2 | |
| 288 | +The traditional | |
| 289 | +.CW if-then-else | |
| 290 | +statement implements conditional execution. | |
| 291 | +.NH | |
| 292 | +Addressing | |
| 293 | +.PP | |
| 294 | +Two indirection operators allow Acid to access values in | |
| 295 | +the program being debugged. | |
| 296 | +The | |
| 297 | +.CW * | |
| 298 | +operator fetches a value from the memory image of an | |
| 299 | +executing process; | |
| 300 | +the | |
| 301 | +.CW @ | |
| 302 | +operator fetches a value from the text file of the process. | |
| 303 | +When either operator appears on the left side of an assignment, the value | |
| 304 | +is written rather than read. | |
| 305 | +.PP | |
| 306 | +The indirection operator must know the size of the object | |
| 307 | +referenced by a variable. | |
| 308 | +The Plan 9 compilers neglect to include this | |
| 309 | +information in the program symbol table, so Acid cannot | |
| 310 | +derive this information implicitly. | |
| 311 | +Instead Acid variables have formats. | |
| 312 | +The format is a code | |
| 313 | +letter specifying the printing style and the effect of some of the | |
| 314 | +operators on that variable. | |
| 315 | +The indirection operators look at the format code to determine the | |
| 316 | +number of bytes to read or write. | |
| 317 | +The format codes are derived from the format letters used by | |
| 318 | +.I db . | |
| 319 | +By default, symbol table variables and numeric constants | |
| 320 | +are assigned the format code | |
| 321 | +.CW 'X' | |
| 322 | +which specifies 32-bit hexadecimal. | |
| 323 | +Printing such a variable yields output of the form | |
| 324 | +.CW 0x00123456 . | |
| 325 | +An indirect reference through the variable fetches 32 bits | |
| 326 | +of data at the address indicated by the variable. | |
| 327 | +Other formats specify various data types, for example | |
| 328 | +.CW i | |
| 329 | +an instruction, | |
| 330 | +.CW D | |
| 331 | +a signed 32 bit decimal, | |
| 332 | +.CW s | |
| 333 | +a null-terminated string. | |
| 334 | +The | |
| 335 | +.CW fmt | |
| 336 | +function | |
| 337 | +allows the user to change the format code of a variable | |
| 338 | +to control the printing format and | |
| 339 | +operator side effects. | |
| 340 | +This function evaluates the expression supplied as the first | |
| 341 | +argument, attaches the format code supplied as the second | |
| 342 | +argument to the result and returns that value. | |
| 343 | +If the result is assigned to a variable, | |
| 344 | +the new format code applies to | |
| 345 | +that variable. For convenience, Acid provides the | |
| 346 | +.CW \e | |
| 347 | +operator as a shorthand infix form of | |
| 348 | +.CW fmt . | |
| 349 | +For example: | |
| 350 | +.P1 | |
| 351 | +acid: x=10 | |
| 352 | +acid: x // print x in hex | |
| 353 | +0x0000000a | |
| 354 | +acid: x = fmt(x, 'D') // make x type decimal | |
| 355 | +acid: print(x, fmt(x, 'X'), x\eX) // print x in decimal & hex | |
| 356 | +10 0x0000000a 0x0000000a | |
| 357 | +acid: x // print x in decimal | |
| 358 | +10 | |
| 359 | +acid: x\eo // print x in octal | |
| 360 | +000000000012 | |
| 361 | +.P2 | |
| 362 | +The | |
| 363 | +.CW ++ | |
| 364 | +and | |
| 365 | +.CW -- | |
| 366 | +operators increment or decrement a variable by an amount | |
| 367 | +determined by its format code. Some formats imply a non-fixed size. | |
| 368 | +For example, the | |
| 369 | +.CW i | |
| 370 | +format code disassembles an instruction into a string. | |
| 371 | +On a 68020, which has variable length instructions: | |
| 372 | +.P1 | |
| 373 | +acid: p=main\ei // p=addr(main), type INST | |
| 374 | +acid: loop 1,5 do print(p\eX, @p++) // disassemble 5 instr's | |
| 375 | +0x0000222e LEA 0xffffe948(A7),A7 | |
| 376 | +0x00002232 MOVL s+0x4(A7),A2 | |
| 377 | +0x00002236 PEA 0x2f($0) | |
| 378 | +0x0000223a MOVL A2,-(A7) | |
| 379 | +0x0000223c BSR utfrrune | |
| 380 | +acid: | |
| 381 | +.P2 | |
| 382 | +Here, | |
| 383 | +.CW main | |
| 384 | +is the address of the function of the same name in the program under test. | |
| 385 | +The loop retrieves the five instructions beginning at that address and | |
| 386 | +then prints the address and the assembly language representation of each. | |
| 387 | +Notice that the stride of the increment operator varies with the size of | |
| 388 | +the instruction: the | |
| 389 | +.CW MOVL | |
| 390 | +at | |
| 391 | +.CW 0x0000223a | |
| 392 | +is a two byte instruction while all others are four bytes long. | |
| 393 | +.PP | |
| 394 | +Registers are treated as normal program variables referenced | |
| 395 | +by their symbolic assembler language names. | |
| 396 | +When a | |
| 397 | +process stops, the register set is saved by the kernel | |
| 398 | +at a known virtual address in the process memory map. | |
| 399 | +The Acid variables associated with the registers point | |
| 400 | +to the saved values and the | |
| 401 | +.CW * | |
| 402 | +indirection operator can then be used to read and write the register set. | |
| 403 | +Since the registers are accessed via Acid variables they may | |
| 404 | +be used in arbitrary expressions. | |
| 405 | +.P1 | |
| 406 | +acid: PC // addr of saved PC | |
| 407 | +0xc0000f60 | |
| 408 | +acid: *PC | |
| 409 | +0x0000623c // contents of PC | |
| 410 | +acid: *PC\ea | |
| 411 | +main | |
| 412 | +acid: *R1=10 // modify R1 | |
| 413 | +acid: asm(*PC+4) // disassemble @ PC+4 | |
| 414 | +main+0x4 0x00006240 MOVW R31,0x0(R29) | |
| 415 | +main+0x8 0x00006244 MOVW $setR30(SB),R30 | |
| 416 | +main+0x10 0x0000624c MOVW R1,_clock(SB) | |
| 417 | +.P2 | |
| 418 | +Here, the saved | |
| 419 | +.CW PC | |
| 420 | +is stored at address | |
| 421 | +.CW 0xc0000f60 ; | |
| 422 | +its current content is | |
| 423 | +.CW 0x0000623c . | |
| 424 | +The | |
| 425 | +.CW a ' ` | |
| 426 | +format code converts this value to a string specifying | |
| 427 | +the address as an offset beyond the nearest symbol. | |
| 428 | +After setting the value of register | |
| 429 | +.CW 1 , | |
| 430 | +the example uses the | |
| 431 | +.CW asm | |
| 432 | +command to disassemble a short section of code beginning | |
| 433 | +at four bytes beyond the current value of the | |
| 434 | +.CW PC . | |
| 435 | +.NH | |
| 436 | +Process Interface | |
| 437 | +.PP | |
| 438 | +A program executing under Acid is monitored through the | |
| 439 | +.I proc | |
| 440 | +file system interface provided by Plan 9. | |
| 441 | +Textual messages written to the | |
| 442 | +.CW ctl | |
| 443 | +file control the execution of the process. | |
| 444 | +For example writing | |
| 445 | +.CW waitstop | |
| 446 | +to the control file causes the write to block until the target | |
| 447 | +process enters the kernel and is stopped. When the process is stopped | |
| 448 | +the write completes. The | |
| 449 | +.CW startstop | |
| 450 | +message starts the target process and then does a | |
| 451 | +.CW waitstop | |
| 452 | +action. | |
| 453 | +Synchronization between the debugger and the target process is determined | |
| 454 | +by the actions of the various messages. Some operate asynchronously to the | |
| 455 | +target process and always complete immediately, others block until the | |
| 456 | +action completes. The asynchronous messages allow Acid to control | |
| 457 | +several processes simultaneously. | |
| 458 | +.PP | |
| 459 | +The interpreter has builtin functions named after each of the control | |
| 460 | +messages. The functions take a process id as argument. | |
| 461 | +Any time a control message causes the program to execute instructions | |
| 462 | +the interpreter performs two actions when the control operation has completed. | |
| 463 | +The Acid variables pointing at the register set are fixed up to point | |
| 464 | +at the saved registers, and then | |
| 465 | +the user defined function | |
| 466 | +.CW stopped | |
| 467 | +is executed. | |
| 468 | +The | |
| 469 | +.CW stopped | |
| 470 | +function may print the current address, | |
| 471 | +line of source or instruction and return to interactive mode. Alternatively | |
| 472 | +it may traverse a complex data structure, gather statistics and then set | |
| 473 | +the program running again. | |
| 474 | +.PP | |
| 475 | +Several Acid variables are maintained by the debugger rather than the | |
| 476 | +programmer. | |
| 477 | +These variables allow generic Acid code to deal with the current process, | |
| 478 | +architecture specifics or the symbol table. | |
| 479 | +The variable | |
| 480 | +.CW pid | |
| 481 | +is the process id of the current process Acid is debugging. | |
| 482 | +The variable | |
| 483 | +.CW symbols | |
| 484 | +contains a list of lists where each sublist contains the symbol | |
| 485 | +name, its type and the value of the symbol. | |
| 486 | +The variable | |
| 487 | +.CW registers | |
| 488 | +contains a list of the machine-specific register names. Global symbols in the target program | |
| 489 | +can be referenced directly by name from Acid. Local variables | |
| 490 | +are referenced using the colon operator as \f(CWfunction:variable\fP. | |
| 491 | +.NH | |
| 492 | +Source Level Debugging | |
| 493 | +.PP | |
| 494 | +Acid provides several builtin functions to manipulate source code. | |
| 495 | +The | |
| 496 | +.CW file | |
| 497 | +function reads a text file, inserting each line into a list. | |
| 498 | +The | |
| 499 | +.CW pcfile | |
| 500 | +and | |
| 501 | +.CW pcline | |
| 502 | +functions each take an address as an argument. | |
| 503 | +The first | |
| 504 | +returns a string containing the name of the source file | |
| 505 | +and the second returns an integer containing the line number | |
| 506 | +of the source line containing the instruction at the address. | |
| 507 | +.P1 | |
| 508 | +acid: pcfile(main) // file containing main | |
| 509 | +main.c | |
| 510 | +acid: pcline(main) // line # of main in source | |
| 511 | +11 | |
| 512 | +acid: file(pcfile(main))[pcline(main)] // print that line | |
| 513 | +main(int argc, char *argv[]) | |
| 514 | +acid: src(*PC) // print statements nearby | |
| 515 | + 9 | |
| 516 | + 10 void | |
| 517 | +>11 main(int argc, char *argv[]) | |
| 518 | + 12 { | |
| 519 | + 13 int a; | |
| 520 | +.P2 | |
| 521 | +In this example, the three primitives are combined in an expression to print | |
| 522 | +a line of source code associated with an address. | |
| 523 | +The | |
| 524 | +.CW src | |
| 525 | +function prints a few lines of source | |
| 526 | +around the address supplied as its argument. A companion routine, | |
| 527 | +.CW Bsrc , | |
| 528 | +communicates with the external editor | |
| 529 | +.CW sam . | |
| 530 | +Given an address, it loads the corresponding source file into the editor | |
| 531 | +and highlights the line containing the address. This simple interface | |
| 532 | +is easily extended to more complex functions. | |
| 533 | +For example, the | |
| 534 | +.CW step | |
| 535 | +function can select the current file and line in the editor | |
| 536 | +each time the target program stops, giving the user a visual | |
| 537 | +trace of the execution path of the program. A more complete interface | |
| 538 | +allowing two way communication between Acid and the | |
| 539 | +.CW acme | |
| 540 | +user interface [Pike93] is under construction. A filter between the debugger | |
| 541 | +and the user interface provides interpretation of results from both | |
| 542 | +sides of the interface. This allows the programming environment to | |
| 543 | +interact with the debugger and vice-versa, a capability missing from the | |
| 544 | +.CW sam | |
| 545 | +interface. | |
| 546 | +The | |
| 547 | +.CW src | |
| 548 | +and | |
| 549 | +.CW Bsrc | |
| 550 | +functions are both written in Acid code using the file and line primitives. | |
| 551 | +Acid provides library functions to step through source level | |
| 552 | +statements and functions. Furthermore, addresses in Acid expressions can be | |
| 553 | +specified by source file and line. | |
| 554 | +Source code is manipulated in the Acid | |
| 555 | +.I list | |
| 556 | +data type. | |
| 557 | +.NH | |
| 558 | +The Acid Library | |
| 559 | +.PP | |
| 560 | +The following examples define some useful commands and | |
| 561 | +illustrate the interaction of the debugger and the interpreter. | |
| 562 | +.P1 | |
| 563 | +defn bpset(addr) // set breakpoint | |
| 564 | +{ | |
| 565 | + if match(addr, bplist) >= 0 then | |
| 566 | + print("bkpoint already set:", addr\ea, "\en"); | |
| 567 | + else { | |
| 568 | + *fmt(addr, bpfmt) = bpinst; // plant it | |
| 569 | + bplist = append bplist, addr; // add to list | |
| 570 | + } | |
| 571 | +} | |
| 572 | +.P2 | |
| 573 | +The | |
| 574 | +.CW bpset | |
| 575 | +function plants a break point in memory. The function starts by | |
| 576 | +using the | |
| 577 | +.CW match | |
| 578 | +builtin to | |
| 579 | +search the breakpoint list to determine if a breakpoint is already | |
| 580 | +set at the address. | |
| 581 | +The indirection operator, controlled by the format code returned | |
| 582 | +by the | |
| 583 | +.CW fmt | |
| 584 | +primitive, is used to plant the breakpoint in memory. | |
| 585 | +The variables | |
| 586 | +.CW bpfmt | |
| 587 | +and | |
| 588 | +.CW bpinst | |
| 589 | +are Acid global variables containing the format code specifying | |
| 590 | +the size of the breakpoint instruction and the breakpoint instruction | |
| 591 | +itself. | |
| 592 | +These | |
| 593 | +variables are set by architecture-dependent library code | |
| 594 | +when the debugger first attaches to the executing image. | |
| 595 | +Finally the address of the breakpoint is | |
| 596 | +appended to the breakpoint list, | |
| 597 | +.CW bplist . | |
| 598 | +.P1 | |
| 599 | +defn step() // single step | |
| 600 | +{ | |
| 601 | + local lst, lpl, addr, bput; | |
| 602 | + | |
| 603 | + bput = 0; // sitting on bkpoint | |
| 604 | + if match(*PC, bplist) >= 0 then { | |
| 605 | + bput = fmt(*PC, bpfmt); // save current addr | |
| 606 | + *bput = @bput; // replace it | |
| 607 | + } | |
| 608 | + | |
| 609 | + lst = follow(*PC); // get follow set | |
| 610 | + | |
| 611 | + lpl = lst; | |
| 612 | + while lpl do { // place breakpoints | |
| 613 | + *(head lpl) = bpinst; | |
| 614 | + lpl = tail lpl; | |
| 615 | + } | |
| 616 | + | |
| 617 | + startstop(pid); // do the step | |
| 618 | + | |
| 619 | + while lst do { // remove breakpoints | |
| 620 | + addr = fmt(head lst, bpfmt); | |
| 621 | + *addr = @addr; // replace instr. | |
| 622 | + lst = tail lst; | |
| 623 | + } | |
| 624 | + if bput != 0 then | |
| 625 | + *bput = bpinst; // restore breakpoint | |
| 626 | +} | |
| 627 | +.P2 | |
| 628 | +The | |
| 629 | +.CW step | |
| 630 | +function executes a single assembler instruction. | |
| 631 | +If the | |
| 632 | +.CW PC | |
| 633 | +is sitting | |
| 634 | +on a breakpoint, the address and size of | |
| 635 | +the breakpoint are saved. | |
| 636 | +The breakpoint instruction | |
| 637 | +is then removed using the | |
| 638 | +.CW @ | |
| 639 | +operator to fetch | |
| 640 | +.CW bpfmt | |
| 641 | +bytes from the text file and to place it into the memory | |
| 642 | +of the executing process using the | |
| 643 | +.CW * | |
| 644 | +operator. | |
| 645 | +The | |
| 646 | +.CW follow | |
| 647 | +function is an Acid | |
| 648 | +builtin which returns a follow-set: a list of instruction addresses which | |
| 649 | +could be executed next. | |
| 650 | +If the instruction stored at the | |
| 651 | +.CW PC | |
| 652 | +is a branch instruction, the | |
| 653 | +list contains the addresses of the next instruction and | |
| 654 | +the branch destination; otherwise, it contains only the | |
| 655 | +address of the next instruction. | |
| 656 | +The follow-set is then used to replace each possible following | |
| 657 | +instruction with a breakpoint instruction. The original | |
| 658 | +instructions need not be saved; they remain | |
| 659 | +in their unaltered state in the text file. | |
| 660 | +The | |
| 661 | +.CW startstop | |
| 662 | +builtin writes the `startstop' message to the | |
| 663 | +.I proc | |
| 664 | +control file for the process named | |
| 665 | +.CW pid . | |
| 666 | +The target process executes until some condition causes it to | |
| 667 | +enter the kernel, in this case, the execution of a breakpoint. | |
| 668 | +When the process blocks, the debugger regains control and invokes the | |
| 669 | +Acid library function | |
| 670 | +.CW stopped | |
| 671 | +which reports the address and cause of the blockage. | |
| 672 | +The | |
| 673 | +.CW startstop | |
| 674 | +function completes and returns to the | |
| 675 | +.CW step | |
| 676 | +function where | |
| 677 | +the follow-set is used to replace the breakpoints placed earlier. | |
| 678 | +Finally, if the address of the original | |
| 679 | +.CW PC | |
| 680 | +contained a breakpoint, it is replaced. | |
| 681 | +.PP | |
| 682 | +Notice that this approach to process control is inherently portable; | |
| 683 | +the Acid code is shared by the debuggers for all architectures. | |
| 684 | +Acid variables and builtin functions provide a transparent interface | |
| 685 | +to architecture-dependent values and functions. Here the breakpoint | |
| 686 | +value and format are referenced through Acid variables and the | |
| 687 | +.CW follow | |
| 688 | +primitive masks the differences in the underlying instruction set. | |
| 689 | +.PP | |
| 690 | +The | |
| 691 | +.CW next | |
| 692 | +function, similar to the | |
| 693 | +.I dbx | |
| 694 | +command of the same name, | |
| 695 | +is a simpler example. | |
| 696 | +This function steps through | |
| 697 | +a single source statement but steps over function calls. | |
| 698 | +.P1 | |
| 699 | +defn next() | |
| 700 | +{ | |
| 701 | + local sp, bound; | |
| 702 | + | |
| 703 | + sp = *SP; // save starting SP | |
| 704 | + bound = fnbound(*PC); // begin & end of fn. | |
| 705 | + stmnt(); // step 1 statement | |
| 706 | + pc = *PC; | |
| 707 | + if pc >= bound[0] && pc < bound[1] then | |
| 708 | + return {}; | |
| 709 | + | |
| 710 | + while (pc<bound[0] || pc>bound[1]) && sp>=*SP do { | |
| 711 | + step(); | |
| 712 | + pc = *PC; | |
| 713 | + } | |
| 714 | + src(*PC); | |
| 715 | +} | |
| 716 | +.P2 | |
| 717 | +The | |
| 718 | +.CW next | |
| 719 | +function | |
| 720 | +starts by saving the current stack pointer in a local variable. | |
| 721 | +It then uses the Acid library function | |
| 722 | +.CW fnbound | |
| 723 | +to return the addresses of the first and last instructions in | |
| 724 | +the current function in a list. | |
| 725 | +The | |
| 726 | +.CW stmnt | |
| 727 | +function executes a single source statement and then uses | |
| 728 | +.CW src | |
| 729 | +to print a few lines of source around the new | |
| 730 | +.CW PC . | |
| 731 | +If the new value of the | |
| 732 | +.CW PC | |
| 733 | +remains in the current function, | |
| 734 | +.CW next | |
| 735 | +returns. | |
| 736 | +When the executed statement is a function call or a return | |
| 737 | +from a function, the new value of the | |
| 738 | +.CW PC | |
| 739 | +is outside the bounds calculated by | |
| 740 | +.CW fnbound | |
| 741 | +and the test of the | |
| 742 | +.CW while | |
| 743 | +loop is evaluated. | |
| 744 | +If the statement was a return, the new value of the stack pointer | |
| 745 | +is greater than the original value and the loop completes without | |
| 746 | +execution. | |
| 747 | +Otherwise, the loop is entered and instructions are continually | |
| 748 | +executed until the value of the | |
| 749 | +.CW PC | |
| 750 | +is between the bounds calculated earlier. At that point, execution | |
| 751 | +ceases and a few lines of source in the vicinity of the | |
| 752 | +.CW PC | |
| 753 | +are printed. | |
| 754 | +.PP | |
| 755 | +Acid provides concise and elegant expression for control and | |
| 756 | +manipulation of target programs. These examples demonstrate how a | |
| 757 | +few well-chosen primitives can be combined to create a rich debugging environment. | |
| 758 | +.NH | |
| 759 | +Dealing With Multiple Architectures | |
| 760 | +.PP | |
| 761 | +A single binary of Acid may be used to debug a program running on any | |
| 762 | +of the five processor architectures supported by Plan 9. For example, | |
| 763 | +Plan 9 allows a user on a MIPS to import the | |
| 764 | +.I proc | |
| 765 | +file system from an i486-based PC and remotely debug a program executing | |
| 766 | +on that processor. | |
| 767 | +.PP | |
| 768 | +Two levels of abstraction provide this architecture independence. | |
| 769 | +On the lowest level, a Plan 9 library supplies functions to | |
| 770 | +decode the file header of the program being debugged and | |
| 771 | +select a table of system parameters | |
| 772 | +and a jump vector of architecture-dependent | |
| 773 | +functions based on the magic number. | |
| 774 | +Among these functions are byte-order-independent | |
| 775 | +access to memory and text files, stack manipulation, disassembly, | |
| 776 | +and floating point number interpretation. | |
| 777 | +The second level of abstraction is supplied by Acid. | |
| 778 | +It consists of primitives and approximately 200 lines | |
| 779 | +of architecture-dependent Acid library code that interface the | |
| 780 | +interpreter to the architecture-dependent library. | |
| 781 | +This layer performs functions such as mapping register names to | |
| 782 | +memory locations, supplying breakpoint values and sizes, | |
| 783 | +and converting processor specific data to Acid data types. | |
| 784 | +An example of the latter is the stack trace function | |
| 785 | +.CW strace , | |
| 786 | +which uses the stack traversal functions in the | |
| 787 | +architecture-dependent library to construct a list of lists describing | |
| 788 | +the context of a process. The first level of list selects | |
| 789 | +each function in the trace; subordinate lists contain the | |
| 790 | +names and values of parameters and local variables of | |
| 791 | +the functions. Acid commands and library functions that | |
| 792 | +manipulate and display process state information operate | |
| 793 | +on the list representation and are independent of the | |
| 794 | +underlying architecture. | |
| 795 | +.NH | |
| 796 | +Alef Runtime | |
| 797 | +.PP | |
| 798 | +Alef is a concurrent programming language, | |
| 799 | +designed specifically for systems programming, which supports both | |
| 800 | +shared variable and message passing paradigms. | |
| 801 | +Alef borrows the C expression syntax but implements | |
| 802 | +a substantially different type system. | |
| 803 | +The language provides a rich set of | |
| 804 | +exception handling, process management, and synchronization | |
| 805 | +primitives, which rely on a runtime system. | |
| 806 | +Alef program bugs are often deadlocks, synchronization failures, | |
| 807 | +or non-termination caused by locks being held incorrectly. | |
| 808 | +In such cases, a process stalls deep | |
| 809 | +in the runtime code and it is clearly | |
| 810 | +unreasonable to expect a programmer using the language | |
| 811 | +to understand the detailed | |
| 812 | +internal semantics of the runtime support functions. | |
| 813 | +.PP | |
| 814 | +Instead, there is an Alef support library, coded in Acid, that | |
| 815 | +allows the programmer to interpret the program state in terms of | |
| 816 | +Alef operations. Consider the example of a multi-process program | |
| 817 | +stalling because of improper synchronization. A stack trace of | |
| 818 | +the program indicates that it is waiting for an event in some | |
| 819 | +obscure Alef runtime | |
| 820 | +synchronization function. | |
| 821 | +The function itself is irrelevant to the | |
| 822 | +programmer; of greater importance is the identity of the | |
| 823 | +unfulfilled event. | |
| 824 | +Commands in the Alef support library decode | |
| 825 | +the runtime data structures and program state to report the cause | |
| 826 | +of the blockage in terms of the high-level operations available to | |
| 827 | +the Alef programmer. | |
| 828 | +Here, the Acid language acts | |
| 829 | +as a communications medium between Alef implementer and Alef user. | |
| 830 | +.NH | |
| 831 | +Parallel Debugging | |
| 832 | +.PP | |
| 833 | +The central issue in parallel debugging is how the debugger is | |
| 834 | +multiplexed between the processes comprising | |
| 835 | +the program. | |
| 836 | +Acid has no intrinsic model of process partitioning; it | |
| 837 | +only assumes that parallel programs share a symbol table, | |
| 838 | +though they need not share memory. | |
| 839 | +The | |
| 840 | +.CW setproc | |
| 841 | +primitive attaches the debugger to a running process | |
| 842 | +associated with the process ID supplied as its argument | |
| 843 | +and assigns that value to the global variable | |
| 844 | +.CW pid , | |
| 845 | +thereby allowing simple rotation among a group of processes. | |
| 846 | +Further, the stack trace primitive is driven by parameters | |
| 847 | +specifying a unique process context, so it is possible to | |
| 848 | +examine the state of cooperating processes without switching | |
| 849 | +the debugger focus from the process of interest. | |
| 850 | +Since Acid is inherently extensible and capable of | |
| 851 | +dynamic interaction with subordinate processes, the | |
| 852 | +programmer can define Acid commands to detect and control | |
| 853 | +complex interactions between processes. | |
| 854 | +In short, the programmer is free to specify how the debugger reacts | |
| 855 | +to events generated in specific threads of the program. | |
| 856 | +.PP | |
| 857 | +The support for parallel debugging in Acid depends on a crucial kernel | |
| 858 | +modification: when the text segment of a program is written (usually to | |
| 859 | +place a breakpoint), the segment is cloned to prevent other threads | |
| 860 | +from encountering the breakpoint. Although this incurs a slight performance | |
| 861 | +penalty, it is of little importance while debugging. | |
| 862 | +.NH | |
| 863 | +Communication Between Tools | |
| 864 | +.PP | |
| 865 | +The Plan 9 Alef and C compilers do not | |
| 866 | +embed detailed type information in the symbol table of an | |
| 867 | +executable file. | |
| 868 | +However, they do accept a command line option causing them to | |
| 869 | +emit descriptions of complex data types | |
| 870 | +(e.g., aggregates and abstract data types) | |
| 871 | +to an auxiliary file. | |
| 872 | +The vehicle for expressing this information is Acid source code. | |
| 873 | +When an Acid debugging session is | |
| 874 | +subsequently started, that file is loaded with the other Acid libraries. | |
| 875 | +.PP | |
| 876 | +For each complex object in the program the compiler generates | |
| 877 | +three pieces of Acid code. | |
| 878 | +The first is a table describing the size and offset of each | |
| 879 | +member of the complex data type. Following is an Acid function, | |
| 880 | +named the same as the object, that formats and prints each member. | |
| 881 | +Finally, Acid declarations associate the | |
| 882 | +Alef or C program variables of a type with the functions | |
| 883 | +to print them. | |
| 884 | +The three forms of declaration are shown in the following example: | |
| 885 | +.P1 | |
| 886 | +struct Bitmap { | |
| 887 | + Rectangle 0 r; | |
| 888 | + Rectangle 16 clipr; | |
| 889 | + 'D' 32 ldepth; | |
| 890 | + 'D' 36 id; | |
| 891 | + 'X' 40 cache; | |
| 892 | +}; | |
| 893 | +.P2 | |
| 894 | +.P1 | |
| 895 | +defn | |
| 896 | +Bitmap(addr) { | |
| 897 | + complex Bitmap addr; | |
| 898 | + print("Rectangle r {\en"); | |
| 899 | + Rectangle(addr.r); | |
| 900 | + print("}\en"); | |
| 901 | + print("Rectangle clipr {\en"); | |
| 902 | + Rectangle(addr.clipr); | |
| 903 | + print("}\en"); | |
| 904 | + print(" ldepth ", addr.ldepth, "\en"); | |
| 905 | + print(" id ", addr.id, "\en"); | |
| 906 | + print(" cache ", addr.cache, "\en"); | |
| 907 | +}; | |
| 908 | + | |
| 909 | +complex Bitmap darkgrey; | |
| 910 | +complex Bitmap Window_settag:b; | |
| 911 | +.P2 | |
| 912 | +The | |
| 913 | +.CW struct | |
| 914 | +declaration specifies decoding instructions for the complex type named | |
| 915 | +.CW Bitmap . | |
| 916 | +Although the syntax is superficially similar to a C structure declaration, | |
| 917 | +the semantics differ markedly: the C declaration specifies a layout, while | |
| 918 | +the Acid declaration tells how to decode it. | |
| 919 | +The declaration specifies a type, an offset, and name for each | |
| 920 | +member of the complex object. The type is either the name of another | |
| 921 | +complex declaration, for example, | |
| 922 | +.CW Rectangle , | |
| 923 | +or a format code. | |
| 924 | +The offset is the number of bytes from the start | |
| 925 | +of the object to the member | |
| 926 | +and the name is the member's name in the Alef or C declaration. | |
| 927 | +This type description is a close match for C and Alef, but is simple enough | |
| 928 | +to be language independent. | |
| 929 | +.PP | |
| 930 | +The | |
| 931 | +.CW Bitmap | |
| 932 | +function expects the address of a | |
| 933 | +.CW Bitmap | |
| 934 | +as its only argument. | |
| 935 | +It uses the decoding information contained in the | |
| 936 | +.CW Bitmap | |
| 937 | +structure declaration to extract, format, and print the | |
| 938 | +value of each member of the complex object pointed to by | |
| 939 | +the argument. | |
| 940 | +The Alef compiler emits code to call other Acid functions | |
| 941 | +where a member is another complex type; here, | |
| 942 | +.CW Bitmap | |
| 943 | +calls | |
| 944 | +.CW Rectangle | |
| 945 | +to print its contents. | |
| 946 | +.PP | |
| 947 | +The | |
| 948 | +.CW complex | |
| 949 | +declarations associate Alef variables with complex types. | |
| 950 | +In the example, | |
| 951 | +.CW darkgrey | |
| 952 | +is the name of a global variable of type | |
| 953 | +.CW Bitmap | |
| 954 | +in the program being debugged. | |
| 955 | +Whenever the name | |
| 956 | +.CW darkgrey | |
| 957 | +is evaluated by Acid, it automatically calls the | |
| 958 | +.CW Bitmap | |
| 959 | +function with the address of | |
| 960 | +.CW darkgrey | |
| 961 | +as the argument. | |
| 962 | +The second | |
| 963 | +.CW complex | |
| 964 | +declaration associates a local variable or parameter named | |
| 965 | +.CW b | |
| 966 | +in function | |
| 967 | +.CW Window_settag | |
| 968 | +with the | |
| 969 | +.CW Bitmap | |
| 970 | +complex data type. | |
| 971 | +.PP | |
| 972 | +Acid borrows the C operators | |
| 973 | +.CW . | |
| 974 | +and | |
| 975 | +.CW -> | |
| 976 | +to access the decoding parameters of a member of a complex type. | |
| 977 | +Although this representation is sufficiently general for describing | |
| 978 | +the decoding of both C and Alef complex data types, it may | |
| 979 | +prove too restrictive for target languages with more complicated | |
| 980 | +type systems. | |
| 981 | +Further, the assumption that the compiler can select the proper | |
| 982 | +Acid format code for each basic type in the language is somewhat | |
| 983 | +naive. For example, when a member of a complex type is a pointer, | |
| 984 | +it is assigned a hexadecimal type code; integer members are always | |
| 985 | +assigned a decimal type code. | |
| 986 | +This heuristic proves inaccurate when an integer field is a | |
| 987 | +bit mask or set of bit flags which are more appropriately displayed | |
| 988 | +in hexadecimal or octal. | |
| 989 | +.NH | |
| 990 | +Code Verification | |
| 991 | +.PP | |
| 992 | +Acid's ability to interact dynamically with | |
| 993 | +an executing program allows passive test and | |
| 994 | +verification of the target program. For example, | |
| 995 | +a common concern is leak detection in programs using | |
| 996 | +.CW malloc . | |
| 997 | +Of interest are two items: finding memory that was allocated | |
| 998 | +but never freed and detecting bad pointers passed to | |
| 999 | +.CW free . | |
| 1000 | +An auxiliary Acid library contains Acid functions to | |
| 1001 | +monitor the execution of a program and detect these | |
| 1002 | +faults, either as they happen or in the automated | |
| 1003 | +post-mortem analysis of the memory arena. | |
| 1004 | +In the following example, the | |
| 1005 | +.CW sort | |
| 1006 | +command is run under the control of the | |
| 1007 | +Acid memory leak library. | |
| 1008 | +.P1 | |
| 1009 | +helix% acid -l malloc /bin/sort | |
| 1010 | +/bin/sort: mips plan 9 executable | |
| 1011 | +/lib/acid/port | |
| 1012 | +/lib/acid/mips | |
| 1013 | +/lib/acid/malloc | |
| 1014 | +acid: go() | |
| 1015 | +now | |
| 1016 | +is | |
| 1017 | +the | |
| 1018 | +time | |
| 1019 | +<ctrl-d> | |
| 1020 | +is | |
| 1021 | +now | |
| 1022 | +the | |
| 1023 | +time | |
| 1024 | +27680 : breakpoint _exits+0x4 MOVW $0x8,R1 | |
| 1025 | +acid: | |
| 1026 | +.P2 | |
| 1027 | +The | |
| 1028 | +.CW go | |
| 1029 | +command creates a process and plants | |
| 1030 | +breakpoints at the entry to | |
| 1031 | +.CW malloc | |
| 1032 | +and | |
| 1033 | +.CW free . | |
| 1034 | +The program is then started and continues until it | |
| 1035 | +exits or stops. If the reason for stopping is anything | |
| 1036 | +other than the breakpoints in | |
| 1037 | +.CW malloc | |
| 1038 | +and | |
| 1039 | +.CW free , | |
| 1040 | +Acid prints the usual status information and returns to the | |
| 1041 | +interactive prompt. | |
| 1042 | +.PP | |
| 1043 | +When the process stops on entering | |
| 1044 | +.CW malloc , | |
| 1045 | +the debugger must capture and save the address that | |
| 1046 | +.CW malloc | |
| 1047 | +will return. | |
| 1048 | +After saving a stack | |
| 1049 | +trace so the calling routine can be identified, it places | |
| 1050 | +a breakpoint at the return address and restarts the program. | |
| 1051 | +When | |
| 1052 | +.CW malloc | |
| 1053 | +returns, the breakpoint stops the program, | |
| 1054 | +allowing the debugger | |
| 1055 | +to grab the address of the new memory block from the return register. | |
| 1056 | +The address and stack trace are added to the list of outstanding | |
| 1057 | +memory blocks, the breakpoint is removed from the return point, and | |
| 1058 | +the process is restarted. | |
| 1059 | +.PP | |
| 1060 | +When the process stops at the beginning of | |
| 1061 | +.CW free , | |
| 1062 | +the memory address supplied as the argument is compared to the list | |
| 1063 | +of outstanding memory blocks. If it is not found an error message | |
| 1064 | +and a stack trace of the call is reported; otherwise, the | |
| 1065 | +address is deleted from the list. | |
| 1066 | +.PP | |
| 1067 | +When the program exits, the list of outstanding memory blocks contains | |
| 1068 | +the addresses of all blocks that were allocated but never freed. | |
| 1069 | +The | |
| 1070 | +.CW leak | |
| 1071 | +library function traverses the list producing a report describing | |
| 1072 | +the allocated blocks. | |
| 1073 | +.P1 1m | |
| 1074 | +acid: leak() | |
| 1075 | +Lost a total of 524288 bytes from: | |
| 1076 | + malloc() malloc.c:32 called from dofile+0xe8 sort.c:217 | |
| 1077 | + dofile() sort.c:190 called from main+0xac sort.c:161 | |
| 1078 | + main() sort.c:128 called from _main+0x20 main9.s:10 | |
| 1079 | +Lost a total of 64 bytes from: | |
| 1080 | + malloc() malloc.c:32 called from newline+0xfc sort.c:280 | |
| 1081 | + newline() sort.c:248 called from dofile+0x110 sort.c:222 | |
| 1082 | + dofile() sort.c:190 called from main+0xac sort.c:161 | |
| 1083 | + main() sort.c:128 called from _main+0x20 main9.s:10 | |
| 1084 | +Lost a total of 64 bytes from: | |
| 1085 | + malloc() malloc.c:32 called from realloc+0x14 malloc.c:129 | |
| 1086 | + realloc() malloc.c:123 called from bldkey+0x358 sort.c:1388 | |
| 1087 | + buildkey() sort.c:1345 called from newline+0x150 sort.c:285 | |
| 1088 | + newline() sort.c:248 called from dofile+0x110 sort.c:222 | |
| 1089 | + dofile() sort.c:190 called from main+0xac sort.c:161 | |
| 1090 | + main() sort.c:128 called from _main+0x20 main9.s:10 | |
| 1091 | +acid: refs() | |
| 1092 | +data...bss...stack... | |
| 1093 | +acid: leak() | |
| 1094 | +acid: | |
| 1095 | +.P2 | |
| 1096 | +The presence of a block in the allocation list does not imply | |
| 1097 | +it is there because of a leak; for instance, it may have been | |
| 1098 | +in use when the program terminated. | |
| 1099 | +The | |
| 1100 | +.CW refs() | |
| 1101 | +library function scans the | |
| 1102 | +.I data , | |
| 1103 | +.I bss , | |
| 1104 | +and | |
| 1105 | +.I stack | |
| 1106 | +segments of the process looking for pointers | |
| 1107 | +into the allocated blocks. When one is found, the block is deleted from | |
| 1108 | +the outstanding block list. | |
| 1109 | +The | |
| 1110 | +.CW leak | |
| 1111 | +function is used again to report the | |
| 1112 | +blocks remaining allocated and unreferenced. | |
| 1113 | +This strategy proves effective in detecting | |
| 1114 | +disconnected (but non-circular) data structures. | |
| 1115 | +.PP | |
| 1116 | +The leak detection process is entirely passive. | |
| 1117 | +The program is not | |
| 1118 | +specially compiled and the source code is not required. | |
| 1119 | +As with the Acid support functions for the Alef runtime environment, | |
| 1120 | +the author of the library routines has encapsulated the | |
| 1121 | +functionality of the library interface | |
| 1122 | +in Acid code. | |
| 1123 | +Any programmer may then check a program's use of the | |
| 1124 | +library routines without knowledge of either implementation. | |
| 1125 | +The performance impact of running leak detection is great | |
| 1126 | +(about 10 times slower), | |
| 1127 | +but it has not prevented interactive programs like | |
| 1128 | +.CW sam | |
| 1129 | +and the | |
| 1130 | +.CW 8½ | |
| 1131 | +window system from being tested. | |
| 1132 | +.NH | |
| 1133 | +Code Coverage | |
| 1134 | +.PP | |
| 1135 | +Another common component of software test uses | |
| 1136 | +.I coverage | |
| 1137 | +analysis. | |
| 1138 | +The purpose of the test is to determine which paths through the code have | |
| 1139 | +not been executed while running the test suite. | |
| 1140 | +This is usually | |
| 1141 | +performed by a combination of compiler support and a reporting tool run | |
| 1142 | +on the output generated by statements compiled into the program. | |
| 1143 | +The compiler emits code that | |
| 1144 | +logs the progress of the program as it executes basic blocks and writes the | |
| 1145 | +results to a file. The file is then processed by the reporting tool | |
| 1146 | +to determine which basic blocks have not been executed. | |
| 1147 | +.PP | |
| 1148 | +Acid can perform the same function in a language independent manner without | |
| 1149 | +modifying the source, object or binary of the program. The following example | |
| 1150 | +shows | |
| 1151 | +.CW ls | |
| 1152 | +being run under the control of the Acid coverage library. | |
| 1153 | +.P1 | |
| 1154 | +philw-helix% acid -l coverage /bin/ls | |
| 1155 | +/bin/ls: mips plan 9 executable | |
| 1156 | +/lib/acid/port | |
| 1157 | +/lib/acid/mips | |
| 1158 | +/lib/acid/coverage | |
| 1159 | +acid: coverage() | |
| 1160 | +acid | |
| 1161 | +newstime | |
| 1162 | +profile | |
| 1163 | +tel | |
| 1164 | +wintool | |
| 1165 | +2: (error) msg: pid=11419 startstop: process exited | |
| 1166 | +acid: analyse(ls) | |
| 1167 | +ls.c:102,105 | |
| 1168 | + 102: return 1; | |
| 1169 | + 103: } | |
| 1170 | + 104: if(db[0].qid.path&CHDIR && dflag==0){ | |
| 1171 | + 105: output(); | |
| 1172 | +ls.c:122,126 | |
| 1173 | + 122: memmove(dirbuf+ndir, db, sizeof(Dir)); | |
| 1174 | + 123: dirbuf[ndir].prefix = 0; | |
| 1175 | + 124: p = utfrrune(s, '/'); | |
| 1176 | + 125: if(p){ | |
| 1177 | + 126: dirbuf[ndir].prefix = s; | |
| 1178 | +.P2 | |
| 1179 | +The | |
| 1180 | +.CW coverage | |
| 1181 | +function begins by looping through the text segment placing | |
| 1182 | +breakpoints at the entry to each basic block. The start of each basic | |
| 1183 | +block is found using the Acid builtin function | |
| 1184 | +.CW follow . | |
| 1185 | +If the list generated by | |
| 1186 | +.CW follow | |
| 1187 | +contains more than one | |
| 1188 | +element, then the addresses mark the start of basic blocks. A breakpoint | |
| 1189 | +is placed at each address to detect entry into the block. If the result | |
| 1190 | +of | |
| 1191 | +.CW follow | |
| 1192 | +is a single address then no action is taken, and the next address is | |
| 1193 | +considered. Acid maintains a list of | |
| 1194 | +breakpoints already in place and avoids placing duplicates (an address may be | |
| 1195 | +the destination of several branches). | |
| 1196 | +.PP | |
| 1197 | +After placing the breakpoints the program is set running. | |
| 1198 | +Each time a breakpoint is encountered | |
| 1199 | +Acid deletes the address from the breakpoint list, removes the breakpoint | |
| 1200 | +from memory and then restarts the program. | |
| 1201 | +At any instant the breakpoint list contains the addresses of basic blocks | |
| 1202 | +which have not been executed. | |
| 1203 | +The | |
| 1204 | +.CW analyse | |
| 1205 | +function reports the lines of source code bounded by basic blocks | |
| 1206 | +whose addresses are have not been deleted from the breakpoint list. | |
| 1207 | +These are the basic blocks which have not been executed. | |
| 1208 | +Program performance is almost unaffected since each breakpoint is executed | |
| 1209 | +only once and then removed. | |
| 1210 | +.PP | |
| 1211 | +The library contains a total of 128 lines of Acid code. | |
| 1212 | +An obvious extension of this algorithm could be used to provide basic block | |
| 1213 | +profiling. | |
| 1214 | +.NH | |
| 1215 | +Conclusion | |
| 1216 | +.PP | |
| 1217 | +Acid has two areas of weakness. As with | |
| 1218 | +other language-based tools like | |
| 1219 | +.I awk , | |
| 1220 | +a programmer must learn yet another language to step beyond the normal | |
| 1221 | +debugging functions and use the full power of the debugger. | |
| 1222 | +Second, the command line interface supplied by the | |
| 1223 | +.I yacc | |
| 1224 | +parser is inordinately clumsy. | |
| 1225 | +Part of the problem relates directly to the use of | |
| 1226 | +.I yacc | |
| 1227 | +and could be circumvented with a custom parser. | |
| 1228 | +However, structural problems would remain: Acid often requires | |
| 1229 | +too much typing to execute a simple | |
| 1230 | +command. | |
| 1231 | +A debugger should prostitute itself to its users, doing whatever | |
| 1232 | +is wanted with a minimum of encouragement; commands should be | |
| 1233 | +concise and obvious. The language interface is more consistent than | |
| 1234 | +an ad hoc command interface but is clumsy to use. | |
| 1235 | +Most of these problems are addressed by an Acme interface | |
| 1236 | +which is under construction. This should provide the best of | |
| 1237 | +both worlds: graphical debugging and access to the underlying acid | |
| 1238 | +language when required. | |
| 1239 | +.PP | |
| 1240 | +The name space clash between Acid variables, keywords, program variables, | |
| 1241 | +and functions is unavoidable. | |
| 1242 | +Although it rarely affects a debugging session, it is annoying | |
| 1243 | +when it happens and is sometimes difficult to circumvent. | |
| 1244 | +The current renaming scheme | |
| 1245 | +is too crude; the new names are too hard to remember. | |
| 1246 | +.PP | |
| 1247 | +Acid has proved to be a powerful tool whose applications | |
| 1248 | +have exceeded expectations. | |
| 1249 | +Of its strengths, portability, extensibility and parallel debugging support | |
| 1250 | +were by design and provide the expected utility. | |
| 1251 | +In retrospect, | |
| 1252 | +its use as a tool for code test and verification and as | |
| 1253 | +a medium for communicating type information and encapsulating | |
| 1254 | +interfaces has provided unanticipated benefits and altered our | |
| 1255 | +view of the debugging process. | |
| 1256 | +.NH | |
| 1257 | +Acknowledgments | |
| 1258 | +.PP | |
| 1259 | +Bob Flandrena was the first user and helped prepare the paper. | |
| 1260 | +Rob Pike endured three buggy Alef compilers and a new debugger | |
| 1261 | +in a single sitting. | |
| 1262 | +.NH | |
| 1263 | +References | |
| 1264 | +.LP | |
| 1265 | +[Pike90] R. Pike, D. Presotto, K. Thompson, H. Trickey, | |
| 1266 | +``Plan 9 from Bell Labs'', | |
| 1267 | +.I | |
| 1268 | +UKUUG Proc. of the Summer 1990 Conf., | |
| 1269 | +.R | |
| 1270 | +London, England, | |
| 1271 | +1990. | |
| 1272 | +.LP | |
| 1273 | +[Gol93] M. Golan, D. Hanson, | |
| 1274 | +``DUEL -- A Very High-Level Debugging Language'', | |
| 1275 | +.I | |
| 1276 | +USENIX Proc. of the Winter 1993 Conf., | |
| 1277 | +.R | |
| 1278 | +San Diego, CA, | |
| 1279 | +1993. | |
| 1280 | +.LP | |
| 1281 | +[Lin90] M. A. Linton, | |
| 1282 | +``The Evolution of DBX'', | |
| 1283 | +.I | |
| 1284 | +USENIX Proc. of the Summer 1990 Conf., | |
| 1285 | +.R | |
| 1286 | +Anaheim, CA, | |
| 1287 | +1990. | |
| 1288 | +.LP | |
| 1289 | +[Stal91] R. M. Stallman, R. H. Pesch, | |
| 1290 | +``Using GDB: A guide to the GNU source level debugger'', | |
| 1291 | +Technical Report, Free Software Foundation, | |
| 1292 | +Cambridge, MA, | |
| 1293 | +1991. | |
| 1294 | +.LP | |
| 1295 | +[Win93] P. Winterbottom, | |
| 1296 | +``Alef reference Manual'', | |
| 1297 | +reprinted in this volume. | |
| 1298 | +.LP | |
| 1299 | +[Pike93] Rob Pike, | |
| 1300 | +``Acme: A User Interface for Programmers'', | |
| 1301 | +.I | |
| 1302 | +USENIX Proc. of the Winter 1994 Conf., | |
| 1303 | +.R | |
| 1304 | +San Francisco, CA, | |
| 1305 | +reprinted in this volume. | |
| 1306 | +.LP | |
| 1307 | +[Ols90] Ronald A. Olsson, Richard H. Crawford, and W. Wilson Ho, | |
| 1308 | +``Dalek: A GNU, improved programmable debugger'', | |
| 1309 | +.I | |
| 1310 | +USENIX Proc. of the Summer 1990 Conf., | |
| 1311 | +.R | |
| 1312 | +Anaheim, CA. | |
| 1313 | +.LP | |
| 1314 | +[May92] Paul Maybee, | |
| 1315 | +``NeD: The Network Extensible Debugger'' | |
| 1316 | +.I | |
| 1317 | +USENIX Proc. of the Summer 1992 Conf., | |
| 1318 | +.R | |
| 1319 | +San Antonio, TX. | |
| 1320 | +.LP | |
| 1321 | +[Aral] Ziya Aral, Ilya Gertner, and Greg Schaffer, | |
| 1322 | +``Efficient debugging primitives for multiprocessors'', | |
| 1323 | +.I | |
| 1324 | +Proceedings of the Third International Conference on Architectural | |
| 1325 | +Support for Programming Languages and Operating Systems, | |
| 1326 | +.R | |
| 1327 | +SIGPLAN notices Nr. 22, May 1989. | |
Binary file not shown.
| @@ -0,0 +1,1062 @@ | ||
| 1 | +.de d0 | |
| 2 | +.nr dP +1 | |
| 3 | +.nr dV +1p | |
| 4 | +.. | |
| 5 | +.de d1 | |
| 6 | +.nr dP -1 | |
| 7 | +.nr dV -1p | |
| 8 | +.. | |
| 9 | +.nr dT 4 | |
| 10 | +.de Af \" acid function | |
| 11 | +.CW "\\$1(" "\fI\\$2\fP\f(CW)\fP" | |
| 12 | +.. | |
| 13 | +.TL | |
| 14 | +Native Kernel Debugging with Acid | |
| 15 | +.AU | |
| 16 | +Tad Hunt | |
| 17 | +tad@plan9.bell-labs.com | |
| 18 | +.br | |
| 19 | +Lucent Technologies Inc | |
| 20 | +.br | |
| 21 | +(Revised 22 May 2000 by Vita Nuova) | |
| 22 | +.SH | |
| 23 | +Introduction | |
| 24 | +.PP | |
| 25 | +This tutorial provides an introduction to the Acid debugger. It assumes that you are familiar with the features of a typical source-level debugger. The Acid debugger is built round a command language with a syntax similar to C. | |
| 26 | +This tutorial is not an | |
| 27 | +introduction to Acid as a whole, but | |
| 28 | +offers a brief tour | |
| 29 | +of the basic built in and standard library functions, | |
| 30 | +especially those needed for debugging native Inferno kernels on a target board. | |
| 31 | +.PP | |
| 32 | +Acid was originally developed by Phil Winterbottom | |
| 33 | +to help debug multi-threaded programs in | |
| 34 | +the concurrent language Alef, and provide more sophisticated | |
| 35 | +debugging for C programs. | |
| 36 | +In the paper | |
| 37 | +.I "Acid: A Debugger Built From a Language" , | |
| 38 | +Winterbottom | |
| 39 | +discusses Acid's design, including some worked examples of unusual | |
| 40 | +applications of Acid to find memory leaks and assist code coverage analysis. | |
| 41 | +Following that is the | |
| 42 | +.I "Acid Reference Manual" , | |
| 43 | +also by Phil Winterbottom, | |
| 44 | +which gives a more precise specification of the Acid debugging language and its libraries. | |
| 45 | +.SH | |
| 46 | +Preliminaries -- the environment | |
| 47 | +.PP | |
| 48 | +Acid runs under the host operating system used for cross-development, | |
| 49 | +in the same way as the Inferno compilers. | |
| 50 | +Before running either compilers or Acid, the following | |
| 51 | +environment variables must be set appropriately: | |
| 52 | +.TS | |
| 53 | +center; | |
| 54 | +lf(CW) lf(R)w(4i) . | |
| 55 | +ROOT T{ | |
| 56 | +the directory in which Inferno lives (eg, | |
| 57 | +.CW /usr/inferno ). | |
| 58 | +T} | |
| 59 | +SYSHOST T{ | |
| 60 | +.I host | |
| 61 | +operating system type: | |
| 62 | +.CW Nt , | |
| 63 | +.CW Solaris , | |
| 64 | +.CW Plan9 , | |
| 65 | +.CW Linux | |
| 66 | +or | |
| 67 | +.CW FreeBSD | |
| 68 | +T} | |
| 69 | +OBJTYPE T{ | |
| 70 | +.I host | |
| 71 | +machine's architecture type: | |
| 72 | +.CW 386 , | |
| 73 | +.CW sparc , | |
| 74 | +.CW mips , | |
| 75 | +or | |
| 76 | +.CW powerpc | |
| 77 | +T} | |
| 78 | +.TE | |
| 79 | +They might be set by a login shell profile | |
| 80 | +(eg, | |
| 81 | +Unix | |
| 82 | +.CW ".profile" , | |
| 83 | +or | |
| 84 | +Plan 9 | |
| 85 | +.CW lib/profile ). | |
| 86 | +Also ensure that the directory | |
| 87 | +.P1 | |
| 88 | +$ROOT/$SYSHOST/$OBJTYPE/bin | |
| 89 | +.P2 | |
| 90 | +is on your search path. | |
| 91 | +For example, on a Solaris sparc, one might use: | |
| 92 | +.P1 | |
| 93 | +ROOT=\fIinferno_root\fP | |
| 94 | +SYSHOST=Solaris | |
| 95 | +OBJTYPE=sparc | |
| 96 | +ACIDLIB=$ROOT/lib/acid | |
| 97 | +PATH=$ROOT/$SYSHOST/$OBJTYPE/bin:$PATH | |
| 98 | +export ROOT ACIDLIB PATH OBJTYPE SYSHOST | |
| 99 | +.P2 | |
| 100 | +where | |
| 101 | +.I "inferno_root" | |
| 102 | +is the directory in which Inferno lives (eg, | |
| 103 | +.CW "/usr/inferno" ). | |
| 104 | +.SH | |
| 105 | +An Example Program | |
| 106 | +.PP | |
| 107 | +The first example is not kernel code, but a small program that | |
| 108 | +will be compiled but not run, to demonstrate basic Acid commands for | |
| 109 | +source and object file inspection. | |
| 110 | +The code is shown below: | |
| 111 | +.P1 | |
| 112 | +int | |
| 113 | +factorial(int n) | |
| 114 | +{ | |
| 115 | + if (n == 1) | |
| 116 | + return 1; | |
| 117 | + return n * factorial(n-1); | |
| 118 | +} | |
| 119 | + | |
| 120 | +int f; | |
| 121 | +void | |
| 122 | +main(void) | |
| 123 | +{ | |
| 124 | + f = factorial(5); | |
| 125 | +} | |
| 126 | + | |
| 127 | +void | |
| 128 | +_main(void) | |
| 129 | +{ | |
| 130 | + main(); | |
| 131 | +} | |
| 132 | +.P2 | |
| 133 | +.SH | |
| 134 | +Compiling and Linking | |
| 135 | +.PP | |
| 136 | +The first step is to create an executable. The example shows the process for creating ARM executables. Substitute the appropriate compiler and linker for other cpu types. | |
| 137 | +.P1 | |
| 138 | +% 5c factorial.c | |
| 139 | +% 5l -o factorial factorial.5 | |
| 140 | +% ls | |
| 141 | +factorial | |
| 142 | +factorial.5 | |
| 143 | +factorial.c | |
| 144 | +.P2 | |
| 145 | +.SH | |
| 146 | +Starting Acid | |
| 147 | +.PP | |
| 148 | +Even without the target machine on which | |
| 149 | +to run the program, many Acid features are available. | |
| 150 | +The following command starts debugging the | |
| 151 | +.CW "factorial" | |
| 152 | +executable. Note that, upon startup, Acid will attempt to load some libaries from the directory specified in the | |
| 153 | +.CW "ACIDLIB" | |
| 154 | +environment variable (defaults to | |
| 155 | +.CW "/usr/inferno/lib/acid" ). | |
| 156 | +It will also attempt to load the file | |
| 157 | +.CW "$HOME/lib/acid" , | |
| 158 | +in which you can place commands to be executed during startup. | |
| 159 | +.P1 | |
| 160 | +% acid factorial | |
| 161 | +factorial:Arm plan 9 executable | |
| 162 | + | |
| 163 | +$ROOT/lib/acid/port | |
| 164 | +$ROOT/lib/acid/arm | |
| 165 | +acid: | |
| 166 | +.P2 | |
| 167 | +.SH | |
| 168 | +Exploring the Executable | |
| 169 | +.PP | |
| 170 | +To find out what symbols are in the program: | |
| 171 | +.P1 | |
| 172 | +acid: symbols("") | |
| 173 | +etext T 0x00001068 | |
| 174 | +f D 0x00002000 | |
| 175 | +setR12 D 0x00002ffc | |
| 176 | +end B 0x00002008 | |
| 177 | +bdata D 0x00002000 | |
| 178 | +edata D 0x00002008 | |
| 179 | +factorial T 0x00001020 | |
| 180 | +main T 0x00001048 | |
| 181 | +_main T 0x0000105c | |
| 182 | +acid: | |
| 183 | +.P2 | |
| 184 | +The output from the | |
| 185 | +.CW symbols() | |
| 186 | +function is similar to the output from the | |
| 187 | +.I nm (10.1) | |
| 188 | +command. The first column is the symbol name, the second column gives the section the symbol is in, and the third column is the address of the symbol. | |
| 189 | +.PP | |
| 190 | +There is also a | |
| 191 | +.CW "symbols" | |
| 192 | +global variable. Variables and functions can have the same names. It holds the list of symbol information that the | |
| 193 | +.CW symbols | |
| 194 | +function uses to generate the table: | |
| 195 | +.d0 | |
| 196 | +.P1 | |
| 197 | +acid: symbols | |
| 198 | +{{"etext", T, 0x00001068}, {"f", D, 0x00002000}, {"setR12", D, 0x00002ffc}, | |
| 199 | + {"end", B, 0x00002008}, {"bdata", D, 0x00002000}, {"edata", D, 0x00002008}, | |
| 200 | + {"factorial", T, 0x00001020}, {"main", T, 0x00001048}, {"_main", T, 0x00001 | |
| 201 | +05c}} | |
| 202 | +acid: | |
| 203 | +.P2 | |
| 204 | +.d1 | |
| 205 | +In large programs, finding the symbol you are interested in from a list that may be thousands of lines long would be difficult. The string argument of | |
| 206 | +.CW symbols() | |
| 207 | +is a regular expression against which to match symbols. | |
| 208 | +All symbols that contain the pattern will be displayed. For example: | |
| 209 | +.P1 | |
| 210 | +acid: symbols("main") | |
| 211 | +main T 0x00001048 | |
| 212 | +_main T 0x0000105c | |
| 213 | +acid: symbols("^main") | |
| 214 | +main T 0x00001048 | |
| 215 | +acid: | |
| 216 | +.P2 | |
| 217 | +The | |
| 218 | +.CW symbols | |
| 219 | +function is written in the | |
| 220 | +.I acid | |
| 221 | +command language and lives in the | |
| 222 | +.CW "port" | |
| 223 | +library | |
| 224 | +.CW $ACIDLIB/port ). ( | |
| 225 | +.P1 | |
| 226 | +defn symbols(pattern) | |
| 227 | +{ | |
| 228 | + local l, s; | |
| 229 | + | |
| 230 | + l = symbols; | |
| 231 | + while l do { | |
| 232 | + s = head l; | |
| 233 | + if regexp(pattern, s[0]) then | |
| 234 | + print(s[0], "\t", s[1], "\t", s[2], "\n"); | |
| 235 | + l = tail l; | |
| 236 | + } | |
| 237 | +} | |
| 238 | +.P2 | |
| 239 | +Acid retrieves the list of symbols from the executable and turns each one into a global variable whose value is the address of the symbol. If the symbol clashes with a builtin name or keyword or a previously defined function, enough | |
| 240 | +.CW "$" | |
| 241 | +characters are prepended to the name to make it unique. The list of such renamings is printed at startup. | |
| 242 | +.PP | |
| 243 | +Most acid functions operate on addresses. For example, to view the source code for a given address, use the | |
| 244 | +.CW src | |
| 245 | +function: | |
| 246 | +.P1 | |
| 247 | +acid: src(main) | |
| 248 | +/usr/jrf/factorial.c:10 | |
| 249 | + 5 return n * factorial(n-1); | |
| 250 | + 6 } | |
| 251 | + 7 | |
| 252 | + 8 int f; | |
| 253 | + 9 void | |
| 254 | +>10 main(void) | |
| 255 | + 11 { | |
| 256 | + 12 f = factorial(5); | |
| 257 | + 13 } | |
| 258 | + 14 | |
| 259 | + 15 void | |
| 260 | +.P2 | |
| 261 | +The | |
| 262 | +.Af "src" addr | |
| 263 | +function displays a section of source code, with the line containing the address passed as an argument in the middle of the display. To print the assembly code beginning at a given address, use the | |
| 264 | +.CW asm() | |
| 265 | +function. | |
| 266 | +.P1 | |
| 267 | +acid: asm(factorial) | |
| 268 | +factorial 0x00001020 MOVW.W R14,#-0x8(R13) | |
| 269 | +factorial+0x4 0x00001024 CMP.S $#0x1,R0 | |
| 270 | +factorial+0x8 0x00001028 MOVW.EQ $#0x1,R0 | |
| 271 | +factorial+0xc 0x0000102c RET.EQ.P #0x8(R13) | |
| 272 | +factorial+0x10 0x00001030 MOVW R0,n+0(FP) | |
| 273 | +factorial+0x14 0x00001034 SUB $#0x1,R0,R0 | |
| 274 | +factorial+0x18 0x00001038 BL factorial | |
| 275 | +factorial+0x1c 0x0000103c MOVW n+0(FP),R2 | |
| 276 | +factorial+0x20 0x00001040 MUL R2,R0,R0 | |
| 277 | +factorial+0x24 0x00001044 RET.P #0x8(R13) | |
| 278 | +main 0x00001048 MOVW.W R14,#-0x8(R13) | |
| 279 | +acid: | |
| 280 | +.P2 | |
| 281 | +The output contains the symbolic address (symbol name+offset, where symbol name is the name of the enclosing function) followed by the absolute address, followed by the disassembled code. | |
| 282 | +The | |
| 283 | +.Af "asm" addr | |
| 284 | +function prints the assembly beginning at | |
| 285 | +.I "addr" | |
| 286 | +and ending after either 30 lines have been printed, or the end of the function has been reached. The | |
| 287 | +.CW "casm()" | |
| 288 | +function continues the assembly listing from where it left off, even past the end of the function and into the next one. | |
| 289 | +.P1 | |
| 290 | +acid: casm() | |
| 291 | +main+0x4 0x0000104c MOVW $#0x5,R0 | |
| 292 | +main+0x8 0x00001050 BL factorial | |
| 293 | +main+0xc 0x00001054 MOVW R0,$f-SB(SB) | |
| 294 | +main+0x10 0x00001058 RET.P #0x8(R13) | |
| 295 | +_main 0x0000105c MOVW.W R14,#-0x4(R13) | |
| 296 | +acid: | |
| 297 | +.P2 | |
| 298 | +All the functions presented so far are written in the acid command language. To see the source of a comand written in the acid command language, use the builtin command | |
| 299 | +.CW "whatis [" "\fIname\fP\f(CW ]\fP." | |
| 300 | +It prints the definition of the optional argument | |
| 301 | +.I "name" . | |
| 302 | +If | |
| 303 | +.I "name" | |
| 304 | +is an Acid builtin, | |
| 305 | +.CW whatis | |
| 306 | +prints | |
| 307 | +.CW "builtin function" . | |
| 308 | +.P1 | |
| 309 | +acid: whatis casm | |
| 310 | +defn casm() { | |
| 311 | + asm(lasmaddr); | |
| 312 | +} | |
| 313 | +acid: | |
| 314 | +acid: whatis atof | |
| 315 | +builtin function | |
| 316 | +acid: | |
| 317 | +.P2 | |
| 318 | +If | |
| 319 | +.I name | |
| 320 | +is a variable, it prints the type of variable, and for the integer type, gives the format code used to print the value: | |
| 321 | +.P1 | |
| 322 | +acid: whatis pid | |
| 323 | +integer variable format D | |
| 324 | +acid: | |
| 325 | +.P2 | |
| 326 | +With no arguments, | |
| 327 | +.CW whatis | |
| 328 | +lists all available functions: | |
| 329 | +.P1 | |
| 330 | +acid: whatis | |
| 331 | +Bsrc bpmask follow new sh | |
| 332 | +_bpconddel bpneq func newproc source | |
| 333 | +_bpcondset bpor gpr next spr | |
| 334 | +_stk bpprint include notestk spsrch | |
| 335 | +access bppush interpret params src | |
| 336 | +acidinit bpset itoa pcfile start | |
| 337 | +addsrcdir bptab kill pcline startstop | |
| 338 | +asm casm kstk pfl status | |
| 339 | +atof cont labstk print stk | |
| 340 | +atoi debug line printto stmnt | |
| 341 | +bpaddr dump linkreg procs stop | |
| 342 | +bpand error lkstk rc stopped | |
| 343 | +bpconddel file locals readfile strace | |
| 344 | +bpcondset filepc lstk reason symbols | |
| 345 | +bpdel findsrc map regexp waitstop | |
| 346 | +bpderef fmt match regs | |
| 347 | +bpeq fnbound mem setproc | |
| 348 | +acid: | |
| 349 | +.P2 | |
| 350 | +The | |
| 351 | +.Af "Bsrc" addr | |
| 352 | +function brings up an editor on the line containing | |
| 353 | +.I "addr" . | |
| 354 | +It simply invokes a shell script named | |
| 355 | +.CW "B" | |
| 356 | +that takes two arguments, | |
| 357 | +.I "-line" | |
| 358 | +and | |
| 359 | +.I "file" | |
| 360 | +The shell script invokes | |
| 361 | +.CW "$EDITOR +" | |
| 362 | +.I "line file" . | |
| 363 | +If unset, | |
| 364 | +.CW "EDITOR" | |
| 365 | +defaults to | |
| 366 | +.I vi . | |
| 367 | +The shell script, or the | |
| 368 | +.CW Bsrc | |
| 369 | +function can be easily rewritten to work with your favorite editor. | |
| 370 | +.PP | |
| 371 | +Entering a symbol name by itself will print the address of the symbol. Prefixing the symbol name with a | |
| 372 | +.CW "*" | |
| 373 | +will print the value at the address in the variable. Continuing to use our | |
| 374 | +.CW "factorial" | |
| 375 | +example: | |
| 376 | +.P1 | |
| 377 | +acid: f | |
| 378 | +0x00002000 | |
| 379 | +acid: *f | |
| 380 | +0x00000000 | |
| 381 | +acid: | |
| 382 | +.P2 | |
| 383 | +.SH | |
| 384 | +Remote Debugging | |
| 385 | +.PP | |
| 386 | +Now that you have a basic understanding of how to explore the executable, it is time to examine a real remote debugging session. | |
| 387 | +.PP | |
| 388 | +We'll use the SA1100 keyboard driver as an example. Examining the kernel configuration file, you'll see the following: | |
| 389 | +.P1 | |
| 390 | +dev | |
| 391 | + keyboard | |
| 392 | +link driver/keyboard port | |
| 393 | + scanfujn860 kbd.h keycodes.h | |
| 394 | +link ./../driver plat | |
| 395 | + kbdfujitsu ./../common/ssp.h \e | |
| 396 | + /driver/keyboard/kbd.h \e | |
| 397 | + /driver/keyboard/keycodes.h | |
| 398 | +port | |
| 399 | + const char *defaultkeyboard = "fujitsu"; | |
| 400 | + const char *defaultkeytable = "scanfujn860"; | |
| 401 | + int debugkeys = 1; /* 1 = enabled, 0 = disabled */ | |
| 402 | +.P2 | |
| 403 | +This describes the pieces of the keyboard driver which are linked into the kernel. The source code lives in two places, | |
| 404 | +.CW "$ROOT/os/driver/keyboard" , | |
| 405 | +and | |
| 406 | +.CW "$ROOT/os/plat/sa1100/driver" . | |
| 407 | +.PP | |
| 408 | +The next step is to build a kernel. Use the | |
| 409 | +.I mk | |
| 410 | +target | |
| 411 | +.CW acid | |
| 412 | +to ensure that the Acid symbolic debugging data is | |
| 413 | +produced. | |
| 414 | +For example: | |
| 415 | +.P1 | |
| 416 | +% mk 'CONF=sword' acid isword.p9.gz | |
| 417 | +.P2 | |
| 418 | +This creates the Acid file | |
| 419 | +.CW isword.acid , | |
| 420 | +containing Acid declarations describing kernel structures, | |
| 421 | +the kernel executable | |
| 422 | +.CW isword.p9 ; | |
| 423 | +and finally | |
| 424 | +.I gzip s | |
| 425 | +a copy of the kernel in | |
| 426 | +.CW isword.p9.gz | |
| 427 | +to load onto the device. Next, copy the gzipped image onto the device and then boot it. Follow the directions found elsewhere for details of this process. | |
| 428 | +.PP | |
| 429 | +From a shell prompt on the target device, start the remote debugger by writing the letter | |
| 430 | +.CW r | |
| 431 | +(for run) to | |
| 432 | +.CW "#b/dbgctl" . | |
| 433 | +Next, start Acid in remote debug mode, specifying the serial port it is connected to with the | |
| 434 | +.CW "-R" | |
| 435 | +option. | |
| 436 | +.CW "$CONF" | |
| 437 | +is the name of the configuration file used, for example | |
| 438 | +.CW "sword" . | |
| 439 | +.P1 | |
| 440 | +% acid -R /dev/cua/b -l i$CONF.acid i$CONF | |
| 441 | +isword:Arm plan 9 executable | |
| 442 | +$ROOT/lib/acid/port | |
| 443 | +i$CONF.acid | |
| 444 | +$ROOT/lib/acid/arm | |
| 445 | +/usr/jrf/lib/acid | |
| 446 | +acid: | |
| 447 | +.P2 | |
| 448 | +You are now debugging the kernel that is running on the target device. All of the previously listed commands will work as described before, in addition, there are many more commands available. | |
| 449 | +.SH | |
| 450 | +Kernel Process Listing | |
| 451 | +.PP | |
| 452 | +To get a list of kernel processes, use the | |
| 453 | +.CW "ps()" | |
| 454 | +function: | |
| 455 | +.P1 | |
| 456 | +acid: ps() | |
| 457 | +PID PC PRI STATE NAME | |
| 458 | +1 0x00054684 5 Queueing interp | |
| 459 | +2 0x00000000 1 Wakeme consdbg | |
| 460 | +3 0x00000000 5 Wakeme tcpack | |
| 461 | +4 0x00000000 5 Wakeme Fs.sync | |
| 462 | +5 0x00000000 4 Wakeme touchscreen | |
| 463 | +6 0x00054684 5 Queueing dis | |
| 464 | +7 0x00059788 5 Wakeme dis | |
| 465 | +8 0x00054684 5 Queueing dis | |
| 466 | +9 0x00054684 5 Queueing dis | |
| 467 | +10 0x00054684 5 Wakeme dis | |
| 468 | +11 0x0004c26c 1 Running dbg | |
| 469 | +acid: | |
| 470 | +.P2 | |
| 471 | +The | |
| 472 | +.CW "PC" | |
| 473 | +column shows the address the process was executing at when the | |
| 474 | +.CW ps | |
| 475 | +command retrieved statistics on it. The | |
| 476 | +.CW "PRI" | |
| 477 | +column lists process priorities. The smaller the number the higher the process priority. Notice that the kernel process (kproc) running the debugger is the highest priority process in the system. The only process you will ever see in the | |
| 478 | +.CW "Running" | |
| 479 | +state while executing the | |
| 480 | +.CW ps | |
| 481 | +command will be the debugger, since it is gathering information about the other processes. | |
| 482 | +.SH | |
| 483 | +Breakpoints | |
| 484 | +.PP | |
| 485 | +Breakpoints in Inferno, unlike most traditional kernel debuggers, are conditional breakpoints. There are minimally two conditions which must be met. These conditions are address and process id. A breakpoint will only be taken when execution for a specific kernel process reaches the specified address. The user can create additional conditions that are evaluated if the address and process id match. If evaluation of these conditions result in a nonzero value, the breakpoint is taken, otherwise it is ignored, and execution continues. | |
| 486 | +.PP | |
| 487 | +Again, the best way to proceed is with an example: | |
| 488 | +.P1 | |
| 489 | +acid: setproc(7) | |
| 490 | +.P2 | |
| 491 | +The | |
| 492 | +.Af setproc pid | |
| 493 | +function selects a kproc to which later commands will be applied; | |
| 494 | +the one with process ID (\fIpid\fP) | |
| 495 | +in this case. | |
| 496 | +.P1 | |
| 497 | +acid: bpset(keyboardread) | |
| 498 | +Waiting... | |
| 499 | +7: stopped flush8to4+0x18c MOVW (R3<<#4),R3 | |
| 500 | +.P2 | |
| 501 | +After selecting a kproc, we set a breakpoint at the address referred to by the | |
| 502 | +.CW "keyboardread" | |
| 503 | +symbol. As described before, the value of a global variable created from a symbol in the executable is the address of the symbol. In this case the address is the first instruction in the | |
| 504 | +.CW "keyboardread()" | |
| 505 | +function. Notice that setting a breakpoint stops the kproc from executing. A bit later, we'll see how to get it to continue execution. | |
| 506 | +.PP | |
| 507 | +Next, display the list of breakpoints using | |
| 508 | +.CW "bptab()" : | |
| 509 | +.P1 | |
| 510 | +acid: bptab() | |
| 511 | +ID PID ADDR CONDITIONS | |
| 512 | +0 7 keyboardread 0x0003c804 { } | |
| 513 | +.P2 | |
| 514 | +The first column is a unique number that identifies the breakpoint. The second column is the process ID in which the breakpoint will be taken. The third and fourth columns are the address of the breakpoint, first in symbolic form, then in numeric form. Finally, the last column is a list of conditions to evaluate whenever the kproc specified in the | |
| 515 | +.CW "PID" | |
| 516 | +column hits the the address specified in the | |
| 517 | +.CW "ADDR" | |
| 518 | +column. When they match, the list of conditions is evaluated. If the result is nonzero, the breakpoint is taken. Since we used the simplified breakpoint creation function, | |
| 519 | +.CW "bpset()" | |
| 520 | +, there are no additional conditions. Later on, we'll see how to set conditional breakpoints. | |
| 521 | +.PP | |
| 522 | +Start the selected kproc executing again, and wait for it to hit the breakpoint. | |
| 523 | +.P1 | |
| 524 | +acid: cont() | |
| 525 | +.P2 | |
| 526 | +The | |
| 527 | +.CW "cont()" | |
| 528 | +function will not return until a breakpoint has been hit, and there is no way to interrupt it. This means you should only set breakpoints that will be hit, otherwise you'll have to reboot the target device and restart your debugging session. | |
| 529 | +.PP | |
| 530 | +To continue our example, repeatedly hit new line (return, enter) | |
| 531 | +on the keyboard on the target device, until the breakpoint occurs: | |
| 532 | +.P1 | |
| 533 | +break 0: pid 7: stopped keyboardread SUB $#0xa4,R13,R13 | |
| 534 | +acid: | |
| 535 | +.P2 | |
| 536 | +This message, followed by the interactive prompt returning tells you that a breakpoint was hit. It gives the breakpoint id, the kernel process id, then the symbolic address at which execution halted, followed by the disassembly of the instruction at that address. | |
| 537 | +.PP | |
| 538 | +The | |
| 539 | +.CW "kstk()" | |
| 540 | +function prints a kernel stack trace, beginning with the current frame, all the way back to the call that started the kproc. For each function, it gives the name name, arguments, source file, and line number, followed by the symbolic address, source file, and line number of the caller. | |
| 541 | +.d0 | |
| 542 | +.P1 | |
| 543 | +acid: kstk() | |
| 544 | +At pc:247812:keyboardread /usr/inferno/os/driver/keyboard/devkey | |
| 545 | +board.c:350 | |
| 546 | +keyboardread(offset=0x0000009d,buf=0x001267f8,n=0x00000001) /usr | |
| 547 | +/inferno/os/driver/keyboard/devkeyboard.c:350 | |
| 548 | + called from kchanio+0x9c /usr/inferno/os/port/sysfile.c: | |
| 549 | +75 | |
| 550 | +kchanio(buf=0x001267f8,n=0x00000001,mode=0x00000000) /usr/infern | |
| 551 | +o/os/port/sysfile.c:64 | |
| 552 | + called from consread+0x144 /usr/inferno/os/driver/port/d | |
| 553 | +evcons | |
| 554 | +consread(offset=0x0000009d,buf=0x0043d4fc,n=0x00000400,c=0x0044e | |
| 555 | +c38) / | |
| 556 | +usr/inferno/os/driver/port/devcons.c:357 | |
| 557 | + called from kread+0x164 /usr/inferno/os/port/sysfile.c:2 | |
| 558 | +97 | |
| 559 | +kread(fd=0x00000006,n=0x00000400,va=0x0043d4fc) /usr/inferno/os/ | |
| 560 | +port/sysfile.c:272 | |
| 561 | + called from Sys_read+0x84 /usr/inferno/os/port/inferno.c | |
| 562 | +:244 | |
| 563 | +Sys_read() /usr/inferno/os/port/inferno.c:229 | |
| 564 | + called from mcall+0x98 /usr/inferno/interp/xec.c:590 | |
| 565 | +mcall() /usr/inferno/interp/xec.c:569 | |
| 566 | + called from xec+0x128 /usr/inferno/interp/xec.c:1098 | |
| 567 | +xec(p=0x0044edd8) /usr/inferno/interp/xec.c:1077 | |
| 568 | + called from vmachine+0xbc /usr/inferno/os/port/dis.c:706 | |
| 569 | +vmachine() /usr/inferno/os/port/dis.c:677 | |
| 570 | + called from _main+0x50 /usr/inferno/os/plat/sa1100/infern | |
| 571 | +o/main.c:237 | |
| 572 | +acid: | |
| 573 | +.P2 | |
| 574 | +.d1 | |
| 575 | +There is another kernel stack dump function, | |
| 576 | +.CW "lkstk()" | |
| 577 | +which shows the same information as | |
| 578 | +.CW "kstk()" | |
| 579 | +plus the names and values of local variables. Notice that in addition to the | |
| 580 | +`called from' | |
| 581 | +information, each local variable and its value is listed on a line by itself. | |
| 582 | +.d0 | |
| 583 | +.P1 | |
| 584 | +acid: lkstk() | |
| 585 | +At pc:247812:keyboardread /usr/inferno/os/driver/keyboard/devkeyboard. | |
| 586 | +c:350 | |
| 587 | +keyboardread(offset=0x00000018,buf=0x001267f9,n=0x00000001) /usr/inferno | |
| 588 | +/os/driver/keyboard/devkeyboard.c:350 | |
| 589 | + called from kchanio+0x9c /usr/inferno/os/port/sysfile.c:75 | |
| 590 | + tmp=0x00000000 | |
| 591 | +kchanio(buf=0x001267f9,n=0x00000001,mode=0x00000000) /usr/inferno/os/por | |
| 592 | +t/sysfile.c:64 | |
| 593 | + called from consread+0x144 /usr/inferno/os/driver/port/devcons | |
| 594 | + c=0x0045a858 | |
| 595 | + r=0x00000001 | |
| 596 | +consread(offset=0x00000015,buf=0x0043d4fc,n=0x00000400,c=0x0044ec38) /us | |
| 597 | +r/inferno/os/driver/port/devcons.c:357 | |
| 598 | + called from kread+0x164 /usr/inferno/os/port/sysfile.c:297 | |
| 599 | + r=0x00000001 | |
| 600 | + ch=0x0000006c | |
| 601 | + eol=0x00000000 | |
| 602 | + i=0x00000000 | |
| 603 | + mt=0x60000053 | |
| 604 | + tmp=0x0007317c | |
| 605 | + l=0x0044ec38 | |
| 606 | + p=0x00049754 | |
| 607 | +kread(fd=0x00000006,n=0x00000400,va=0x0043d4fc) /usr/inferno/os/port/sys | |
| 608 | +file.c:272 | |
| 609 | + called from Sys_read+0x84 /usr/inferno/os/port/inferno.c:244 | |
| 610 | + c=0x0044ec38 | |
| 611 | + dir=0x00000000 | |
| 612 | +Sys_read() /usr/inferno/os/port/inferno.c:229 | |
| 613 | + called from mcall+0x98 /usr/inferno/interp/xec.c:590 | |
| 614 | + f=0x0044eff0 | |
| 615 | + n=0x00000400 | |
| 616 | +mcall() /usr/inferno/interp/xec.c:569 | |
| 617 | + called from xec+0x128 /usr/inferno/interp/xec.c:1098 | |
| 618 | + ml=0x0043d92c | |
| 619 | + f=0x0044eff0 | |
| 620 | +xec(p=0x0044edd8) /usr/inferno/interp/xec.c:1077 | |
| 621 | + called from vmachine+0xbc /usr/inferno/os/port/dis.c:706 | |
| 622 | +vmachine() /usr/inferno/os/port/dis.c:677 | |
| 623 | + called from _main+0x50 /usr/inferno/os/plat/sa1100/inferno/main. | |
| 624 | +c:237 | |
| 625 | + r=0x0044edd8 | |
| 626 | + o=0x0044ee50 | |
| 627 | +.P2 | |
| 628 | +.d1 | |
| 629 | +The | |
| 630 | +.CW "step()" | |
| 631 | +function allows the currently selected process to execute a single instruction, and then stop. | |
| 632 | +.P1 | |
| 633 | +acid: step() | |
| 634 | +break 1: pid 7: stopped keyboardread+0x4 MOVW R14,#0x0(R13) | |
| 635 | +acid: | |
| 636 | +.P2 | |
| 637 | +The | |
| 638 | +.CW "bpdel" ( | |
| 639 | +.I id ) | |
| 640 | +command deletes the breakpoint identified by | |
| 641 | +.I id : | |
| 642 | +.P1 | |
| 643 | +acid: bpdel(0) | |
| 644 | +.P2 | |
| 645 | +The | |
| 646 | +.CW "start()" | |
| 647 | +command places the kproc back into the state it was in when it was stopped. | |
| 648 | +.P1 | |
| 649 | +acid: start(7) | |
| 650 | +acid: | |
| 651 | +.P2 | |
| 652 | +Now lets look at how to set conditional breakpoints. | |
| 653 | +.d0 | |
| 654 | +.P1 | |
| 655 | +acid: bpcondset(7, keyboardread, {bppush(_startup), bpderef()}) | |
| 656 | +Waiting... | |
| 657 | +7: stopped sched+0x20 MOVW #0xffffff70(R12),R6 | |
| 658 | +acid: bptab() | |
| 659 | +ID PID ADDR CONDITIONS | |
| 660 | +0 7 keyboardread 0x0003c804 { | |
| 661 | + {"p", 0x00008020} | |
| 662 | + {"*", 0x00000000} } | |
| 663 | +acid: *_startup = 0 | |
| 664 | +acid: cont() | |
| 665 | +.P2 | |
| 666 | +.d1 | |
| 667 | +Conditional breakpoints are set with | |
| 668 | +.CW "bpcondset()" | |
| 669 | +. It takes three arguments, the kernel process id, the address, and a list of stack based operations which are executed if the pid and addr match. The operations push values onto the stack, and if at the end of execution, a nonzero value is on the top of the stack, the breakpoint is taken. Examining the list of breakpoints with the | |
| 670 | +.CW "bptab()" | |
| 671 | +function shows the list of conditions to apply. The list is a bit confusing to read, but the | |
| 672 | +.CW ""p"" | |
| 673 | +means push and the | |
| 674 | +.CW ""*"" | |
| 675 | +means | |
| 676 | +.I dereference . | |
| 677 | +.PP | |
| 678 | +No matter how much you type on the keyboard, this particular breakpoint will never be taken. That's because before continuing, we set the value at the address | |
| 679 | +.CW "_startup" | |
| 680 | +to zero, so whenever execution reaches | |
| 681 | +.CW "keyboardread" | |
| 682 | +in kproc number 7, it pushes the address | |
| 683 | +.CW "_startup" , | |
| 684 | +then pops it and pushes the word at that address. Since the top of the stack is zero, the breakpoint is ignored. | |
| 685 | +.PP | |
| 686 | +This contrived example may not be all that useful, but you can use a similar method in your driver to examine some state before making the decision to take the breakpoint. | |
| 687 | +.SH | |
| 688 | +Examining Registers | |
| 689 | +.PP | |
| 690 | +There are three commands to dump registers: | |
| 691 | +.CW gpr() , | |
| 692 | +.CW spr() | |
| 693 | +and | |
| 694 | +.CW "regs()" . | |
| 695 | +The | |
| 696 | +.CW "gpr()" | |
| 697 | +function dumps the general purpose registers, | |
| 698 | +.CW "spr()" | |
| 699 | +dumps special purpose registers (such as the | |
| 700 | +.CW "PC" | |
| 701 | +and | |
| 702 | +.CW "LINK " | |
| 703 | +registers), and | |
| 704 | +.CW "regs()" | |
| 705 | +dumps both: | |
| 706 | +.d0 | |
| 707 | +.P1 | |
| 708 | +acid: regs() | |
| 709 | +PC 0x0004a3b0 sched+0x20 /home/tad/inf2.1/os/port/proc.c:82 | |
| 710 | +LINK 0x0004b8e8 kchanio+0xa4 /home/tad/inf2.1/os/port/sysfile.c:75 | |
| 711 | +SP 0x00453c4c | |
| 712 | +R0 0x00458798 R1 0x000fdf9c R2 0x0003c804 R3 0x00000000 | |
| 713 | +R4 0xffffffff R5 0x00000001 R6 0x00458798 R7 0x00000001 | |
| 714 | +R8 0x001267f8 R9 0x00000000 R10 0x0044ee50 R11 0x00029f9c | |
| 715 | +R12 0x000fc854 | |
| 716 | +acid: | |
| 717 | +.P2 | |
| 718 | +.d1 | |
| 719 | +.SH | |
| 720 | +Complex Types | |
| 721 | +.PP | |
| 722 | +When reading in the symbol table, Acid treats all of the symbols in the executable as pointers to integers. This is fine for global integer variables, but it makes examining more complex types difficult. Luckily there is a solution. Acid allows you to create a description for more complex types, and a function which will automatically be called for these complex types. In fact, the compiler can automatically generate the acid code to describe these complex types. For example, if we wanted to print out the devtab structure for the keyboard driver, we can just give its name: | |
| 723 | +.P1 | |
| 724 | +acid: whatis keyboarddevtab | |
| 725 | +integer variable format a complex Dev | |
| 726 | +acid: keyboarddevtab | |
| 727 | + dc 107 | |
| 728 | + name 0x0010e0ea | |
| 729 | + reset 0x0003c3fc | |
| 730 | + init 0x0003c438 | |
| 731 | + attach 0x0003c5dc | |
| 732 | + clone 0x000480d0 | |
| 733 | + walk 0x0003c600 | |
| 734 | + stat 0x0003c640 | |
| 735 | + open 0x0003c680 | |
| 736 | + create 0x0004881c | |
| 737 | + close 0x0003c768 | |
| 738 | + read 0x0003c804 | |
| 739 | + bread 0x0004883c | |
| 740 | + write 0x0003c968 | |
| 741 | + bwrite 0x00048900 | |
| 742 | + remove 0x00048978 | |
| 743 | + wstat 0x00048998 | |
| 744 | +acid: | |
| 745 | +.P2 | |
| 746 | +Acid knows the keyboarddevtab variable is of type Dev, and it prints it by invoking the function Dev(keyboarddevtab). | |
| 747 | +.P1 | |
| 748 | +acid: whatis Dev | |
| 749 | +complex Dev { | |
| 750 | + 'D' 0 dc; | |
| 751 | + 'X' 4 name; | |
| 752 | + 'X' 8 reset; | |
| 753 | + 'X' 12 init; | |
| 754 | + 'X' 16 attach; | |
| 755 | + 'X' 20 clone; | |
| 756 | + 'X' 24 walk; | |
| 757 | + 'X' 28 stat; | |
| 758 | + 'X' 32 open; | |
| 759 | + 'X' 36 create; | |
| 760 | + 'X' 40 close; | |
| 761 | + 'X' 44 read; | |
| 762 | + 'X' 48 bread; | |
| 763 | + 'X' 52 write; | |
| 764 | + 'X' 56 bwrite; | |
| 765 | + 'X' 60 remove; | |
| 766 | + 'X' 64 wstat; | |
| 767 | +}; | |
| 768 | +.P3 | |
| 769 | +defn Dev(addr) { | |
| 770 | + complex Dev addr; | |
| 771 | + print("\etdct",addr.dc,"\en"); | |
| 772 | + print("\etnamet",addr.nameX,"\en"); | |
| 773 | + print("\etresett",addr.resetX,"\en"); | |
| 774 | + print("\etinitt",addr.initX,"\en"); | |
| 775 | + print("\etattacht",addr.attachX,"\en"); | |
| 776 | + print("\etclonet",addr.cloneX,"\en"); | |
| 777 | + print("\etwalkt",addr.walkX,"\en"); | |
| 778 | + print("\etstatt",addr.statX,"\en"); | |
| 779 | + print("\etopent",addr.openX,"\en"); | |
| 780 | + print("\etcreatet",addr.createX,"\en"); | |
| 781 | + print("\etcloset",addr.closeX,"\en"); | |
| 782 | + print("\etreadt",addr.readX,"\en"); | |
| 783 | + print("\etbreadt",addr.breadX,"\en"); | |
| 784 | + print("\etwritet",addr.writeX,"\en"); | |
| 785 | + print("\etbwritet",addr.bwriteX,"\en"); | |
| 786 | + print("\etremovet",addr.removeX,"\en"); | |
| 787 | + print("\etwstatt",addr.wstatX,"\en"); | |
| 788 | +} | |
| 789 | +.P2 | |
| 790 | +Notice the complex type definition and the function to print the type both have the same name. If we know that an address is the address of a complex type, even though acid may not | |
| 791 | +(say we're storing multiple types of data in a void pointer), | |
| 792 | +we can print the complex type by calling the type printing function ourselves. | |
| 793 | +.P1 | |
| 794 | +acid: print(fmt(keyboarddevtab, 'X')) | |
| 795 | +0x00106d50 | |
| 796 | +acid: Dev(0x00106d50) | |
| 797 | + dc 107 | |
| 798 | + name 0x0010e0ea | |
| 799 | + reset 0x0003c3fc | |
| 800 | + init 0x0003c438 | |
| 801 | + attach 0x0003c5dc | |
| 802 | + clone 0x000480d0 | |
| 803 | + walk 0x0003c600 | |
| 804 | + stat 0x0003c640 | |
| 805 | + open 0x0003c680 | |
| 806 | + create 0x0004881c | |
| 807 | + close 0x0003c768 | |
| 808 | + read 0x0003c804 | |
| 809 | + bread 0x0004883c | |
| 810 | + write 0x0003c968 | |
| 811 | + bwrite 0x00048900 | |
| 812 | + remove 0x00048978 | |
| 813 | + wstat 0x00048998 | |
| 814 | +acid: | |
| 815 | +.P2 | |
| 816 | +.SH | |
| 817 | +Conclusion | |
| 818 | +.PP | |
| 819 | +This introduction to using Acid for remote debugging Inferno kernels should be enough to get you started. As a tutorial, it only describes how to use some of the features of the debugger, and does not attempt to describe how to do advanced debugging such as writing your own functions, or modifying existing ones. Exploring the source, setting breakpoints, single stepping through code, and examining the contents of variables are the usual uses of a debugger. This tutorial gives examples of all of these. | |
| 820 | +.PP | |
| 821 | +For a more in depth discussion of the acid command language, and how to write your own acid functions, see the manual page | |
| 822 | +.I acid (10.1) | |
| 823 | +and Phil Winterbottom's papers on the Acid Debugger, | |
| 824 | +reprinted in this volume. | |
| 825 | +.TL | |
| 826 | +Appendix | |
| 827 | +.LP | |
| 828 | +There are two important differences between Acid described in the | |
| 829 | +accompanying paper, and Acid as distributed with Inferno for use in | |
| 830 | +kernel debugging. | |
| 831 | +.SH | |
| 832 | +Connecting Acid to the remote Inferno kernel | |
| 833 | +.PP | |
| 834 | +A remote Plan 9 kernel can be debugged in the same | |
| 835 | +way as a Plan 9 user process, using the | |
| 836 | +file server | |
| 837 | +.I rdbfs (4). | |
| 838 | +It is a user-level file server on Plan 9 that | |
| 839 | +uses a special debugging protocol on a serial connection to | |
| 840 | +the remote kernel, but on the Plan 9 side serves a file system interface | |
| 841 | +like that of | |
| 842 | +.I proc (3), | |
| 843 | +for use by Acid. | |
| 844 | +Acid therefore does not need any special code to access the remote kernel's memory, | |
| 845 | +or exert control over it. | |
| 846 | +.PP | |
| 847 | +Inferno's version of Acid currently runs under the host operating systems, | |
| 848 | +which do not support such a mechanism (except for Plan 9). | |
| 849 | +Instead, Acid itself provides a special debugging protocol, | |
| 850 | +with (host) platform-specific interface code to access a serial port. | |
| 851 | +This might well be addressed in future by implementing the native kernel debugger | |
| 852 | +in Limbo. | |
| 853 | +.SH | |
| 854 | +Handling of breakpoints | |
| 855 | +.PP | |
| 856 | +.de Ip | |
| 857 | +.KS | |
| 858 | +.LP | |
| 859 | +.tl '\f2\\$1\fP\ \ \f(CW\\$2(\f2\\$3\f(CW)\f1''\\$4' | |
| 860 | +.IP | |
| 861 | +.. | |
| 862 | +.de Ex | |
| 863 | +.KE | |
| 864 | +.KS | |
| 865 | +.IP | |
| 866 | +.ft CW | |
| 867 | +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n | |
| 868 | +.nf | |
| 869 | +.in +4n | |
| 870 | +.br | |
| 871 | +.. | |
| 872 | +.de Ee | |
| 873 | +.fi | |
| 874 | +.ft 1 | |
| 875 | +.br | |
| 876 | +.in -4n | |
| 877 | +.KE | |
| 878 | +.. | |
| 879 | +The following functions are provided by the Acid library | |
| 880 | +.CW $ROOT/lib/acid/$OBJTYPE | |
| 881 | +for use in native kernel debugging. | |
| 882 | +In several cases they change the behavior described in the Acid manual. | |
| 883 | +The functions are: | |
| 884 | +.P1 | |
| 885 | + id = bpset(addr) | |
| 886 | + id = bpcondset(pid, addr, list) | |
| 887 | + bppush(val) | |
| 888 | + bpderef() | |
| 889 | + bpmask() | |
| 890 | + bpeq() | |
| 891 | + bpneq() | |
| 892 | + bpand() | |
| 893 | + bpor() | |
| 894 | + bptab() | |
| 895 | + addr = bpaddr(id) | |
| 896 | + bpdel(id) | |
| 897 | + bpconddel(id) | |
| 898 | +.P2 | |
| 899 | +.PP | |
| 900 | +With traditional breakpoints, when a program reaches an address at which a breakpoint is set, execution is halted, and the debugger is notified. In applications programming, this type of breakpoint is sufficient because communicating the break in execution to the debugger is handled by the operating system. The traditional method of handling breakpoints breaks down when program being debugged is the kernel. A breakpoint cannot entirely suspend the execution of the kernel because there is no other program that can handle the communication to the debugger. | |
| 901 | +.PP | |
| 902 | +Some operating systems solve this problem by including a | |
| 903 | +`mini' operating system, | |
| 904 | +a self-contained program within the kernel that has its own code to handle the hardware used to communicate with the remote debugger or user. There are many problems with this mechanism. First, the debugger code that lives inside the kernel must duplicate a lot of code contained elsewhere in the kernel. This makes the kernel much bigger, and can increase maintenance costs. Typically this type of debug support treats the kernel as having a single thread of control, so a breakpoint stops everything while the user decides what to do about it. The only places in the kernel breakpoints cannot be set are in the debugger itself, and in the code that handles notifying the debugger of the breakpoint. | |
| 905 | +.PP | |
| 906 | +The Inferno kernel takes a different approach. The remote debug support is provided by a device driver that makes use of kernel services. Communication with the remote debugger is handled by a kernel process dedicated entirely to that task. All breakpoints can be considered to be minimally conditional on two values. First, the address to take the break at, and second, the kernel process to take the break in. This method allows the kernel debugger to be implemented as a regular Inferno device driver. The device driver can make use of all the APIs available to device drivers, it does not need to be self contained. Additionally, conditional breakpoints can be set anywhere in the kernel, with two exceptions. As with traditional debugger implementations, breakpoints can not be set in the code that handles notifying the debugger of the breakpoint. Unlike traditional implementations, the code that handles the execution and evaluation of the conditions applied to the breakpoint is the only other place breakpoint | |
| 907 | +cannot be set. Since both of these parts of the kernel code are self contained, the user can set breakpoints in any other kernel routines. For example, the user could set a breakpoint in | |
| 908 | +.CW kread() , | |
| 909 | +for a given kernel process, but the debugger can still call | |
| 910 | +.CW kread() | |
| 911 | +itself. | |
| 912 | +.PP | |
| 913 | +Use of conditional breakpoints can help make the debugging process more efficient. If there is a bug that occurs in the Nth iteration of a loop, with unconditional breakpoints, user intervention is required N-1 times before reaching the state the bug occurs in. Conditional breakpoints give the user the ability to automatically check the value of N, and only take the breakpoint when it reaches the critical value. | |
| 914 | +.PP | |
| 915 | +The following changed | |
| 916 | +and additional functions in the Acid library provide access | |
| 917 | +to this extended breakpoint support: | |
| 918 | +.SH | |
| 919 | +Setting Breakpoints | |
| 920 | +.LP | |
| 921 | +.\" | |
| 922 | +.\" | |
| 923 | +.\" | |
| 924 | +.Ip integer bpset integer "Set a breakpoint | |
| 925 | +.CW bpset | |
| 926 | +places an unconditional breakpoint for the currently | |
| 927 | +selected kernel process at the address specified | |
| 928 | +by its | |
| 929 | +.I integer | |
| 930 | +argument. | |
| 931 | +It returns the ID of the newly created breakpoint, or the nil list on error. | |
| 932 | +It is simply shorthand for a call | |
| 933 | +.Ex | |
| 934 | +bpcondset(pid, addr, {}) | |
| 935 | +.Ee | |
| 936 | +where | |
| 937 | +.I pid | |
| 938 | +is the global variable identifying the currently selected process, | |
| 939 | +.I addr | |
| 940 | +is the user-supplied address for the breakpoint, | |
| 941 | +and | |
| 942 | +.CW {} | |
| 943 | +is the empty list, signifying no conditions. | |
| 944 | +.Ip integer bpcondset "pid,addr,list" "Set conditional breakpoint | |
| 945 | +Sets a conditional breakpoint at addr for the kernel process identified by | |
| 946 | +.I pid . | |
| 947 | +The | |
| 948 | +.I list | |
| 949 | +argument is a list of operations that are executed when execution reaches | |
| 950 | +.I addr . | |
| 951 | +If execution results in a a non-zero value on the top of the stack, the breakpoint is taken, otherwise it is skipped. | |
| 952 | +The | |
| 953 | +.I list | |
| 954 | +is in reverse polish notation format, and has these operations: | |
| 955 | +.Ex | |
| 956 | +PUSH | |
| 957 | +DEREF (pop val, push *(ulong*)val) | |
| 958 | +MASK (pop mask, pop value, push value & mask) | |
| 959 | +EQ (pop v1, pop v2, push v1 == v2) | |
| 960 | +NEQ (pop v1, pop v2, push v1 != v2) | |
| 961 | +AND (pop v1, pop v2, push v1 && v1) | |
| 962 | +OR (pop v1, pop v2, push v1 || v2) | |
| 963 | +.Ee | |
| 964 | +Condition lists are executed in a single pass, starting with the first command in the list, ending with the last. If a nonzero value is on the top of the stack at the end of execution, the breakpoint is taken, otherwise it is skipped. | |
| 965 | +.RS | |
| 966 | +.LP | |
| 967 | +In effect, there are two mandatory conditions, the address of the breakpoint, and the kernel process id. These two conditions must be met for the condition list to be processed. If these conditions are met, the entire condition list is processed, there is no short circuit evaluation path. | |
| 968 | +.LP | |
| 969 | +For example, given the following code fragment: | |
| 970 | +.P1 +.4i | |
| 971 | +int i; | |
| 972 | + | |
| 973 | +for(i=0; i<1000; i++) { | |
| 974 | + ... | |
| 975 | +} | |
| 976 | +.P2 | |
| 977 | +the following call to | |
| 978 | +.CW bpcondset() | |
| 979 | +sets a conditional breakpoint to be taken when execution reaches | |
| 980 | +.I addr | |
| 981 | +in kernel process | |
| 982 | +.I pid | |
| 983 | +on the 500th iteration of the loop: | |
| 984 | +.P1 +.4i | |
| 985 | +bpcondset(pid, addr, {bppush(i), | |
| 986 | + bpderef(), bppush(500), bpeq()}); | |
| 987 | +.P2 | |
| 988 | +.RE | |
| 989 | +.SH | |
| 990 | +Condition List Construction | |
| 991 | +.LP | |
| 992 | +.Ip list bppush val "Construct breakpoint stack | |
| 993 | +Push val onto the stack. | |
| 994 | +.KE | |
| 995 | +.Ip list bpderef "" "Construct breakpoint stack | |
| 996 | +Replace the value at the top of the stack with the value found at the address obtained by treating value at the top of the stack as an address. Pop the value on the top of the stack, treat it as a ulong*, and push the value at the address. | |
| 997 | +.Ex | |
| 998 | +addr = pop(); | |
| 999 | +push(*(ulong*)addr); | |
| 1000 | +.Ee | |
| 1001 | +.Ip list bpmask "" "Construct breakpoint stack | |
| 1002 | +Replace the top two values on the stack with the value obtained by masking the second value on the stack with the top of the stack. | |
| 1003 | +.Ex | |
| 1004 | +mask = pop(); | |
| 1005 | +value = pop(); | |
| 1006 | +push(value & mask); | |
| 1007 | +.Ee | |
| 1008 | +.Ip list bpeq "" "Construct breakpoint stack | |
| 1009 | +Comparison of the top two values on the stack. Replace the top two values on the stack with a 1 if the values are equal, or a zero if they are not. | |
| 1010 | +.Ex | |
| 1011 | +v1 = pop(); | |
| 1012 | +v2 = pop(); | |
| 1013 | +push(v1 == v2); | |
| 1014 | +.Ee | |
| 1015 | +.Ip list bpneq "" "Construct breakpoint stack | |
| 1016 | +Negative comparison of the top two values on the stack. Replace the top two values on the stack with a 0 if the values are equal, or 1 if they are not. | |
| 1017 | +.Ex | |
| 1018 | +v1 = pop(); | |
| 1019 | +v2 = pop(); | |
| 1020 | +push(v1 != v2); | |
| 1021 | +.Ee | |
| 1022 | +.Ip list bpand "" "Construct breakpoint stack | |
| 1023 | +Logical and of the top two values on the stack. Replace the top two values on the stack with a 0 if both are zero, or 1 if both are nonzero. | |
| 1024 | +.Ex | |
| 1025 | +v1 = pop(); | |
| 1026 | +v2 = pop(); | |
| 1027 | +push(v1 && v2); | |
| 1028 | +.Ee | |
| 1029 | +.Ip list bpor "" "Construct breakpoint stack | |
| 1030 | +Logical or of the top two values on the stack. Replace the top two values on the stack with a 1 if either is nonzero, 0 otherwise. | |
| 1031 | +.Ex | |
| 1032 | +v1 = pop(); | |
| 1033 | +v2 = pop(); | |
| 1034 | +push(v1 || v2); | |
| 1035 | +.Ee | |
| 1036 | +.SH | |
| 1037 | +Breakpoint Status | |
| 1038 | +.LP | |
| 1039 | +.Ip {} bptab "" "List active breakpoints | |
| 1040 | +Prints the list of breakpoints containing the following information in order: breakpoint number, kernel process id, breakpoint address, and the list of conditions to execute to determine if the breakpoint will be taken. | |
| 1041 | +.Ex | |
| 1042 | +acid: bptab() | |
| 1043 | +ID PID ADDR CONDITIONS | |
| 1044 | +0 1 consread+0x20 0x216cc {} | |
| 1045 | +acid: | |
| 1046 | +.Ee | |
| 1047 | +.Ip integer bpaddr id "Address of breakpoint | |
| 1048 | +Returns the address the breakpoint identified by | |
| 1049 | +.I id | |
| 1050 | +is set to trigger on. | |
| 1051 | +.KE | |
| 1052 | +.SH | |
| 1053 | +Deleting breakpoints | |
| 1054 | +.Ip {} bpdel id "Delete breakpoint | |
| 1055 | +Delete the breakpoint identified by | |
| 1056 | +.I id . | |
| 1057 | +Shorthand for bpconddel(). | |
| 1058 | +.KE | |
| 1059 | +.Ip {} bpconddel id "Delete conditional breakpoint | |
| 1060 | +Delete the conditional breakpoint identified by the integer | |
| 1061 | +.I id . | |
| 1062 | +.KE | |
Binary file not shown.
| @@ -0,0 +1,1295 @@ | ||
| 1 | +.de EX | |
| 2 | +.nr x \\$1v | |
| 3 | +\\!h0c n \\nx 0 | |
| 4 | +.. | |
| 5 | +.de FG \" start figure caption: .FG filename.ps verticalsize | |
| 6 | +.KF | |
| 7 | +.BP \\$1 \\$2 | |
| 8 | +.sp .5v | |
| 9 | +.EX \\$2v | |
| 10 | +.ps -1 | |
| 11 | +.vs -1 | |
| 12 | +.. | |
| 13 | +.de fg \" end figure caption (yes, it is clumsy) | |
| 14 | +.ps | |
| 15 | +.vs | |
| 16 | +.br | |
| 17 | +\l'1i' | |
| 18 | +.KE | |
| 19 | +.. | |
| 20 | +.TL | |
| 21 | +Acme: A User Interface for Programmers | |
| 22 | +.AU | |
| 23 | +.I "Rob Pike | |
| 24 | +.I rob@plan9.bell-labs.com | |
| 25 | +.SP .22i exactly | |
| 26 | +.AB | |
| 27 | +.FS | |
| 28 | +\l'1i' | |
| 29 | +.br | |
| 30 | +Originally appeared in | |
| 31 | +.I | |
| 32 | +Proc. of the Winter 1994 USENIX Conf., | |
| 33 | +.R | |
| 34 | +pp. 223-234, | |
| 35 | +San Francisco, CA | |
| 36 | +.br | |
| 37 | +Reprinted in | |
| 38 | +.I "Plan 9 Programmer's Manual: Volume 2" | |
| 39 | +(Second Edition), AT&T 1995. | |
| 40 | +.FE | |
| 41 | +A hybrid of window system, shell, and editor, Acme gives text-oriented | |
| 42 | +applications a clean, expressive, and consistent style of interaction. | |
| 43 | +Traditional window systems support interactive client programs and offer libraries of | |
| 44 | +pre-defined operations such as pop-up menus | |
| 45 | +and buttons to promote a consistent | |
| 46 | +user interface among the clients. | |
| 47 | +Acme instead provides its clients with a fixed user interface and | |
| 48 | +simple conventions to encourage its uniform use. | |
| 49 | +Clients access the facilities of Acme through a file system interface; | |
| 50 | +Acme is in part a file server that exports device-like files that may be | |
| 51 | +manipulated to access and control the contents of its windows. | |
| 52 | +Written in a concurrent programming language, | |
| 53 | +Acme is structured as a set of communicating processes that neatly subdivide | |
| 54 | +the various aspects of its tasks: display management, input, file server, and so on. | |
| 55 | +.PP | |
| 56 | +Acme attaches distinct functions to the three mouse buttons: | |
| 57 | +the left selects text; | |
| 58 | +the middle executes textual commands; | |
| 59 | +and the right combines context search and file opening | |
| 60 | +functions to integrate the various applications and files in | |
| 61 | +the system. | |
| 62 | +.PP | |
| 63 | +Acme works well enough to have developed | |
| 64 | +a community that uses it exclusively. | |
| 65 | +Although Acme discourages the traditional style of interaction | |
| 66 | +based on typescript windows\(emteletypes\(emits | |
| 67 | +users find Acme's other services render | |
| 68 | +typescripts obsolete. | |
| 69 | +.AE | |
| 70 | +.SH | |
| 71 | +History and motivation | |
| 72 | +.PP | |
| 73 | +The usual typescript style of interaction with | |
| 74 | +Unix and its relatives is an old one. | |
| 75 | +The typescript\(eman intermingling of textual commands and their | |
| 76 | +output\(emoriginates with the scrolls of paper on teletypes. | |
| 77 | +The advent of windowed terminals has given each user what | |
| 78 | +amounts to an array of teletypes, a limited and unimaginative | |
| 79 | +use of the powers of bitmap displays and mice. | |
| 80 | +Systems like the Macintosh | |
| 81 | +that do involve the mouse as an integral part of the interaction | |
| 82 | +are geared towards general users, not experts, and certainly | |
| 83 | +not programmers. | |
| 84 | +Software developers, at least on time-sharing systems, have been left behind. | |
| 85 | +.FG ./acme.fig1 5i | |
| 86 | +Figure 1. A small Acme screen\(emnormally it runs on a larger display\(emdemonstrating | |
| 87 | +some of the details discussed in the text. | |
| 88 | +The right column contains some guide files, | |
| 89 | +a mailbox presented by Acme's mail program, | |
| 90 | +the columnated display of files in Acme's own source directory, | |
| 91 | +a couple of windows from the OED browser, | |
| 92 | +a debugger window, | |
| 93 | +and an error window showing diagnostics from a compilation. | |
| 94 | +The left column holds a couple of source files | |
| 95 | +.CW dat.h "" ( | |
| 96 | +and | |
| 97 | +.CW acme.l ), | |
| 98 | +another debugger window displaying a stack trace, | |
| 99 | +and a third source file | |
| 100 | +.CW time.l ). ( | |
| 101 | +.CW Time.l | |
| 102 | +was opened from the debugger by clicking the right mouse button | |
| 103 | +on a line in the stack window; | |
| 104 | +the mouse cursor landed on the offending line of | |
| 105 | +.CW acme.l | |
| 106 | +after a click on the compiler message. | |
| 107 | +.fg | |
| 108 | +.PP | |
| 109 | +Some programs have mouse-based editing of | |
| 110 | +text files and typescripts; | |
| 111 | +ones I have built include | |
| 112 | +the window systems | |
| 113 | +.CW mux | |
| 114 | +[Pike88] | |
| 115 | +and | |
| 116 | +.CW 8½ | |
| 117 | +[Pike91] | |
| 118 | +and the text editor | |
| 119 | +Sam [Pike87]. | |
| 120 | +These have put the programmer's mouse to some productive work, | |
| 121 | +but not wholeheartedly. Even experienced users of these programs | |
| 122 | +often retype text that could be grabbed with the mouse, | |
| 123 | +partly because the menu-driven interface is imperfect | |
| 124 | +and partly because the various pieces are not well enough integrated. | |
| 125 | +.PP | |
| 126 | +Other programs\(emEMACS [Stal93] is the prime example\(emoffer a high | |
| 127 | +degree of integration but with a user interface built around the | |
| 128 | +ideas of cursor-addressed terminals that date from the 1970's. | |
| 129 | +They are still keyboard-intensive and | |
| 130 | +dauntingly complex. | |
| 131 | +.PP | |
| 132 | +The most ambitious attempt to face these issues was the Cedar | |
| 133 | +system, developed at Xerox [Swei86]. | |
| 134 | +It combined a new programming language, compilers, | |
| 135 | +window system, even microcode\(ema complete system\(emto | |
| 136 | +construct a productive, highly | |
| 137 | +integrated and interactive environment | |
| 138 | +for experienced users of compiled languages. | |
| 139 | +Although successful internally, the system was so large | |
| 140 | +and so tied to specific hardware that it never fledged. | |
| 141 | +.PP | |
| 142 | +Cedar was, however, the major inspiration for Oberon [Wirt89], | |
| 143 | +a system of similar scope but much smaller scale. | |
| 144 | +Through careful selection of Cedar's ideas, Oberon shows | |
| 145 | +that its lessons can be applied to a small, coherent system | |
| 146 | +that can run efficiently on modest hardware. | |
| 147 | +In fact, Oberon probably | |
| 148 | +errs too far towards simplicity: a single-process system | |
| 149 | +with weak networking, it seems an architectural throwback. | |
| 150 | +.PP | |
| 151 | +Acme is a new program, | |
| 152 | +a combined window system, editor, and shell, | |
| 153 | +that applies | |
| 154 | +some of the ideas distilled by Oberon. | |
| 155 | +Where Oberon uses objects and modules within a programming language (also called Oberon), | |
| 156 | +Acme uses files and commands within an existing operating system (Plan 9). | |
| 157 | +Unlike Oberon, Acme does not yet have support for graphical output, just text. | |
| 158 | +At least for now, the work on Acme has concentrated on | |
| 159 | +producing the smoothest user interface possible for a programmer | |
| 160 | +at work. | |
| 161 | +.PP | |
| 162 | +The rest of this paper describes Acme's interface, | |
| 163 | +explains how programs can access it, | |
| 164 | +compares it to existing systems, | |
| 165 | +and finally presents some unusual aspects of its implementation. | |
| 166 | +.SH | |
| 167 | +User interface | |
| 168 | +.PP | |
| 169 | +.FG ./acme.fig2 3i | |
| 170 | +Figure 2. An Acme window showing a section of code. | |
| 171 | +The upper line of text is the tag containing the file name, | |
| 172 | +relevant commands, and a scratch area (right of the vertical bar); | |
| 173 | +the lower portion of the window is the | |
| 174 | +body, or contents, of the file. | |
| 175 | +Here the scratch area contains a command for the middle button | |
| 176 | +.CW mk ) ( | |
| 177 | +and a word to search for with the right button | |
| 178 | +.CW cxfidalloc ). ( | |
| 179 | +The user has just | |
| 180 | +clicked the right button on | |
| 181 | +.CW cxfidalloc | |
| 182 | +and Acme has searched for the word, highlighted it, | |
| 183 | +and moved the mouse cursor there. The file has been modified: | |
| 184 | +the center of the layout box is black and the command | |
| 185 | +.CW Put | |
| 186 | +appears in the tag. | |
| 187 | +.fg | |
| 188 | +Acme windows are arrayed in columns (Figure 1) and are used more | |
| 189 | +dynamically than in an environment like X Windows or | |
| 190 | +.CW 8½ | |
| 191 | +[Sche86, Pike91]. | |
| 192 | +The system frequently creates them automatically and the user | |
| 193 | +can order a new one with a single mouse button click. | |
| 194 | +The initial placement of a new window is determined | |
| 195 | +automatically, but the user may move an existing window anywhere | |
| 196 | +by clicking or dragging a | |
| 197 | +.I "layout box | |
| 198 | +in the upper left corner of | |
| 199 | +the window. | |
| 200 | +.PP | |
| 201 | +Acme windows have two parts: a | |
| 202 | +.I tag | |
| 203 | +holding a single line of text, | |
| 204 | +above a | |
| 205 | +.I body | |
| 206 | +holding zero or more lines (Figure 2). | |
| 207 | +The body typically contains an image of a file being edited | |
| 208 | +or the editable output of a | |
| 209 | +program, analogous to an | |
| 210 | +EMACS shell | |
| 211 | +window. The tag contains | |
| 212 | +the name of the window | |
| 213 | +(usually the name of the associated | |
| 214 | +file or directory), some built-in commands, and a scratch area to hold arbitrary text. | |
| 215 | +If a window represents a directory, the name in the tag ends with | |
| 216 | +a slash and the body contains a list of the names of the files | |
| 217 | +in the directory. | |
| 218 | +Finally, each non-empty body holds a scroll bar at the left of the text. | |
| 219 | +.PP | |
| 220 | +Each column of windows also has a layout box and a tag. | |
| 221 | +The tag has no special meaning, although Acme pre-loads it with a few | |
| 222 | +built-in commands. | |
| 223 | +There is also a tag across the whole display, also loaded with | |
| 224 | +helpful commands and a list of active processes started | |
| 225 | +by Acme. | |
| 226 | +.PP | |
| 227 | +Typing with the keyboard and selecting with the left button are as in | |
| 228 | +many other systems, including the Macintosh, | |
| 229 | +.CW 8½ , | |
| 230 | +and Sam. | |
| 231 | +The middle and right buttons are used, somewhat like the left button, | |
| 232 | +to `sweep' text, but the indicated text is treated in a way | |
| 233 | +that depends on the text's location\(em\f2context\f1\(emas well as its content. | |
| 234 | +This context, based on the directory of the file containing the text, | |
| 235 | +is a central component of Acme's style of interaction. | |
| 236 | +.PP | |
| 237 | +Acme has no single notion of `current directory'. | |
| 238 | +Instead, every command, file name, | |
| 239 | +action, and so on is interpreted or executed in the directory named by the | |
| 240 | +tag of the window containing the command. For example, the string | |
| 241 | +.CW mammals | |
| 242 | +in a window labeled | |
| 243 | +.CW /lib/ | |
| 244 | +or | |
| 245 | +.CW /lib/insects | |
| 246 | +will be interpreted as the file name | |
| 247 | +.CW /lib/mammals | |
| 248 | +if such a file exists. | |
| 249 | +.PP | |
| 250 | +Throughout Acme, the middle mouse button is used to execute commands | |
| 251 | +and the right mouse button is used to locate and select files and text. | |
| 252 | +Even when there are no true files on which to operate\(emfor example | |
| 253 | +when editing mail messages\(emAcme and its applications use | |
| 254 | +consistent extensions of these basic functions. | |
| 255 | +This idea is as vital to Acme as icons are to the Macintosh. | |
| 256 | +.PP | |
| 257 | +The middle button executes commands: text swept with the button | |
| 258 | +pressed is underlined; when the button is released, the underline is | |
| 259 | +removed and the indicated text is executed. | |
| 260 | +A modest number of commands are recognized as built-ins: words like | |
| 261 | +.CW Cut , | |
| 262 | +.CW Paste , | |
| 263 | +and | |
| 264 | +.CW New | |
| 265 | +name | |
| 266 | +functions performed directly by Acme. | |
| 267 | +These words often appear in tags to make them always available, | |
| 268 | +but the tags are not menus: any text anywhere in Acme may be a command. | |
| 269 | +For example, in the tag or body of any window one may type | |
| 270 | +.CW Cut , | |
| 271 | +select it with the left button, use the middle button to execute it, | |
| 272 | +and watch it disappear again. | |
| 273 | +.PP | |
| 274 | +If the middle button indicates a command that is not recognized as a built-in, | |
| 275 | +it is executed in the directory | |
| 276 | +named by the tag of the window holding the text. | |
| 277 | +Also, the file to be executed is searched for first in that directory. | |
| 278 | +Standard input is connected to | |
| 279 | +.CW /dev/null , | |
| 280 | +but standard and error outputs are connected to an Acme window, | |
| 281 | +created if needed, called | |
| 282 | +\f2dir\f(CW/+Errors\f1 where | |
| 283 | +.I dir | |
| 284 | +is the directory of the window. | |
| 285 | +(Programs that need interactive input use a different interface, described below.) | |
| 286 | +A typical use of this is to type | |
| 287 | +.CW mk | |
| 288 | +(Plan 9's | |
| 289 | +.CW make ) | |
| 290 | +in the scratch area in the tag of a C source window, say | |
| 291 | +.CW /sys/src/cmd/sam/regexp.c , | |
| 292 | +and execute it. | |
| 293 | +Output, including compiler errors, appears in the window labeled | |
| 294 | +.CW /sys/src/cmd/sam/+Errors , | |
| 295 | +so file names in the output are associated with the windows and directory | |
| 296 | +holding the source. | |
| 297 | +The | |
| 298 | +.CW mk | |
| 299 | +command remains in the tag, serving as a sort of menu item for the associated | |
| 300 | +window. | |
| 301 | +.PP | |
| 302 | +Like the middle button, the right button is used to indicate text by sweeping it out. | |
| 303 | +The indicated text is not a command, however, but the argument of a generalized | |
| 304 | +search operator. | |
| 305 | +If the text, perhaps after appending it to the directory of the window containing it, | |
| 306 | +is the name of an existing file, Acme creates a new window to hold the file | |
| 307 | +and reads it in. It then moves the mouse cursor to that window. If the file is | |
| 308 | +already loaded into Acme, the mouse motion happens but no new window is made. | |
| 309 | +For example, indicating the string | |
| 310 | +.CW sam.h | |
| 311 | +in | |
| 312 | +.P1 | |
| 313 | +#include "sam.h" | |
| 314 | +.P2 | |
| 315 | +in a window on the file | |
| 316 | +.CW /sys/src/cmd/sam/regexp.c | |
| 317 | +will open the file | |
| 318 | +.CW /sys/src/cmd/sam/sam.h . | |
| 319 | +.PP | |
| 320 | +If the file name is followed immediately by a colon and a legal address in | |
| 321 | +Sam notation (for example a line number or a regular expression delimited in | |
| 322 | +slashes or a comma-separated compound of such addresses), Acme highlights | |
| 323 | +the target of that address in the file and places the mouse there. One may jump to | |
| 324 | +line 27 of | |
| 325 | +.CW dat.h | |
| 326 | +by indicating with the right button the text | |
| 327 | +.CW dat.h:27 . | |
| 328 | +If the file is not already open, Acme loads it. | |
| 329 | +If the file name is null, for example if the indicated string is | |
| 330 | +.CW :/^main/ , | |
| 331 | +the file is assumed to be that of the window containing the string. | |
| 332 | +Such strings, when typed and evaluated in the tag of a window, amount to | |
| 333 | +context searches. | |
| 334 | +.PP | |
| 335 | +If the indicated text is not the name of an existing file, it is taken to be literal | |
| 336 | +text and is searched for in the body of the window containing the text, highlighting | |
| 337 | +the result as if it were the result of a context search. | |
| 338 | +.PP | |
| 339 | +For the rare occasion when a file name | |
| 340 | +.I is | |
| 341 | +just text to search for, it can be selected with the left button and used as the | |
| 342 | +argument to a built-in | |
| 343 | +.CW Look | |
| 344 | +command that always searches for literal text. | |
| 345 | +.SH | |
| 346 | +Nuances and heuristics | |
| 347 | +.PP | |
| 348 | +A user interface should not only provide the necessary functions, it should also | |
| 349 | +.I feel | |
| 350 | +right. | |
| 351 | +In fact, it should almost not be felt at all; when one notices a | |
| 352 | +user interface, one is distracted from the job at hand [Pike88]. | |
| 353 | +To approach this invisibility, some of Acme's properties and features | |
| 354 | +are there just to make the others easy to use. | |
| 355 | +Many are based on a fundamental principle of good design: | |
| 356 | +let the machine do the work. | |
| 357 | +.PP | |
| 358 | +Acme tries to avoid needless clicking and typing. | |
| 359 | +There is no `click-to-type', eliminating a button click. | |
| 360 | +There are no pop-up or pull-down menus, eliminating the mouse action needed to | |
| 361 | +make a menu appear. | |
| 362 | +The overall design is intended to make text on the screen useful without | |
| 363 | +copying or retyping; the ways in which this happens involve | |
| 364 | +the combination of many aspects of the interface. | |
| 365 | +.PP | |
| 366 | +Acme tiles its windows and places them automatically | |
| 367 | +to avoid asking the user to place and arrange them. | |
| 368 | +For this policy to succeed, the automatic placement must behave well enough | |
| 369 | +that the user is usually content with the location of a new window. | |
| 370 | +The system will never get it right all the time, but in practice most | |
| 371 | +windows are used at least for a while where Acme first places them. | |
| 372 | +There have been several complete rewrites of the | |
| 373 | +heuristics for placing a new window, | |
| 374 | +and with each rewrite the system became | |
| 375 | +noticeably more comfortable. The rules are as follows, although | |
| 376 | +they are still subject to improvement. | |
| 377 | +The window appears in the `active' column, that most recently used for typing or | |
| 378 | +selecting. | |
| 379 | +Executing and searching do not affect the choice of active column, | |
| 380 | +so windows of commands and such do not draw new windows towards them, | |
| 381 | +but rather let them form near the targets of their actions. | |
| 382 | +Output (error) windows always appear towards the right, away from | |
| 383 | +edited text, which is typically kept towards the left. | |
| 384 | +Within the column, several competing desires are balanced to decide where | |
| 385 | +and how large the window should be: | |
| 386 | +large blank spaces should be consumed; | |
| 387 | +existing text should remain visible; | |
| 388 | +existing large windows should be divided before small ones; | |
| 389 | +and the window should appear near the one containing the action that caused | |
| 390 | +its creation. | |
| 391 | +.PP | |
| 392 | +Acme binds some actions to chords of mouse buttons. | |
| 393 | +These include | |
| 394 | +.CW Cut | |
| 395 | +and | |
| 396 | +.CW Paste | |
| 397 | +so these common operations can be done without | |
| 398 | +moving the mouse. | |
| 399 | +Another is a way to apply a command in one window to text (often a file name) | |
| 400 | +in another, avoiding the actions needed to assemble the command textually. | |
| 401 | +.PP | |
| 402 | +Another way Acme avoids the need to move the mouse is instead to move the cursor | |
| 403 | +to where it is likely to be used next. When a new window is made, Acme | |
| 404 | +moves the cursor to the new window; in fact, to the selected text in that window. | |
| 405 | +When the user deletes a newly made window, the cursor is | |
| 406 | +returned to the point it was before the window was made, | |
| 407 | +reducing the irritation of windows that pop up to report annoying errors. | |
| 408 | +.PP | |
| 409 | +When a window is moved, Acme moves the cursor to the layout box in | |
| 410 | +its new place, to permit further adjustment without moving the mouse. | |
| 411 | +For example, when a click of the left mouse button on the layout box grows | |
| 412 | +the window, the cursor moves to the new location of the box so repeated clicks, | |
| 413 | +without moving the mouse, continue to grow it. | |
| 414 | +.PP | |
| 415 | +Another form of assistance the system can offer is to supply precision in | |
| 416 | +pointing the mouse. The best-known form of this is `double-clicking' to | |
| 417 | +select a word rather than carefully sweeping out the entire word. | |
| 418 | +Acme provides this feature, using context to decide whether to select | |
| 419 | +a word, line, quoted string, parenthesized expression, and so on. | |
| 420 | +But Acme takes the idea much further by applying it to execution | |
| 421 | +and searching. | |
| 422 | +A | |
| 423 | +.I single | |
| 424 | +click, that is, a null selection, with either the middle or right buttons, | |
| 425 | +is expanded automatically to indicate the appropriate text containing | |
| 426 | +the click. What is appropriate depends on the context. | |
| 427 | +.PP | |
| 428 | +For example, to execute a single-word command | |
| 429 | +such as | |
| 430 | +.CW Cut , | |
| 431 | +it is not necessary to sweep the entire word; just clicking the button once with | |
| 432 | +the mouse pointing at the word is sufficient. `Word' | |
| 433 | +means the largest string of likely file name characters surrounding the location | |
| 434 | +of the click: click on a file name, run that program. | |
| 435 | +On the right button, the rules are more complicated because | |
| 436 | +the target of the click might be a file name, file name with address, | |
| 437 | +or just plain text. Acme examines the text near the click to find | |
| 438 | +a likely file name; | |
| 439 | +if it finds one, it checks that it names an existing file (in the directory named in the tag, if the name is relative) | |
| 440 | +and if so, takes that as the result, after extending it with any address | |
| 441 | +that may be present. If there is no file with that name, Acme | |
| 442 | +just takes the largest alphanumeric string under the click. | |
| 443 | +The effect is a natural overloading of the button to refer to plain text as | |
| 444 | +well as file names. | |
| 445 | +.PP | |
| 446 | +First, though, if the click occurs over the left-button-selected text in the window, | |
| 447 | +that text is taken to be what is selected. | |
| 448 | +This makes it easy to skip through the occurrences of a string in a file: just click | |
| 449 | +the right button | |
| 450 | +on some occurrence of the text in the window (perhaps after typing it in the tag) | |
| 451 | +and click once for each subsequent occurrence. It isn't even necessary to move | |
| 452 | +the mouse between clicks; Acme does that. | |
| 453 | +To turn a complicated command into a sort of menu item, select it: | |
| 454 | +thereafter, clicking the middle button on it will execute the full command. | |
| 455 | +.PP | |
| 456 | +As an extra feature, Acme recognizes file names in angle brackets | |
| 457 | +.CW <> | |
| 458 | +as names of files in standard directories of include files, | |
| 459 | +making it possible for instance to look at | |
| 460 | +.CW <stdio.h> | |
| 461 | +with a single click. | |
| 462 | +.PP | |
| 463 | +Here's an example to demonstrate how the actions and defaults work together. | |
| 464 | +Assume | |
| 465 | +.CW /sys/src/cmd/sam/regexp.c | |
| 466 | +is | |
| 467 | +open and has been edited. We write it (execute | |
| 468 | +.CW Put | |
| 469 | +in the tag; once the file is written, Acme removes the word from the tag) | |
| 470 | +and type | |
| 471 | +.CW mk | |
| 472 | +in the tag. We execute | |
| 473 | +.CW mk | |
| 474 | +and get some errors, which appear in a new window labeled | |
| 475 | +.CW /sys/src/cmd/sam/+Errors . | |
| 476 | +The cursor moves automatically to that window. | |
| 477 | +Say the error is | |
| 478 | +.P1 | |
| 479 | +main.c:112: incompatible types on assignment to `pattern' | |
| 480 | +.P2 | |
| 481 | +We move the mouse slightly and click the right button | |
| 482 | +at the left of the error message; Acme | |
| 483 | +makes a new window, reads | |
| 484 | +.CW /sys/src/cmd/main.c | |
| 485 | +into it, selects line 112 | |
| 486 | +and places the mouse there, right on the offending line. | |
| 487 | +.SH | |
| 488 | +Coupling to existing programs | |
| 489 | +.PP | |
| 490 | +Acme's syntax for file names and addresses makes it easy for other programs | |
| 491 | +to connect automatically to Acme's capabilities. For example, the output of | |
| 492 | +.P1 | |
| 493 | +grep -n variable *.[ch] | |
| 494 | +.P2 | |
| 495 | +can be used to help Acme step through the occurrences of a variable in a program; | |
| 496 | +every line of output is potentially a command to open a file. | |
| 497 | +The file names need not be absolute, either: the output | |
| 498 | +appears in a window labeled with the directory in which | |
| 499 | +.CW grep | |
| 500 | +was run, from which Acme can derive the full path names. | |
| 501 | +.PP | |
| 502 | +When necessary, we have changed the output of some programs, | |
| 503 | +such as compiler error messages, to match | |
| 504 | +Acme's syntax. | |
| 505 | +Some might argue that it shouldn't be necessary to change old programs, | |
| 506 | +but sometimes programs need to be updated when systems change, | |
| 507 | +and consistent output benefits people as well as programs. | |
| 508 | +A historical example is the retrofitting of standard error output to the | |
| 509 | +early Unix programs when pipes were invented. | |
| 510 | +.PP | |
| 511 | +Another change was to record full path names in | |
| 512 | +the symbol table of executables, so line numbers reported by the debugger | |
| 513 | +are absolute names that may be used directly by Acme; it's not necessary | |
| 514 | +to run the debugger in the source directory. (This aids debugging | |
| 515 | +even without Acme.) | |
| 516 | +.PP | |
| 517 | +A related change was to add lines of the form | |
| 518 | +.P1 | |
| 519 | +#pragma src "/sys/src/libregexp" | |
| 520 | +.P2 | |
| 521 | +to header files; coupled with Acme's ability to locate a header file, | |
| 522 | +this provides a fast, keyboardless way to get the source associated with a library. | |
| 523 | +.PP | |
| 524 | +Finally, Acme directs the standard output of programs it runs to | |
| 525 | +windows labeled by the directory in which the program is run. | |
| 526 | +Acme's splitting of the | |
| 527 | +output into directory-labeled windows is a small feature that has a major effect: | |
| 528 | +local file names printed by programs can be interpreted directly by Acme. | |
| 529 | +By indirectly coupling the output of programs to the input, | |
| 530 | +it also simplifies the management of software that occupies multiple | |
| 531 | +directories. | |
| 532 | +.SH | |
| 533 | +Coupling to new programs | |
| 534 | +.PP | |
| 535 | +Like many Plan 9 programs, | |
| 536 | +Acme offers a programmable interface to | |
| 537 | +other programs by acting as a file server. | |
| 538 | +The best example of such a file server is the window system | |
| 539 | +.CW 8½ | |
| 540 | +[Pike91], | |
| 541 | +which exports files with names such as | |
| 542 | +.CW screen , | |
| 543 | +.CW cons , | |
| 544 | +and | |
| 545 | +.CW mouse | |
| 546 | +through which applications may access the I/O capabilities of the windows. | |
| 547 | +.CW 8½ | |
| 548 | +provides a | |
| 549 | +.I distinct | |
| 550 | +set of files for each window and builds a private file name space | |
| 551 | +for the clients running `in' each window; | |
| 552 | +clients in separate windows see distinct files with the same names | |
| 553 | +(for example | |
| 554 | +.CW /dev/mouse ). | |
| 555 | +Acme, like the process file system [PPTTW93], instead associates each | |
| 556 | +window with a directory of files; the files of each window are visible | |
| 557 | +to any application. | |
| 558 | +This difference reflects a difference in how the systems are used: | |
| 559 | +.CW 8½ | |
| 560 | +tells a client what keyboard and mouse activity has happened in its window; | |
| 561 | +Acme tells a client what changes that activity wrought on any window it asks about. | |
| 562 | +Putting it another way, | |
| 563 | +.CW 8½ | |
| 564 | +enables the construction of interactive applications; | |
| 565 | +Acme provides the interaction for applications. | |
| 566 | +.PP | |
| 567 | +The root of | |
| 568 | +Acme's file system is mounted using Plan 9 operations on the directory | |
| 569 | +.CW /mnt/acme . | |
| 570 | +In | |
| 571 | +that root directory appears a directory for each window, numbered with the window's identifier, | |
| 572 | +analogous to a process identifier, for example | |
| 573 | +.CW /mnt/acme/27 . | |
| 574 | +The window's directory | |
| 575 | +contains 6 files: | |
| 576 | +.CW /mnt/acme/27/addr , | |
| 577 | +.CW body , | |
| 578 | +.CW ctl , | |
| 579 | +.CW data , | |
| 580 | +.CW event , | |
| 581 | +and | |
| 582 | +.CW tag . | |
| 583 | +The | |
| 584 | +.CW body | |
| 585 | +and | |
| 586 | +.CW tag | |
| 587 | +files contain the text of the respective parts of the window; they may be | |
| 588 | +read to recover the contents. Data written to these files is appended to the text; | |
| 589 | +.CW seeks | |
| 590 | +are ignored. | |
| 591 | +The | |
| 592 | +.CW addr | |
| 593 | +and | |
| 594 | +.CW data | |
| 595 | +files provide random access to the contents of the body. | |
| 596 | +The | |
| 597 | +.CW addr | |
| 598 | +file is written to set a character position within the body; the | |
| 599 | +.CW data | |
| 600 | +file may then be read to recover the contents at that position, | |
| 601 | +or written to change them. | |
| 602 | +(The tag is assumed | |
| 603 | +small and special-purpose enough not to need special treatment. | |
| 604 | +Also, | |
| 605 | +.CW addr | |
| 606 | +indexes by character position, which is not the same as byte offset | |
| 607 | +in Plan 9's multi-byte character set [Pike93]). | |
| 608 | +The format accepted by the | |
| 609 | +.CW addr | |
| 610 | +file is exactly the syntax of addresses within the user interface, | |
| 611 | +permitting regular expressions, line numbers, and compound addresses | |
| 612 | +to be specified. For example, to replace the contents of lines 3 through 7, | |
| 613 | +write the text | |
| 614 | +.P1 | |
| 615 | +3,7 | |
| 616 | +.P2 | |
| 617 | +to the | |
| 618 | +.CW addr | |
| 619 | +file, then write the replacement text to the | |
| 620 | +.CW data | |
| 621 | +file. A zero-length write deletes the addressed text; further writes extend the replacement. | |
| 622 | +.PP | |
| 623 | +The control file, | |
| 624 | +.CW ctl , | |
| 625 | +may be written with commands to effect actions on the window; for example | |
| 626 | +the command | |
| 627 | +.P1 | |
| 628 | +name /adm/users | |
| 629 | +.P2 | |
| 630 | +sets the name in the tag of the window to | |
| 631 | +.CW /adm/users . | |
| 632 | +Other commands allow deleting the window, writing it to a file, and so on. | |
| 633 | +Reading the | |
| 634 | +.CW ctl | |
| 635 | +file recovers a fixed-format string containing 5 textual numbers\(emthe window | |
| 636 | +identifier, the number of characters in the tag, the number in the body, | |
| 637 | +and some status information\(emfollowed by the text of the tag, up to a newline. | |
| 638 | +.PP | |
| 639 | +The last file, | |
| 640 | +.CW event , | |
| 641 | +is the most unusual. | |
| 642 | +A program reading a window's | |
| 643 | +.CW event | |
| 644 | +file is notified of all changes to the text of the window, and | |
| 645 | +is asked to interpret all middle- and right-button actions. | |
| 646 | +The data passed to the program is fixed-format and reports | |
| 647 | +the source of the action (keyboard, mouse, external program, etc.), | |
| 648 | +its location (what was pointed at or modified), and its nature (change, | |
| 649 | +search, execution, etc.). | |
| 650 | +This message, for example, | |
| 651 | +.P1 | |
| 652 | +MI15 19 0 4 time | |
| 653 | +.P2 | |
| 654 | +reports that actions of the mouse | |
| 655 | +.CW M ) ( | |
| 656 | +inserted in the body (capital | |
| 657 | +.CW I ) | |
| 658 | +the 4 characters of | |
| 659 | +.CW time | |
| 660 | +at character positions 15 through 19; the zero is a flag word. | |
| 661 | +Programs may apply their own interpretations of searching and | |
| 662 | +execution, or may simply reflect the events back to Acme, | |
| 663 | +by writing them back to the | |
| 664 | +.CW event | |
| 665 | +file, to have the default interpretation applied. | |
| 666 | +Some examples of these ideas in action are presented below. | |
| 667 | +.PP | |
| 668 | +Notice that changes to the window are reported | |
| 669 | +after the fact; the program is told about them but is not required to act | |
| 670 | +on them. Compare this to a more traditional interface in which a program | |
| 671 | +is told, for example, that a character has been typed on the keyboard and | |
| 672 | +must then display and interpret it. | |
| 673 | +Acme's style stems from the basic model of the system, in which any | |
| 674 | +number of agents\(emthe keyboard, mouse, external programs | |
| 675 | +writing to | |
| 676 | +.CW data | |
| 677 | +or | |
| 678 | +.CW body , | |
| 679 | +and so on\(emmay | |
| 680 | +change the contents of a window. | |
| 681 | +The style is efficient: many programs are content | |
| 682 | +to have Acme do most of the work and act only when the editing is completed. | |
| 683 | +An example is the Acme mail program, which can ignore the changes | |
| 684 | +made to a message being composed | |
| 685 | +and just read its body when asked to send it. | |
| 686 | +A disadvantage is that some traditional ways of working are impossible. | |
| 687 | +For example, there is no way `to turn off echo': characters appear on the | |
| 688 | +screen and are read from there; no agent or buffer stands between | |
| 689 | +the keyboard and the display. | |
| 690 | +.PP | |
| 691 | +There are a couple of other files made available by Acme in its root directory | |
| 692 | +rather than in the directory of each window. | |
| 693 | +The text file | |
| 694 | +.CW /mnt/acme/index | |
| 695 | +holds a list of all window names and numerical identifiers, | |
| 696 | +somewhat analogous to the output of the | |
| 697 | +.CW ps | |
| 698 | +command for processes. | |
| 699 | +The most important, though, is | |
| 700 | +.CW /mnt/acme/new , | |
| 701 | +a directory that makes new windows, similar to the | |
| 702 | +.CW clone | |
| 703 | +directory in the Plan 9 network devices [Pres93]. | |
| 704 | +The act of opening any file in | |
| 705 | +.CW new | |
| 706 | +creates a new Acme window; thus the shell command | |
| 707 | +.P1 | |
| 708 | +grep -n var *.c > /mnt/acme/new/body | |
| 709 | +.P2 | |
| 710 | +places its output in the body of a fresh window. | |
| 711 | +More sophisticated applications may open | |
| 712 | +.CW new/ctl , | |
| 713 | +read it to discover the new window's identifier, and then | |
| 714 | +open the window's other files in the numbered directory. | |
| 715 | +.SH | |
| 716 | +Acme-specific programs | |
| 717 | +.PP | |
| 718 | +Although Acme is in part an attempt to move beyond typescripts, | |
| 719 | +they will probably always have utility. | |
| 720 | +The first program written for Acme was therefore one | |
| 721 | +to run a shell or other traditional interactive application | |
| 722 | +in a window, the Acme analog of | |
| 723 | +.CW xterm . | |
| 724 | +This program, | |
| 725 | +.CW win , | |
| 726 | +has a simple structure: | |
| 727 | +it acts as a two-way intermediary between Acme and the shell, | |
| 728 | +cross-connecting the standard input and output of the shell to the | |
| 729 | +text of the window. | |
| 730 | +The style of interaction is modeled after | |
| 731 | +.CW mux | |
| 732 | +[Pike88]: standard output is added to the window at the | |
| 733 | +.I "output point; | |
| 734 | +text typed after the output point | |
| 735 | +is made available on standard input when a newline is typed. | |
| 736 | +After either of these actions, the output point is advanced. | |
| 737 | +This is different from the working of a regular terminal, | |
| 738 | +permitting cut-and-paste editing of an input line until the newline is typed. | |
| 739 | +Arbitrary editing may be done to any text in the window. | |
| 740 | +The implementation of | |
| 741 | +.CW win , | |
| 742 | +using the | |
| 743 | +.CW event , | |
| 744 | +.CW addr , | |
| 745 | +and | |
| 746 | +.CW data | |
| 747 | +files, is straightforward. | |
| 748 | +.CW Win | |
| 749 | +needs no code for handling the keyboard and mouse; it just monitors the | |
| 750 | +contents of the window. Nonetheless, it allows Acme's full editing to be | |
| 751 | +applied to shell commands. | |
| 752 | +The division of labor between | |
| 753 | +.CW win | |
| 754 | +and | |
| 755 | +.CW Acme | |
| 756 | +contrasted with | |
| 757 | +.CW xterm | |
| 758 | +and the X server demonstrates how much work Acme handles automatically. | |
| 759 | +.CW Win | |
| 760 | +is implemented by a single source file 560 lines long and has no graphics code. | |
| 761 | +.PP | |
| 762 | +.CW Win | |
| 763 | +uses the middle and right buttons to connect itself in a consistent way | |
| 764 | +with the rest of Acme. | |
| 765 | +The middle button still executes commands, but in a style more suited | |
| 766 | +to typescripts. Text selected with the middle button is treated as if | |
| 767 | +it had been typed after the output point, much as a similar feature in | |
| 768 | +.CW xterm | |
| 769 | +or | |
| 770 | +.CW 8½ , | |
| 771 | +and therefore causes it to be `executed' by the application running in the window. | |
| 772 | +Right button actions are reflected back to Acme but refer to the appropriate | |
| 773 | +files because | |
| 774 | +.CW win | |
| 775 | +places the name of the current directory in the tag of the window. | |
| 776 | +If the shell is running, a simple shell function replacing the | |
| 777 | +.CW cd | |
| 778 | +command can maintain the tag as the shell navigates the file system. | |
| 779 | +This means, for example, that a right button click on a file mentioned in an | |
| 780 | +.CW ls | |
| 781 | +listing opens the file within Acme. | |
| 782 | +.PP | |
| 783 | +Another Acme-specific program is a mail reader that begins by presenting, | |
| 784 | +in a window, a listing of the messages in the user's mailbox, one per line. | |
| 785 | +Here the middle and right button actions are modified to refer to | |
| 786 | +mail commands | |
| 787 | +and messages, but the change feels natural. | |
| 788 | +Clicking the right button on a line creates a new window and displays the | |
| 789 | +message there, or, if it's already displayed, moves the mouse to that window. | |
| 790 | +The metaphor is that the mailbox is a directory whose constituent files are messages. | |
| 791 | +The mail program also places some relevant commands in the tag lines of | |
| 792 | +the windows; for example, executing the word | |
| 793 | +.CW Reply | |
| 794 | +in a message's tag creates a new window | |
| 795 | +in which to compose a message to the sender of the original; | |
| 796 | +.CW Post | |
| 797 | +then dispatches it. | |
| 798 | +In such windows, the addressee is just a list of names | |
| 799 | +on the first line of the body, which may be edited to add or change recipients. | |
| 800 | +The program also monitors the mailbox, updating the `directory' as new messages | |
| 801 | +arrive. | |
| 802 | +.PP | |
| 803 | +The mail program is as simple as it sounds; all the work of interaction, | |
| 804 | +editing, and management of the display is done by Acme. | |
| 805 | +The only | |
| 806 | +difficult sections of the 1200 | |
| 807 | +lines of code concern honoring the external protocols for managing | |
| 808 | +the mailbox and connecting to | |
| 809 | +.CW sendmail . | |
| 810 | +.PP | |
| 811 | +One of the things Acme does not provide directly is a facility like | |
| 812 | +Sam's command language to enable actions such as global substitution; | |
| 813 | +within Acme, all editing is done manually. | |
| 814 | +It is easy, though, to write external programs for such tasks. | |
| 815 | +In this, Acme comes closer to the original intent of Oberon: | |
| 816 | +a directory, | |
| 817 | +.CW /acme/edit , | |
| 818 | +contains a set of tools for repetitive editing and a template | |
| 819 | +or `guide' file that gives examples | |
| 820 | +of its use. | |
| 821 | +Acme's editing guide, | |
| 822 | +.CW /acme/edit/guide , | |
| 823 | +looks like this: | |
| 824 | +.P1 | |
| 825 | +e file | x '/regexp/' | c 'replacement' | |
| 826 | +e file:'0,$' | x '/.*word.*\en/' | p -n | |
| 827 | +e file | pipe command args ... | |
| 828 | +.P2 | |
| 829 | +The syntax is reminiscent of Sam's command language, but here the individual | |
| 830 | +one-letter commands are all stand-alone programs connected by pipes. | |
| 831 | +Passed along the pipes are addresses, analogous to structural expressions | |
| 832 | +in Sam terminology. | |
| 833 | +The | |
| 834 | +.CW e | |
| 835 | +command, unlike that of Sam, starts the process by generating the address | |
| 836 | +(default dot, the highlighted selection) in the named files. | |
| 837 | +The other commands are as in Sam: | |
| 838 | +.CW p | |
| 839 | +prints the addressed text on standard output (the | |
| 840 | +.CW -n | |
| 841 | +option is analogous to that of | |
| 842 | +.CW grep , | |
| 843 | +useful in combination with the right mouse button); | |
| 844 | +.CW x | |
| 845 | +matches a regular expression to the addressed (incoming) text, | |
| 846 | +subdividing the text; | |
| 847 | +.CW c | |
| 848 | +replaces the text; and so on. Thus, global substitution throughout a file, | |
| 849 | +which would be expressed in Sam as | |
| 850 | +.P1 | |
| 851 | +0,$ x/regexp/ c/replacement/ | |
| 852 | +.P2 | |
| 853 | +in Acme's editor becomes | |
| 854 | +.P1 | |
| 855 | +e 'file:0,$' | x '/regexp/' | c 'replacement' | |
| 856 | +.P2 | |
| 857 | +.PP | |
| 858 | +To use the Acme editing commands, open | |
| 859 | +.CW /acme/edit/guide , | |
| 860 | +use the mouse and keyboard to edit one of the commands to the right form, | |
| 861 | +and execute it with the middle button. | |
| 862 | +Acme's context rules find the appropriate binaries in | |
| 863 | +.CW /acme/edit | |
| 864 | +rather than | |
| 865 | +.CW /bin ; | |
| 866 | +the effect is to turn | |
| 867 | +.CW /acme/edit | |
| 868 | +into a toolbox containing tools and instructions (the guide file) for their use. | |
| 869 | +In fact, the source for these tools is also there, in the directory | |
| 870 | +.CW /acme/edit/src . | |
| 871 | +This setup allows some control of the file name space for binary programs; | |
| 872 | +not only does it group related programs, it permits the use of common | |
| 873 | +names for uncommon jobs. For example, the single-letter names would | |
| 874 | +be unwise in a directory in everyone's search path; here they are only | |
| 875 | +visible when running editing commands. | |
| 876 | +.PP | |
| 877 | +In Oberon, | |
| 878 | +such a collection would be called a | |
| 879 | +.I tool | |
| 880 | +and would consist | |
| 881 | +of a set of entry points in a module and a menu-like piece of text containing | |
| 882 | +representative commands that may be edited to suit and executed. | |
| 883 | +There is, in fact, a tool called | |
| 884 | +.CW Edit | |
| 885 | +in Oberon. | |
| 886 | +To provide related functionality, | |
| 887 | +Acme exploits the directory and file structure of the underlying | |
| 888 | +system, rather than the module structure of the language; | |
| 889 | +this fits well with Plan 9's | |
| 890 | +file-oriented philosophy. | |
| 891 | +Such tools are central to the working of Oberon but they are | |
| 892 | +less used in Acme, at least so far. | |
| 893 | +The main reason is probably that Acme's program interface permits | |
| 894 | +an external program to remain executing in the background, providing | |
| 895 | +its own commands as needed (for example, the | |
| 896 | +.CW Reply | |
| 897 | +command in the mail program); Oberon uses tools to | |
| 898 | +implement such services because its must invoke | |
| 899 | +a fresh program for each command. | |
| 900 | +Also, | |
| 901 | +Acme's better integration allows more | |
| 902 | +basic functions to be handled internally; the right mouse button | |
| 903 | +covers a lot of the basic utility of the editing tools in Oberon. | |
| 904 | +Nonetheless, as more applications are written for Acme, | |
| 905 | +many are sure to take this Oberon tool-like form. | |
| 906 | +.SH | |
| 907 | +Comparison with other systems | |
| 908 | +.PP | |
| 909 | +Acme's immediate ancestor is Help [Pike92], an experimental system written | |
| 910 | +a few years ago as a first try at exploring some of Oberon's ideas | |
| 911 | +in an existing operating system. | |
| 912 | +Besides much better engineering, Acme's advances over Help | |
| 913 | +include the actions of the right button (Help had nothing comparable), | |
| 914 | +the ability to connect long-running programs to the user interface | |
| 915 | +(Help had no analog of the | |
| 916 | +.CW event | |
| 917 | +file), | |
| 918 | +and the small but important change to split command output into | |
| 919 | +windows labeled with the directory in which the commands run. | |
| 920 | +.PP | |
| 921 | +Most of Acme's style, however, derives from the user interface and window | |
| 922 | +system of Oberon [Wirt89, Reis91]. | |
| 923 | +Oberon includes a programming language and operating system, | |
| 924 | +which Acme instead borrows from an existing system, Plan 9. | |
| 925 | +When I first saw Oberon, in 1988, I was struck by the | |
| 926 | +simplicity of its user interface, particularly its lack of menus | |
| 927 | +and its elegant use of multiple mouse buttons. | |
| 928 | +The system seemed restrictive, though\(emsingle process, | |
| 929 | +single language, no networking, event-driven programming\(emand | |
| 930 | +failed to follow through on some of its own ideas. | |
| 931 | +For example, the middle mouse button had to be pointed accurately and | |
| 932 | +the right button was essentially unused. | |
| 933 | +Acme does follow through: | |
| 934 | +to the basic idea planted by Oberon, it adds | |
| 935 | +the ability to run on different operating systems and hardware, | |
| 936 | +connection to existing applications including | |
| 937 | +interactive ones such as shells and debuggers, | |
| 938 | +support for multiple processes, | |
| 939 | +the right mouse button's features, | |
| 940 | +the default actions and context-dependent properties | |
| 941 | +of execution and searching, | |
| 942 | +and a host of little touches such as moving the mouse cursor that make the system | |
| 943 | +more pleasant. | |
| 944 | +At the moment, though, Oberon does have one distinct advantage: it incorporates | |
| 945 | +graphical programs well into its model, an issue Acme has not yet faced. | |
| 946 | +.PP | |
| 947 | +Acme shares with the Macintosh a desire to use the mouse well and it is | |
| 948 | +worth comparing the results. | |
| 949 | +The mouse on the Macintosh has a single button, so menus are essential | |
| 950 | +and the mouse must frequently move a long way | |
| 951 | +to reach the appropriate function. | |
| 952 | +An indication that this style has trouble is that applications provide | |
| 953 | +keyboard sequences to invoke menu selections and users often prefer them. | |
| 954 | +A deeper comparison is that the Macintosh uses pictures where Acme uses text. | |
| 955 | +In contrast to pictures, text can be edited quickly, created on demand, | |
| 956 | +and fine-tuned to the job at hand; consider adding an option to a command. | |
| 957 | +It is also self-referential; Acme doesn't need menus because any text can be | |
| 958 | +in effect a menu item. | |
| 959 | +The result is that, although a Macintosh screen is certainly prettier and probably | |
| 960 | +more attractive, especially to beginners, an Acme screen is more dynamic | |
| 961 | +and expressive, at least for programmers and experienced users. | |
| 962 | +.PP | |
| 963 | +For its role in the overall system, | |
| 964 | +Acme most resembles EMACS [Stal93]. | |
| 965 | +It is tricky to compare Acme to EMACS, though, because there are | |
| 966 | +many versions of EMACS and, since it is fully programmable, EMACS | |
| 967 | +can in principle do anything Acme does. | |
| 968 | +Also, Acme is much younger and therefore has not | |
| 969 | +had the time to acquire as many features. | |
| 970 | +The issue therefore is less what the systems can be programmed to do than | |
| 971 | +how they are used. | |
| 972 | +The EMACS versions that come closest to Acme's style are those that | |
| 973 | +have been extended to provide a programming environment, usually | |
| 974 | +for a language such as LISP [Alle92, Lucid92]. | |
| 975 | +For richness of the existing interface, these EMACS versions are certainly superior to Acme. | |
| 976 | +On the other hand, Acme's interface works equally well already for a variety | |
| 977 | +of languages; for example, one of its most enthusiastic users works almost | |
| 978 | +exclusively in Standard ML, a language nothing like C. | |
| 979 | +.PP | |
| 980 | +Where Acme excels is in the smoothness of its interface. | |
| 981 | +Until recently, EMACS did not support the mouse especially well, | |
| 982 | +and even with the latest version providing features such as `extents' | |
| 983 | +that can be programmed to behave much like Acme commands, | |
| 984 | +many users don't bother to upgrade. | |
| 985 | +Moreover, in the versions that provide extents, | |
| 986 | +most EMACS packages don't take advantage of them. | |
| 987 | +.PP | |
| 988 | +The most important distinction is just that | |
| 989 | +EMACS is fundamentally keyboard-based, while | |
| 990 | +Acme is mouse-based. | |
| 991 | +.PP | |
| 992 | +People who try Acme find it hard to go back to their previous environment. | |
| 993 | +Acme automates so much that to return to a traditional interface | |
| 994 | +is to draw attention to the extra work it requires. | |
| 995 | +.SH | |
| 996 | +Concurrency in the implementation | |
| 997 | +.PP | |
| 998 | +Acme is about 8,000 lines of code in Alef, a concurrent object-oriented language syntactically similar to C [Alef]. | |
| 999 | +Acme's structure is a set of communicating | |
| 1000 | +processes in a single address space. | |
| 1001 | +One subset of the processes drives the display and user interface, | |
| 1002 | +maintaining the windows; other processes forward mouse and keyboard | |
| 1003 | +activity and implement the file server interface for external programs. | |
| 1004 | +The language and design worked out well; | |
| 1005 | +as explained elsewhere [Pike89, Gans93, Reppy93], | |
| 1006 | +user interfaces built with concurrent systems | |
| 1007 | +can avoid the clumsy | |
| 1008 | +top-level event loop typical of traditional interactive systems. | |
| 1009 | +.PP | |
| 1010 | +An example of the benefits of the multi-process style | |
| 1011 | +is the management of the state of open | |
| 1012 | +files held by clients of the file system interface. | |
| 1013 | +The problem is that some I/O requests, | |
| 1014 | +such as reading the | |
| 1015 | +.CW event | |
| 1016 | +file, may block if no data is available, and the server must | |
| 1017 | +maintain the state of (possibly many) requests until data appears. | |
| 1018 | +For example, | |
| 1019 | +in | |
| 1020 | +.CW 8½ , | |
| 1021 | +a single-process window system written in C, pending requests were queued in | |
| 1022 | +a data structure associated with each window. | |
| 1023 | +After activity in the window that might complete pending I/O, | |
| 1024 | +the data structure was scanned for requests that could now finish. | |
| 1025 | +This structure did not fit well with the rest of the program and, worse, | |
| 1026 | +required meticulous effort | |
| 1027 | +to guarantee correct behavior under all conditions | |
| 1028 | +(consider raw mode, reads of partial lines, deleting a window, | |
| 1029 | +multibyte characters, etc.). | |
| 1030 | +.PP | |
| 1031 | +Acme instead creates a new dedicated process | |
| 1032 | +for each I/O request. | |
| 1033 | +This process coordinates with the rest of the system | |
| 1034 | +using Alef's synchronous communication; | |
| 1035 | +its state implicitly encodes the state of | |
| 1036 | +the I/O request and obviates the need for queuing. | |
| 1037 | +The passage of the request through Acme proceeds as follows. | |
| 1038 | +.PP | |
| 1039 | +Acme contains a file server process, F, that executes a | |
| 1040 | +.CW read | |
| 1041 | +system call to receive a Plan 9 file protocol (9P) message from the client [AT&T92]. | |
| 1042 | +The client blocks until Acme answers the request. | |
| 1043 | +F communicates with an allocation process, M, | |
| 1044 | +to acquire an object of type | |
| 1045 | +.CW Xfid | |
| 1046 | +(`executing fid'; fid is a 9P term) | |
| 1047 | +to hold the request. | |
| 1048 | +M sits in a loop (reproduced in Figure 2) waiting for either a request for | |
| 1049 | +a new | |
| 1050 | +.CW Xfid | |
| 1051 | +or notification that an existing one has finished its task. | |
| 1052 | +When an | |
| 1053 | +.CW Xfid | |
| 1054 | +is created, an associated process, X, | |
| 1055 | +is also made. | |
| 1056 | +M queues idle | |
| 1057 | +.CW Xfids , | |
| 1058 | +allocating new ones only when the list is empty. | |
| 1059 | +Thus, there is always a pool of | |
| 1060 | +.CW Xfids , | |
| 1061 | +some executing, some idle. | |
| 1062 | +.PP | |
| 1063 | +The | |
| 1064 | +.CW Xfid | |
| 1065 | +object contains a channel, | |
| 1066 | +.CW Xfid.c , | |
| 1067 | +for communication with its process; | |
| 1068 | +the unpacked message; and some associated functions, | |
| 1069 | +mostly corresponding to 9P messages such as | |
| 1070 | +.CW Xfid.write | |
| 1071 | +to handle a 9P write request. | |
| 1072 | +.PP | |
| 1073 | +The file server process F parses the message to see its nature\(emopen, | |
| 1074 | +close, read, write, etc. Many messages, such as directory | |
| 1075 | +lookups, can be handled immediately; these are responded to directly | |
| 1076 | +and efficiently | |
| 1077 | +by F without invoking the | |
| 1078 | +.CW Xfid , | |
| 1079 | +which is therefore maintained until the next message. | |
| 1080 | +When a message, such as a write to the display, requires the attention | |
| 1081 | +of the main display process and interlocked access to its data structures, | |
| 1082 | +F enables X | |
| 1083 | +by sending a function pointer on | |
| 1084 | +.CW Xfid.c . | |
| 1085 | +For example, if the message is a write, F executes | |
| 1086 | +.P1 | |
| 1087 | +x->c <-= Xfid.write; | |
| 1088 | +.P2 | |
| 1089 | +which sends | |
| 1090 | +the address of | |
| 1091 | +.CW Xfid.write | |
| 1092 | +on | |
| 1093 | +.CW Xfid.c , | |
| 1094 | +waking up X. | |
| 1095 | +.PP | |
| 1096 | +The | |
| 1097 | +.CW Xfid | |
| 1098 | +process, X, executes a simple loop: | |
| 1099 | +.P1 | |
| 1100 | +void | |
| 1101 | +Xfid.ctl(Xfid *x) | |
| 1102 | +{ | |
| 1103 | + for(;;){ | |
| 1104 | + (*<-x->c)(x); /* receive and execute message */ | |
| 1105 | + bflush(); /* synchronize bitmap display */ | |
| 1106 | + cxfidfree <-= x; /* return to free list */ | |
| 1107 | + } | |
| 1108 | +} | |
| 1109 | +.P2 | |
| 1110 | +Thus X | |
| 1111 | +will wake up with the address of a function to call (here | |
| 1112 | +.CW Xfid.write ) | |
| 1113 | +and execute it; once that completes, it returns itself to the pool of | |
| 1114 | +free processes by sending its address back to the allocator. | |
| 1115 | +.PP | |
| 1116 | +Although this sequence may seem complicated, it is just a few lines | |
| 1117 | +of code and is in fact far simpler | |
| 1118 | +than the management of the I/O queues in | |
| 1119 | +.CW 8½ . | |
| 1120 | +The hard work of synchronization is done by the Alef run time system. | |
| 1121 | +Moreover, the code worked the first time, which cannot be said for the code in | |
| 1122 | +.CW 8½ . | |
| 1123 | +.SH | |
| 1124 | +Undo | |
| 1125 | +.PP | |
| 1126 | +Acme provides a general undo facility like that of Sam, permitting | |
| 1127 | +textual changes to be unwound arbitrarily. | |
| 1128 | +The implementation is superior to Sam's, though, | |
| 1129 | +with much higher performance and the ability to `redo' changes. | |
| 1130 | +.PP | |
| 1131 | +Sam uses | |
| 1132 | +a multi-pass algorithm that builds | |
| 1133 | +a transcript of changes to be made simultaneously | |
| 1134 | +and then executes them atomically. | |
| 1135 | +This was thought necessary because the elements of a repetitive | |
| 1136 | +command such as a global substitution should all be applied to the same | |
| 1137 | +initial file and implemented simultaneously; forming the complete | |
| 1138 | +transcript before executing any of the changes avoids the | |
| 1139 | +cumbersome management of addresses in a changing file. | |
| 1140 | +Acme, however, doesn't have this problem; global substitution | |
| 1141 | +is controlled externally and may be made incrementally by exploiting | |
| 1142 | +an observation: if the changes are sorted in address order and | |
| 1143 | +executed in reverse, changes will not invalidate the addresses of | |
| 1144 | +pending changes. | |
| 1145 | +.PP | |
| 1146 | +Acme therefore avoids the initial transcript. Instead, changes are applied | |
| 1147 | +directly to the file, with an undo transcript recorded in a separate list. | |
| 1148 | +For example, when text is added to a window, it is added directly and a record | |
| 1149 | +of what to delete to restore the state is appended to the undo list. | |
| 1150 | +Each undo action and the file are marked with a sequence number; | |
| 1151 | +actions with the same sequence number are considered a unit | |
| 1152 | +to be undone together. | |
| 1153 | +The invariant state of the structure | |
| 1154 | +is that the last action in the undo list applies to the current state of the file, | |
| 1155 | +even if that action is one of a related set from, for example, a global substitute. | |
| 1156 | +(In Sam, a related set of actions needed to be undone simultaneously.) | |
| 1157 | +To undo an action, pop the last item on the undo list, apply it to the file, | |
| 1158 | +revert it, and append it to a second, redo list. | |
| 1159 | +To redo an action, do the identical operation with the lists interchanged. | |
| 1160 | +The expensive operations occur | |
| 1161 | +only when actually undoing; in normal editing the overhead is minor. | |
| 1162 | +For example, Acme reads files about seven times faster than Sam, partly | |
| 1163 | +because of this improvement and partly because of a cleaner implementation. | |
| 1164 | +.PP | |
| 1165 | +Acme uses a temporary file to hold the text, keeping in memory only the | |
| 1166 | +visible portion, and therefore can edit large files comfortably | |
| 1167 | +even on small-memory machines such as laptops. | |
| 1168 | +.SH | |
| 1169 | +Future | |
| 1170 | +.PP | |
| 1171 | +Acme is still under development. | |
| 1172 | +Some things are simply missing. | |
| 1173 | +For example, Acme should support non-textual graphics, but this is being | |
| 1174 | +deferred until it can be done using a new graphics model being developed | |
| 1175 | +for Plan 9. Also, it is undecided how Acme's style of interaction should best be | |
| 1176 | +extended to graphical applications. | |
| 1177 | +On a smaller scale, although the system feels smooth and comfortable, | |
| 1178 | +work continues to tune the heuristics and | |
| 1179 | +try new ideas for the user interface. | |
| 1180 | +.PP | |
| 1181 | +There need to be more programs that use Acme. Browsers for | |
| 1182 | +Usenet and AP News articles, the Oxford English Dictionary, and other | |
| 1183 | +such text sources exist, but more imaginative applications will | |
| 1184 | +be necessary to prove that Acme's approach is viable. | |
| 1185 | +One that has recently been started is an interface to the debugger Acid [Wint94], | |
| 1186 | +although it is still | |
| 1187 | +unclear what form it will ultimately take. | |
| 1188 | +.PP | |
| 1189 | +Acme shows that it is possible to make a user interface a stand-alone component | |
| 1190 | +of an interactive environment. By absorbing more of the interactive | |
| 1191 | +functionality than a simple window system, Acme off-loads much of the | |
| 1192 | +computation from its applications, which helps keep them small and | |
| 1193 | +consistent in their interface. Acme can afford to dedicate | |
| 1194 | +considerable effort to making that interface as good as possible; the result | |
| 1195 | +will benefit the entire system. | |
| 1196 | +.PP | |
| 1197 | +Acme is complete and useful enough to attract users. | |
| 1198 | +Its comfortable user interface, | |
| 1199 | +the ease with which it handles multiple tasks and | |
| 1200 | +programs in multiple directories, | |
| 1201 | +and its high level of integration | |
| 1202 | +make it addictive. | |
| 1203 | +Perhaps most telling, | |
| 1204 | +Acme shows that typescripts may not be the most | |
| 1205 | +productive interface to a time-sharing system. | |
| 1206 | +.SH | |
| 1207 | +Acknowledgements | |
| 1208 | +.PP | |
| 1209 | +Howard Trickey, Acme's first user, suffered buggy versions gracefully and made | |
| 1210 | +many helpful suggestions. Chris Fraser provided the necessary insight for the Acme editing | |
| 1211 | +commands. | |
| 1212 | +.SH | |
| 1213 | +References | |
| 1214 | +.LP | |
| 1215 | +[Alef] P. Winterbottom, | |
| 1216 | +``Alef Language Reference Manual'', | |
| 1217 | +.I | |
| 1218 | +Plan 9 Programmer's Manual, | |
| 1219 | +.R | |
| 1220 | +AT&T Bell Laboratories, | |
| 1221 | +Murray Hill, NJ, | |
| 1222 | +1992; | |
| 1223 | +revised in this volume. | |
| 1224 | +.br | |
| 1225 | +[Alle92] | |
| 1226 | +.I | |
| 1227 | +Allegro Common Lisp user Guide, Vol 2, | |
| 1228 | +.R | |
| 1229 | +Chapter 14, "The Emacs-Lisp Interface". | |
| 1230 | +March 1992. | |
| 1231 | +.br | |
| 1232 | +[AT&T92] Plan 9 Programmer's manual, Murray Hill, New Jersey, 1992. | |
| 1233 | +.br | |
| 1234 | +[Far89] Far too many people, XTERM(1), Massachusetts Institute of Technology, 1989. | |
| 1235 | +.br | |
| 1236 | +[Gans93] Emden R. Gansner and John H. Reppy, ``A Multi-threaded Higher-order User Interface Toolkit'', in | |
| 1237 | +.I | |
| 1238 | +Software Trends, Volume 1, | |
| 1239 | +User Interface Software, | |
| 1240 | +.R | |
| 1241 | +Bass and Dewan (Eds.), | |
| 1242 | +John Wiley & Sons 1993, | |
| 1243 | +pp. 61-80. | |
| 1244 | +.br | |
| 1245 | +[Lucid92] Richard Stallman and Lucid, Inc., | |
| 1246 | +.I | |
| 1247 | +Lucid GNU EMACS Manual, | |
| 1248 | +.R | |
| 1249 | +March 1992. | |
| 1250 | +.br | |
| 1251 | +[Pike87] Rob Pike, ``The Text Editor \f(CWsam\fP'', Softw. - Pract. and Exp., Nov 1987, Vol 17 #11, pp. 813-845; reprinted in this volume. | |
| 1252 | +.br | |
| 1253 | +[Pike88] Rob Pike, ``Window Systems Should Be Transparent'', Comp. Sys., Summer 1988, Vol 1 #3, pp. 279-296. | |
| 1254 | +.br | |
| 1255 | +[Pike89] Rob Pike, ``A Concurrent Window System'', Comp. Sys., Spring 1989, Vol 2 #2, pp. 133-153. | |
| 1256 | +.br | |
| 1257 | +[PPTTW93] Rob Pike, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom, ``The Use of Name Spaces in Plan 9'', | |
| 1258 | +Op. Sys. Rev., Vol. 27, No. 2, April 1993, pp. 72-76, | |
| 1259 | +reprinted in this volume. | |
| 1260 | +.br | |
| 1261 | +[Pike91] Rob Pike, ``8½, the Plan 9 Window System'', USENIX Summer Conf. Proc., Nashville, June, 1991, pp. 257-265, | |
| 1262 | +reprinted in this volume. | |
| 1263 | +.br | |
| 1264 | +[Pike92] Rob Pike, ``A Minimalist Global User Interface'', Graphics Interface '92 Proc., Vancouver, 1992, pp. 282-293. An earlier version appeared under the same title in USENIX Summer Conf. Proc., Nashville, June, 1991, pp. 267-279. | |
| 1265 | +.br | |
| 1266 | +[Pike93] Rob Pike and Ken Thompson, ``Hello World or Καλημέρα κόσμε or | |
| 1267 | +\f(Jpこんにちは 世界\fP'', USENIX Winter Conf. Proc., San Diego, 1993, pp. 43-50, | |
| 1268 | +reprinted in this volume. | |
| 1269 | +.br | |
| 1270 | +[Pres93] Dave Presotto and Phil Winterbottom, ``The Organization of Networks in Plan 9'', Proc. Usenix Winter 1993, pp. 271-287, San Diego, CA, | |
| 1271 | +reprinted in this volume. | |
| 1272 | +.br | |
| 1273 | +[Reis91] Martin Reiser, \fIThe Oberon System,\fP Addison Wesley, New York, 1991. | |
| 1274 | +.br | |
| 1275 | +[Reppy93] John H. Reppy, | |
| 1276 | +``CML: A higher-order concurrent language'', Proc. SIGPLAN'91 Conf. on Programming, Lang. Design and Impl., June, 1991, pp. 293-305. | |
| 1277 | +.br | |
| 1278 | +[Sche86] Robert W. Scheifler and Jim Gettys, | |
| 1279 | +``The X Window System'', | |
| 1280 | +ACM Trans. on Graph., Vol 5 #2, pp. 79-109. | |
| 1281 | +.br | |
| 1282 | +[Stal93] Richard Stallman, | |
| 1283 | +.I | |
| 1284 | +Gnu Emacs Manual, 9th edition, Emacs version 19.19, | |
| 1285 | +.R | |
| 1286 | +MIT. | |
| 1287 | +.br | |
| 1288 | +[Swei86] Daniel Sweinhart, Polle Zellweger, Richard Beach, and Robert Hagmann, | |
| 1289 | +``A Structural View of the Cedar Programming Environment'', | |
| 1290 | +ACM Trans. Prog. Lang. and Sys., Vol. 8, No. 4, pp. 419-490, Oct. 1986. | |
| 1291 | +.br | |
| 1292 | +[Wint94], Philip Winterbottom, ``Acid: A Debugger based on a Language'', USENIX Winter Conf. Proc., San Francisco, CA, 1993, | |
| 1293 | +reprinted in this volume. | |
| 1294 | +.br | |
| 1295 | +[Wirt89] N. Wirth and J. Gutknecht, ``The Oberon System'', Softw. - Prac. and Exp., Sep 1989, Vol 19 #9, pp 857-894. | |
Binary file not shown.
| @@ -0,0 +1,1394 @@ | ||
| 1 | +.ft CW | |
| 2 | +.ta 8n +8n +8n +8n +8n +8n +8n | |
| 3 | +.ft | |
| 4 | +.TL | |
| 5 | +A Manual for the Plan 9 assembler | |
| 6 | +.AU | |
| 7 | +.I "Rob Pike" | |
| 8 | +.AI | |
| 9 | +rob@plan9.bell-labs.com | |
| 10 | +.SH | |
| 11 | +Machines | |
| 12 | +.PP | |
| 13 | +There is an assembler for each of the MIPS, SPARC, Intel 386, | |
| 14 | +Motorola 68020 and 68000, IBM Power PC, DEC Alpha, and ARM. | |
| 15 | +The 68020 assembler, | |
| 16 | +.CW 2a , | |
| 17 | +is the oldest and in many ways the prototype. | |
| 18 | +The assemblers are really just variations of a single program: | |
| 19 | +they share many properties such as left-to-right assignment order for | |
| 20 | +instruction operands and the synthesis of macro instructions | |
| 21 | +such as | |
| 22 | +.CW MOVE | |
| 23 | +to hide the peculiarities of the load and store structure of the machines. | |
| 24 | +To keep things concrete, the first part of this manual is | |
| 25 | +specifically about the 68020. | |
| 26 | +At the end is a description of the differences among | |
| 27 | +the other assemblers. | |
| 28 | +.ig | |
| 29 | +.PP | |
| 30 | +The document, ``How to Use the Plan 9 C Compiler'', by Rob Pike, | |
| 31 | +is a prerequisite for this manual. | |
| 32 | +.. | |
| 33 | +.SH | |
| 34 | +Registers | |
| 35 | +.PP | |
| 36 | +All pre-defined symbols in the assembler are upper-case. | |
| 37 | +Data registers are | |
| 38 | +.CW R0 | |
| 39 | +through | |
| 40 | +.CW R7 ; | |
| 41 | +address registers are | |
| 42 | +.CW A0 | |
| 43 | +through | |
| 44 | +.CW A7 ; | |
| 45 | +floating-point registers are | |
| 46 | +.CW F0 | |
| 47 | +through | |
| 48 | +.CW F7 . | |
| 49 | +.PP | |
| 50 | +A pointer in | |
| 51 | +.CW A6 | |
| 52 | +is used by the C compiler to point to data, enabling short addresses to | |
| 53 | +be used more often. | |
| 54 | +The value of | |
| 55 | +.CW A6 | |
| 56 | +is constant and must be set during C program initialization | |
| 57 | +to the address of the externally-defined symbol | |
| 58 | +.CW a6base . | |
| 59 | +.PP | |
| 60 | +The following hardware registers are defined in the assembler; their | |
| 61 | +meaning should be obvious given a 68020 manual: | |
| 62 | +.CW CAAR , | |
| 63 | +.CW CACR , | |
| 64 | +.CW CCR , | |
| 65 | +.CW DFC , | |
| 66 | +.CW ISP , | |
| 67 | +.CW MSP , | |
| 68 | +.CW SFC , | |
| 69 | +.CW SR , | |
| 70 | +.CW USP , | |
| 71 | +and | |
| 72 | +.CW VBR . | |
| 73 | +.PP | |
| 74 | +The assembler also defines several pseudo-registers that | |
| 75 | +manipulate the stack: | |
| 76 | +.CW FP , | |
| 77 | +.CW SP , | |
| 78 | +and | |
| 79 | +.CW TOS . | |
| 80 | +.CW FP | |
| 81 | +is the frame pointer, so | |
| 82 | +.CW 0(FP) | |
| 83 | +is the first argument, | |
| 84 | +.CW 4(FP) | |
| 85 | +is the second, and so on. | |
| 86 | +.CW SP | |
| 87 | +is the local stack pointer, where automatic variables are held | |
| 88 | +(SP is a pseudo-register only on the 68020); | |
| 89 | +.CW 0(SP) | |
| 90 | +is the first automatic, and so on as with | |
| 91 | +.CW FP . | |
| 92 | +Finally, | |
| 93 | +.CW TOS | |
| 94 | +is the top-of-stack register, used for pushing parameters to procedures, | |
| 95 | +saving temporary values, and so on. | |
| 96 | +.PP | |
| 97 | +The assembler and loader track these pseudo-registers so | |
| 98 | +the above statements are true regardless of what has been | |
| 99 | +pushed on the hardware stack, pointed to by | |
| 100 | +.CW A7 . | |
| 101 | +The name | |
| 102 | +.CW A7 | |
| 103 | +refers to the hardware stack pointer, but beware of mixed use of | |
| 104 | +.CW A7 | |
| 105 | +and the above stack-related pseudo-registers, which will cause trouble. | |
| 106 | +Note, too, that the | |
| 107 | +.CW PEA | |
| 108 | +instruction is observed by the loader to | |
| 109 | +alter SP and thus will insert a corresponding pop before all returns. | |
| 110 | +The assembler accepts a label-like name to be attached to | |
| 111 | +.CW FP | |
| 112 | +and | |
| 113 | +.CW SP | |
| 114 | +uses, such as | |
| 115 | +.CW p+0(FP) , | |
| 116 | +to help document that | |
| 117 | +.CW p | |
| 118 | +is the first argument to a routine. | |
| 119 | +The name goes in the symbol table but has no significance to the result | |
| 120 | +of the program. | |
| 121 | +.SH | |
| 122 | +Referring to data | |
| 123 | +.PP | |
| 124 | +All external references must be made relative to some pseudo-register, | |
| 125 | +either | |
| 126 | +.CW PC | |
| 127 | +(the virtual program counter) or | |
| 128 | +.CW SB | |
| 129 | +(the ``static base'' register). | |
| 130 | +.CW PC | |
| 131 | +counts instructions, not bytes of data. | |
| 132 | +For example, to branch to the second following instruction, that is, | |
| 133 | +to skip one instruction, one may write | |
| 134 | +.P1 | |
| 135 | + BRA 2(PC) | |
| 136 | +.P2 | |
| 137 | +Labels are also allowed, as in | |
| 138 | +.P1 | |
| 139 | + BRA return | |
| 140 | + NOP | |
| 141 | +return: | |
| 142 | + RTS | |
| 143 | +.P2 | |
| 144 | +When using labels, there is no | |
| 145 | +.CW (PC) | |
| 146 | +annotation. | |
| 147 | +.PP | |
| 148 | +The pseudo-register | |
| 149 | +.CW SB | |
| 150 | +refers to the beginning of the address space of the program. | |
| 151 | +Thus, references to global data and procedures are written as | |
| 152 | +offsets to | |
| 153 | +.CW SB , | |
| 154 | +as in | |
| 155 | +.P1 | |
| 156 | + MOVL $array(SB), TOS | |
| 157 | +.P2 | |
| 158 | +to push the address of a global array on the stack, or | |
| 159 | +.P1 | |
| 160 | + MOVL array+4(SB), TOS | |
| 161 | +.P2 | |
| 162 | +to push the second (4-byte) element of the array. | |
| 163 | +Note the use of an offset; the complete list of addressing modes is given below. | |
| 164 | +Similarly, subroutine calls must use | |
| 165 | +.CW SB : | |
| 166 | +.P1 | |
| 167 | + BSR exit(SB) | |
| 168 | +.P2 | |
| 169 | +File-static variables have syntax | |
| 170 | +.P1 | |
| 171 | + local<>+4(SB) | |
| 172 | +.P2 | |
| 173 | +The | |
| 174 | +.CW <> | |
| 175 | +will be filled in at load time by a unique integer. | |
| 176 | +.PP | |
| 177 | +When a program starts, it must execute | |
| 178 | +.P1 | |
| 179 | + MOVL $a6base(SB), A6 | |
| 180 | +.P2 | |
| 181 | +before accessing any global data. | |
| 182 | +(On machines such as the MIPS and SPARC that cannot load a register | |
| 183 | +in a single instruction, constants are loaded through the static base | |
| 184 | +register. The loader recognizes code that initializes the static | |
| 185 | +base register and treats it specially. You must be careful, however, | |
| 186 | +not to load large constants on such machines when the static base | |
| 187 | +register is not set up, such as early in interrupt routines.) | |
| 188 | +.SH | |
| 189 | +Expressions | |
| 190 | +.PP | |
| 191 | +Expressions are mostly what one might expect. | |
| 192 | +Where an offset or a constant is expected, | |
| 193 | +a primary expression with unary operators is allowed. | |
| 194 | +A general C constant expression is allowed in parentheses. | |
| 195 | +.PP | |
| 196 | +Source files are preprocessed exactly as in the C compiler, so | |
| 197 | +.CW #define | |
| 198 | +and | |
| 199 | +.CW #include | |
| 200 | +work. | |
| 201 | +.SH | |
| 202 | +Addressing modes | |
| 203 | +.PP | |
| 204 | +The simple addressing modes are shared by all the assemblers. | |
| 205 | +Here, for completeness, follows a table of all the 68020 addressing modes, | |
| 206 | +since that machine has the richest set. | |
| 207 | +In the table, | |
| 208 | +.CW o | |
| 209 | +is an offset, which if zero may be elided, and | |
| 210 | +.CW d | |
| 211 | +is a displacement, which is a constant between -128 and 127 inclusive. | |
| 212 | +Many of the modes listed have the same name; | |
| 213 | +scrutiny of the format will show what default is being applied. | |
| 214 | +For instance, indexed mode with no address register supplied operates | |
| 215 | +as though a zero-valued register were used. | |
| 216 | +For "offset" read "displacement." | |
| 217 | +For "\f(CW.s\fP" read one of | |
| 218 | +.CW .L , | |
| 219 | +or | |
| 220 | +.CW .W | |
| 221 | +followed by | |
| 222 | +.CW *1 , | |
| 223 | +.CW *2 , | |
| 224 | +.CW *4 , | |
| 225 | +or | |
| 226 | +.CW *8 | |
| 227 | +to indicate the size and scaling of the data. | |
| 228 | +.IP | |
| 229 | +.TS | |
| 230 | +l lfCW. | |
| 231 | +data register R0 | |
| 232 | +address register A0 | |
| 233 | +floating-point register F0 | |
| 234 | +special names CAAR, CACR, etc. | |
| 235 | +constant $con | |
| 236 | +floating point constant $fcon | |
| 237 | +external symbol name+o(SB) | |
| 238 | +local symbol name<>+o(SB) | |
| 239 | +automatic symbol name+o(SP) | |
| 240 | +argument name+o(FP) | |
| 241 | +address of external $name+o(SB) | |
| 242 | +address of local $name<>+o(SB) | |
| 243 | +indirect post-increment (A0)+ | |
| 244 | +indirect pre-decrement -(A0) | |
| 245 | +indirect with offset o(A0) | |
| 246 | +indexed with offset o()(R0.s) | |
| 247 | +indexed with offset o(A0)(R0.s) | |
| 248 | +external indexed name+o(SB)(R0.s) | |
| 249 | +local indexed name<>+o(SB)(R0.s) | |
| 250 | +automatic indexed name+o(SP)(R0.s) | |
| 251 | +parameter indexed name+o(FP)(R0.s) | |
| 252 | +offset indirect post-indexed d(o())(R0.s) | |
| 253 | +offset indirect post-indexed d(o(A0))(R0.s) | |
| 254 | +external indirect post-indexed d(name+o(SB))(R0.s) | |
| 255 | +local indirect post-indexed d(name<>+o(SB))(R0.s) | |
| 256 | +automatic indirect post-indexed d(name+o(SP))(R0.s) | |
| 257 | +parameter indirect post-indexed d(name+o(FP))(R0.s) | |
| 258 | +offset indirect pre-indexed d(o()(R0.s)) | |
| 259 | +offset indirect pre-indexed d(o(A0)) | |
| 260 | +offset indirect pre-indexed d(o(A0)(R0.s)) | |
| 261 | +external indirect pre-indexed d(name+o(SB)) | |
| 262 | +external indirect pre-indexed d(name+o(SB)(R0.s)) | |
| 263 | +local indirect pre-indexed d(name<>+o(SB)) | |
| 264 | +local indirect pre-indexed d(name<>+o(SB)(R0.s)) | |
| 265 | +automatic indirect pre-indexed d(name+o(SP)) | |
| 266 | +automatic indirect pre-indexed d(name+o(SP)(R0.s)) | |
| 267 | +parameter indirect pre-indexed d(name+o(FP)) | |
| 268 | +parameter indirect pre-indexed d(name+o(FP)(R0.s)) | |
| 269 | +.TE | |
| 270 | +.in | |
| 271 | +.SH | |
| 272 | +Laying down data | |
| 273 | +.PP | |
| 274 | +Placing data in the instruction stream, say for interrupt vectors, is easy: | |
| 275 | +the pseudo-instructions | |
| 276 | +.CW LONG | |
| 277 | +and | |
| 278 | +.CW WORD | |
| 279 | +(but not | |
| 280 | +.CW BYTE ) | |
| 281 | +lay down the value of their single argument, of the appropriate size, | |
| 282 | +as if it were an instruction: | |
| 283 | +.P1 | |
| 284 | + LONG $12345 | |
| 285 | +.P2 | |
| 286 | +places the long 12345 (base 10) | |
| 287 | +in the instruction stream. | |
| 288 | +(On most machines, | |
| 289 | +the only such operator is | |
| 290 | +.CW WORD | |
| 291 | +and it lays down 32-bit quantities. | |
| 292 | +The 386 has all three: | |
| 293 | +.CW LONG , | |
| 294 | +.CW WORD , | |
| 295 | +and | |
| 296 | +.CW BYTE . | |
| 297 | +The AMD64 adds | |
| 298 | +.CW QUAD | |
| 299 | +for 64-bit values.) | |
| 300 | +.PP | |
| 301 | +Placing information in the data section is more painful. | |
| 302 | +The pseudo-instruction | |
| 303 | +.CW DATA | |
| 304 | +does the work, given two arguments: an address at which to place the item, | |
| 305 | +including its size, | |
| 306 | +and the value to place there. For example, to define a character array | |
| 307 | +.CW array | |
| 308 | +containing the characters | |
| 309 | +.CW abc | |
| 310 | +and a terminating null: | |
| 311 | +.P1 | |
| 312 | + DATA array+0(SB)/1, $'a' | |
| 313 | + DATA array+1(SB)/1, $'b' | |
| 314 | + DATA array+2(SB)/1, $'c' | |
| 315 | + GLOBL array(SB), $4 | |
| 316 | +.P2 | |
| 317 | +or | |
| 318 | +.P1 | |
| 319 | + DATA array+0(SB)/4, $"abc\ez" | |
| 320 | + GLOBL array(SB), $4 | |
| 321 | +.P2 | |
| 322 | +The | |
| 323 | +.CW /1 | |
| 324 | +defines the number of bytes to define, | |
| 325 | +.CW GLOBL | |
| 326 | +makes the symbol global, and the | |
| 327 | +.CW $4 | |
| 328 | +says how many bytes the symbol occupies. | |
| 329 | +Uninitialized data is zeroed automatically. | |
| 330 | +The character | |
| 331 | +.CW \ez | |
| 332 | +is equivalent to the C | |
| 333 | +.CW \e0. | |
| 334 | +The string in a | |
| 335 | +.CW DATA | |
| 336 | +statement may contain a maximum of eight bytes; | |
| 337 | +build larger strings piecewise. | |
| 338 | +Two pseudo-instructions, | |
| 339 | +.CW DYNT | |
| 340 | +and | |
| 341 | +.CW INIT , | |
| 342 | +allow the (obsolete) Alef compilers to build dynamic type information during the load | |
| 343 | +phase. | |
| 344 | +The | |
| 345 | +.CW DYNT | |
| 346 | +pseudo-instruction has two forms: | |
| 347 | +.P1 | |
| 348 | + DYNT , ALEF_SI_5+0(SB) | |
| 349 | + DYNT ALEF_AS+0(SB), ALEF_SI_5+0(SB) | |
| 350 | +.P2 | |
| 351 | +In the first form, | |
| 352 | +.CW DYNT | |
| 353 | +defines the symbol to be a small unique integer constant, chosen by the loader, | |
| 354 | +which is some multiple of the word size. In the second form, | |
| 355 | +.CW DYNT | |
| 356 | +defines the second symbol in the same way, | |
| 357 | +places the address of the most recently | |
| 358 | +defined text symbol in the array specified by the first symbol at the | |
| 359 | +index defined by the value of the second symbol, | |
| 360 | +and then adjusts the size of the array accordingly. | |
| 361 | +.PP | |
| 362 | +The | |
| 363 | +.CW INIT | |
| 364 | +pseudo-instruction takes the same parameters as a | |
| 365 | +.CW DATA | |
| 366 | +statement. Its symbol is used as the base of an array and the | |
| 367 | +data item is installed in the array at the offset specified by the most recent | |
| 368 | +.CW DYNT | |
| 369 | +pseudo-instruction. | |
| 370 | +The size of the array is adjusted accordingly. | |
| 371 | +The | |
| 372 | +.CW DYNT | |
| 373 | +and | |
| 374 | +.CW INIT | |
| 375 | +pseudo-instructions are not implemented on the 68020. | |
| 376 | +.SH | |
| 377 | +Defining a procedure | |
| 378 | +.PP | |
| 379 | +Entry points are defined by the pseudo-operation | |
| 380 | +.CW TEXT , | |
| 381 | +which takes as arguments the name of the procedure (including the ubiquitous | |
| 382 | +.CW (SB) ) | |
| 383 | +and the number of bytes of automatic storage to pre-allocate on the stack, | |
| 384 | +which will usually be zero when writing assembly language programs. | |
| 385 | +On machines with a link register, such as the MIPS and SPARC, | |
| 386 | +the special value -4 instructs the loader to generate no PC save | |
| 387 | +and restore instructions, even if the function is not a leaf. | |
| 388 | +Here is a complete procedure that returns the sum | |
| 389 | +of its two arguments: | |
| 390 | +.P1 | |
| 391 | +TEXT sum(SB), $0 | |
| 392 | + MOVL arg1+0(FP), R0 | |
| 393 | + ADDL arg2+4(FP), R0 | |
| 394 | + RTS | |
| 395 | +.P2 | |
| 396 | +An optional middle argument | |
| 397 | +to the | |
| 398 | +.CW TEXT | |
| 399 | +pseudo-op is a bit field of options to the loader. | |
| 400 | +Setting the 1 bit suspends profiling the function when profiling is enabled for the rest of | |
| 401 | +the program. | |
| 402 | +For example, | |
| 403 | +.P1 | |
| 404 | +TEXT sum(SB), 1, $0 | |
| 405 | + MOVL arg1+0(FP), R0 | |
| 406 | + ADDL arg2+4(FP), R0 | |
| 407 | + RTS | |
| 408 | +.P2 | |
| 409 | +will not be profiled; the first version above would be. | |
| 410 | +Subroutines with peculiar state, such as system call routines, | |
| 411 | +should not be profiled. | |
| 412 | +.PP | |
| 413 | +Setting the 2 bit allows multiple definitions of the same | |
| 414 | +.CW TEXT | |
| 415 | +symbol in a program; the loader will place only one such function in the image. | |
| 416 | +It was emitted only by the Alef compilers. | |
| 417 | +.PP | |
| 418 | +Subroutines to be called from C should place their result in | |
| 419 | +.CW R0 , | |
| 420 | +even if it is an address. | |
| 421 | +Floating point values are returned in | |
| 422 | +.CW F0 . | |
| 423 | +Functions that return a structure to a C program | |
| 424 | +receive as their first argument the address of the location to | |
| 425 | +store the result; | |
| 426 | +.CW R0 | |
| 427 | +is unused in the calling protocol for such procedures. | |
| 428 | +A subroutine is responsible for saving its own registers, | |
| 429 | +and therefore is free to use any registers without saving them (``caller saves''). | |
| 430 | +.CW A6 | |
| 431 | +and | |
| 432 | +.CW A7 | |
| 433 | +are the exceptions as described above. | |
| 434 | +.SH | |
| 435 | +When in doubt | |
| 436 | +.PP | |
| 437 | +If you get confused, try using the | |
| 438 | +.CW -S | |
| 439 | +option to | |
| 440 | +.CW 2c | |
| 441 | +and compiling a sample program. | |
| 442 | +The standard output is valid input to the assembler. | |
| 443 | +.SH | |
| 444 | +Instructions | |
| 445 | +.PP | |
| 446 | +The instruction set of the assembler is not identical to that | |
| 447 | +of the machine. | |
| 448 | +It is chosen to match what the compiler generates, augmented | |
| 449 | +slightly by specific needs of the operating system. | |
| 450 | +For example, | |
| 451 | +.CW 2a | |
| 452 | +does not distinguish between the various forms of | |
| 453 | +.CW MOVE | |
| 454 | +instruction: move quick, move address, etc. Instead the context | |
| 455 | +does the job. For example, | |
| 456 | +.P1 | |
| 457 | + MOVL $1, R1 | |
| 458 | + MOVL A0, R2 | |
| 459 | + MOVW SR, R3 | |
| 460 | +.P2 | |
| 461 | +generates official | |
| 462 | +.CW MOVEQ , | |
| 463 | +.CW MOVEA , | |
| 464 | +and | |
| 465 | +.CW MOVESR | |
| 466 | +instructions. | |
| 467 | +A number of instructions do not have the syntax necessary to specify | |
| 468 | +their entire capabilities. Notable examples are the bitfield | |
| 469 | +instructions, the | |
| 470 | +multiply and divide instructions, etc. | |
| 471 | +For a complete set of generated instruction names (in | |
| 472 | +.CW 2a | |
| 473 | +notation, not Motorola's) see the file | |
| 474 | +.CW /sys/src/cmd/2c/2.out.h . | |
| 475 | +Despite its name, this file contains an enumeration of the | |
| 476 | +instructions that appear in the intermediate files generated | |
| 477 | +by the compiler, which correspond exactly to lines of assembly language. | |
| 478 | +.PP | |
| 479 | +The MC68000 assembler, | |
| 480 | +.CW 1a , | |
| 481 | +is essentially the same, honoring the appropriate subset of the instructions | |
| 482 | +and addressing modes. | |
| 483 | +The definitions of these are, nonetheless, part of | |
| 484 | +.CW 2.out.h . | |
| 485 | +.SH | |
| 486 | +Laying down instructions | |
| 487 | +.PP | |
| 488 | +The loader modifies the code produced by the assembler and compiler. | |
| 489 | +It folds branches, | |
| 490 | +copies short sequences of code to eliminate branches, | |
| 491 | +and discards unreachable code. | |
| 492 | +The first instruction of every function is assumed to be reachable. | |
| 493 | +The pseudo-instruction | |
| 494 | +.CW NOP , | |
| 495 | +which you may see in compiler output, | |
| 496 | +means no instruction at all, rather than an instruction that does nothing. | |
| 497 | +The loader discards all | |
| 498 | +.CW NOP 's. | |
| 499 | +.PP | |
| 500 | +To generate a true | |
| 501 | +.CW NOP | |
| 502 | +instruction, or any other instruction not known to the assembler, use a | |
| 503 | +.CW WORD | |
| 504 | +pseudo-instruction. | |
| 505 | +Such instructions on RISCs are not scheduled by the loader and must have | |
| 506 | +their delay slots filled manually. | |
| 507 | +.SH | |
| 508 | +MIPS | |
| 509 | +.PP | |
| 510 | +The registers are only addressed by number: | |
| 511 | +.CW R0 | |
| 512 | +through | |
| 513 | +.CW R31 . | |
| 514 | +.CW R29 | |
| 515 | +is the stack pointer; | |
| 516 | +.CW R30 | |
| 517 | +is used as the static base pointer, the analogue of | |
| 518 | +.CW A6 | |
| 519 | +on the 68020. | |
| 520 | +Its value is the address of the global symbol | |
| 521 | +.CW setR30(SB) . | |
| 522 | +The register holding returned values from subroutines is | |
| 523 | +.CW R1 . | |
| 524 | +When a function is called, space for the first argument | |
| 525 | +is reserved at | |
| 526 | +.CW 0(FP) | |
| 527 | +but in C (not Alef) the value is passed in | |
| 528 | +.CW R1 | |
| 529 | +instead. | |
| 530 | +.PP | |
| 531 | +The loader uses | |
| 532 | +.CW R28 | |
| 533 | +as a temporary. The system uses | |
| 534 | +.CW R26 | |
| 535 | +and | |
| 536 | +.CW R27 | |
| 537 | +as interrupt-time temporaries. Therefore none of these registers | |
| 538 | +should be used in user code. | |
| 539 | +.PP | |
| 540 | +The control registers are not known to the assembler. | |
| 541 | +Instead they are numbered registers | |
| 542 | +.CW M0 , | |
| 543 | +.CW M1 , | |
| 544 | +etc. | |
| 545 | +Use this trick to access, say, | |
| 546 | +.CW STATUS : | |
| 547 | +.P1 | |
| 548 | +#define STATUS 12 | |
| 549 | + MOVW M(STATUS), R1 | |
| 550 | +.P2 | |
| 551 | +.PP | |
| 552 | +Floating point registers are called | |
| 553 | +.CW F0 | |
| 554 | +through | |
| 555 | +.CW F31 . | |
| 556 | +By convention, | |
| 557 | +.CW F24 | |
| 558 | +must be initialized to the value 0.0, | |
| 559 | +.CW F26 | |
| 560 | +to 0.5, | |
| 561 | +.CW F28 | |
| 562 | +to 1.0, and | |
| 563 | +.CW F30 | |
| 564 | +to 2.0; | |
| 565 | +this is done by the operating system. | |
| 566 | +.PP | |
| 567 | +The instructions and their syntax are different from those of the manufacturer's | |
| 568 | +manual. | |
| 569 | +There are no | |
| 570 | +.CW lui | |
| 571 | +and kin; instead there are | |
| 572 | +.CW MOVW | |
| 573 | +(move word), | |
| 574 | +.CW MOVH | |
| 575 | +(move halfword), | |
| 576 | +and | |
| 577 | +.CW MOVB | |
| 578 | +(move byte) pseudo-instructions. If the operand is unsigned, the instructions | |
| 579 | +are | |
| 580 | +.CW MOVHU | |
| 581 | +and | |
| 582 | +.CW MOVBU . | |
| 583 | +The order of operands is from left to right in dataflow order, just as | |
| 584 | +on the 68020 but not as in MIPS documentation. | |
| 585 | +This means that the | |
| 586 | +.CW Bcond | |
| 587 | +instructions are reversed with respect to the book; for example, a | |
| 588 | +.CW va | |
| 589 | +.CW BGTZ | |
| 590 | +generates a MIPS | |
| 591 | +.CW bltz | |
| 592 | +instruction. | |
| 593 | +.PP | |
| 594 | +The assembler is for the R2000, R3000, and most of the R4000 and R6000 architectures. | |
| 595 | +It understands the 64-bit instructions | |
| 596 | +.CW MOVV , | |
| 597 | +.CW MOVVL , | |
| 598 | +.CW ADDV , | |
| 599 | +.CW ADDVU , | |
| 600 | +.CW SUBV , | |
| 601 | +.CW SUBVU , | |
| 602 | +.CW MULV , | |
| 603 | +.CW MULVU , | |
| 604 | +.CW DIVV , | |
| 605 | +.CW DIVVU , | |
| 606 | +.CW SLLV , | |
| 607 | +.CW SRLV , | |
| 608 | +and | |
| 609 | +.CW SRAV . | |
| 610 | +The assembler does not have any cache, load-linked, or store-conditional instructions. | |
| 611 | +.PP | |
| 612 | +Some assembler instructions are expanded into multiple instructions by the loader. | |
| 613 | +For example the loader may convert the load of a 32 bit constant into an | |
| 614 | +.CW lui | |
| 615 | +followed by an | |
| 616 | +.CW ori . | |
| 617 | +.PP | |
| 618 | +Assembler instructions should be laid out as if there | |
| 619 | +were no load, branch, or floating point compare delay slots; | |
| 620 | +the loader will rearrange\(em\f2schedule\f1\(emthe instructions | |
| 621 | +to guarantee correctness and improve performance. | |
| 622 | +The only exception is that the correct scheduling of instructions | |
| 623 | +that use control registers varies from model to model of machine | |
| 624 | +(and is often undocumented) so you should schedule such instructions | |
| 625 | +by hand to guarantee correct behavior. | |
| 626 | +The loader generates | |
| 627 | +.P1 | |
| 628 | + NOR R0, R0, R0 | |
| 629 | +.P2 | |
| 630 | +when it needs a true no-op instruction. | |
| 631 | +Use exactly this instruction when scheduling code manually; | |
| 632 | +the loader recognizes it and schedules the code before it and after it independently. Also, | |
| 633 | +.CW WORD | |
| 634 | +pseudo-ops are scheduled like no-ops. | |
| 635 | +.PP | |
| 636 | +The | |
| 637 | +.CW NOSCHED | |
| 638 | +pseudo-op disables instruction scheduling | |
| 639 | +(scheduling is enabled by default); | |
| 640 | +.CW SCHED | |
| 641 | +re-enables it. | |
| 642 | +Branch folding, code copying, and dead code elimination are | |
| 643 | +disabled for instructions that are not scheduled. | |
| 644 | +.SH | |
| 645 | +SPARC | |
| 646 | +.PP | |
| 647 | +Once you understand the Plan 9 model for the MIPS, the SPARC is familiar. | |
| 648 | +Registers have numerical names only: | |
| 649 | +.CW R0 | |
| 650 | +through | |
| 651 | +.CW R31 . | |
| 652 | +Forget about register windows: Plan 9 doesn't use them at all. | |
| 653 | +The machine has 32 global registers, period. | |
| 654 | +.CW R1 | |
| 655 | +[sic] is the stack pointer. | |
| 656 | +.CW R2 | |
| 657 | +is the static base register, with value the address of | |
| 658 | +.CW setSB(SB) . | |
| 659 | +.CW R7 | |
| 660 | +is the return register and also the register holding the first | |
| 661 | +argument to a C (not Alef) function, again with space reserved at | |
| 662 | +.CW 0(FP) . | |
| 663 | +.CW R14 | |
| 664 | +is the loader temporary. | |
| 665 | +.PP | |
| 666 | +Floating-point registers are exactly as on the MIPS. | |
| 667 | +.PP | |
| 668 | +The control registers are known by names such as | |
| 669 | +.CW FSR . | |
| 670 | +The instructions to access these registers are | |
| 671 | +.CW MOVW | |
| 672 | +instructions, for example | |
| 673 | +.P1 | |
| 674 | + MOVW Y, R8 | |
| 675 | +.P2 | |
| 676 | +for the SPARC instruction | |
| 677 | +.P1 | |
| 678 | + rdy %r8 | |
| 679 | +.P2 | |
| 680 | +.PP | |
| 681 | +Move instructions are similar to those on the MIPS: pseudo-operations | |
| 682 | +that turn into appropriate sequences of | |
| 683 | +.CW sethi | |
| 684 | +instructions, adds, etc. | |
| 685 | +Instructions read from left to right. Because the arguments are | |
| 686 | +flipped to | |
| 687 | +.CW SUBCC , | |
| 688 | +the condition codes are not inverted as on the MIPS. | |
| 689 | +.PP | |
| 690 | +The syntax for the ASI stuff is, for example to move a word from ASI 2: | |
| 691 | +.P1 | |
| 692 | + MOVW (R7, 2), R8 | |
| 693 | +.P2 | |
| 694 | +The syntax for double indexing is | |
| 695 | +.P1 | |
| 696 | + MOVW (R7+R8), R9 | |
| 697 | +.P2 | |
| 698 | +.PP | |
| 699 | +The SPARC's instruction scheduling is similar to the MIPS's. | |
| 700 | +The official no-op instruction is: | |
| 701 | +.P1 | |
| 702 | + ORN R0, R0, R0 | |
| 703 | +.P2 | |
| 704 | +.SH | |
| 705 | +i386 | |
| 706 | +.PP | |
| 707 | +The assembler assumes 32-bit protected mode. | |
| 708 | +The register names are | |
| 709 | +.CW SP , | |
| 710 | +.CW AX , | |
| 711 | +.CW BX , | |
| 712 | +.CW CX , | |
| 713 | +.CW DX , | |
| 714 | +.CW BP , | |
| 715 | +.CW DI , | |
| 716 | +and | |
| 717 | +.CW SI . | |
| 718 | +The stack pointer (not a pseudo-register) is | |
| 719 | +.CW SP | |
| 720 | +and the return register is | |
| 721 | +.CW AX . | |
| 722 | +There is no physical frame pointer but, as for the MIPS, | |
| 723 | +.CW FP | |
| 724 | +is a pseudo-register that acts as | |
| 725 | +a frame pointer. | |
| 726 | +.PP | |
| 727 | +Opcode names are mostly the same as those listed in the Intel manual | |
| 728 | +with an | |
| 729 | +.CW L , | |
| 730 | +.CW W , | |
| 731 | +or | |
| 732 | +.CW B | |
| 733 | +appended to identify 32-bit, | |
| 734 | +16-bit, and 8-bit operations. | |
| 735 | +The exceptions are loads, stores, and conditionals. | |
| 736 | +All load and store opcodes to and from general registers, special registers | |
| 737 | +(such as | |
| 738 | +.CW CR0, | |
| 739 | +.CW CR3, | |
| 740 | +.CW GDTR, | |
| 741 | +.CW IDTR, | |
| 742 | +.CW SS, | |
| 743 | +.CW CS, | |
| 744 | +.CW DS, | |
| 745 | +.CW ES, | |
| 746 | +.CW FS, | |
| 747 | +and | |
| 748 | +.CW GS ) | |
| 749 | +or memory are written | |
| 750 | +as | |
| 751 | +.P1 | |
| 752 | + MOV\f2x\fP src,dst | |
| 753 | +.P2 | |
| 754 | +where | |
| 755 | +.I x | |
| 756 | +is | |
| 757 | +.CW L , | |
| 758 | +.CW W , | |
| 759 | +or | |
| 760 | +.CW B . | |
| 761 | +Thus to get | |
| 762 | +.CW AL | |
| 763 | +use a | |
| 764 | +.CW MOVB | |
| 765 | +instruction. If you need to access | |
| 766 | +.CW AH , | |
| 767 | +you must mention it explicitly in a | |
| 768 | +.CW MOVB : | |
| 769 | +.P1 | |
| 770 | + MOVB AH, BX | |
| 771 | +.P2 | |
| 772 | +There are many examples of illegal moves, for example, | |
| 773 | +.P1 | |
| 774 | + MOVB BP, DI | |
| 775 | +.P2 | |
| 776 | +that the loader actually implements as pseudo-operations. | |
| 777 | +.PP | |
| 778 | +The names of conditions in all conditional instructions | |
| 779 | +.CW J , ( | |
| 780 | +.CW SET ) | |
| 781 | +follow the conventions of the 68020 instead of those of the Intel | |
| 782 | +assembler: | |
| 783 | +.CW JOS , | |
| 784 | +.CW JOC , | |
| 785 | +.CW JCS , | |
| 786 | +.CW JCC , | |
| 787 | +.CW JEQ , | |
| 788 | +.CW JNE , | |
| 789 | +.CW JLS , | |
| 790 | +.CW JHI , | |
| 791 | +.CW JMI , | |
| 792 | +.CW JPL , | |
| 793 | +.CW JPS , | |
| 794 | +.CW JPC , | |
| 795 | +.CW JLT , | |
| 796 | +.CW JGE , | |
| 797 | +.CW JLE , | |
| 798 | +and | |
| 799 | +.CW JGT | |
| 800 | +instead of | |
| 801 | +.CW JO , | |
| 802 | +.CW JNO , | |
| 803 | +.CW JB , | |
| 804 | +.CW JNB , | |
| 805 | +.CW JZ , | |
| 806 | +.CW JNZ , | |
| 807 | +.CW JBE , | |
| 808 | +.CW JNBE , | |
| 809 | +.CW JS , | |
| 810 | +.CW JNS , | |
| 811 | +.CW JP , | |
| 812 | +.CW JNP , | |
| 813 | +.CW JL , | |
| 814 | +.CW JNL , | |
| 815 | +.CW JLE , | |
| 816 | +and | |
| 817 | +.CW JNLE . | |
| 818 | +.PP | |
| 819 | +The addressing modes have syntax like | |
| 820 | +.CW AX , | |
| 821 | +.CW (AX) , | |
| 822 | +.CW (AX)(BX*4) , | |
| 823 | +.CW 10(AX) , | |
| 824 | +and | |
| 825 | +.CW 10(AX)(BX*4) . | |
| 826 | +The offsets from | |
| 827 | +.CW AX | |
| 828 | +can be replaced by offsets from | |
| 829 | +.CW FP | |
| 830 | +or | |
| 831 | +.CW SB | |
| 832 | +to access names, for example | |
| 833 | +.CW extern+5(SB)(AX*2) . | |
| 834 | +.PP | |
| 835 | +Other notes: Non-relative | |
| 836 | +.CW JMP | |
| 837 | +and | |
| 838 | +.CW CALL | |
| 839 | +have a | |
| 840 | +.CW * | |
| 841 | +added to the syntax. | |
| 842 | +Only | |
| 843 | +.CW LOOP , | |
| 844 | +.CW LOOPEQ , | |
| 845 | +and | |
| 846 | +.CW LOOPNE | |
| 847 | +are legal loop instructions. Only | |
| 848 | +.CW REP | |
| 849 | +and | |
| 850 | +.CW REPN | |
| 851 | +are recognized repeaters. These are not prefixes, but rather | |
| 852 | +stand-alone opcodes that precede the strings, for example | |
| 853 | +.P1 | |
| 854 | + CLD; REP; MOVSL | |
| 855 | +.P2 | |
| 856 | +Segment override prefixes in | |
| 857 | +.CW MOD/RM | |
| 858 | +fields are not supported. | |
| 859 | +.SH | |
| 860 | +AMD64 | |
| 861 | +.PP | |
| 862 | +The assembler's conventions are similar to those for the 386, above. | |
| 863 | +The architecture provides extra fixed-point registers | |
| 864 | +.CW R8 | |
| 865 | +to | |
| 866 | +.CW R15 . | |
| 867 | +All registers are 64 bit, but instructions access low-order 8, 16 and 32 bits | |
| 868 | +as described in the processor handbook. | |
| 869 | +For example, | |
| 870 | +.CW MOVL | |
| 871 | +to | |
| 872 | +.CW AX | |
| 873 | +puts a value in the low-order 32 bits and clears the top 32 bits to zero. | |
| 874 | +Literal operands are limited to signed 32 bit values, which are sign-extended | |
| 875 | +to 64 bits in 64 bit operations; the exception is | |
| 876 | +.CW MOVQ , | |
| 877 | +which allows 64-bit literals. | |
| 878 | +MMX registers are | |
| 879 | +.CW M0 | |
| 880 | +to | |
| 881 | +.CW M7 , | |
| 882 | +and | |
| 883 | +XMM registers are | |
| 884 | +.CW X0 | |
| 885 | +to | |
| 886 | +.CW X15 . | |
| 887 | +.PP | |
| 888 | +There are many new instructions, including the MMX and XMM media instructions, | |
| 889 | +and conditional move instructions. | |
| 890 | +As with the 386 instruction names, | |
| 891 | +all new 64-bit integer instructions, and the MMX and XMM instructions | |
| 892 | +uniformly use | |
| 893 | +.CW L | |
| 894 | +for `long word' (32 bits) and | |
| 895 | +.CW Q | |
| 896 | +for `quad word' (64 bits). | |
| 897 | +Some instructions use | |
| 898 | +.CW O | |
| 899 | +(`octword') for 128-bit values, where the processor handbook | |
| 900 | +variously uses | |
| 901 | +.CW O | |
| 902 | +or | |
| 903 | +.CW DQ . | |
| 904 | +The assembler also consistently uses | |
| 905 | +.CW PL | |
| 906 | +for `packed long' in | |
| 907 | +XMM instructions, instead of | |
| 908 | +.CW Q , | |
| 909 | +.CW DQ | |
| 910 | +or | |
| 911 | +.CW PI . | |
| 912 | +Either | |
| 913 | +.CW MOVL | |
| 914 | +or | |
| 915 | +.CW MOVQ | |
| 916 | +can be used to move values to and from control registers, even when | |
| 917 | +the registers might be 64 bits. | |
| 918 | +The assembler often accepts the handbook's name to ease conversion | |
| 919 | +of existing code (but remember that the operand order is uniformly | |
| 920 | +source then destination). | |
| 921 | +.PP | |
| 922 | +C's | |
| 923 | +.CW "long long" | |
| 924 | +type is 64 bits, but passed and returned by value, not by reference. | |
| 925 | +More notably, C pointer values are 64 bits, and thus | |
| 926 | +.CW "long long" | |
| 927 | +and | |
| 928 | +.CW "unsigned long long" | |
| 929 | +are the only integer types wide enough to hold a pointer value. | |
| 930 | +The C compiler and library use the XMM floating-point instructions, not | |
| 931 | +the old 387 ones, although the latter are implemented by assembler and loader. | |
| 932 | +The compiler provides external registers, | |
| 933 | +allocated from | |
| 934 | +.CW R15 | |
| 935 | +down. | |
| 936 | +.PP | |
| 937 | +The calling conventions are different from the 386. | |
| 938 | +.CW CALL | |
| 939 | +pushes, and | |
| 940 | +.CW RET | |
| 941 | +pops a 64-bit return address on the stack. | |
| 942 | +The first integer or pointer argument is passed in a register, which is | |
| 943 | +.CW BP | |
| 944 | +for an integer or pointer (it can be referred to in assembly code by the pseudonym | |
| 945 | +.CW RARG ). | |
| 946 | +.CW AX | |
| 947 | +holds the return value from subroutines as before. | |
| 948 | +Floating-point results are returned in | |
| 949 | +.CW X0 , | |
| 950 | +although currently the first parameter is not passed in a register if floating-point. | |
| 951 | +All parameters less than 8 bytes in length have 8 byte slots reserved on the stack | |
| 952 | +to preserve alignment and simplify variable-length argument list access, | |
| 953 | +including the first parameter when passed in a register, | |
| 954 | +although bytes 4 to 7 are not initialized. | |
| 955 | +.PP | |
| 956 | +The assembler assumes 64-bit mode unless a | |
| 957 | +.CW MODE | |
| 958 | +pseudo-operation is given: | |
| 959 | +.P1 | |
| 960 | + MODE $32 | |
| 961 | +.P2 | |
| 962 | +to change to 32-bit mode. | |
| 963 | +The effect is mainly to diagnose instructions that are illegal in | |
| 964 | +the given mode, but the loader will also assume 32-bit operands and addresses, | |
| 965 | +and 32-bit PC values for call and return. | |
| 966 | +.SH | |
| 967 | +Alpha | |
| 968 | +.PP | |
| 969 | +On the Alpha, all registers are 64 bits. The architecture handles 32-bit values | |
| 970 | +by giving them a canonical format (sign extension in the case of integer registers). | |
| 971 | +Registers are numbered | |
| 972 | +.CW R0 | |
| 973 | +through | |
| 974 | +.CW R31 . | |
| 975 | +.CW R0 | |
| 976 | +holds the return value from subroutines, and also the first parameter. | |
| 977 | +.CW R30 | |
| 978 | +is the stack pointer, | |
| 979 | +.CW R29 | |
| 980 | +is the static base, | |
| 981 | +.CW R26 | |
| 982 | +is the link register, and | |
| 983 | +.CW R27 | |
| 984 | +and | |
| 985 | +.CW R28 | |
| 986 | +are linker temporaries. | |
| 987 | +.PP | |
| 988 | +Floating point registers are numbered | |
| 989 | +.CW F0 | |
| 990 | +to | |
| 991 | +.CW F31 . | |
| 992 | +.CW F28 | |
| 993 | +contains | |
| 994 | +.CW 0.5 , | |
| 995 | +.CW F29 | |
| 996 | +contains | |
| 997 | +.CW 1.0 , | |
| 998 | +and | |
| 999 | +.CW F30 | |
| 1000 | +contains | |
| 1001 | +.CW 2.0 . | |
| 1002 | +.CW F31 | |
| 1003 | +is always | |
| 1004 | +.CW 0.0 | |
| 1005 | +on the Alpha. | |
| 1006 | +.PP | |
| 1007 | +The extension character for | |
| 1008 | +.CW MOV | |
| 1009 | +follows DEC's notation: | |
| 1010 | +.CW B | |
| 1011 | +for byte (8 bits), | |
| 1012 | +.CW W | |
| 1013 | +for word (16 bits), | |
| 1014 | +.CW L | |
| 1015 | +for long (32 bits), | |
| 1016 | +and | |
| 1017 | +.CW Q | |
| 1018 | +for quadword (64 bits). | |
| 1019 | +Byte and ``word'' loads and stores may be made unsigned | |
| 1020 | +by appending a | |
| 1021 | +.CW U . | |
| 1022 | +.CW S | |
| 1023 | +and | |
| 1024 | +.CW T | |
| 1025 | +refer to IEEE floating point single precision (32 bits) and double precision (64 bits), respectively. | |
| 1026 | +.SH | |
| 1027 | +PowerPC | |
| 1028 | +.PP | |
| 1029 | +The PowerPC follows the Plan 9 model set by the MIPS and SPARC, | |
| 1030 | +not the elaborate ABIs. | |
| 1031 | +The 32-bit instructions of the 60x and 8xx PowerPC architectures are supported; | |
| 1032 | +there is no support for the older POWER instructions. | |
| 1033 | +Registers are | |
| 1034 | +.CW R0 | |
| 1035 | +through | |
| 1036 | +.CW R31 . | |
| 1037 | +.CW R0 | |
| 1038 | +is initialized to zero; this is done by C start up code | |
| 1039 | +and assumed by the compiler and loader. | |
| 1040 | +.CW R1 | |
| 1041 | +is the stack pointer. | |
| 1042 | +.CW R2 | |
| 1043 | +is the static base register, with value the address of | |
| 1044 | +.CW setSB(SB) . | |
| 1045 | +.CW R3 | |
| 1046 | +is the return register and also the register holding the first | |
| 1047 | +argument to a C function, with space reserved at | |
| 1048 | +.CW 0(FP) | |
| 1049 | +as on the MIPS. | |
| 1050 | +.CW R31 | |
| 1051 | +is the loader temporary. | |
| 1052 | +The external registers in Plan 9's C are allocated from | |
| 1053 | +.CW R30 | |
| 1054 | +down. | |
| 1055 | +.PP | |
| 1056 | +Floating point registers are called | |
| 1057 | +.CW F0 | |
| 1058 | +through | |
| 1059 | +.CW F31 . | |
| 1060 | +By convention, several registers are initialized | |
| 1061 | +to specific values; this is done by the operating system. | |
| 1062 | +.CW F27 | |
| 1063 | +must be initialized to the value | |
| 1064 | +.CW 0x4330000080000000 | |
| 1065 | +(used by float-to-int conversion), | |
| 1066 | +.CW F28 | |
| 1067 | +to the value 0.0, | |
| 1068 | +.CW F29 | |
| 1069 | +to 0.5, | |
| 1070 | +.CW F30 | |
| 1071 | +to 1.0, and | |
| 1072 | +.CW F31 | |
| 1073 | +to 2.0. | |
| 1074 | +.PP | |
| 1075 | +As on the MIPS and SPARC, the assembler accepts arbitrary literals | |
| 1076 | +as operands to | |
| 1077 | +.CW MOVW , | |
| 1078 | +and also to | |
| 1079 | +.CW ADD | |
| 1080 | +and others where `immediate' variants exist, | |
| 1081 | +and the loader generates sequences | |
| 1082 | +of | |
| 1083 | +.CW addi , | |
| 1084 | +.CW addis , | |
| 1085 | +.CW oris , | |
| 1086 | +etc. as required. | |
| 1087 | +The register indirect addressing modes use the same syntax as the SPARC, | |
| 1088 | +including double indexing when allowed. | |
| 1089 | +.PP | |
| 1090 | +The instruction names are generally derived from the Motorola ones, | |
| 1091 | +subject to slight transformation: | |
| 1092 | +the | |
| 1093 | +.CW . ' ` | |
| 1094 | +marking the setting of condition codes is replaced by | |
| 1095 | +.CW CC , | |
| 1096 | +and when the letter | |
| 1097 | +.CW o ' ` | |
| 1098 | +represents `OE=1' it is replaced by | |
| 1099 | +.CW V . | |
| 1100 | +Thus | |
| 1101 | +.CW add , | |
| 1102 | +.CW addo. | |
| 1103 | +and | |
| 1104 | +.CW subfzeo. | |
| 1105 | +become | |
| 1106 | +.CW ADD , | |
| 1107 | +.CW ADDVCC | |
| 1108 | +and | |
| 1109 | +.CW SUBFZEVCC . | |
| 1110 | +As well as the three-operand conditional branch instruction | |
| 1111 | +.CW BC , | |
| 1112 | +the assembler provides pseudo-instructions for the common cases: | |
| 1113 | +.CW BEQ , | |
| 1114 | +.CW BNE , | |
| 1115 | +.CW BGT , | |
| 1116 | +.CW BGE , | |
| 1117 | +.CW BLT , | |
| 1118 | +.CW BLE , | |
| 1119 | +.CW BVC , | |
| 1120 | +and | |
| 1121 | +.CW BVS . | |
| 1122 | +The unconditional branch instruction is | |
| 1123 | +.CW BR . | |
| 1124 | +Indirect branches use | |
| 1125 | +.CW "(CTR)" | |
| 1126 | +or | |
| 1127 | +.CW "(LR)" | |
| 1128 | +as target. | |
| 1129 | +.PP | |
| 1130 | +Load or store operations are replaced by | |
| 1131 | +.CW MOV | |
| 1132 | +variants in the usual way: | |
| 1133 | +.CW MOVW | |
| 1134 | +(move word), | |
| 1135 | +.CW MOVH | |
| 1136 | +(move halfword with sign extension), and | |
| 1137 | +.CW MOVB | |
| 1138 | +(move byte with sign extension, a pseudo-instruction), | |
| 1139 | +with unsigned variants | |
| 1140 | +.CW MOVHZ | |
| 1141 | +and | |
| 1142 | +.CW MOVBZ , | |
| 1143 | +and byte-reversing | |
| 1144 | +.CW MOVWBR | |
| 1145 | +and | |
| 1146 | +.CW MOVHBR . | |
| 1147 | +`Load or store with update' versions are | |
| 1148 | +.CW MOVWU , | |
| 1149 | +.CW MOVHU , | |
| 1150 | +and | |
| 1151 | +.CW MOVBZU . | |
| 1152 | +Load or store multiple is | |
| 1153 | +.CW MOVMW . | |
| 1154 | +The exceptions are the string instructions, which are | |
| 1155 | +.CW LSW | |
| 1156 | +and | |
| 1157 | +.CW STSW , | |
| 1158 | +and the reservation instructions | |
| 1159 | +.CW lwarx | |
| 1160 | +and | |
| 1161 | +.CW stwcx. , | |
| 1162 | +which are | |
| 1163 | +.CW LWAR | |
| 1164 | +and | |
| 1165 | +.CW STWCCC , | |
| 1166 | +all with operands in the usual data-flow order. | |
| 1167 | +Floating-point load or store instructions are | |
| 1168 | +.CW FMOVD , | |
| 1169 | +.CW FMOVDU , | |
| 1170 | +.CW FMOVS , | |
| 1171 | +and | |
| 1172 | +.CW FMOVSU . | |
| 1173 | +The register to register move instructions | |
| 1174 | +.CW fmr | |
| 1175 | +and | |
| 1176 | +.CW fmr. | |
| 1177 | +are written | |
| 1178 | +.CW FMOVD | |
| 1179 | +and | |
| 1180 | +.CW FMOVDCC . | |
| 1181 | +.PP | |
| 1182 | +The assembler knows the commonly used special purpose registers: | |
| 1183 | +.CW CR , | |
| 1184 | +.CW CTR , | |
| 1185 | +.CW DEC , | |
| 1186 | +.CW LR , | |
| 1187 | +.CW MSR , | |
| 1188 | +and | |
| 1189 | +.CW XER . | |
| 1190 | +The rest, which are often architecture-dependent, are referenced as | |
| 1191 | +.CW SPR(n) . | |
| 1192 | +The segment registers of the 60x series are similarly | |
| 1193 | +.CW SEG(n) , | |
| 1194 | +but | |
| 1195 | +.I n | |
| 1196 | +can also be a register name, as in | |
| 1197 | +.CW SEG(R3) . | |
| 1198 | +Moves between special purpose registers and general purpose ones, | |
| 1199 | +when allowed by the architecture, | |
| 1200 | +are written as | |
| 1201 | +.CW MOVW , | |
| 1202 | +replacing | |
| 1203 | +.CW mfcr , | |
| 1204 | +.CW mtcr , | |
| 1205 | +.CW mfmsr , | |
| 1206 | +.CW mtmsr , | |
| 1207 | +.CW mtspr , | |
| 1208 | +.CW mfspr , | |
| 1209 | +.CW mftb , | |
| 1210 | +and many others. | |
| 1211 | +.PP | |
| 1212 | +The fields of the condition register | |
| 1213 | +.CW CR | |
| 1214 | +are referenced as | |
| 1215 | +.CW CR(0) | |
| 1216 | +through | |
| 1217 | +.CW CR(7) . | |
| 1218 | +They are used by the | |
| 1219 | +.CW MOVFL | |
| 1220 | +(move field) pseudo-instruction, | |
| 1221 | +which produces | |
| 1222 | +.CW mcrf | |
| 1223 | +or | |
| 1224 | +.CW mtcrf . | |
| 1225 | +For example: | |
| 1226 | +.P1 | |
| 1227 | + MOVFL CR(3), CR(0) | |
| 1228 | + MOVFL R3, CR(1) | |
| 1229 | + MOVFL R3, $7, CR | |
| 1230 | +.P2 | |
| 1231 | +They are also accepted in | |
| 1232 | +the conditional branch instruction, for example | |
| 1233 | +.P1 | |
| 1234 | + BEQ CR(7), label | |
| 1235 | +.P2 | |
| 1236 | +Fields of the | |
| 1237 | +.CW FPSCR | |
| 1238 | +are accessed using | |
| 1239 | +.CW MOVFL | |
| 1240 | +in a similar way: | |
| 1241 | +.P1 | |
| 1242 | + MOVFL FPSCR, F0 | |
| 1243 | + MOVFL F0, FPSCR | |
| 1244 | + MOVFL F0, $7, FPSCR | |
| 1245 | + MOVFL $0, FPSCR(3) | |
| 1246 | +.P2 | |
| 1247 | +producing | |
| 1248 | +.CW mffs , | |
| 1249 | +.CW mtfsf , | |
| 1250 | +or | |
| 1251 | +.CW mtfsfi | |
| 1252 | +as appropriate. | |
| 1253 | +.SH | |
| 1254 | +ARM | |
| 1255 | +.PP | |
| 1256 | +The assembler provides access to | |
| 1257 | +.CW R0 | |
| 1258 | +through | |
| 1259 | +.CW R14 | |
| 1260 | +and the | |
| 1261 | +.CW PC . | |
| 1262 | +The stack pointer is | |
| 1263 | +.CW R13 , | |
| 1264 | +the link register is | |
| 1265 | +.CW R14 , | |
| 1266 | +and the static base register is | |
| 1267 | +.CW R12 . | |
| 1268 | +.CW R0 | |
| 1269 | +is the return register and also the register holding | |
| 1270 | +the first argument to a subroutine. | |
| 1271 | +The assembler supports the | |
| 1272 | +.CW CPSR | |
| 1273 | +and | |
| 1274 | +.CW SPSR | |
| 1275 | +registers. | |
| 1276 | +It also knows about coprocessor registers | |
| 1277 | +.CW C0 | |
| 1278 | +through | |
| 1279 | +.CW C15 . | |
| 1280 | +Floating registers are | |
| 1281 | +.CW F0 | |
| 1282 | +through | |
| 1283 | +.CW F7 , | |
| 1284 | +.CW FPSR | |
| 1285 | +and | |
| 1286 | +.CW FPCR . | |
| 1287 | +.PP | |
| 1288 | +As with the other architectures, loads and stores are called | |
| 1289 | +.CW MOV , | |
| 1290 | +e.g. | |
| 1291 | +.CW MOVW | |
| 1292 | +for load word or store word, and | |
| 1293 | +.CW MOVM | |
| 1294 | +for | |
| 1295 | +load or store multiple, | |
| 1296 | +depending on the operands. | |
| 1297 | +.PP | |
| 1298 | +Addressing modes are supported by suffixes to the instructions: | |
| 1299 | +.CW .IA | |
| 1300 | +(increment after), | |
| 1301 | +.CW .IB | |
| 1302 | +(increment before), | |
| 1303 | +.CW .DA | |
| 1304 | +(decrement after), and | |
| 1305 | +.CW .DB | |
| 1306 | +(decrement before). | |
| 1307 | +These can only be used with the | |
| 1308 | +.CW MOV | |
| 1309 | +instructions. | |
| 1310 | +The move multiple instruction, | |
| 1311 | +.CW MOVM , | |
| 1312 | +defines a range of registers using brackets, e.g. | |
| 1313 | +.CW [R0-R12] . | |
| 1314 | +The special | |
| 1315 | +.CW MOVM | |
| 1316 | +addressing mode bits | |
| 1317 | +.CW W , | |
| 1318 | +.CW U , | |
| 1319 | +and | |
| 1320 | +.CW P | |
| 1321 | +are written in the same manner, for example, | |
| 1322 | +.CW MOVM.DB.W . | |
| 1323 | +A | |
| 1324 | +.CW .S | |
| 1325 | +suffix allows a | |
| 1326 | +.CW MOVM | |
| 1327 | +instruction to access user | |
| 1328 | +.CW R13 | |
| 1329 | +and | |
| 1330 | +.CW R14 | |
| 1331 | +when in another processor mode. | |
| 1332 | +Shifts and rotates in addressing modes are supported by binary operators | |
| 1333 | +.CW << | |
| 1334 | +(logical left shift), | |
| 1335 | +.CW >> | |
| 1336 | +(logical right shift), | |
| 1337 | +.CW -> | |
| 1338 | +(arithmetic right shift), and | |
| 1339 | +.CW @> | |
| 1340 | +(rotate right); for example | |
| 1341 | +.CW "R7>>R2" or | |
| 1342 | +.CW "R2@>2" . | |
| 1343 | +The assembler does not support indexing by a shifted expression; | |
| 1344 | +only names can be doubly indexed. | |
| 1345 | +.PP | |
| 1346 | +Any instruction can be followed by a suffix that makes the instruction conditional: | |
| 1347 | +.CW .EQ , | |
| 1348 | +.CW .NE , | |
| 1349 | +and so on, as in the ARM manual, with synonyms | |
| 1350 | +.CW .HS | |
| 1351 | +(for | |
| 1352 | +.CW .CS ) | |
| 1353 | +and | |
| 1354 | +.CW .LO | |
| 1355 | +(for | |
| 1356 | +.CW .CC ), | |
| 1357 | +for example | |
| 1358 | +.CW ADD.NE . | |
| 1359 | +Arithmetic | |
| 1360 | +and logical instructions | |
| 1361 | +can have a | |
| 1362 | +.CW .S | |
| 1363 | +suffix, as ARM allows, to set condition codes. | |
| 1364 | +.PP | |
| 1365 | +The syntax of the | |
| 1366 | +.CW MCR | |
| 1367 | +and | |
| 1368 | +.CW MRC | |
| 1369 | +coprocessor instructions is largely as in the manual, with the usual adjustments. | |
| 1370 | +The assembler directly supports only the ARM floating-point coprocessor | |
| 1371 | +operations used by the compiler: | |
| 1372 | +.CW CMP , | |
| 1373 | +.CW ADD , | |
| 1374 | +.CW SUB , | |
| 1375 | +.CW MUL , | |
| 1376 | +and | |
| 1377 | +.CW DIV , | |
| 1378 | +all with | |
| 1379 | +.CW F | |
| 1380 | +or | |
| 1381 | +.CW D | |
| 1382 | +suffix selecting single or double precision. | |
| 1383 | +Floating-point load or store become | |
| 1384 | +.CW MOVF | |
| 1385 | +and | |
| 1386 | +.CW MOVD . | |
| 1387 | +Conversion instructions are also specified by moves: | |
| 1388 | +.CW MOVWD , | |
| 1389 | +.CW MOVWF , | |
| 1390 | +.CW MOVDW , | |
| 1391 | +.CW MOVWD , | |
| 1392 | +.CW MOVFD , | |
| 1393 | +and | |
| 1394 | +.CW MOVDF . | |
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,1073 @@ | ||
| 1 | +.TL | |
| 2 | +The Inferno Operating System | |
| 3 | +.AU | |
| 4 | +Sean Dorward | |
| 5 | +Rob Pike | |
| 6 | +David Leo Presotto | |
| 7 | +Dennis M. Ritchie | |
| 8 | +Howard Trickey | |
| 9 | +Phil Winterbottom | |
| 10 | +.AI | |
| 11 | +Computing Science Research Center | |
| 12 | +Lucent Technologies, Bell Labs | |
| 13 | +Murray Hill, New Jersey | |
| 14 | +USA | |
| 15 | +.FS | |
| 16 | +.FA | |
| 17 | +Originally appeared in the | |
| 18 | +.I "Bell Labs Technical Journal" , | |
| 19 | +Vol. 2, No. 1, Winter 1997, pp. 5-18. | |
| 20 | +.br | |
| 21 | +Minor revisions have been made by Vita Nuova to reflect subsequent changes to Inferno. | |
| 22 | +.br | |
| 23 | +Copyright © 1997 Lucent Technologies Inc. All rights reserved. | |
| 24 | +.FE | |
| 25 | +.AB | |
| 26 | +Inferno is an operating system for creating and supporting distributed services. | |
| 27 | +It was originally developed by the Computing Science Research Center of Bell Labs, the R&D arm of Lucent Technologies, and | |
| 28 | +further developed by other groups in Lucent. | |
| 29 | +.LP | |
| 30 | +Inferno was designed specifically as a commercial product, both for licensing | |
| 31 | +in the marketplace and for use within new Lucent offerings. | |
| 32 | +It encapsulates many years of Bell Labs research in operating systems, languages, on-the-fly compilers, graphics, security, networking and portability. | |
| 33 | +.AE | |
| 34 | +.SH | |
| 35 | +Introduction | |
| 36 | +.LP | |
| 37 | +Inferno is intended to be used in a variety of network environments, for example those supporting | |
| 38 | +advanced telephones, hand-held devices, TV set-top boxes attached to cable or satellite systems, and inexpensive Internet computers, but also in conjunction with traditional computing systems. | |
| 39 | +.LP | |
| 40 | +The most visible new environments involve cable television, direct satellite broadcast, the Internet, and other networks. As the entertainment, telecommunications, and computing industries converge and interconnect, a variety of public data networks are emerging, each potentially as useful and profitable as the telephone system. Unlike the telephone system, which started with standard terminals and signaling, these networks are developing in a world of diverse terminals, network hardware, and protocols. Only a well-designed, economical operating system can insulate the various providers of content and services from the equally varied transport and presentation | |
| 41 | +platforms. Inferno is a network operating system for this new world. | |
| 42 | +.LP | |
| 43 | +Inferno's definitive strength lies in its portability and versatility across several dimensions: | |
| 44 | +.IP • | |
| 45 | +Portability across processors: it currently runs on Intel, Sparc, MIPS, ARM, HP-PA, and PowerPC architectures and is readily portable to others. | |
| 46 | +.IP • | |
| 47 | +Portability across environments: it runs as a stand-alone operating system on small terminals, and also as a user application under Windows NT, Windows 95, Unix (Irix, Solaris, FreeBSD, Linux, AIX, HP/UX) and Plan 9. In all of these environments, Inferno applications see an identical interface. | |
| 48 | +.IP • | |
| 49 | +Distributed design: the identical environment is established at the user's terminal and at the server, and each may import the resources (for example, the attached I/O devices or networks) of the other. Aided by the communications facilities of the run-time system, applications may be split easily (and even dynamically) between client and server. | |
| 50 | +.IP • | |
| 51 | +Minimal hardware requirements: it runs useful applications stand-alone on machines with as little as 1 MB of memory, and does not require memory-mapping hardware. | |
| 52 | +.IP • | |
| 53 | +Portable applications: Inferno applications are written in the type-safe language Limbo, whose binary representation is identical over all platforms. | |
| 54 | +.IP • | |
| 55 | +Dynamic adaptability: applications may, depending on the hardware or other resources available, load different program modules to perform a specific function. For example, a video player application might use any of several different decoder modules. | |
| 56 | +.LP | |
| 57 | +Underlying the design of Inferno is a model of the diversity of application areas it intends to stimulate. Many providers are interested in purveying media and services: telephone network service providers, WWW servers, cable companies, merchants, various information providers. | |
| 58 | +There are many connection technologies: ordinary telephone modems, ISDN, ATM, the Internet, analog broadcast or cable TV, cable modems, digital video on demand, and other interactive TV systems. | |
| 59 | +.LP | |
| 60 | +Applications more clearly related to Lucent's current and planned product offerings include | |
| 61 | +control of switches and routers, and the associated operations system facilities needed to support them. | |
| 62 | +For example, Inferno software controls an IP switch/router for voice and data being | |
| 63 | +developed by Lucent's Bell Labs research and Network Systems organizations. | |
| 64 | +An Inferno-based firewall (Signet) is being used to secure outside access to the Research | |
| 65 | +Internet connection. | |
| 66 | +.LP | |
| 67 | +Finally, there are existing or potential hardware endpoints. Some are in consumers' homes: PCs, | |
| 68 | +game consoles, newer set-top boxes. Some are inside the networks themselves: nodes for billing, network monitoring or provisioning. The higher ends of these spectra, epitomized by fully interactive TV with video on demand, may be fascinating, but have developed more slowly than expected. One reason is the cost of the set-top box, especially its memory requirements. Portable terminals, because of weight and cost considerations, are similarly constrained. | |
| 69 | +.LP | |
| 70 | +Inferno is parsimonious enough in its resource requirements to support interesting applications on today's hardware, while being versatile enough to grow into the future. In particular, it enables developers to create applications that will work across a range of facilities. An example: an interactive shopping catalog that works in text mode over a POTS modem, shows still pictures (perhaps with audio) of the merchandise over ISDN, and includes video clips over digital cable. | |
| 71 | +.LP | |
| 72 | +Clearly not everyone who deploys an Inferno-based solution will want to span the whole range of possibilities, but the system architecture should be constrained only by the desired markets and the available interconnection and server technologies, not by the software. | |
| 73 | +.SH | |
| 74 | +Inferno interfaces | |
| 75 | +.LP | |
| 76 | +The role of the Inferno system is to | |
| 77 | +.I "create" | |
| 78 | +several standard interfaces for its applications: | |
| 79 | +.IP • | |
| 80 | +Applications use various resources internal to the system, such as a consistent virtual machine that runs the application programs, together with library modules that perform services as simple as string manipulation through more sophisticated graphics services for dealing with text, pictures, | |
| 81 | +higher-level toolkits, and video. | |
| 82 | +.IP • | |
| 83 | +Applications exist in an external environment containing resources such as data files that can be read and manipulated, together with objects that are named and manipulated like files but are more active. Devices (for example a hand-held remote control, an MPEG decoder or a network interface) present themselves to the application as files. | |
| 84 | +.IP • | |
| 85 | +Standard protocols exist for communication within and between separate machines running Inferno, so that applications can cooperate. | |
| 86 | +.LP | |
| 87 | +At the same time, Inferno | |
| 88 | +.I uses | |
| 89 | +interfaces supplied by an existing environment, either bare hardware or standard operating systems and protocols. | |
| 90 | +.LP | |
| 91 | +Most typically, an Inferno-based service would consist of many relatively cheap terminals running Inferno as a native system, and a smaller number of large machines running Inferno as a hosted system. On these server machines Inferno might interface to databases, transaction systems, existing OA&M facilities, and other resources provided under the native operating system. The Inferno applications themselves would run either on the client or server machines, or both. | |
| 92 | +.SH | |
| 93 | +External Environment of Inferno Applications | |
| 94 | +.LP | |
| 95 | +The purpose of most Inferno applications is to present information or media to the user; thus applications must locate the information sources in the network and construct a local representation of them. The information flow is not one-way: the user's terminal (whether a network computer, TV set-top, PC, or videophone) is also an information source and its devices represent resources to applications. Inferno draws heavily on the design of the Plan 9 operating system [1] in the way it presents resources to these applications. | |
| 96 | +.LP | |
| 97 | +The design has three principles. | |
| 98 | +.IP • | |
| 99 | +All resources are named and accessed like files in a forest of hierarchical file systems. | |
| 100 | +.IP • | |
| 101 | +The disjoint resource hierarchies provided by different services are joined together into a single private hierarchical | |
| 102 | +.I "name space" . | |
| 103 | +.IP • | |
| 104 | +A communication protocol, called | |
| 105 | +.I "Styx" , | |
| 106 | +is applied uniformly to access these resources, whether local or remote. | |
| 107 | +.LP | |
| 108 | +In practice, most applications see a fixed set of files organized as a directory tree. Some of the files contain ordinary data, but others represent more active resources. Devices are represented as files, and device drivers (such as a modem, an MPEG decoder, a network interface, or the TV screen) attached to a particular hardware box present themselves as small directories. These directories typically containing two files, | |
| 109 | +.CW "data" | |
| 110 | +and | |
| 111 | +.CW "ctl" , | |
| 112 | +which respectively perform actual device input/output and control operations. System services also live behind file names. For example, an Internet domain name server might be attached to an agreed-upon name (say | |
| 113 | +.CW "/net/dns" ); | |
| 114 | +after writing to this file a string representing a symbolic Internet domain name, a subsequent read from the file would return the corresponding numeric Internet address. | |
| 115 | +.LP | |
| 116 | +The glue that connects the separate parts of the resource name space together is the Styx protocol. | |
| 117 | +Within an instance of Inferno, all the device drivers and other internal resources respond to the procedural version of Styx. The Inferno kernel implements a | |
| 118 | +.I "mount driver" | |
| 119 | +that transforms file system operations into remote procedure calls for transport over a network. On the other side of the connection, a server unwraps the Styx messages and implements them using resources local to it. Thus, it is possible to import parts of the name space (and thus resources) from other machines. | |
| 120 | +.LP | |
| 121 | +To extend the example above, it is unlikely that a set-top box would store the code needed for an Internet domain name-server within itself. Instead, an Internet browser would import the | |
| 122 | +.CW "/net/dns" | |
| 123 | +resource into its own name space from a server machine across a network. | |
| 124 | +.LP | |
| 125 | +The Styx protocol lies above and is independent of the communications transport layer; it is readily carried over TCP/IP, PPP, ATM or various modem transport protocols. | |
| 126 | +.SH | |
| 127 | +Internal Environment of Inferno Applications | |
| 128 | +.LP | |
| 129 | +Inferno applications are written in a new language called Limbo [2], which was designed specifically for the Inferno environment. Its syntax is influenced by C and Pascal, and it supports the standard data types common to them, together with several higher-level data types such as lists, tuples, strings, dynamic arrays, and simple abstract data types. | |
| 130 | +.LP | |
| 131 | +In addition, Limbo supplies several advanced constructs carefully integrated into the Inferno virtual machine. In particular, a communication mechanism called a | |
| 132 | +.I "channel" | |
| 133 | +is used to connect different Limbo tasks on the same machine or across the network. | |
| 134 | +A channel transports typed data in a machine-independent fashion, so that complex data structures (including channels themselves) may be passed between Limbo tasks or attached to files in the name space for language-level communication between machines. | |
| 135 | +.LP | |
| 136 | +Multi-tasking is supported directly by the Limbo language: independently scheduled threads of control may be spawned, and an | |
| 137 | +.CW "alt" | |
| 138 | +statement is used to coordinate the channel communication | |
| 139 | +between tasks (that is, | |
| 140 | +.CW "alt" | |
| 141 | +is used to select one of several channels that are ready to communicate). | |
| 142 | +By building channels and tasks into the language and its virtual machine, Inferno encourages a communication style that is easy to use and safe. | |
| 143 | +.LP | |
| 144 | +Limbo programs are built of | |
| 145 | +.I "modules" , | |
| 146 | +which are self-contained units with a well-defined interface | |
| 147 | +containing functions (methods), abstract data types, and constants defined by the module and visible outside it. Modules are accessed dynamically; that is, when one module wishes to make use of another, it dynamically executes a | |
| 148 | +.CW "load" | |
| 149 | +statement naming the desired module, and uses a returned handle to access the new module. | |
| 150 | +When the module is no longer in use, its storage and code will be released. | |
| 151 | +The flexibility of the modular structure contributes to the smallness of typical Inferno applications, and also to their adaptability. | |
| 152 | +For example, in the shopping catalog described above, | |
| 153 | +the application's main module checks dynamically for the existence of the video resource. | |
| 154 | +If it is unavailable, the video-decoder module is never loaded. | |
| 155 | +.LP | |
| 156 | +Limbo is fully type-checked at compile- and run-time; for example, pointers, besides being more | |
| 157 | +restricted than in C, are checked before being dereferenced, and the type-consistency of a dynamically loaded module is checked when it is loaded. Limbo programs run safely on a machine | |
| 158 | +without memory-protection hardware. | |
| 159 | +Moreover, all Limbo data and program objects are subject to | |
| 160 | +a garbage collector, built deeply into the Limbo run-time system. All system data objects are tracked by the virtual machine and freed as soon as they become unused. For example, if an application task creates a graphics window and then terminates, the window automatically disappears the instant the last reference to it has gone away. | |
| 161 | +.LP | |
| 162 | +Limbo programs are compiled into byte-codes representing instructions for a virtual machine called | |
| 163 | +Dis. The architecture of the arithmetic part of Dis is a simple 3-address machine, supplemented with a few specialized operations for handling some of the higher-level data types like arrays and strings. Garbage collection is handled below the level of the machine language; the scheduling of tasks is similarly hidden. When loaded into memory for execution, the byte-codes are expanded | |
| 164 | +into a format more efficient for execution; there is also an optional on-the-fly compiler that turns a Dis instruction stream into native machine instructions for the appropriate real hardware. This can be done efficiently because Dis instructions match well with the instruction-set architecture of today's machines. The resulting code executes at a speed approaching that of compiled C. | |
| 165 | +.LP | |
| 166 | +Underlying Dis is the Inferno kernel, which contains the interpreter and on-the-fly compiler as well as memory management, scheduling, device drivers, protocol stacks, and the like. | |
| 167 | +The kernel also contains the core of the file system (the name evaluator and the code that turns file system operations into remote procedure calls over communications links) as well as the small file systems implemented internally. | |
| 168 | +.LP | |
| 169 | +Finally, the Inferno virtual machine implements several standard modules internally. These include | |
| 170 | +.CW "Sys" , | |
| 171 | +which provides system calls and a small library of useful routines (e.g. creation of network connections, string manipulations). Module | |
| 172 | +.CW "Draw" | |
| 173 | +is a basic graphics library that handles raster graphics, fonts, and windows. Module | |
| 174 | +.CW "Prefab" | |
| 175 | +builds on | |
| 176 | +.CW "Draw" | |
| 177 | +to provide structured complexes containing images and text inside of windows; these elements may be scrolled, selected, and changed by the methods of | |
| 178 | +.CW "Prefab" . | |
| 179 | +Module | |
| 180 | +.CW "Tk" | |
| 181 | +is an all-new implementation of the Tk graphics toolkit [18], with a Limbo interface. A | |
| 182 | +.CW "Math" | |
| 183 | +module encapsulates the procedures for numerical programming. | |
| 184 | +.SH | |
| 185 | +The Environment of the Inferno System | |
| 186 | +.LP | |
| 187 | +Inferno creates a standard environment for applications. Identical application programs can run | |
| 188 | +under any instance of this environment, even in distributed fashion, and see the same resources. | |
| 189 | +Depending on the environment in which Inferno itself is implemented, there are several versions of the Inferno kernel, Dis/Limbo interpreter, and device driver set. | |
| 190 | +.LP | |
| 191 | +When running as the native operating system, the kernel includes all the low-level glue (interrupt handlers, graphics and other device drivers) needed to implement the abstractions presented to applications. | |
| 192 | +For a hosted system, for example under Unix, Windows NT or Windows 95, Inferno runs as a set of ordinary processes. | |
| 193 | +Instead of mapping its device-control functionality to real hardware, | |
| 194 | +it adapts to the resources provided by the operating system under which it runs. | |
| 195 | +For example, under Unix, the graphics library might be implemented using the X window system and the networking using the socket interface; under Windows, it uses the native Windows graphics and Winsock calls. | |
| 196 | +.LP | |
| 197 | +Inferno is, to the extent possible, written in standard C and most of its components are independent of the many operating systems that can host it. | |
| 198 | +.SH | |
| 199 | +Security in Inferno | |
| 200 | +.LP | |
| 201 | +Inferno provides security of communication, resource control, and | |
| 202 | +system integrity. | |
| 203 | +.LP | |
| 204 | +Each external communication channel may be transmitted in the clear, | |
| 205 | +accompanied by message digests to prevent corruption, or encrypted to | |
| 206 | +prevent corruption and interception. Once communication is set up, | |
| 207 | +the encryption is transparent to the application. Key exchange is | |
| 208 | +provided through standard public-key mechanisms; after key exchange, | |
| 209 | +message digesting and line encryption likewise use standard symmetric | |
| 210 | +mechanisms. | |
| 211 | +.LP | |
| 212 | +Inferno is secure against erroneous or malicious applications, and | |
| 213 | +encourages safe collaboration between mutually suspicious service | |
| 214 | +providers and clients. The resources available to applications appear | |
| 215 | +exclusively in the name space of the application, and standard | |
| 216 | +protection modes are available. This applies to data, to | |
| 217 | +communication resources, and to the executable modules that constitute | |
| 218 | +the applications. Security-sensitive resources of the system are | |
| 219 | +accessible only by calling the modules that provide them; in | |
| 220 | +particular, adding new files and servers to the name space is | |
| 221 | +controlled and is an authenticated operation. For example, if the | |
| 222 | +network resources are removed from an application's name space, then | |
| 223 | +it is impossible for it to establish new network connections. | |
| 224 | +.LP | |
| 225 | +Object modules may be signed by trusted authorities who guarantee | |
| 226 | +their validity and behavior, and these signatures may be checked by | |
| 227 | +the system the modules are accessed. | |
| 228 | +.LP | |
| 229 | +Although Inferno provides a rich variety of authentication and security | |
| 230 | +mechanisms, as detailed below, few application programs need to | |
| 231 | +be aware of them or explicitly include coding to make use of them. | |
| 232 | +Most often, access to resources across a secure communications link | |
| 233 | +is arranged in advance by the larger system in which the application operates. | |
| 234 | +For example, when a client system uses a server system | |
| 235 | +and connection authentication or link encryption is appropriate, | |
| 236 | +the server resources will most naturally be supplied | |
| 237 | +as a part of the application's name space. | |
| 238 | +The communications channel that carries the Styx protocol | |
| 239 | +can be set to authenticate or encrypt; thereafter, | |
| 240 | +all use of the resource is automatically protected. | |
| 241 | +.SH | |
| 242 | +Security mechanisms | |
| 243 | +.LP | |
| 244 | +Authentication and digital signatures are performed using | |
| 245 | +public key cryptography. Public keys are certified by | |
| 246 | +Inferno-based or other certifying authorities that sign the public keys with their | |
| 247 | +own private key. | |
| 248 | +.LP | |
| 249 | +Inferno uses encryption for: | |
| 250 | +.IP • | |
| 251 | +mutual authentication of communicating parties; | |
| 252 | +.IP • | |
| 253 | +authentication of messages between these parties; and | |
| 254 | +.IP • | |
| 255 | +encryption of messages between these parties. | |
| 256 | +.LP | |
| 257 | +The encryption algorithms provided by Inferno | |
| 258 | +include the SHA, MD4, and MD5 secure hashes; | |
| 259 | +Elgamal public key signatures and signature verification [4]; | |
| 260 | +RC4 encryption; | |
| 261 | +DES encryption; | |
| 262 | +and public key exchange based on the Diffie-Hellman scheme. | |
| 263 | +The public key signatures use keys with moduli up to 4096 bits, | |
| 264 | +512 bits by default. | |
| 265 | +.LP | |
| 266 | +There is no generally accepted national or international authority | |
| 267 | +for storing or generating public or private encryption keys. | |
| 268 | +Thus Inferno includes tools for using or implementing a trusted authority, | |
| 269 | +but it does not itself provide the authority, | |
| 270 | +which is an administrative function. | |
| 271 | +Thus an organization using Inferno (or any other security | |
| 272 | +and key-distribution scheme) must design its system to suit its | |
| 273 | +own needs, and in particular decide whom to trust as a Certifying | |
| 274 | +Authority (CA). However, the Inferno design is sufficiently flexible | |
| 275 | +and modular to accommodate the protocols likely to be attractive in practice. | |
| 276 | +.LP | |
| 277 | +The certifying authority that signs a user's | |
| 278 | +public key determines the size of the key and the public key | |
| 279 | +algorithm used. Tools provided with | |
| 280 | +Inferno use these signatures for authentication. Library | |
| 281 | +interfaces are provided for Limbo programs to sign and verify | |
| 282 | +signatures. | |
| 283 | +.LP | |
| 284 | +Generally authentication is performed using public key cryptography. Parties | |
| 285 | +register by having their public keys signed by the certifying authority (CA). | |
| 286 | +The signature covers a secure hash (SHA, MD4, or MD5) of | |
| 287 | +the name of the party, his public key, and an expiration time. The signature, | |
| 288 | +which contains the name of the signer, along with the signed information, | |
| 289 | +is termed a | |
| 290 | +.I "certificate" . | |
| 291 | +.LP | |
| 292 | +When parties communicate, they use the Station to Station protocol[5] to | |
| 293 | +establish the identities of the two parties and to create a mutually known secret. | |
| 294 | +This STS protocol uses the Diffie-Hellman algorithm [6] to create this shared | |
| 295 | +secret. | |
| 296 | +The protocol is protected against replay attacks by choosing new random | |
| 297 | +parameters for each conversation. It is secured against `man in | |
| 298 | +the middle' attacks by having the parties exchange certificates and then | |
| 299 | +digitally signing key parts of the protocol. To masquerade as another | |
| 300 | +party an attacker would have to be able to forge that party's signature. | |
| 301 | +.SH | |
| 302 | +Line Security | |
| 303 | +.LP | |
| 304 | +A network conversation can be secured against modification alone | |
| 305 | +or against both modification and snooping. To secure against | |
| 306 | +modification, Inferno can append a secure MD5 or SHA hash (called a digest), | |
| 307 | +.P1 | |
| 308 | +hash(secret, message, messageid) | |
| 309 | +.P2 | |
| 310 | +to each message. | |
| 311 | +.I "Messageid" | |
| 312 | +is a 32 bit number that starts at 0 and is incremented by | |
| 313 | +one for each message sent. Thus messages can be neither | |
| 314 | +changed, removed, reordered or inserted into the stream without knowing | |
| 315 | +the secret or breaking the secure hash algorithm. | |
| 316 | +.LP | |
| 317 | +To secure against snooping, Inferno supports encryption of the complete conversation | |
| 318 | +using either RC4 or DES with either DES chain block coding (DESCBC) | |
| 319 | +and electronic code book (DESECB). | |
| 320 | +.LP | |
| 321 | +Inferno uses the same encapsulation format as Netscape's Secure Sockets Layer [7]. | |
| 322 | +It is possible to encapsulate | |
| 323 | +a message stream in multiple encapsulations to provide varying degrees of | |
| 324 | +security. | |
| 325 | +.SH | |
| 326 | +Random Numbers | |
| 327 | +.LP | |
| 328 | +The strength of cryptographic algorithms depends in part on strength | |
| 329 | +of the random numbers | |
| 330 | +used for choosing keys, Diffie-Hellman parameters, initialization vectors, etc. | |
| 331 | +Inferno achieves this in two steps: a slow (100 to 200 bit | |
| 332 | +per second) random bit stream comes from sampling the low order bits of a | |
| 333 | +free running counter whenever a clock ticks. The clock must be unsynchronized, | |
| 334 | +or at least poorly synchronized, with the counter. This generator is then used to | |
| 335 | +alter the state of a faster pseudo-random number generator. | |
| 336 | +Both the slow and fast generators were tested on a number of architectures | |
| 337 | +using self correlation, random walk, and repeatability tests. | |
| 338 | +.SH | |
| 339 | +Introduction to Limbo | |
| 340 | +.LP | |
| 341 | +Limbo is the application programming language for the Inferno operating system. Although Limbo looks syntactically like C, it has a number of features that make it easier to use, safer, and more suited to the heterogeneous, networked Inferno environment: a rich set of basic types, strong typing, garbage collection, concurrency, communications, and modules. Limbo may be interpreted or compiled `just in time' for efficient, portable execution. | |
| 342 | +.LP | |
| 343 | +This paper introduces the language by studying an example of a complete, useful Limbo program. The program illustrates general programming as well as aspects of concurrency, graphics, module loading, and other features of Limbo and Inferno. | |
| 344 | +.SH | |
| 345 | +The problem | |
| 346 | +.LP | |
| 347 | +Our example program is a stripped-down version of the Inferno[14] program | |
| 348 | +.CW "view" , | |
| 349 | +which displays graphical image files on the screen, one per window. This version sacrifices some functionality, generality, and error-checking but performs the basic job. The files may be in either GIF[12, 13] or JPEG[19] format and must be converted before display, or they may already be in the Inferno standard format that needs no conversion. | |
| 350 | +.CW "View" | |
| 351 | +`sniffs' each file to determine what processing it requires, maps the colors if necessary, creates a new window, and copies the converted image to it. Each window is given a title bar across the top to identify it and hold the buttons to move and delete the window. | |
| 352 | +.SH | |
| 353 | +The Source | |
| 354 | +.LP | |
| 355 | +Here is the complete Limbo source for our version of | |
| 356 | +.CW "view" , | |
| 357 | +annotated with line numbers for easy reference (Limbo, of course, does not use line numbers). Subsequent sections explain the workings of the program. Although the program is too large to absorb as a first example without some assistance, it's worth skimming before moving to the next section, to get an idea of the style of the language. Control syntax derives from C[11], while declaration syntax comes from the Pascal family of languages[17]. Limbo borrows features from a number of languages (e.g., tuples on lines 45 and 48) and introduces a few new ones (e.g. explicit module loading on lines 90 and 92). | |
| 358 | +.P1 | |
| 359 | + 1 implement View; | |
| 360 | +.P3 | |
| 361 | + 2 include "sys.m"; | |
| 362 | + 3 sys: Sys; | |
| 363 | +.P3 | |
| 364 | + 4 include "draw.m"; | |
| 365 | + 5 draw: Draw; | |
| 366 | + 6 Rect, Display, Image: import draw; | |
| 367 | +.P3 | |
| 368 | + 7 include "bufio.m"; | |
| 369 | +.P3 | |
| 370 | + 8 include "imagefile.m"; | |
| 371 | +.P3 | |
| 372 | + 9 include "tk.m"; | |
| 373 | +10 tk: Tk; | |
| 374 | +.P3 | |
| 375 | +11 include "wmlib.m"; | |
| 376 | +12 wmlib: Wmlib; | |
| 377 | +.P3 | |
| 378 | +13 include "string.m"; | |
| 379 | +14 str: String; | |
| 380 | +.P3 | |
| 381 | +15 View: module | |
| 382 | +16 { | |
| 383 | +17 init: fn(ctxt: ref Draw->Context, | |
| 384 | + argv: list of string); | |
| 385 | +18 }; | |
| 386 | +.P3 | |
| 387 | +19 init(ctxt: ref Draw->Context, | |
| 388 | + argv: list of string) | |
| 389 | +20 { | |
| 390 | +21 sys = load Sys Sys->PATH; | |
| 391 | +22 draw = load Draw Draw->PATH; | |
| 392 | +23 tk = load Tk Tk->PATH; | |
| 393 | +24 wmlib = load Wmlib Wmlib->PATH; | |
| 394 | +25 str = load String String->PATH; | |
| 395 | +26 wmlib->init(); | |
| 396 | +.P3 | |
| 397 | +27 imageremap := load Imageremap | |
| 398 | + Imageremap->PATH; | |
| 399 | +28 bufio := load Bufio Bufio->PATH; | |
| 400 | +.P3 | |
| 401 | +29 argv = tl argv; | |
| 402 | +30 if(argv != nil | |
| 403 | + && str->prefix("-x ", hd argv)) | |
| 404 | +31 argv = tl argv; | |
| 405 | +.P3 | |
| 406 | +32 viewer := 0; | |
| 407 | +33 while(argv != nil){ | |
| 408 | +34 file := hd argv; | |
| 409 | +35 argv = tl argv; | |
| 410 | +.P3 | |
| 411 | +36 im := ctxt.display.open(file); | |
| 412 | +37 if(im == nil){ | |
| 413 | +38 idec := filetype(file); | |
| 414 | +39 if(idec == nil) | |
| 415 | +40 continue; | |
| 416 | +.P3 | |
| 417 | +41 fd := bufio->open(file, | |
| 418 | + Bufio->OREAD); | |
| 419 | +42 if(fd == nil) | |
| 420 | +43 continue; | |
| 421 | +.P3 | |
| 422 | +44 idec->init(bufio); | |
| 423 | +45 (ri, err) := idec->read(fd); | |
| 424 | +46 if(ri == nil) | |
| 425 | +47 continue; | |
| 426 | +.P3 | |
| 427 | +48 (im, err) = imageremap->remap( | |
| 428 | + ri, ctxt.display, 1); | |
| 429 | +49 if(im == nil) | |
| 430 | +50 continue; | |
| 431 | +51 } | |
| 432 | +.P3 | |
| 433 | +52 spawn view(ctxt, im, file, | |
| 434 | + viewer++); | |
| 435 | +53 } | |
| 436 | +54 } | |
| 437 | +.P3 | |
| 438 | +55 view(ctxt: ref Draw->Context, | |
| 439 | + im: ref Image, file: string, | |
| 440 | + viewer: int) | |
| 441 | +56 { | |
| 442 | +57 corner := string(25+20*(viewer%5)); | |
| 443 | +.P3 | |
| 444 | +58 (nil, file) = str->splitr(file, "/"); | |
| 445 | +59 (t, menubut) := wmlib->titlebar(ctxt.screen, | |
| 446 | + " -x "+corner+" -y "+corner+ | |
| 447 | + " -bd 2 -relief raised", | |
| 448 | + "View: "+file, Wmlib->Hide); | |
| 449 | +.P3 | |
| 450 | +60 event := chan of string; | |
| 451 | +61 tk->namechan(t, event, "event"); | |
| 452 | +.P3 | |
| 453 | +62 tk->cmd(t, "frame .im -height " + | |
| 454 | + string im.r.dy() + | |
| 455 | + " -width " + | |
| 456 | + string im.r.dx()); | |
| 457 | +63 tk->cmd(t, "bind . <Configure> "+ | |
| 458 | + "{send event resize}"); | |
| 459 | +64 tk->cmd(t, "bind . <Map> "+ | |
| 460 | + "{send event resize}"); | |
| 461 | +65 tk->cmd(t, "pack .im -side bottom"+ | |
| 462 | + " -fill both -expand 1"); | |
| 463 | +66 tk->cmd(t, "update"); | |
| 464 | +.P3 | |
| 465 | +67 t.image.draw(posn(t), im, ctxt.display.ones, im.r.min); | |
| 466 | +68 for(;;) alt{ | |
| 467 | +69 menu := <-menubut => | |
| 468 | +70 if(menu == "exit") | |
| 469 | +71 return; | |
| 470 | +72 wmlib->titlectl(t, menu); | |
| 471 | +73 <-event => | |
| 472 | +74 t.image.draw(posn(t), im, | |
| 473 | + ctxt.display.ones, im.r.min); | |
| 474 | +75 } | |
| 475 | +76 } | |
| 476 | +.P3 | |
| 477 | +77 posn(t: ref Tk->Toplevel): Rect | |
| 478 | +78 { | |
| 479 | +79 minx := int tk->cmd(t, | |
| 480 | + ".im cget -actx"); | |
| 481 | +80 miny := int tk->cmd(t, | |
| 482 | + ".im cget -acty"); | |
| 483 | +81 maxx := minx + int tk->cmd(t, | |
| 484 | + ".im cget -actwidth"); | |
| 485 | +82 maxy := miny + int tk->cmd(t, | |
| 486 | + ".im cget -actheight"); | |
| 487 | +.P3 | |
| 488 | +83 return ((minx, miny), (maxx, maxy)); | |
| 489 | +84 } | |
| 490 | +.P3 | |
| 491 | +85 filetype(file: string): RImagefile | |
| 492 | +86 { | |
| 493 | +87 if(len file>4 | |
| 494 | + && file[len file-4:]==".gif") | |
| 495 | +88 r := load RImagefile | |
| 496 | + RImagefile->READGIFPATH; | |
| 497 | +89 if(len file>4 | |
| 498 | + && file[len file-4:]==".jpg") | |
| 499 | +90 r = load RImagefile | |
| 500 | + RImagefile->READJPGPATH; | |
| 501 | +91 return r; | |
| 502 | +92 } | |
| 503 | +.P2 | |
| 504 | +.SH | |
| 505 | +Modules | |
| 506 | +.LP | |
| 507 | +Limbo programs are composed of modules that are loaded and linked at run-time. Each Limbo source file is the implementation of a single module; here line 1 states this file implements a module called | |
| 508 | +.CW "View" , | |
| 509 | +whose declaration appears in the | |
| 510 | +.CW "module" | |
| 511 | +declaration on lines 15-18. The declaration states that the module has one publicly visible element, the function | |
| 512 | +.CW "init" . | |
| 513 | +Other functions and variables defined in the file will be compiled into the module but only accessible internally. | |
| 514 | +.LP | |
| 515 | +The function | |
| 516 | +.CW "init" | |
| 517 | +has a type signature (argument and return types) that makes it callable from the Inferno shell, a convention not made explicit here. The type of | |
| 518 | +.CW "init" | |
| 519 | +allows | |
| 520 | +.CW "View" | |
| 521 | +to be invoked by typing, for example, | |
| 522 | +.P1 | |
| 523 | +view *.jpg | |
| 524 | +.P2 | |
| 525 | +at the Inferno command prompt to view all the JPEG files in a directory. This interface is all that is required for the module to be callable from the shell; all programs are constructed from modules, and some modules are directly callable by the shell because of their type. In fact the shell invokes | |
| 526 | +.CW "View" | |
| 527 | +by loading it and calling | |
| 528 | +.CW "init" , | |
| 529 | +not for example through the services of a system | |
| 530 | +.CW "exec" | |
| 531 | +function as in a traditional operating system. | |
| 532 | +.LP | |
| 533 | +Not all modules, of course, implement shell commands; modules are also used to construct libraries, services, and other program components. The module | |
| 534 | +.CW "View" | |
| 535 | +uses the services of other modules for I/O, graphics, file format conversion, and string processing. These modules are identified on lines 2-14. Each module's interface is stored in a public `include file' that holds a definition of a module much like lines 15-18 of the | |
| 536 | +.CW "View" | |
| 537 | +program. For example, here is an excerpt from the include file | |
| 538 | +.CW "sys.m" : | |
| 539 | +.P1 | |
| 540 | +Sys: module | |
| 541 | +{ | |
| 542 | + PATH: con "$Sys"; | |
| 543 | + | |
| 544 | + FD: adt # File descriptor | |
| 545 | + { | |
| 546 | + fd: int; | |
| 547 | + }; | |
| 548 | + | |
| 549 | + OREAD: con 0; | |
| 550 | + OWRITE: con 1; | |
| 551 | + ORDWR: con 2; | |
| 552 | + | |
| 553 | + open: fn(s: string, mode: int): ref FD; | |
| 554 | + print: fn(s: string, *): int; | |
| 555 | + read: fn(fd: ref FD, buf: array of byte, n: int): int; | |
| 556 | + write: fn(fd: ref FD, buf: array of byte, n: int): int; | |
| 557 | +}; | |
| 558 | +.P2 | |
| 559 | +This defines a module type, called | |
| 560 | +.CW "Sys" , | |
| 561 | +that has functions with familiar names like | |
| 562 | +.CW "open" | |
| 563 | +and | |
| 564 | +.CW "print" , | |
| 565 | +constants like | |
| 566 | +.CW "OREAD" | |
| 567 | +to specify the mode for opening a file, an aggregate type | |
| 568 | +.CW "adt" ) ( | |
| 569 | +called | |
| 570 | +.CW "FD" , | |
| 571 | +returned by | |
| 572 | +.CW "open" , | |
| 573 | +and a constant string called | |
| 574 | +.CW "PATH" . | |
| 575 | +.LP | |
| 576 | +After including the definition of each module, | |
| 577 | +.CW "View" | |
| 578 | +declares variables to access the module. Line 3, for example, declares the variable | |
| 579 | +.CW "sys" | |
| 580 | +to have type | |
| 581 | +.CW "Sys" ; | |
| 582 | +it will be used to hold a reference to the implementation of the module. Line 6 imports a number of types from the | |
| 583 | +.CW "draw" | |
| 584 | +(graphics) module to simplify their use; this line states that the implementation of these types is by default to be that provided by the module referenced by the variable | |
| 585 | +.CW "draw" . | |
| 586 | +Without such an | |
| 587 | +.CW "import" | |
| 588 | +statement, calls to methods of these types would require explicit mention of the module providing the implementation. | |
| 589 | +.LP | |
| 590 | +Unlike most module languages, which resolve unbound references to modules automatically, Limbo requires explicit `loading' of module implementations. | |
| 591 | +Although this requires more bookkeeping, it allows a program to have fine control over the loading (and unloading) of modules, an important property in the small-memory systems in which Inferno is intended to run. | |
| 592 | +Also, it allows easy garbage collection of unused modules and allows multiple implementations to serve a single interface, a style of programming we will exploit in | |
| 593 | +.CW "View" . | |
| 594 | +.LP | |
| 595 | +Declaring a module variable such as | |
| 596 | +.CW "sys" | |
| 597 | +is not sufficient to access a module; an implementation must also be loaded and bound to the variable. Lines 21-25 load the implementations of the standard modules used by | |
| 598 | +.CW "View" . | |
| 599 | +The | |
| 600 | +.CW "load" | |
| 601 | +operator, for example | |
| 602 | +.P1 | |
| 603 | +sys = load Sys Sys->PATH; | |
| 604 | +.P2 | |
| 605 | +takes a type | |
| 606 | +.CW "Sys" ), ( | |
| 607 | +the file name of the implementation | |
| 608 | +.CW "Sys->PATH" ), ( | |
| 609 | +and loads it into memory. If the implementation matches the specified type, a reference to the implementation is returned and stored in the variable | |
| 610 | +.CW "sys" ). ( | |
| 611 | +If not, the constant | |
| 612 | +.CW "nil" | |
| 613 | +will be returned to indicate an error. Conventionally, the | |
| 614 | +.CW "PATH" | |
| 615 | +constant defined by a module names the default implementation. Because | |
| 616 | +.CW "Sys" | |
| 617 | +is a built-in module provided by the system, it has a special form of name; other modules' | |
| 618 | +.CW "PATH" | |
| 619 | +variables name files containing actual code. For example, | |
| 620 | +.CW "Wmlib->PATH" | |
| 621 | +is \f5"/dis/lib/wmlib.dis"\fP. | |
| 622 | +Note, though, that the name of the implementation of the module in a | |
| 623 | +.CW "load" | |
| 624 | +statement can be any string. | |
| 625 | +.LP | |
| 626 | +Line 26 initializes the | |
| 627 | +.CW "wmlib" | |
| 628 | +module by invoking its | |
| 629 | +.CW "init" | |
| 630 | +function (unrelated to the | |
| 631 | +.CW "init" | |
| 632 | +of | |
| 633 | +.CW "View" ). | |
| 634 | +Note the use of the | |
| 635 | +.CW "->" | |
| 636 | +operator to access the member function of the module. The next two lines load modules, but add a new wrinkle: they also | |
| 637 | +.I "declare" | |
| 638 | +and | |
| 639 | +.I "initialize" | |
| 640 | +the module variables storing the reference. Limbo declarations have the general form | |
| 641 | +.P1 | |
| 642 | +\fIvar\fP: \fItype\fP = \fIvalue\fP; | |
| 643 | +.P2 | |
| 644 | +If the type is missing, it is taken to be the type of the value, so for example, | |
| 645 | +.P1 | |
| 646 | +bufio := load Bufio Bufio->PATH; | |
| 647 | +.P2 | |
| 648 | +on line 28 declares a variable of type | |
| 649 | +.CW "Bufio" | |
| 650 | +and initializes it to the result of the | |
| 651 | +.CW "load" | |
| 652 | +expression. | |
| 653 | +.SH | |
| 654 | +The main loop | |
| 655 | +.LP | |
| 656 | +The | |
| 657 | +.CW "init" | |
| 658 | +function takes two parameters, a graphics context, | |
| 659 | +.CW "ctxt" , | |
| 660 | +for the program and a list of command-line argument strings, | |
| 661 | +.CW "argv" . | |
| 662 | +.CW "Argv" | |
| 663 | +is a | |
| 664 | +.CW "list" | |
| 665 | +.CW "of" | |
| 666 | +.CW "string" ; | |
| 667 | +strings are a built-in type in Limbo and lists are a built-in form of constructor. Lists have several operations defined: | |
| 668 | +.CW "hd" | |
| 669 | +(head) returns the first element in the list, | |
| 670 | +.CW "tl" | |
| 671 | +(tail) the remainder after the head, and | |
| 672 | +.CW "len" | |
| 673 | +(length) the number of elements in the list. | |
| 674 | +.LP | |
| 675 | +Line 29 throws away the first element of | |
| 676 | +.CW "argv" , | |
| 677 | +which is conventionally the name of the program being invoked by the shell, and lines 30-31 ignore a geometry argument passed by the window system. The loop from lines 33 to 53 processes each file named in the remaining arguments; when | |
| 678 | +.CW "argv" | |
| 679 | +is a | |
| 680 | +.CW "nil" | |
| 681 | +list, the loop is complete. Line 34 picks off the next file name and line 35 updates the list. | |
| 682 | +.LP | |
| 683 | +Line 36 is the first method call we have seen: | |
| 684 | +.P1 | |
| 685 | +im := ctxt.display.open(file); | |
| 686 | +.P2 | |
| 687 | +The parameter | |
| 688 | +.CW "ctxt" | |
| 689 | +is an | |
| 690 | +.CW "adt" | |
| 691 | +that contains all the relevant information for the program to access its graphics environment. One of its elements, called | |
| 692 | +.CW "display" , | |
| 693 | +represents the connection to the frame buffer on which the program may write. The | |
| 694 | +.CW "adt" | |
| 695 | +.CW "display" | |
| 696 | +(whose type is imported on line 6) has a member function | |
| 697 | +.CW "open" | |
| 698 | +that reads a named image file into the memory associated with the frame buffer, returning a reference to the new image. (In X[20] terminology, | |
| 699 | +.CW "display" | |
| 700 | +represents a connection to the server and | |
| 701 | +.CW "open" | |
| 702 | +reads a pixmap from a file and instantiates it on that server.) | |
| 703 | +.LP | |
| 704 | +The | |
| 705 | +.CW "display.open" | |
| 706 | +method succeeds only if the file exists and is in the standard Inferno image format. If it fails, it will return | |
| 707 | +.CW "nil" | |
| 708 | +and lines 38-50 will attempt to convert the file into the right form. | |
| 709 | +.SH | |
| 710 | +Decoding the file | |
| 711 | +.LP | |
| 712 | +Line 38 calls | |
| 713 | +.CW "filetype" | |
| 714 | +to determine what format the file has. The simple version here, on lines 85-92, just looks at the file suffix to determine the type. A realistic implementation would work harder, but even this version illustrates the utility of program-controlled loading of modules. | |
| 715 | +.LP | |
| 716 | +The decoding interface for an image file format is specified by the module type | |
| 717 | +.CW "RImagefile" . | |
| 718 | +However, unlike the other modules we have looked at, | |
| 719 | +.CW "RImagefile" | |
| 720 | +has a number of implementations. If the file is a GIF file, | |
| 721 | +.CW "filetype" | |
| 722 | +returns the implementation of | |
| 723 | +.CW "RImagefile" | |
| 724 | +that decodes GIFs; if it is a JPEG file, | |
| 725 | +.CW "filetype" | |
| 726 | +returns an implementation that decodes JPEGs. In either case, the | |
| 727 | +.CW "read" | |
| 728 | +method has the same interface. Since reference variables like | |
| 729 | +.CW "r" | |
| 730 | +are implicitly initialized to | |
| 731 | +.CW "nil" , | |
| 732 | +that is what | |
| 733 | +.CW "filetype" | |
| 734 | +will return if it does not recognize the image format. | |
| 735 | +.LP | |
| 736 | +Thus, | |
| 737 | +.CW "filetype" | |
| 738 | +accepts a file name and returns the implementation of a module to decode it. | |
| 739 | +.LP | |
| 740 | +A couple of other points about | |
| 741 | +.CW "filetype" . | |
| 742 | +First, the expression | |
| 743 | +.CW "file[len file-4:]" | |
| 744 | +is a | |
| 745 | +.I "slice" | |
| 746 | +of the string | |
| 747 | +.CW "file" ; | |
| 748 | +it creates a string holding the last four characters of the file name. The colon separates the starting and ending indices of the slice; the missing second index defaults to the end of the string. As with lists, | |
| 749 | +.CW "len" | |
| 750 | +returns the number of characters (not bytes; Limbo uses Unicode[21] throughout) in the string. | |
| 751 | +.LP | |
| 752 | +Second, and more important, this version of | |
| 753 | +.CW "filetype" | |
| 754 | +loads the decoder module anew every time it is called, which is clearly inefficient. It's easy to do better, though: just store the module in a global, as in this fragment: | |
| 755 | +.P1 | |
| 756 | +readjpg: RImagefile; | |
| 757 | +filetype(...)... | |
| 758 | +{ | |
| 759 | + if(isjpg()){ | |
| 760 | + if(readjpg == nil) | |
| 761 | + readjpg = load RImagefile | |
| 762 | + RImagefile->READJPGPATH; | |
| 763 | + return readjpg; | |
| 764 | + } | |
| 765 | +} | |
| 766 | +.P2 | |
| 767 | +The program can form its own policies on loading and unloading modules based on time/space or other tradeoffs; the system does not impose its own. | |
| 768 | +.LP | |
| 769 | +Returning to the main loop, after the type of the file has been discovered, line 41 opens the file for I/O using the buffered I/O package. Line 44 calls the | |
| 770 | +.CW "init" | |
| 771 | +function of the decoder module, passing it the instance of the buffered I/O module being used (if we were caching decoder modules, this call to | |
| 772 | +.CW "init" | |
| 773 | +would be done only when the decoder is first loaded.) Finally, the Limbo-characteristic line 45 reads in the file: | |
| 774 | +.P1 | |
| 775 | +(ri, err) := idec->read(fd); | |
| 776 | +.P2 | |
| 777 | +The | |
| 778 | +.CW "read" | |
| 779 | +method of the decoder does the hard job of cracking the image format, which is beyond the scope of this paper. The result is a | |
| 780 | +.I "tuple" : | |
| 781 | +a pair of values. The first element of the pair is the image, while the second is an error string. If all goes well, the | |
| 782 | +.CW "err" | |
| 783 | +will be | |
| 784 | +.CW "nil" ; | |
| 785 | +if there is a problem, however, | |
| 786 | +.CW "err" | |
| 787 | +may be printed by the application to report what went wrong. The interesting property of this style of error reporting, common to Limbo programs, is that an error can be returned even if the decoding was successful (that is, even if | |
| 788 | +.CW "ri" | |
| 789 | +is non- | |
| 790 | +.CW "nil" ). | |
| 791 | +For example, the error may be recoverable, in which case it is worth returning the result but also worth reporting that an error did occur, leaving the application to decide whether to display the error or ignore it. | |
| 792 | +.CW "View" "\ " ( | |
| 793 | +ignores it, for brevity.) | |
| 794 | +.LP | |
| 795 | +In a similar manner, line 48 remaps the colors from the incoming colormap associated with the file to the standard Inferno color map. The result is an image ready to be displayed. | |
| 796 | +.SH | |
| 797 | +Creating a process | |
| 798 | +.LP | |
| 799 | +By line 52 in the main loop, we have an image ready in the variable | |
| 800 | +.CW "im" | |
| 801 | +and use the Limbo primitive | |
| 802 | +.CW "spawn" | |
| 803 | +to create a new process to display that image on the screen. | |
| 804 | +.CW "Spawn" | |
| 805 | +operates on a function call, creating a new process to execute that function. The process doing the spawning, here the main loop, continues immediately, while the new process begins execution in the specified function with the specified parameters. Thus line 52 begins a new process in the function | |
| 806 | +.CW "view" | |
| 807 | +with arguments the graphics context, the image to display, the file name, and a unique identification number used in placing the windows. | |
| 808 | +.LP | |
| 809 | +The new process shares with the calling process all variables except the stack. Shared memory can therefore be used to communicate between them; for synchronization, a more sophisticated mechanism is needed, a subject we will cover in the section on communications. | |
| 810 | +.SH | |
| 811 | +Starting Tk | |
| 812 | +.LP | |
| 813 | +The function | |
| 814 | +.CW "view" | |
| 815 | +uses the Inferno Tk graphics toolkit (a re-implementation for Limbo of Ousterhout's Tcl/Tk toolkit [18]) to place the image on the screen in a new window. Line 57 computes the position of the corner of the window, using the viewer number to stagger the positions of successive windows. The | |
| 816 | +.CW "string" | |
| 817 | +keyword is a conversion; in this example the conversion does an automatic translation from an integer expression into a decimal representation of the number. Thus | |
| 818 | +.CW "corner" | |
| 819 | +is a string variable, a form more useful in the calls to the Tk library. | |
| 820 | +.LP | |
| 821 | +The Inferno Tk implementation uses Limbo as its controlling language. | |
| 822 | +Rather than building a rich procedural interface, the interface passes strings to a generic Tk command processor, which returns strings as results. | |
| 823 | +This is similar to the use Tk within Tcl, but with most of the control flow, arithmetic, and so on written in Limbo. | |
| 824 | +.LP | |
| 825 | +A good introduction to the style is the function | |
| 826 | +.CW "posn" | |
| 827 | +on lines 77-84. The calls to | |
| 828 | +.CW "tk->cmd" | |
| 829 | +evaluate the textual command in the context defined by the | |
| 830 | +.CW "Tk->Toplevel" | |
| 831 | +variable | |
| 832 | +.CW "t" | |
| 833 | +(created on line 57 and passed to | |
| 834 | +.CW "posn" ); | |
| 835 | +the result is a decimal integer, converted to binary by the explicit | |
| 836 | +.CW "int" | |
| 837 | +conversion. On line 83, all the coordinates of the rectangle are known, and the function returns a nested tuple defining the rectangular position of the | |
| 838 | +.CW ".im" | |
| 839 | +component of the Toplevel. This tuple is automatically promoted to the | |
| 840 | +.CW "Rect" | |
| 841 | +type by the return statement. | |
| 842 | +.LP | |
| 843 | +Back in function | |
| 844 | +.CW "view" , | |
| 845 | +line 58 uses a function from the higher-level | |
| 846 | +.CW "String" | |
| 847 | +module to strip off the basename of the file name, for use in the banner of the window. Note that one component of the tuple is nil; the value of this component is discarded. | |
| 848 | +Line 58 calls the window manager function | |
| 849 | +.CW "wmlib->titlebar" | |
| 850 | +to establish a title bar on the window | |
| 851 | +The arguments are | |
| 852 | +.CW "ctxt.screen" , | |
| 853 | +a data structure representing the window stack on the frame buffer, | |
| 854 | +a string specifying the size and properties of the new window, the window's | |
| 855 | +label, and the set of control buttons required. | |
| 856 | +The | |
| 857 | +.CW "+" | |
| 858 | +operator on strings performs concatenation. | |
| 859 | +The window is labelled \f5"View"\fP | |
| 860 | +and the file basename, with a control button to hide the window. | |
| 861 | +Titlebars always include a control button to dismiss the window. | |
| 862 | +(The size and properties argument is more commonly nil or the empty string, | |
| 863 | +leaving the choice of position and style to the window manager.) | |
| 864 | +The first value | |
| 865 | +in the tuple returned by | |
| 866 | +.CW "wmlib->titlebar" | |
| 867 | +is a reference to a `top-level' widget\-a window\-upon which the program will assemble its display. | |
| 868 | +.SH | |
| 869 | +Communications | |
| 870 | +.LP | |
| 871 | +The second value in the tuple | |
| 872 | +returned from | |
| 873 | +.CW "wmlib->titlebar" | |
| 874 | +is a built-in Limbo type called a channel | |
| 875 | +.CW "chan" "" ( | |
| 876 | +is the keyword). A channel is a communications mechanism in the manner of Hoare's CSP[15]. Two processes that wish to communicate do so using a shared channel; data sent on the channel by one process may be received by another process. The communication is | |
| 877 | +.I "synchronous" : | |
| 878 | +both processes must be ready to communicate before the data changes hands, and if one is not ready the other blocks until it is. Channels are a feature of the Limbo language: they have a declared type | |
| 879 | +.CW "chan" "" ( | |
| 880 | +.CW "of" | |
| 881 | +.CW "int" , | |
| 882 | +.CW "chan" | |
| 883 | +.CW "of" | |
| 884 | +.CW "list" | |
| 885 | +.CW "of" | |
| 886 | +.CW "string" , | |
| 887 | +etc.) and only data of the correct type may be sent. There is no restriction on what may be sent; one may even send a channel on a channel. Channels therefore serve both to communicate and to synchronize. | |
| 888 | +.LP | |
| 889 | +Channels are used throughout Inferno to provide interfaces to system functions. The threading and communications primitives in Limbo are not designed to implement efficient multicomputer algorithms, but rather to provide an elegant way to build active interfaces to devices and other programs. | |
| 890 | +.LP | |
| 891 | +One example is the | |
| 892 | +.CW "menubut" | |
| 893 | +channel returned by | |
| 894 | +.CW "wmlib->titlebar" , | |
| 895 | +a channel of textual commands sent by the window manager. The expression on line 69, | |
| 896 | +.P1 | |
| 897 | +menu := <-menubut | |
| 898 | +.P2 | |
| 899 | +receives the next message on the channel and assigns it to the variable menu. The communications operator, | |
| 900 | +.CW "<-" , | |
| 901 | +receives a datum when prefixed to channel and transmits a datum when combined with an assignment operator (e.g. | |
| 902 | +.CW "channel<-=2" ). | |
| 903 | +This use of menubut appears inside an | |
| 904 | +.CW "alt" | |
| 905 | +(alternation) statement, a construct we'll discuss later. | |
| 906 | +.LP | |
| 907 | +Lines 60 and 61 create and register a new channel, | |
| 908 | +.CW "event" , | |
| 909 | +to be used by the Tk module to report user interface events. Lines 62-66 use simple Tk operations to make the window in which the image may be drawn. Lines 63 and 64 bind events within this window to messages to be sent on the channel | |
| 910 | +.CW "event" . | |
| 911 | +For example, line 63 defines that when the configuration of the window is changed, presumably by actions of the window manager, the string | |
| 912 | +\f5"resize"\fP | |
| 913 | +is to be transmitted on | |
| 914 | +.CW "event" | |
| 915 | +for interpretation by the application. This translation of events into messages on explicit channels is fundamental to the Limbo style of programming. | |
| 916 | +.SH | |
| 917 | +Displaying the image | |
| 918 | +.LP | |
| 919 | +The payoff occurs on line 67, which steps outside the Tk model to draw the image | |
| 920 | +.CW "im" | |
| 921 | +directly on the window: | |
| 922 | +.P1 | |
| 923 | +t.image.draw(posn(t), im, ctxt.display.ones, im.r.min); | |
| 924 | +.P2 | |
| 925 | +.CW "Posn" | |
| 926 | +calculates where on the screen the image is to go. The | |
| 927 | +.CW "draw" | |
| 928 | +method is the fundamental graphics operation in Inferno, whose design is outside our scope here. In this statement, it just copies the pixels from | |
| 929 | +.CW "im" | |
| 930 | +to the window's own image, | |
| 931 | +.CW "t.image" ; | |
| 932 | +the argument | |
| 933 | +.CW "ctxt.display.ones" | |
| 934 | +is a mask that selects every pixel. | |
| 935 | +.SH | |
| 936 | +Multi-way communications | |
| 937 | +.LP | |
| 938 | +Once the image is on the screen, | |
| 939 | +.CW "view" | |
| 940 | +waits for any changes in the status of the window. Two things may happen: either the buttons on the title bar may be used, in which case a message will appear on | |
| 941 | +.CW "menubut" , | |
| 942 | +or a configuration or mapping operation will apply to the window, in which case a message will appear on | |
| 943 | +.CW "event" . | |
| 944 | +.LP | |
| 945 | +The Limbo | |
| 946 | +.CW "alt" | |
| 947 | +statement provides control when more than one communication may proceed. Analogous to a | |
| 948 | +.CW "case" | |
| 949 | +statement, the | |
| 950 | +.CW "alt" | |
| 951 | +evaluates a set of expressions and executes the statements associated with the correct expression. Unlike a | |
| 952 | +.CW "case" , | |
| 953 | +though, the expressions in an | |
| 954 | +.CW "alt" | |
| 955 | +must each be a communication, and the | |
| 956 | +.CW "alt" | |
| 957 | +will execute the statements associated with the communication that can first proceed. If none can proceed, the | |
| 958 | +.CW "alt" | |
| 959 | +waits until one can; if more than one can proceed, it chooses one randomly. | |
| 960 | +.LP | |
| 961 | +Thus the loop on lines 68-75 processes messages received by the two classes of actions. When the window is moved or resized, line 73 will receive a \f5"resize"\fP | |
| 962 | +message due to the bindings on lines 63 and 64. The message is discarded but the action of receiving it triggers the repainting of the newly placed window on line 74. Similarly, messages triggered by buttons on the title bar send a message on | |
| 963 | +.CW "menubut" , | |
| 964 | +and the value of that is examined to see if it is | |
| 965 | +\f5"exit"\fP, | |
| 966 | +which should be handled locally, or anything else, which can be passed on to the underlying library. | |
| 967 | +.SH | |
| 968 | +Cleanup | |
| 969 | +.LP | |
| 970 | +If the exit button is pushed, line 71 will return from | |
| 971 | +.CW "view" . | |
| 972 | +Since | |
| 973 | +.CW "view" | |
| 974 | +was the top-level function in this process, the process will exit, freeing all its resources. All memory, open file descriptors, windows, and other resources held by the process will be garbage collected when the return executes. | |
| 975 | +.LP | |
| 976 | +The Limbo garbage collector [16] uses a hybrid scheme that combines reference counting to reclaim memory the instant its last reference disappears with a real-time sweeping algorithm that runs as an idle-time process to reclaim unreferenced circular structures. | |
| 977 | +The instant-free property means that system resources like file descriptors and windows can be tied to the collector for recovery as soon as they become unused; there is no pause until a sweeper discovers it. | |
| 978 | +This property allows Inferno to run in smaller memory arenas than are required for efficient mark-and-sweep algorithms, as well as providing an extra level of programmer convenience. | |
| 979 | +.SH | |
| 980 | +Summary | |
| 981 | +.LP | |
| 982 | +Inferno supplies a rich environment for constructing distributed applications that are portable\-in fact identical\-even when running on widely divergent underlying hardware. Its unique advantage over other solutions is that it encompasses not only a virtual machine, but also a complete virtual operating system including network facilities. | |
| 983 | +.SH | |
| 984 | +Acknowledgment | |
| 985 | +.LP | |
| 986 | +The cryptographic elements of Inferno owe much | |
| 987 | +to the cryptographic library of Lacy et al. [22]. | |
| 988 | +.SH | |
| 989 | +References | |
| 990 | +.LP | |
| 991 | +.nr PS -1 | |
| 992 | +.nr VS -1 | |
| 993 | +.IP 1. | |
| 994 | +R. Pike, D. Presotto, S. Dorward, B. Flandrena, K. Thompson, H. Trickey, and P. Winterbottom. ``Plan 9 from Bell Labs'', | |
| 995 | +.I "J. Computing Systems" | |
| 996 | +8:3, Summer 1995, pp. 221-254. | |
| 997 | +.IP 2. | |
| 998 | +S. Dorward, R. Pike, and P. Winterbottom. ``Programming in Limbo'', | |
| 999 | +.I "IEEE Compcon 97 Proceedings" , | |
| 1000 | +1997. | |
| 1001 | +.IP 3. | |
| 1002 | +J. K. Ousterhout. | |
| 1003 | +.I "Tcl and the Tk Toolkit" , | |
| 1004 | +Addison-Wesley, 1994. | |
| 1005 | +.IP 4. | |
| 1006 | +T. Elgamal, ``A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms'', | |
| 1007 | +.I "Advances in Cryptography: Proceedings of CRYPTO 84, " | |
| 1008 | +Springer Verlag, 1985, pp. 10-18 | |
| 1009 | +.IP 5. | |
| 1010 | +B. Schneier, ``Applied Cryptography'', Wiley, 1996, p. 516 | |
| 1011 | +.IP 6. | |
| 1012 | +D. Stinson, ``Cryptography, Theory and Practice'', | |
| 1013 | +.I "CRC Press" , | |
| 1014 | +1996, p. 271 | |
| 1015 | +.IP 7. | |
| 1016 | +K. Hickman and T. Elgamal, ``The SSL Protocol (V3.0)'', | |
| 1017 | +.I "IETF Internet-draft" | |
| 1018 | +.IP 8. | |
| 1019 | +S. M. Bellovin and M. Merritt, ``Encrypted Key Exchange: Password-Based Protocols Secure Against Dictionary Attack'', Proceedings of the 1992 IEEE Computer Society Conference on Research in Security and Privacy, 1992, pp. 72-84 | |
| 1020 | +.IP 9. | |
| 1021 | +M. Blaze, J. Feigenbaum, J. Lacy, ``Decentralized Trust Management'', | |
| 1022 | +.I "Proceedings 1996 IEEE Symposium on Security and Privacy" , | |
| 1023 | +May 1996 | |
| 1024 | +.IP 10. | |
| 1025 | +R. Rivest and B. Lampson, ``SDSI - A Simple Distributed Security Architecture'', unpublished, | |
| 1026 | +.I "http://theory.lcs.mit.edu/~rivest/sdsi10.ps" | |
| 1027 | +.IP 11. | |
| 1028 | +.I "American National Standard for Information Systems Programming Language C" , | |
| 1029 | +American National Standards Institute, X3.159-1989. | |
| 1030 | +.IP 12. | |
| 1031 | +.I "GIF Graphics Interchange Format: A standard defining a mechanism for the storage and transmission of bitmap-based graphics information" , | |
| 1032 | +CompuServe Incorporated, Columbus, OH, 1987. | |
| 1033 | +.IP 13. | |
| 1034 | +.I "GIF Graphics Interchange Format: Version 89a" , | |
| 1035 | +CompuServe Incorporated, Columbus, OH, 1990. | |
| 1036 | +.IP 14. | |
| 1037 | +S. Dorward et al., ``Inferno'', | |
| 1038 | +.I "IEEE Compcon 97 Proceedings" , | |
| 1039 | +1997. | |
| 1040 | +.IP 15. | |
| 1041 | +C. A. R. Hoare, ``Communicating Sequential Processes''. | |
| 1042 | +.I "Comm. ACM" | |
| 1043 | +21:8, pp. 666-677, 1978. | |
| 1044 | +.IP 16. | |
| 1045 | +L. Huelsbergen, and P. Winterbottom, ``Very Concurrent Mark & Sweep Garbage Collection without Fine-Grain Synchronization'', Submitted | |
| 1046 | +.I "International Conference of Functional Programming" , | |
| 1047 | +Amsterdam, 1997. | |
| 1048 | +.IP 17. | |
| 1049 | +K. Jensen, and N. Wirth, | |
| 1050 | +.I "PascalUser Manual and Report" . | |
| 1051 | +Springer-Verlag, 1974. | |
| 1052 | +.IP 18. | |
| 1053 | +John K. Ousterhout, | |
| 1054 | +.I "Tcl and the Tk Toolkit" , | |
| 1055 | +Addison-Wesley, 1994. | |
| 1056 | +.IP 19. | |
| 1057 | +W. B. Pennebaker. and J. L. Mitchell, | |
| 1058 | +.I "JPEG Still Image Data Compression" , | |
| 1059 | +Van Nostrand Reinhold, New York, 1992. | |
| 1060 | +.IP 20. | |
| 1061 | +R. W. Scheifler, J. Gettys, and R. Newman, | |
| 1062 | +.I "X Window System" , | |
| 1063 | +Digital Press, 1988. | |
| 1064 | +.IP 21. | |
| 1065 | +The Unicode Consortium, | |
| 1066 | +.I "The Unicode Standard, Version 2.0, " | |
| 1067 | +Addison Wesley, 1996. | |
| 1068 | +.IP 22. | |
| 1069 | +J. B. Lacy, D. P. Mitchell, and W. M. Schell, ``CryptoLib: Cryptography in Software,'' | |
| 1070 | +.I "UNIX Security Symposium IV Proceedings" , | |
| 1071 | +USENIX Association, 1993 pp. 1-17. | |
| 1072 | +.nr PS +1 | |
| 1073 | +.nr VS +1 | |
Binary file not shown.
Binary file not shown.
Binary file not shown.
| @@ -0,0 +1,1174 @@ | ||
| 1 | +.TL | |
| 2 | +Plan 9 C Compilers \(dg | |
| 3 | +.AU | |
| 4 | +.I "Ken Thompson" | |
| 5 | +.AI | |
| 6 | +ken@plan9.bell-labs.com | |
| 7 | +.AB | |
| 8 | +.FS | |
| 9 | +\l'1i' | |
| 10 | +.br | |
| 11 | +\(dg Originally appeared, in a different form, in | |
| 12 | +.I | |
| 13 | +Proceedings of the Summer 1990 UKUUG Conference, | |
| 14 | +.R | |
| 15 | +pp. 41-51, | |
| 16 | +London, 1990. | |
| 17 | +This version first appeared in | |
| 18 | +.I "Plan 9 Programmer's Manual, Volume 2 (Second Edition)" . | |
| 19 | +The Plan 9 compiler suite forms the basis for the portable Inferno compiler suite, | |
| 20 | +making this paper still relevant. | |
| 21 | +.FE | |
| 22 | +This paper describes the overall structure and function of the Plan 9 C compilers. | |
| 23 | +A more detailed implementation document | |
| 24 | +for any one of the compilers | |
| 25 | +is yet to be written. | |
| 26 | +.AE | |
| 27 | +.NH | |
| 28 | +Introduction | |
| 29 | +.LP | |
| 30 | +There are many compilers in the series. | |
| 31 | +Eight of the compilers (MIPS 3000, SPARC, Intel 386, AMD64, Power PC, ARM, DEC Alpha, and Motorola 68020) | |
| 32 | +are considered active and are used to compile | |
| 33 | +current versions of Plan 9 or Inferno. | |
| 34 | +Several others (Motorola 68000, Intel 960, AMD 29000) have had only limited use, such as | |
| 35 | +to program peripherals or experimental devices. | |
| 36 | +.NH | |
| 37 | +Structure | |
| 38 | +.LP | |
| 39 | +The compiler is a single program that produces an | |
| 40 | +object file. | |
| 41 | +Combined in the compiler are the traditional | |
| 42 | +roles of preprocessor, lexical analyzer, parser, code generator, | |
| 43 | +local optimizer, | |
| 44 | +and first half of the assembler. | |
| 45 | +The object files are binary forms of assembly | |
| 46 | +language, | |
| 47 | +similar to what might be passed between | |
| 48 | +the first and second passes of an assembler. | |
| 49 | +.LP | |
| 50 | +Object files and libraries | |
| 51 | +are combined by a loader | |
| 52 | +program to produce the executable binary. | |
| 53 | +The loader combines the roles of second half | |
| 54 | +of the assembler, global optimizer, and loader. | |
| 55 | +The names of the compliers, loaders, and assemblers | |
| 56 | +are as follows: | |
| 57 | +.DS | |
| 58 | +.ta 1.5i | |
| 59 | +.de Ta | |
| 60 | +\\$1 \f(CW\\$2\fP \f(CW\\$3\fP \f(CW\\$4\fP | |
| 61 | +.. | |
| 62 | +.Ta SPARC kc kl ka | |
| 63 | +.Ta PowerPC qc ql qa | |
| 64 | +.Ta MIPS vc vl va | |
| 65 | +.Ta Motorola\ 68000 1c 1l 1a | |
| 66 | +.Ta Motorola\ 68020 2c 2l 2a | |
| 67 | +.Ta ARM 5c 5l 5a | |
| 68 | +.Ta AMD64 6c 6l 6a | |
| 69 | +.Ta DEC\ Alpha 7c 7l 7a | |
| 70 | +.Ta Intel\ 386 8c 8l 8a | |
| 71 | +.Ta AMD\ 29000 9c 9l 9a | |
| 72 | +.DE | |
| 73 | +There is a further breakdown | |
| 74 | +in the source of the compilers into | |
| 75 | +object-independent and | |
| 76 | +object-dependent | |
| 77 | +parts. | |
| 78 | +All of the object-independent parts | |
| 79 | +are combined into source files in the | |
| 80 | +directory | |
| 81 | +.CW /sys/src/cmd/cc . | |
| 82 | +The object-dependent parts are collected | |
| 83 | +in a separate directory for each compiler, | |
| 84 | +for example | |
| 85 | +.CW /sys/src/cmd/vc . | |
| 86 | +All of the code, | |
| 87 | +both object-independent and | |
| 88 | +object-dependent, | |
| 89 | +is machine-independent | |
| 90 | +and may be cross-compiled and executed on any | |
| 91 | +of the architectures. | |
| 92 | +.NH | |
| 93 | +The Language | |
| 94 | +.LP | |
| 95 | +The compiler implements ANSI C with some | |
| 96 | +restrictions and extensions | |
| 97 | +[ANSI90]. | |
| 98 | +Most of the restrictions are due to | |
| 99 | +personal preference, while | |
| 100 | +most of the extensions were to help in | |
| 101 | +the implementation of Plan 9. | |
| 102 | +There are other departures from the standard, | |
| 103 | +particularly in the libraries, | |
| 104 | +that are beyond the scope of this | |
| 105 | +paper. | |
| 106 | +.NH 2 | |
| 107 | +Register, volatile, const | |
| 108 | +.LP | |
| 109 | +The keyword | |
| 110 | +.CW register | |
| 111 | +is recognized syntactically | |
| 112 | +but is semantically ignored. | |
| 113 | +Thus taking the address of a | |
| 114 | +.CW register | |
| 115 | +variable is not diagnosed. | |
| 116 | +The keyword | |
| 117 | +.CW volatile | |
| 118 | +disables all optimizations, in particular registerization, of the corresponding variable. | |
| 119 | +The keyword | |
| 120 | +.CW const | |
| 121 | +generates warnings (if warnings are enabled by the compiler's | |
| 122 | +.CW -w | |
| 123 | +option) of non-constant use of the variable, | |
| 124 | +but does not affect the generated code. | |
| 125 | +.NH 2 | |
| 126 | +The preprocessor | |
| 127 | +.LP | |
| 128 | +The C preprocessor is probably the | |
| 129 | +biggest departure from the ANSI standard. | |
| 130 | +.LP | |
| 131 | +The preprocessor built into the Plan 9 compilers does not support | |
| 132 | +.CW #if , | |
| 133 | +although it does handle | |
| 134 | +.CW #ifdef | |
| 135 | +and | |
| 136 | +.CW #include . | |
| 137 | +If it is necessary to be more standard, | |
| 138 | +the source text can first be run through the separate ANSI C | |
| 139 | +preprocessor, | |
| 140 | +.CW cpp . | |
| 141 | +.NH 2 | |
| 142 | +Unnamed substructures | |
| 143 | +.LP | |
| 144 | +The most important and most heavily used of the | |
| 145 | +extensions is the declaration of an | |
| 146 | +unnamed substructure or subunion. | |
| 147 | +For example: | |
| 148 | +.DS | |
| 149 | +.CW | |
| 150 | +.ta .1i .6i 1.1i 1.6i | |
| 151 | + typedef | |
| 152 | + struct lock | |
| 153 | + { | |
| 154 | + int locked; | |
| 155 | + } Lock; | |
| 156 | + | |
| 157 | + typedef | |
| 158 | + struct node | |
| 159 | + { | |
| 160 | + int type; | |
| 161 | + union | |
| 162 | + { | |
| 163 | + double dval; | |
| 164 | + float fval; | |
| 165 | + long lval; | |
| 166 | + }; | |
| 167 | + Lock; | |
| 168 | + } Node; | |
| 169 | + | |
| 170 | + Lock* lock; | |
| 171 | + Node* node; | |
| 172 | +.R | |
| 173 | +.DE | |
| 174 | +The declaration of | |
| 175 | +.CW Node | |
| 176 | +has an unnamed substructure of type | |
| 177 | +.CW Lock | |
| 178 | +and an unnamed subunion. | |
| 179 | +One use of this feature allows references to elements of the | |
| 180 | +subunit to be accessed as if they were in | |
| 181 | +the outer structure. | |
| 182 | +Thus | |
| 183 | +.CW node->dval | |
| 184 | +and | |
| 185 | +.CW node->locked | |
| 186 | +are legitimate references. | |
| 187 | +.LP | |
| 188 | +When an outer structure is used | |
| 189 | +in a context that is only legal for | |
| 190 | +an unnamed substructure, | |
| 191 | +the compiler promotes the reference to the | |
| 192 | +unnamed substructure. | |
| 193 | +This is true for references to structures and | |
| 194 | +to references to pointers to structures. | |
| 195 | +This happens in assignment statements and | |
| 196 | +in argument passing where prototypes have been | |
| 197 | +declared. | |
| 198 | +Thus, continuing with the example, | |
| 199 | +.DS | |
| 200 | +.CW | |
| 201 | +.ta .1i .6i 1.1i 1.6i | |
| 202 | + lock = node; | |
| 203 | +.R | |
| 204 | +.DE | |
| 205 | +would assign a pointer to the unnamed | |
| 206 | +.CW Lock | |
| 207 | +in | |
| 208 | +the | |
| 209 | +.CW Node | |
| 210 | +to the variable | |
| 211 | +.CW lock . | |
| 212 | +Another example, | |
| 213 | +.DS | |
| 214 | +.CW | |
| 215 | +.ta .1i .6i 1.1i 1.6i | |
| 216 | + extern void lock(Lock*); | |
| 217 | + func(...) | |
| 218 | + { | |
| 219 | + ... | |
| 220 | + lock(node); | |
| 221 | + ... | |
| 222 | + } | |
| 223 | +.R | |
| 224 | +.DE | |
| 225 | +will pass a pointer to the | |
| 226 | +.CW Lock | |
| 227 | +substructure. | |
| 228 | +.LP | |
| 229 | +Finally, in places where context is insufficient to identify the unnamed structure, | |
| 230 | +the type name (it must be a | |
| 231 | +.CW typedef ) | |
| 232 | +of the unnamed structure can be used as an identifier. | |
| 233 | +In our example, | |
| 234 | +.CW &node->Lock | |
| 235 | +gives the address of the anonymous | |
| 236 | +.CW Lock | |
| 237 | +structure. | |
| 238 | +.NH 2 | |
| 239 | +Structure displays | |
| 240 | +.LP | |
| 241 | +A structure cast followed by a list of expressions in braces is | |
| 242 | +an expression with the type of the structure and elements assigned from | |
| 243 | +the corresponding list. | |
| 244 | +Structures are now almost first-class citizens of the language. | |
| 245 | +It is common to see code like this: | |
| 246 | +.DS | |
| 247 | +.CW | |
| 248 | +.ta .1i | |
| 249 | + r = (Rectangle){point1, (Point){x,y+2}}; | |
| 250 | +.R | |
| 251 | +.DE | |
| 252 | +.NH 2 | |
| 253 | +Initialization indexes | |
| 254 | +.LP | |
| 255 | +In initializers of arrays, | |
| 256 | +one may place a constant expression | |
| 257 | +in square brackets before an initializer. | |
| 258 | +This causes the next initializer to assign | |
| 259 | +the indicated element. | |
| 260 | +For example: | |
| 261 | +.DS | |
| 262 | +.CW | |
| 263 | +.ta .1i .6i 1.6i | |
| 264 | + enum errors | |
| 265 | + { | |
| 266 | + Etoobig, | |
| 267 | + Ealarm, | |
| 268 | + Egreg | |
| 269 | + }; | |
| 270 | + char* errstrings[] = | |
| 271 | + { | |
| 272 | + [Ealarm] "Alarm call", | |
| 273 | + [Egreg] "Panic: out of mbufs", | |
| 274 | + [Etoobig] "Arg list too long", | |
| 275 | + }; | |
| 276 | +.R | |
| 277 | +.DE | |
| 278 | +In the same way, | |
| 279 | +individual structures members may | |
| 280 | +be initialized in any order by preceding the initialization with | |
| 281 | +.CW .tagname . | |
| 282 | +Both forms allow an optional | |
| 283 | +.CW = , | |
| 284 | +to be compatible with a proposed | |
| 285 | +extension to ANSI C. | |
| 286 | +.NH 2 | |
| 287 | +External register | |
| 288 | +.LP | |
| 289 | +The declaration | |
| 290 | +.CW extern | |
| 291 | +.CW register | |
| 292 | +will dedicate a register to | |
| 293 | +a variable on a global basis. | |
| 294 | +It can be used only under special circumstances. | |
| 295 | +External register variables must be identically | |
| 296 | +declared in all modules and | |
| 297 | +libraries. | |
| 298 | +The feature is not intended for efficiency, | |
| 299 | +although it can produce efficient code; | |
| 300 | +rather it represents a unique storage class that | |
| 301 | +would be hard to get any other way. | |
| 302 | +On a shared-memory multi-processor, | |
| 303 | +an external register is | |
| 304 | +one-per-processor and neither one-per-procedure (automatic) | |
| 305 | +or one-per-system (external). | |
| 306 | +It is used for two variables in the Plan 9 kernel, | |
| 307 | +.CW u | |
| 308 | +and | |
| 309 | +.CW m . | |
| 310 | +.CW U | |
| 311 | +is a pointer to the structure representing the currently running process | |
| 312 | +and | |
| 313 | +.CW m | |
| 314 | +is a pointer to the per-machine data structure. | |
| 315 | +.NH 2 | |
| 316 | +Long long | |
| 317 | +.LP | |
| 318 | +The compilers accept | |
| 319 | +.CW long | |
| 320 | +.CW long | |
| 321 | +as a basic type meaning 64-bit integer. | |
| 322 | +On all of the machines | |
| 323 | +this type is synthesized from 32-bit instructions. | |
| 324 | +.NH 2 | |
| 325 | +Pragma | |
| 326 | +.LP | |
| 327 | +The compilers accept | |
| 328 | +.CW #pragma | |
| 329 | +.CW lib | |
| 330 | +.I libname | |
| 331 | +and pass the | |
| 332 | +library name string uninterpreted | |
| 333 | +to the loader. | |
| 334 | +The loader uses the library name to | |
| 335 | +find libraries to load. | |
| 336 | +If the name contains | |
| 337 | +.CW $O , | |
| 338 | +it is replaced with | |
| 339 | +the single character object type of the compiler | |
| 340 | +(e.g., | |
| 341 | +.CW v | |
| 342 | +for the MIPS). | |
| 343 | +If the name contains | |
| 344 | +.CW $M , | |
| 345 | +it is replaced with | |
| 346 | +the architecture type for the compiler | |
| 347 | +(e.g., | |
| 348 | +.CW mips | |
| 349 | +for the MIPS). | |
| 350 | +If the name starts with | |
| 351 | +.CW / | |
| 352 | +it is an absolute pathname; | |
| 353 | +if it starts with | |
| 354 | +.CW . | |
| 355 | +then it is searched for in the loader's current directory. | |
| 356 | +Otherwise, the name is searched from | |
| 357 | +.CW /$M/lib . | |
| 358 | +Such | |
| 359 | +.CW #pragma | |
| 360 | +statements in header files guarantee that the correct | |
| 361 | +libraries are always linked with a program without the | |
| 362 | +need to specify them explicitly at link time. | |
| 363 | +.LP | |
| 364 | +They also accept | |
| 365 | +.CW #pragma | |
| 366 | +.CW packed | |
| 367 | +.CW on | |
| 368 | +(or | |
| 369 | +.CW yes | |
| 370 | +or | |
| 371 | +.CW 1 ) | |
| 372 | +to cause subsequently declared data, until | |
| 373 | +.CW #pragma | |
| 374 | +.CW packed | |
| 375 | +.CW off | |
| 376 | +(or | |
| 377 | +.CW no | |
| 378 | +or | |
| 379 | +.CW 0 ), | |
| 380 | +to be laid out in memory tightly packed in successive bytes, disregarding | |
| 381 | +the usual alignment rules. | |
| 382 | +Accessing such data can cause faults. | |
| 383 | +.LP | |
| 384 | +Similarly, | |
| 385 | +.CW #pragma | |
| 386 | +.CW profile | |
| 387 | +.CW off | |
| 388 | +(or | |
| 389 | +.CW no | |
| 390 | +or | |
| 391 | +.CW 0 ) | |
| 392 | +causes subsequently declared functions, until | |
| 393 | +.CW #pragma | |
| 394 | +.CW profile | |
| 395 | +.CW on | |
| 396 | +(or | |
| 397 | +.CW yes | |
| 398 | +or | |
| 399 | +.CW 1 ), | |
| 400 | +to be marked as unprofiled. | |
| 401 | +Such functions will not be profiled when | |
| 402 | +profiling is enabled for the rest of the program. | |
| 403 | +.LP | |
| 404 | +Two | |
| 405 | +.CW #pragma | |
| 406 | +statements allow type-checking of | |
| 407 | +.CW print -like | |
| 408 | +functions. | |
| 409 | +The first, of the form | |
| 410 | +.P1 | |
| 411 | +#pragma varargck argpos error 2 | |
| 412 | +.P2 | |
| 413 | +tells the compiler that the second argument to | |
| 414 | +.CW error | |
| 415 | +is a | |
| 416 | +.CW print | |
| 417 | +format string (see the manual page | |
| 418 | +.I print (2)) | |
| 419 | +that specifies how to format | |
| 420 | +.CW error 's | |
| 421 | +subsequent arguments. | |
| 422 | +The second, of the form | |
| 423 | +.P1 | |
| 424 | +#pragma varargck type "s" char* | |
| 425 | +.P2 | |
| 426 | +says that the | |
| 427 | +.CW print | |
| 428 | +format verb | |
| 429 | +.CW s | |
| 430 | +processes an argument of | |
| 431 | +type | |
| 432 | +.CW char* . | |
| 433 | +If the compiler's | |
| 434 | +.CW -F | |
| 435 | +option is enabled, the compiler will use this information | |
| 436 | +to report type violations in the arguments to | |
| 437 | +.CW print , | |
| 438 | +.CW error , | |
| 439 | +and similar routines. | |
| 440 | +.NH | |
| 441 | +Object module conventions | |
| 442 | +.LP | |
| 443 | +The overall conventions of the runtime environment | |
| 444 | +are important | |
| 445 | +to runtime efficiency. | |
| 446 | +In this section, | |
| 447 | +several of these conventions are discussed. | |
| 448 | +.NH 2 | |
| 449 | +Register saving | |
| 450 | +.LP | |
| 451 | +In the Plan 9 compilers, | |
| 452 | +the caller of a procedure saves the registers. | |
| 453 | +With caller-saves, | |
| 454 | +the leaf procedures can use all the | |
| 455 | +registers and never save them. | |
| 456 | +If you spend a lot of time at the leaves, | |
| 457 | +this seems preferable. | |
| 458 | +With callee-saves, | |
| 459 | +the saving of the registers is done | |
| 460 | +in the single point of entry and return. | |
| 461 | +If you are interested in space, | |
| 462 | +this seems preferable. | |
| 463 | +In both, | |
| 464 | +there is a degree of uncertainty | |
| 465 | +about what registers need to be saved. | |
| 466 | +Callee-saved registers make it difficult to | |
| 467 | +find variables in registers in debuggers. | |
| 468 | +Callee-saved registers also complicate | |
| 469 | +the implementation of | |
| 470 | +.CW longjmp . | |
| 471 | +The convincing argument is | |
| 472 | +that with caller-saves, | |
| 473 | +the decision to registerize a variable | |
| 474 | +can include the cost of saving the register | |
| 475 | +across calls. | |
| 476 | +For a further discussion of caller- vs. callee-saves, | |
| 477 | +see the paper by Davidson and Whalley [Dav91]. | |
| 478 | +.LP | |
| 479 | +In the Plan 9 operating system, | |
| 480 | +calls to the kernel look like normal procedure | |
| 481 | +calls, which means | |
| 482 | +the caller | |
| 483 | +has saved the registers and the system | |
| 484 | +entry does not have to. | |
| 485 | +This makes system calls considerably faster. | |
| 486 | +Since this is a potential security hole, | |
| 487 | +and can lead to non-determinism, | |
| 488 | +the system may eventually save the registers | |
| 489 | +on entry, | |
| 490 | +or more likely clear the registers on return. | |
| 491 | +.NH 2 | |
| 492 | +Calling convention | |
| 493 | +.LP | |
| 494 | +Older C compilers maintain a frame pointer, which is at a known constant | |
| 495 | +offset from the stack pointer within each function. | |
| 496 | +For machines where the stack grows towards zero, | |
| 497 | +the argument pointer is at a known constant offset | |
| 498 | +from the frame pointer. | |
| 499 | +Since the stack grows down in Plan 9, | |
| 500 | +the Plan 9 compilers | |
| 501 | +keep neither an | |
| 502 | +explicit frame pointer nor | |
| 503 | +an explicit argument pointer; | |
| 504 | +instead they generate addresses relative to the stack pointer. | |
| 505 | +.LP | |
| 506 | +On some architectures, the first argument to a subroutine is passed in a register. | |
| 507 | +.NH 2 | |
| 508 | +Functions returning structures | |
| 509 | +.LP | |
| 510 | +Structures longer than one word are awkward to implement | |
| 511 | +since they do not fit in registers and must | |
| 512 | +be passed around in memory. | |
| 513 | +Functions that return structures | |
| 514 | +are particularly clumsy. | |
| 515 | +The Plan 9 compilers pass the return address of | |
| 516 | +a structure as the first argument of a | |
| 517 | +function that has a structure return value. | |
| 518 | +Thus | |
| 519 | +.DS | |
| 520 | +.CW | |
| 521 | +.ta .1i .6i 1.1i 1.6i | |
| 522 | + x = f(...) | |
| 523 | +.R | |
| 524 | +.DE | |
| 525 | +is rewritten as | |
| 526 | +.DS | |
| 527 | +.CW | |
| 528 | +.ta .1i .6i 1.1i 1.6i | |
| 529 | + f(&x, ...)\f1. | |
| 530 | +.R | |
| 531 | +.DE | |
| 532 | +This saves a copy and makes the compilation | |
| 533 | +much less clumsy. | |
| 534 | +A disadvantage is that if you call this | |
| 535 | +function without an assignment, | |
| 536 | +a dummy location must be invented. | |
| 537 | +.LP | |
| 538 | +There is also a danger of calling a function | |
| 539 | +that returns a structure without declaring | |
| 540 | +it as such. | |
| 541 | +With ANSI C function prototypes, | |
| 542 | +this error need never occur. | |
| 543 | +.NH | |
| 544 | +Implementation | |
| 545 | +.LP | |
| 546 | +The compiler is divided internally into | |
| 547 | +four machine-independent passes, | |
| 548 | +four machine-dependent passes, | |
| 549 | +and an output pass. | |
| 550 | +The next nine sections describe each pass in order. | |
| 551 | +.NH 2 | |
| 552 | +Parsing | |
| 553 | +.LP | |
| 554 | +The first pass is a YACC-based parser | |
| 555 | +[Joh79]. | |
| 556 | +Declarations are interpreted immediately, | |
| 557 | +building a block structured symbol table. | |
| 558 | +Executable statements are put into a parse tree | |
| 559 | +and collected, | |
| 560 | +without interpretation. | |
| 561 | +At the end of each procedure, | |
| 562 | +the parse tree for the function is | |
| 563 | +examined by the other passes of the compiler. | |
| 564 | +.LP | |
| 565 | +The input stream of the parser is | |
| 566 | +a pushdown list of input activations. | |
| 567 | +The preprocessor | |
| 568 | +expansions of | |
| 569 | +macros | |
| 570 | +and | |
| 571 | +.CW #include | |
| 572 | +are implemented as pushdowns. | |
| 573 | +Thus there is no separate | |
| 574 | +pass for preprocessing. | |
| 575 | +.NH 2 | |
| 576 | +Typing | |
| 577 | +.LP | |
| 578 | +The next pass distributes typing information | |
| 579 | +to every node of the tree. | |
| 580 | +Implicit operations on the tree are added, | |
| 581 | +such as type promotions and taking the | |
| 582 | +address of arrays and functions. | |
| 583 | +.NH 2 | |
| 584 | +Machine-independent optimization | |
| 585 | +.LP | |
| 586 | +The next pass performs optimizations | |
| 587 | +and transformations of the tree, such as converting | |
| 588 | +.CW &*x | |
| 589 | +and | |
| 590 | +.CW *&x | |
| 591 | +into | |
| 592 | +.CW x . | |
| 593 | +Constant expressions are converted to constants in this pass. | |
| 594 | +.NH 2 | |
| 595 | +Arithmetic rewrites | |
| 596 | +.LP | |
| 597 | +This is another machine-independent optimization. | |
| 598 | +Subtrees of add, subtract, and multiply of integers are | |
| 599 | +rewritten for easier compilation. | |
| 600 | +The major transformation is factoring: | |
| 601 | +.CW 4+8*a+16*b+5 | |
| 602 | +is transformed into | |
| 603 | +.CW 9+8*(a+2*b) . | |
| 604 | +Such expressions arise from address | |
| 605 | +manipulation and array indexing. | |
| 606 | +.NH 2 | |
| 607 | +Addressability | |
| 608 | +.LP | |
| 609 | +This is the first of the machine-dependent passes. | |
| 610 | +The addressability of a processor is defined as the set of | |
| 611 | +expressions that is legal in the address field | |
| 612 | +of a machine language instruction. | |
| 613 | +The addressability of different processors varies widely. | |
| 614 | +At one end of the spectrum are the 68020 and VAX, | |
| 615 | +which allow a complex mix of incrementing, | |
| 616 | +decrementing, | |
| 617 | +indexing, and relative addressing. | |
| 618 | +At the other end is the MIPS, | |
| 619 | +which allows only registers and constant offsets from the | |
| 620 | +contents of a register. | |
| 621 | +The addressability can be different for different instructions | |
| 622 | +within the same processor. | |
| 623 | +.LP | |
| 624 | +It is important to the code generator to know when a | |
| 625 | +subtree represents an address of a particular type. | |
| 626 | +This is done with a bottom-up walk of the tree. | |
| 627 | +In this pass, the leaves are labeled with small integers. | |
| 628 | +When an internal node is encountered, | |
| 629 | +it is labeled by consulting a table indexed by the | |
| 630 | +labels on the left and right subtrees. | |
| 631 | +For example, | |
| 632 | +on the 68020 processor, | |
| 633 | +it is possible to address an | |
| 634 | +offset from a named location. | |
| 635 | +In C, this is represented by the expression | |
| 636 | +.CW *(&name+constant) . | |
| 637 | +This is marked addressable by the following table. | |
| 638 | +In the table, | |
| 639 | +a node represented by the left column is marked | |
| 640 | +with a small integer from the right column. | |
| 641 | +Marks of the form | |
| 642 | +.CW A\s-2\di\u\s0 | |
| 643 | +are addressable while | |
| 644 | +marks of the form | |
| 645 | +.CW N\s-2\di\u\s0 | |
| 646 | +are not addressable. | |
| 647 | +.DS | |
| 648 | +.B | |
| 649 | +.ta .1i 1.1i | |
| 650 | + Node Marked | |
| 651 | +.CW | |
| 652 | + name A\s-2\d1\u\s0 | |
| 653 | + const A\s-2\d2\u\s0 | |
| 654 | + &A\s-2\d1\u\s0 A\s-2\d3\u\s0 | |
| 655 | + A\s-2\d3\u\s0+A\s-2\d1\u\s0 N\s-2\d1\u\s0 \fR(note that this is not addressable)\fP | |
| 656 | + *N\s-2\d1\u\s0 A\s-2\d4\u\s0 | |
| 657 | +.R | |
| 658 | +.DE | |
| 659 | +Here there is a distinction between | |
| 660 | +a node marked | |
| 661 | +.CW A\s-2\d1\u\s0 | |
| 662 | +and a node marked | |
| 663 | +.CW A\s-2\d4\u\s0 | |
| 664 | +because the address operator of an | |
| 665 | +.CW A\s-2\d4\u\s0 | |
| 666 | +node is not addressable. | |
| 667 | +So to extend the table: | |
| 668 | +.DS | |
| 669 | +.B | |
| 670 | +.ta .1i 1.1i | |
| 671 | + Node Marked | |
| 672 | +.CW | |
| 673 | + &A\s-2\d4\u\s0 N\s-2\d2\u\s0 | |
| 674 | + N\s-2\d2\u\s0+N\s-2\d1\u\s0 N\s-2\d1\u\s0 | |
| 675 | +.R | |
| 676 | +.DE | |
| 677 | +The full addressability of the 68020 is expressed | |
| 678 | +in 18 rules like this, | |
| 679 | +while the addressability of the MIPS is expressed | |
| 680 | +in 11 rules. | |
| 681 | +When one ports the compiler, | |
| 682 | +this table is usually initialized | |
| 683 | +so that leaves are labeled as addressable and nothing else. | |
| 684 | +The code produced is poor, | |
| 685 | +but porting is easy. | |
| 686 | +The table can be extended later. | |
| 687 | +.LP | |
| 688 | +This pass also rewrites some complex operators | |
| 689 | +into procedure calls. | |
| 690 | +Examples include 64-bit multiply and divide. | |
| 691 | +.LP | |
| 692 | +In the same bottom-up pass of the tree, | |
| 693 | +the nodes are labeled with a Sethi-Ullman complexity | |
| 694 | +[Set70]. | |
| 695 | +This number is roughly the number of registers required | |
| 696 | +to compile the tree on an ideal machine. | |
| 697 | +An addressable node is marked 0. | |
| 698 | +A function call is marked infinite. | |
| 699 | +A unary operator is marked as the | |
| 700 | +maximum of 1 and the mark of its subtree. | |
| 701 | +A binary operator with equal marks on its subtrees is | |
| 702 | +marked with a subtree mark plus 1. | |
| 703 | +A binary operator with unequal marks on its subtrees is | |
| 704 | +marked with the maximum mark of its subtrees. | |
| 705 | +The actual values of the marks are not too important, | |
| 706 | +but the relative values are. | |
| 707 | +The goal is to compile the harder | |
| 708 | +(larger mark) | |
| 709 | +subtree first. | |
| 710 | +.NH 2 | |
| 711 | +Code generation | |
| 712 | +.LP | |
| 713 | +Code is generated by recursive | |
| 714 | +descent. | |
| 715 | +The Sethi-Ullman complexity completely guides the | |
| 716 | +order. | |
| 717 | +The addressability defines the leaves. | |
| 718 | +The only difficult part is compiling a tree | |
| 719 | +that has two infinite (function call) | |
| 720 | +subtrees. | |
| 721 | +In this case, | |
| 722 | +one subtree is compiled into the return register | |
| 723 | +(usually the most convenient place for a function call) | |
| 724 | +and then stored on the stack. | |
| 725 | +The other subtree is compiled into the return register | |
| 726 | +and then the operation is compiled with | |
| 727 | +operands from the stack and the return register. | |
| 728 | +.LP | |
| 729 | +There is a separate boolean code generator that compiles | |
| 730 | +conditional expressions. | |
| 731 | +This is fundamentally different from compiling an arithmetic expression. | |
| 732 | +The result of the boolean code generator is the | |
| 733 | +position of the program counter and not an expression. | |
| 734 | +The boolean code generator makes extensive use of De Morgan's rule. | |
| 735 | +The boolean code generator is an expanded version of that described | |
| 736 | +in chapter 8 of Aho, Sethi, and Ullman | |
| 737 | +[Aho87]. | |
| 738 | +.LP | |
| 739 | +There is a considerable amount of talk in the literature | |
| 740 | +about automating this part of a compiler with a machine | |
| 741 | +description. | |
| 742 | +Since this code generator is so small | |
| 743 | +(less than 500 lines of C) | |
| 744 | +and easy, | |
| 745 | +it hardly seems worth the effort. | |
| 746 | +.NH 2 | |
| 747 | +Registerization | |
| 748 | +.LP | |
| 749 | +Up to now, | |
| 750 | +the compiler has operated on syntax trees | |
| 751 | +that are roughly equivalent to the original source language. | |
| 752 | +The previous pass has produced machine language in an internal | |
| 753 | +format. | |
| 754 | +The next two passes operate on the internal machine language | |
| 755 | +structures. | |
| 756 | +The purpose of the next pass is to reintroduce | |
| 757 | +registers for heavily used variables. | |
| 758 | +.LP | |
| 759 | +All of the variables that can be | |
| 760 | +potentially registerized within a procedure are | |
| 761 | +placed in a table. | |
| 762 | +(Suitable variables are any automatic or external | |
| 763 | +scalars that do not have their addresses extracted. | |
| 764 | +Some constants that are hard to reference are also | |
| 765 | +considered for registerization.) | |
| 766 | +Four separate data flow equations are evaluated | |
| 767 | +over the procedure on all of these variables. | |
| 768 | +Two of the equations are the normal set-behind | |
| 769 | +and used-ahead | |
| 770 | +bits that define the life of a variable. | |
| 771 | +The two new bits tell if a variable life | |
| 772 | +crosses a function call ahead or behind. | |
| 773 | +By examining a variable over its lifetime, | |
| 774 | +it is possible to get a cost | |
| 775 | +for registerizing. | |
| 776 | +Loops are detected and the costs are multiplied | |
| 777 | +by three for every level of loop nesting. | |
| 778 | +Costs are sorted and the variables | |
| 779 | +are replaced by available registers on a greedy basis. | |
| 780 | +.LP | |
| 781 | +The 68020 has two different | |
| 782 | +types of registers. | |
| 783 | +For the 68020, | |
| 784 | +two different costs are calculated for | |
| 785 | +each variable life and the register type that | |
| 786 | +affords the better cost is used. | |
| 787 | +Ties are broken by counting the number of available | |
| 788 | +registers of each type. | |
| 789 | +.LP | |
| 790 | +Note that externals are registerized together with automatics. | |
| 791 | +This is done by evaluating the semantics of a ``call'' instruction | |
| 792 | +differently for externals and automatics. | |
| 793 | +Since a call goes outside the local procedure, | |
| 794 | +it is assumed that a call references all externals. | |
| 795 | +Similarly, | |
| 796 | +externals are assumed to be set before an ``entry'' instruction | |
| 797 | +and assumed to be referenced after a ``return'' instruction. | |
| 798 | +This makes sure that externals are in memory across calls. | |
| 799 | +.LP | |
| 800 | +The overall results are satisfactory. | |
| 801 | +It would be nice to be able to do this processing in | |
| 802 | +a machine-independent way, | |
| 803 | +but it is impossible to get all of the costs and | |
| 804 | +side effects of different choices by examining the parse tree. | |
| 805 | +.LP | |
| 806 | +Most of the code in the registerization pass is machine-independent. | |
| 807 | +The major machine-dependency is in | |
| 808 | +examining a machine instruction to ask if it sets or references | |
| 809 | +a variable. | |
| 810 | +.NH 2 | |
| 811 | +Machine code optimization | |
| 812 | +.LP | |
| 813 | +The next pass walks the machine code | |
| 814 | +for opportunistic optimizations. | |
| 815 | +For the most part, | |
| 816 | +this is highly specific to a particular | |
| 817 | +processor. | |
| 818 | +One optimization that is performed | |
| 819 | +on all of the processors is the | |
| 820 | +removal of unnecessary ``move'' | |
| 821 | +instructions. | |
| 822 | +Ironically, | |
| 823 | +most of these instructions were inserted by | |
| 824 | +the previous pass. | |
| 825 | +There are two patterns that are repetitively | |
| 826 | +matched and replaced until no more matches are | |
| 827 | +found. | |
| 828 | +The first tries to remove ``move'' instructions | |
| 829 | +by relabeling variables. | |
| 830 | +.LP | |
| 831 | +When a ``move'' instruction is encountered, | |
| 832 | +if the destination variable is set before the | |
| 833 | +source variable is referenced, | |
| 834 | +then all of the references to the destination | |
| 835 | +variable can be renamed to the source and the ``move'' | |
| 836 | +can be deleted. | |
| 837 | +This transformation uses the reverse data flow | |
| 838 | +set up in the previous pass. | |
| 839 | +.LP | |
| 840 | +An example of this pattern is depicted in the following | |
| 841 | +table. | |
| 842 | +The pattern is in the left column and the | |
| 843 | +replacement action is in the right column. | |
| 844 | +.DS | |
| 845 | +.CW | |
| 846 | +.ta .1i .6i 1.6i 2.1i 2.6i | |
| 847 | + MOVE a->b \fR(remove)\fP | |
| 848 | +.R | |
| 849 | + (sequence with no mention of \f(CWa\fP) | |
| 850 | +.CW | |
| 851 | + USE b USE a | |
| 852 | +.R | |
| 853 | + (sequence with no mention of \f(CWa\fP) | |
| 854 | +.CW | |
| 855 | + SET b SET b | |
| 856 | +.R | |
| 857 | +.DE | |
| 858 | +.LP | |
| 859 | +Experiments have shown that it is marginally | |
| 860 | +worthwhile to rename uses of the destination variable | |
| 861 | +with uses of the source variable up to | |
| 862 | +the first use of the source variable. | |
| 863 | +.LP | |
| 864 | +The second transform will do relabeling | |
| 865 | +without deleting instructions. | |
| 866 | +When a ``move'' instruction is encountered, | |
| 867 | +if the source variable has been set prior | |
| 868 | +to the use of the destination variable | |
| 869 | +then all of the references to the source | |
| 870 | +variable are replaced by the destination and | |
| 871 | +the ``move'' is inverted. | |
| 872 | +Typically, | |
| 873 | +this transformation will alter two ``move'' | |
| 874 | +instructions and allow the first transformation | |
| 875 | +another chance to remove code. | |
| 876 | +This transformation uses the forward data flow | |
| 877 | +set up in the previous pass. | |
| 878 | +.LP | |
| 879 | +Again, | |
| 880 | +the following is a depiction of the transformation where | |
| 881 | +the pattern is in the left column and the | |
| 882 | +rewrite is in the right column. | |
| 883 | +.DS | |
| 884 | +.CW | |
| 885 | +.ta .1i .6i 1.6i 2.1i 2.6i | |
| 886 | + SET a SET b | |
| 887 | +.R | |
| 888 | + (sequence with no use of \f(CWb\fP) | |
| 889 | +.CW | |
| 890 | + USE a USE b | |
| 891 | +.R | |
| 892 | + (sequence with no use of \f(CWb\fP) | |
| 893 | +.CW | |
| 894 | + MOVE a->b MOVE b->a | |
| 895 | +.R | |
| 896 | +.DE | |
| 897 | +Iterating these transformations | |
| 898 | +will usually get rid of all redundant ``move'' instructions. | |
| 899 | +.LP | |
| 900 | +A problem with this organization is that the costs | |
| 901 | +of registerization calculated in the previous pass | |
| 902 | +must depend on how well this pass can detect and remove | |
| 903 | +redundant instructions. | |
| 904 | +Often, | |
| 905 | +a fine candidate for registerization is rejected | |
| 906 | +because of the cost of instructions that are later | |
| 907 | +removed. | |
| 908 | +.NH 2 | |
| 909 | +Writing the object file | |
| 910 | +.LP | |
| 911 | +The last pass walks the internal assembly language | |
| 912 | +and writes the object file. | |
| 913 | +The object file is reduced in size by about a factor | |
| 914 | +of three with simple compression | |
| 915 | +techniques. | |
| 916 | +The most important aspect of the object file | |
| 917 | +format is that it is independent of the compiling machine. | |
| 918 | +All integer and floating numbers in the object | |
| 919 | +code are converted to known formats and byte | |
| 920 | +orders. | |
| 921 | +.NH | |
| 922 | +The loader | |
| 923 | +.LP | |
| 924 | +The loader is a multiple pass program that | |
| 925 | +reads object files and libraries and produces | |
| 926 | +an executable binary. | |
| 927 | +The loader also does some minimal | |
| 928 | +optimizations and code rewriting. | |
| 929 | +Many of the operations performed by the | |
| 930 | +loader are machine-dependent. | |
| 931 | +.LP | |
| 932 | +The first pass of the loader reads the | |
| 933 | +object modules into an internal data | |
| 934 | +structure that looks like binary assembly language. | |
| 935 | +As the instructions are read, | |
| 936 | +code is reordered to remove | |
| 937 | +unconditional branch instructions. | |
| 938 | +Conditional branch instructions are inverted | |
| 939 | +to prevent the insertion of unconditional branches. | |
| 940 | +The loader will also make a copy of a few instructions | |
| 941 | +to remove an unconditional branch. | |
| 942 | +.LP | |
| 943 | +The next pass allocates addresses for | |
| 944 | +all external data. | |
| 945 | +Typical of processors is the MIPS, | |
| 946 | +which can reference ±32K bytes from a | |
| 947 | +register. | |
| 948 | +The loader allocates the register | |
| 949 | +.CW R30 | |
| 950 | +as the static pointer. | |
| 951 | +The value placed in | |
| 952 | +.CW R30 | |
| 953 | +is the base of the data segment plus 32K. | |
| 954 | +It is then cheap to reference all data in the | |
| 955 | +first 64K of the data segment. | |
| 956 | +External variables are allocated to | |
| 957 | +the data segment | |
| 958 | +with the smallest variables allocated first. | |
| 959 | +If all of the data cannot fit into the first | |
| 960 | +64K of the data segment, | |
| 961 | +then usually only a few large arrays | |
| 962 | +need more expensive addressing modes. | |
| 963 | +.LP | |
| 964 | +For the MIPS processor, | |
| 965 | +the loader makes a pass over the internal | |
| 966 | +structures, | |
| 967 | +exchanging instructions to try | |
| 968 | +to fill ``delay slots'' with useful work. | |
| 969 | +If a useful instruction cannot be found | |
| 970 | +to fill a delay slot, | |
| 971 | +the loader will insert | |
| 972 | +``noop'' | |
| 973 | +instructions. | |
| 974 | +This pass is very expensive and does not | |
| 975 | +do a good job. | |
| 976 | +About 40% of all instructions are in | |
| 977 | +delay slots. | |
| 978 | +About 65% of these are useful instructions and | |
| 979 | +35% are ``noops.'' | |
| 980 | +The vendor-supplied assembler does this job | |
| 981 | +more effectively, | |
| 982 | +filling about 80% | |
| 983 | +of the delay slots with useful instructions. | |
| 984 | +.LP | |
| 985 | +On the 68020 processor, | |
| 986 | +branch instructions come in a variety of | |
| 987 | +sizes depending on the relative distance | |
| 988 | +of the branch. | |
| 989 | +Thus the size of branch instructions | |
| 990 | +can be mutually dependent. | |
| 991 | +The loader uses a multiple pass algorithm | |
| 992 | +to resolve the branch lengths | |
| 993 | +[Szy78]. | |
| 994 | +Initially, all branches are assumed minimal length. | |
| 995 | +On each subsequent pass, | |
| 996 | +the branches are reassessed | |
| 997 | +and expanded if necessary. | |
| 998 | +When no more expansions occur, | |
| 999 | +the locations of the instructions in | |
| 1000 | +the text segment are known. | |
| 1001 | +.LP | |
| 1002 | +On the MIPS processor, | |
| 1003 | +all instructions are one size. | |
| 1004 | +A single pass over the instructions will | |
| 1005 | +determine the locations of all addresses | |
| 1006 | +in the text segment. | |
| 1007 | +.LP | |
| 1008 | +The last pass of the loader produces the | |
| 1009 | +executable binary. | |
| 1010 | +A symbol table and other tables are | |
| 1011 | +produced to help the debugger to | |
| 1012 | +interpret the binary symbolically. | |
| 1013 | +.LP | |
| 1014 | +The loader places absolute source line numbers in the symbol table. | |
| 1015 | +The name and absolute line number of all | |
| 1016 | +.CW #include | |
| 1017 | +files is also placed in the | |
| 1018 | +symbol table so that the debuggers can | |
| 1019 | +associate object code to source files. | |
| 1020 | +.NH | |
| 1021 | +Performance | |
| 1022 | +.LP | |
| 1023 | +The following is a table of the source size of the MIPS | |
| 1024 | +compiler. | |
| 1025 | +.DS | |
| 1026 | +.ta .1i .6i | |
| 1027 | + lines module | |
| 1028 | + \0509 machine-independent headers | |
| 1029 | + 1070 machine-independent YACC source | |
| 1030 | + 6090 machine-independent C source | |
| 1031 | + | |
| 1032 | + \0545 machine-dependent headers | |
| 1033 | + 6532 machine-dependent C source | |
| 1034 | + | |
| 1035 | + \0298 loader headers | |
| 1036 | + 5215 loader C source | |
| 1037 | +.DE | |
| 1038 | +.LP | |
| 1039 | +The following table shows timing | |
| 1040 | +of a test program | |
| 1041 | +that plays checkers, running on a MIPS R4000. | |
| 1042 | +The test program is 26 files totaling 12600 lines of C. | |
| 1043 | +The execution time does not significantly | |
| 1044 | +depend on library implementation. | |
| 1045 | +Since no other compiler runs on Plan 9, | |
| 1046 | +the Plan 9 tests were done with the Plan 9 operating system; | |
| 1047 | +the other tests were done on the vendor's operating system. | |
| 1048 | +The hardware was identical in both cases. | |
| 1049 | +The optimizer in the vendor's compiler | |
| 1050 | +is reputed to be extremely good. | |
| 1051 | +.DS | |
| 1052 | +.ta .1i .9i | |
| 1053 | + \0\04.49s Plan 9 \f(CWvc\fP \f(CW-N\fP compile time (opposite of \f(CW-O\fP) | |
| 1054 | + \0\01.72s Plan 9 \f(CWvc\fP \f(CW-N\fP load time | |
| 1055 | + 148.69s Plan 9 \f(CWvc\fP \f(CW-N\fP run time | |
| 1056 | + | |
| 1057 | + \015.07s Plan 9 \f(CWvc\fP compile time (\f(CW-O\fP implicit) | |
| 1058 | + \0\01.66s Plan 9 \f(CWvc\fP load time | |
| 1059 | + \089.96s Plan 9 \f(CWvc\fP run time | |
| 1060 | + | |
| 1061 | + \014.83s vendor \f(CWcc\fP compile time | |
| 1062 | + \0\00.38s vendor \f(CWcc\fP load time | |
| 1063 | + 104.75s vendor \f(CWcc\fP run time | |
| 1064 | + | |
| 1065 | + \043.59s vendor \f(CWcc\fP \f(CW-O\fP compile time | |
| 1066 | + \0\00.38s vendor \f(CWcc\fP \f(CW-O\fP load time | |
| 1067 | + \076.19s vendor \f(CWcc\fP \f(CW-O\fP run time | |
| 1068 | + | |
| 1069 | + \0\08.19s vendor \f(CWcc\fP \f(CW-O3\fP compile time | |
| 1070 | + \035.97s vendor \f(CWcc\fP \f(CW-O3\fP load time | |
| 1071 | + \071.16s vendor \f(CWcc\fP \f(CW-O3\fP run time | |
| 1072 | +.DE | |
| 1073 | +.LP | |
| 1074 | +To compare the Intel compiler, | |
| 1075 | +a program that is about 40% bit manipulation and | |
| 1076 | +about 60% single precision floating point was | |
| 1077 | +run on the same 33 MHz 486, once under Windows | |
| 1078 | +compiled with the Watcom compiler, version 10.0, | |
| 1079 | +in 16-bit mode and once under | |
| 1080 | +Plan 9 in 32-bit mode. | |
| 1081 | +The Plan 9 execution time was 27 sec while the Windows | |
| 1082 | +execution time was 31 sec. | |
| 1083 | +.NH | |
| 1084 | +Conclusions | |
| 1085 | +.LP | |
| 1086 | +The new compilers compile | |
| 1087 | +quickly, | |
| 1088 | +load slowly, | |
| 1089 | +and produce | |
| 1090 | +medium quality | |
| 1091 | +object code. | |
| 1092 | +The compilers are relatively | |
| 1093 | +portable, | |
| 1094 | +requiring but a couple of weeks' work to | |
| 1095 | +produce a compiler for a different computer. | |
| 1096 | +For Plan 9, | |
| 1097 | +where we needed several compilers | |
| 1098 | +with specialized features and | |
| 1099 | +our own object formats, | |
| 1100 | +this project was indispensable. | |
| 1101 | +It is also necessary for us to | |
| 1102 | +be able to freely distribute our compilers | |
| 1103 | +with the Plan 9 distribution. | |
| 1104 | +.LP | |
| 1105 | +Two problems have come up in retrospect. | |
| 1106 | +The first has to do with the | |
| 1107 | +division of labor between compiler and loader. | |
| 1108 | +Plan 9 runs on multi-processors and as such | |
| 1109 | +compilations are often done in parallel. | |
| 1110 | +Unfortunately, | |
| 1111 | +all compilations must be complete before loading | |
| 1112 | +can begin. | |
| 1113 | +The load is then single-threaded. | |
| 1114 | +With this model, | |
| 1115 | +any shift of work from compile to load | |
| 1116 | +results in a significant increase in real time. | |
| 1117 | +The same is true of libraries that are compiled | |
| 1118 | +infrequently and loaded often. | |
| 1119 | +In the future, | |
| 1120 | +we may try to put some of the loader work | |
| 1121 | +back into the compiler. | |
| 1122 | +.LP | |
| 1123 | +The second problem comes from | |
| 1124 | +the various optimizations performed over several | |
| 1125 | +passes. | |
| 1126 | +Often optimizations in different passes depend | |
| 1127 | +on each other. | |
| 1128 | +Iterating the passes could compromise efficiency, | |
| 1129 | +or even loop. | |
| 1130 | +We see no real solution to this problem. | |
| 1131 | +.NH | |
| 1132 | +References | |
| 1133 | +.LP | |
| 1134 | +[Aho87] A. V. Aho, R. Sethi, and J. D. Ullman, | |
| 1135 | +.I | |
| 1136 | +Compilers \- Principles, Techniques, and Tools, | |
| 1137 | +.R | |
| 1138 | +Addison Wesley, | |
| 1139 | +Reading, MA, | |
| 1140 | +1987. | |
| 1141 | +.LP | |
| 1142 | +[ANSI90] \f2American National Standard for Information Systems \- | |
| 1143 | +Programming Language C\f1, American National Standards Institute, Inc., | |
| 1144 | +New York, 1990. | |
| 1145 | +.LP | |
| 1146 | +[Dav91] J. W. Davidson and D. B. Whalley, | |
| 1147 | +``Methods for Saving and Restoring Register Values across Function Calls'', | |
| 1148 | +.I | |
| 1149 | +Software\-Practice and Experience, | |
| 1150 | +.R | |
| 1151 | +Vol 21(2), pp. 149-165, February 1991. | |
| 1152 | +.LP | |
| 1153 | +[Joh79] S. C. Johnson, | |
| 1154 | +``YACC \- Yet Another Compiler Compiler'', | |
| 1155 | +.I | |
| 1156 | +UNIX Programmer's Manual, Seventh Ed., Vol. 2A, | |
| 1157 | +.R | |
| 1158 | +AT&T Bell Laboratories, | |
| 1159 | +Murray Hill, NJ, | |
| 1160 | +1979. | |
| 1161 | +.LP | |
| 1162 | +[Set70] R. Sethi and J. D. Ullman, | |
| 1163 | +``The Generation of Optimal Code for Arithmetic Expressions'', | |
| 1164 | +.I | |
| 1165 | +Journal of the ACM, | |
| 1166 | +.R | |
| 1167 | +Vol 17(4), pp. 715-728, 1970. | |
| 1168 | +.LP | |
| 1169 | +[Szy78] T. G. Szymanski, | |
| 1170 | +``Assembling Code for Machines with Span-dependent Instructions'', | |
| 1171 | +.I | |
| 1172 | +Communications of the ACM, | |
| 1173 | +.R | |
| 1174 | +Vol 21(4), pp. 300-308, 1978. | |
Binary file not shown.
| @@ -0,0 +1,2056 @@ | ||
| 1 | +.de EX | |
| 2 | +.nr x \\$1v | |
| 3 | +\\!h0c n \\nx 0 | |
| 4 | +.. | |
| 5 | +.de FG \" start figure caption: .FG filename.ps verticalsize | |
| 6 | +.KF | |
| 7 | +.BP \\$1 \\$2 | |
| 8 | +.sp .5v | |
| 9 | +.EX \\$2v | |
| 10 | +.ps -1 | |
| 11 | +.vs -1 | |
| 12 | +.. | |
| 13 | +.de fg \" end figure caption (yes, it is clumsy) | |
| 14 | +.ps | |
| 15 | +.vs | |
| 16 | +.br | |
| 17 | +.KE | |
| 18 | +.. | |
| 19 | +.TL | |
| 20 | +A Descent into Limbo | |
| 21 | +.AU | |
| 22 | +Brian W. Kernighan | |
| 23 | +.AI | |
| 24 | +bwk@bell-labs.com | |
| 25 | +.br | |
| 26 | +Revised April 2005 by Vita Nuova | |
| 27 | +.AB | |
| 28 | +.DS B | |
| 29 | +.ps -2 | |
| 30 | +.vs -1 | |
| 31 | +``If, reader, you are slow now to believe | |
| 32 | +What I shall tell, that is no cause for wonder, | |
| 33 | +For I who saw it hardly can accept it.'' | |
| 34 | +.ft R | |
| 35 | + Dante Alighieri, \fIInferno\fP, Canto XXV. | |
| 36 | +.ps +2 | |
| 37 | +.vs +1 | |
| 38 | +.DE | |
| 39 | +.LP | |
| 40 | +Limbo is a new programming language, designed by | |
| 41 | +Sean Dorward, Phil Winterbottom, and Rob Pike. | |
| 42 | +Limbo borrows from, among other things, | |
| 43 | +C (expression syntax and control flow), | |
| 44 | +Pascal (declarations), | |
| 45 | +Winterbottom's Alef (abstract data types and channels), | |
| 46 | +and Hoare's CSP and Pike's Newsqueak (processes). | |
| 47 | +Limbo is strongly typed, provides automatic garbage collection, | |
| 48 | +supports only very restricted pointers, | |
| 49 | +and compiles into machine-independent byte code for execution on | |
| 50 | +a virtual machine. | |
| 51 | +.LP | |
| 52 | +This paper is a brief introduction to Limbo. | |
| 53 | +Since Limbo is an integral part of the Inferno system, | |
| 54 | +the examples here illustrate not only | |
| 55 | +the language but also a certain amount about how to write | |
| 56 | +programs to run within Inferno. | |
| 57 | +.AE | |
| 58 | +.NH 1 | |
| 59 | +Introduction | |
| 60 | +.LP | |
| 61 | +This document is a quick look at the basics | |
| 62 | +of Limbo; it is not a replacement for the reference manual. | |
| 63 | +The first section is a short overview of | |
| 64 | +concepts and constructs; | |
| 65 | +subsequent sections illustrate the language with examples. | |
| 66 | +Although Limbo is intended to be used in Inferno, | |
| 67 | +which emphasizes networking and graphical interfaces, | |
| 68 | +the discussion here begins with standard text-manipulation | |
| 69 | +examples, since they require less background to understand. | |
| 70 | +.SH | |
| 71 | +Modules: | |
| 72 | +.LP | |
| 73 | +A Limbo program is a set of modules that cooperate | |
| 74 | +to perform a task. | |
| 75 | +In source form, a module consists of a | |
| 76 | +.CW "module" | |
| 77 | +declaration that specifies the public interface \- the functions, | |
| 78 | +abstract data types, | |
| 79 | +and constants that the module makes visible to other modules \- | |
| 80 | +and an implementation that provides the actual code. | |
| 81 | +By convention, the module declaration is usually placed in a separate | |
| 82 | +.CW ".m" | |
| 83 | +file so it can be included by other modules, | |
| 84 | +and the implementation is stored in a | |
| 85 | +.CW ".b" | |
| 86 | +file. | |
| 87 | +Modules may have multiple implementations, | |
| 88 | +each in a separate implementation file. | |
| 89 | +.LP | |
| 90 | +Modules are always loaded dynamically, at run time: the Limbo | |
| 91 | +.CW "load" | |
| 92 | +operator fetches the code and performs run-time type checking. | |
| 93 | +Once a module has been loaded, its functions can be called. | |
| 94 | +Several instances of the same module type can be in use at once, | |
| 95 | +with possibly different implementations. | |
| 96 | +.LP | |
| 97 | +Limbo is strongly typed; programs are checked at compile time, | |
| 98 | +and further when modules are loaded. | |
| 99 | +The Limbo compiler compiles each source file into a | |
| 100 | +machine-independent byte-coded | |
| 101 | +.CW ".dis" | |
| 102 | +file that can be loaded at run time. | |
| 103 | +.SH | |
| 104 | +Functions and variables: | |
| 105 | +.LP | |
| 106 | +Functions are associated with specific modules, either directly or | |
| 107 | +as members of abstract data types within a module. | |
| 108 | +Functions are visible outside their module only | |
| 109 | +if they are part of the module interface. | |
| 110 | +If the target module is loaded, specific names | |
| 111 | +can be used in a qualified form like | |
| 112 | +.CW "sys->print" | |
| 113 | +or without the qualifier if imported with an explicit | |
| 114 | +.CW "import" | |
| 115 | +statement. | |
| 116 | +.LP | |
| 117 | +Besides normal block structure within functions, | |
| 118 | +variables may have global scope within a module; | |
| 119 | +module data can be accessed via the module pointer. | |
| 120 | +.SH | |
| 121 | +Data: | |
| 122 | +.LP | |
| 123 | +The numeric types are: | |
| 124 | +.RS | |
| 125 | +.TS | |
| 126 | +lf(CW) lf(R)w(3i) . | |
| 127 | +byte unsigned, 8 bits | |
| 128 | +int signed, 32 bits | |
| 129 | +big signed, 64 bits | |
| 130 | +real IEEE long float, 64 bits | |
| 131 | +.TE | |
| 132 | +.RE | |
| 133 | +The size and signedness of integral types are | |
| 134 | +as specified above, and will be the same everywhere. | |
| 135 | +Character constants are enclosed in single quotes | |
| 136 | +and may use escapes like | |
| 137 | +.CW "'\en'" | |
| 138 | +or | |
| 139 | +.CW "'\eudddd'" , | |
| 140 | +but the characters themselves | |
| 141 | +are in Unicode and have type | |
| 142 | +.CW "int" . | |
| 143 | +There is no enumeration type, but there is a | |
| 144 | +.CW "con" | |
| 145 | +declaration that creates a named constant, and a special | |
| 146 | +.CW "iota" | |
| 147 | +operation that can be used to generate unique values. | |
| 148 | +.LP | |
| 149 | +Limbo also provides | |
| 150 | +Unicode strings, | |
| 151 | +arrays of arbitrary types, | |
| 152 | +lists of arbitrary types, | |
| 153 | +tuples (in effect, unnamed structures with unnamed members of arbitrary types), | |
| 154 | +abstract data types or adt's (in effect, named structures with function | |
| 155 | +members as well as data members), | |
| 156 | +reference types (in effect, restricted pointers that can point only to adt objects), | |
| 157 | +and | |
| 158 | +typed channels (for passing objects between processes). | |
| 159 | +.LP | |
| 160 | +A channel is a mechanism for synchronized communication. | |
| 161 | +It provides a place for one process to send or receive | |
| 162 | +an object of a specific type; | |
| 163 | +the attempt to send or receive blocks until a matching receive or send | |
| 164 | +is attempted by another process. | |
| 165 | +The | |
| 166 | +.CW "alt" | |
| 167 | +statement selects randomly but fairly among channels | |
| 168 | +that are ready to read or write. | |
| 169 | +The | |
| 170 | +.CW "spawn" | |
| 171 | +statement creates a new process that, | |
| 172 | +except for its stack, shares memory with other processes. | |
| 173 | +Processes are pre-emptively scheduled by the Inferno kernel. | |
| 174 | +(Inferno processes are sometimes called ``threads'' in | |
| 175 | +other operating systems.) | |
| 176 | +.LP | |
| 177 | +Limbo performs automatic garbage collection, so there is no | |
| 178 | +need to free dynamically created objects. | |
| 179 | +Objects are deleted and their resources freed when | |
| 180 | +the last reference to them goes away. | |
| 181 | +This release of resources happens immediately | |
| 182 | +(``instant free'') for non-cyclic structures; | |
| 183 | +release of cyclic data structures might be delayed but will happen eventually. | |
| 184 | +(The language allows the programmer to ensure a given structure is non-cyclic | |
| 185 | +when required.) | |
| 186 | +.SH | |
| 187 | +Operators and expressions: | |
| 188 | +.LP | |
| 189 | +Limbo provides many of C's operators, | |
| 190 | +but not the | |
| 191 | +.CW "?:" | |
| 192 | +or | |
| 193 | +`comma' (sequential execution) operators. | |
| 194 | +Pointers, or `references', created with | |
| 195 | +.CW "ref" , | |
| 196 | +are restricted compared to C: they can only refer to adt values on the heap. | |
| 197 | +There is no | |
| 198 | +.CW "&" | |
| 199 | +(address of) operator, nor is address arithmetic possible. | |
| 200 | +Arrays are also reference types, however, | |
| 201 | +and since | |
| 202 | +array slicing is supported, that replaces | |
| 203 | +many of C's pointer constructions. | |
| 204 | +.LP | |
| 205 | +There are no implicit coercions between types, | |
| 206 | +and only a handful of explicit casts. | |
| 207 | +The numeric types | |
| 208 | +.CW "byte" , | |
| 209 | +.CW "int" , | |
| 210 | +etc., can be used to convert a numeric expression, as in | |
| 211 | +.P1 | |
| 212 | +nl := byte 10; | |
| 213 | +.P2 | |
| 214 | +and | |
| 215 | +.CW "string" | |
| 216 | +can be used as a unary operator to convert any numeric expression | |
| 217 | +to a string (in | |
| 218 | +.CW "%g" | |
| 219 | +format) and to convert an array of bytes in UTF-8 format to a Limbo | |
| 220 | +.CW string | |
| 221 | +value. | |
| 222 | +In the other direction, the cast | |
| 223 | +.CW "array of byte" | |
| 224 | +converts a string to its UTF-8 representation in an array of bytes. | |
| 225 | +.SH | |
| 226 | +Statements: | |
| 227 | +.LP | |
| 228 | +Statements and control flow in Limbo are similar to those in C. | |
| 229 | +A statement is an expression followed by a semicolon, | |
| 230 | +or a sequence of statements enclosed in braces. | |
| 231 | +The similar control flow statements are | |
| 232 | +.P1 | |
| 233 | +if (\fIexpr\fP) \fIstat\fP | |
| 234 | +if (\fIexpr\fP) \fIstat\fP else \fIstat\fP | |
| 235 | +while (\fIexpr\fP) \fIstat\fP | |
| 236 | +for (\fIexpr\fP; \fIexpr\fP; \fIexpr\fP) \fIstat\fP | |
| 237 | +do \fIstat\fP while (\fIexpr\fP) ; | |
| 238 | +return \fIexpr\fP ; | |
| 239 | +exit ; | |
| 240 | +.P2 | |
| 241 | +The | |
| 242 | +.CW "exit" | |
| 243 | +statement terminates a process and frees its resources. | |
| 244 | +There is also a | |
| 245 | +.CW "case" | |
| 246 | +statement analogous to C's | |
| 247 | +.CW "switch" , | |
| 248 | +but it differs in that it also supports string and range tests, | |
| 249 | +and more critically, control flow does not ``flow through'' one arm of the case to another | |
| 250 | +but stops without requiring an explicit | |
| 251 | +.CW break | |
| 252 | +(in that respect it is closer to Pascal's | |
| 253 | +.CW case | |
| 254 | +statement, hence the change of name). | |
| 255 | +A | |
| 256 | +.CW "break" | |
| 257 | +or | |
| 258 | +.CW "continue" | |
| 259 | +followed by a label | |
| 260 | +causes a break out of, or the next iteration of, the enclosing | |
| 261 | +construct that is labeled with the same label. | |
| 262 | +.LP | |
| 263 | +Comments begin with | |
| 264 | +.CW "#" | |
| 265 | +and extend to the end of the line. | |
| 266 | +There is no preprocessor, but an | |
| 267 | +.CW "include" | |
| 268 | +statement can be used to include source code, usually module declaration files. | |
| 269 | +.SH | |
| 270 | +Libraries: | |
| 271 | +.LP | |
| 272 | +Limbo has an extensive and growing set of standard libraries, | |
| 273 | +each implemented as a module. | |
| 274 | +A handful of these | |
| 275 | +(notably | |
| 276 | +.CW "Sys" , | |
| 277 | +.CW "Draw" , | |
| 278 | +and | |
| 279 | +.CW "Tk" ) | |
| 280 | +are included in the Inferno kernel because they will be | |
| 281 | +needed to support almost any Limbo program. | |
| 282 | +Among the others are | |
| 283 | +.CW "Bufio" , | |
| 284 | +a buffered I/O package based on Plan 9's Bio; | |
| 285 | +.CW "Regex" , | |
| 286 | +for regular expressions; | |
| 287 | +and | |
| 288 | +.CW "Math" , | |
| 289 | +for mathematical functions. | |
| 290 | +Some of the examples that follow provide the sort | |
| 291 | +of functionality that might be a suitable module. | |
| 292 | +.NH 1 | |
| 293 | +Examples | |
| 294 | +.LP | |
| 295 | +The examples in this section are each complete, in the sense that they | |
| 296 | +will run as presented; I have tried to avoid code fragments | |
| 297 | +that merely illustrate syntax. | |
| 298 | +.NH 2 | |
| 299 | +Hello, World | |
| 300 | +.LP | |
| 301 | +The first example is the traditional ``hello, world'', | |
| 302 | +in the file | |
| 303 | +.CW "hello.b" : | |
| 304 | +.P1 | |
| 305 | +implement Hello; | |
| 306 | + | |
| 307 | +include "sys.m"; | |
| 308 | + sys: Sys; | |
| 309 | +include "draw.m"; | |
| 310 | + | |
| 311 | +Hello: module | |
| 312 | +{ | |
| 313 | + init: fn(ctxt: ref Draw->Context, args: list of string); | |
| 314 | +}; | |
| 315 | + | |
| 316 | +init(ctxt: ref Draw->Context, args: list of string) | |
| 317 | +{ | |
| 318 | + sys = load Sys Sys->PATH; | |
| 319 | + sys->print("hello, world\en"); | |
| 320 | +} | |
| 321 | +.P2 | |
| 322 | +An implementation file implements a single module, | |
| 323 | +named in the | |
| 324 | +.CW "implement" | |
| 325 | +declaration at the top of the file. | |
| 326 | +The two | |
| 327 | +.CW "include" | |
| 328 | +lines copy interface definitions from two other modules, | |
| 329 | +.CW "Sys" | |
| 330 | +(which describes a variety of system functions like | |
| 331 | +.CW "print" ), | |
| 332 | +and | |
| 333 | +.CW "Draw" | |
| 334 | +(which describes a variety of graphics types and functions, | |
| 335 | +only one of which, | |
| 336 | +.CW "Context" , | |
| 337 | +is used here). | |
| 338 | +.LP | |
| 339 | +The | |
| 340 | +.CW "module" | |
| 341 | +declaration defines the external interface that this module | |
| 342 | +presents to the rest of the world. | |
| 343 | +In this case, it's a single function named | |
| 344 | +.CW "init" . | |
| 345 | +Since this module is to be called from a command interpreter | |
| 346 | +(shell), by convention its | |
| 347 | +.CW "init" | |
| 348 | +function takes two arguments, | |
| 349 | +the graphical context | |
| 350 | +and a list of strings, the command-line arguments, | |
| 351 | +though neither is used here. | |
| 352 | +This is like | |
| 353 | +.CW "main" | |
| 354 | +in a C program. | |
| 355 | +Essentially all of the other examples begin with this standard code. | |
| 356 | +Commands are unusual, though, in that a command's module declaration | |
| 357 | +appears in the same file as its implementation. | |
| 358 | +.LP | |
| 359 | +Most modules have a more extensive set of declarations; for example, | |
| 360 | +.CW "draw.m" | |
| 361 | +is 298 lines of constants, function prototypes, and | |
| 362 | +type declarations for graphics types like | |
| 363 | +.CW "Point" | |
| 364 | +and | |
| 365 | +.CW "Rect" , | |
| 366 | +and | |
| 367 | +.CW "sys.m" | |
| 368 | +is 160 lines of declarations for functions like | |
| 369 | +.CW "open" , | |
| 370 | +.CW "read" , | |
| 371 | +and | |
| 372 | +.CW "print" . | |
| 373 | +Most module declarations are therefore stored in separate files, | |
| 374 | +conventionally suffixed with | |
| 375 | +.CW ".m" , | |
| 376 | +so they can be included in other modules. | |
| 377 | +The system library module declaration files are collected in the | |
| 378 | +.CW module | |
| 379 | +directory at the root of the Inferno source tree. | |
| 380 | +Modules that are components of a single program are typically | |
| 381 | +stored in that program's source directory. | |
| 382 | +.LP | |
| 383 | +The last few lines of | |
| 384 | +.CW "hello.b" | |
| 385 | +are the implementation of the | |
| 386 | +.CW "init" | |
| 387 | +function, which loads the | |
| 388 | +.CW "Sys" | |
| 389 | +module, then calls its | |
| 390 | +.CW "print" | |
| 391 | +function. | |
| 392 | +By convention, each module declaration includes a pathname constant | |
| 393 | +that points to the code for the module; this is the second parameter | |
| 394 | +.CW "Sys->PATH" | |
| 395 | +of the | |
| 396 | +.CW "load" | |
| 397 | +statement. | |
| 398 | +Note that the | |
| 399 | +.CW Draw | |
| 400 | +module is not loaded because none of its functions is used, but | |
| 401 | +it is included to define the type | |
| 402 | +.CW Draw->Context . | |
| 403 | +.SH | |
| 404 | +Compiling and Running Limbo Programs | |
| 405 | +.LP | |
| 406 | +With this much of the language described, | |
| 407 | +we can compile and run this program. | |
| 408 | +On Unix or Windows, the command | |
| 409 | +.P1 | |
| 410 | +$ limbo -g hello.b | |
| 411 | +.P2 | |
| 412 | +creates | |
| 413 | +.CW "hello.dis" , | |
| 414 | +a byte-coded version of the program for the Dis | |
| 415 | +virtual machine. | |
| 416 | +The | |
| 417 | +.CW "-g" | |
| 418 | +argument adds a symbol table, useful for subsequent debugging. | |
| 419 | +(Another common option is | |
| 420 | +.CW -w , | |
| 421 | +which causes the compiler to produce helpful warnings about possible errors.) | |
| 422 | +The program can then be run as | |
| 423 | +.CW "hello" | |
| 424 | +in Inferno; this shows execution under the Inferno emulator | |
| 425 | +on a Unix system: | |
| 426 | +.P1 | |
| 427 | +$ limbo -g hello.b | |
| 428 | +$ emu | |
| 429 | +; /usr/bwk/hello | |
| 430 | +hello, world | |
| 431 | +; | |
| 432 | +.P2 | |
| 433 | +From within Inferno, it's also possible to run a | |
| 434 | +program by selecting it from a menu. | |
| 435 | +In any case, as the program runs, it loads as necessary other modules that it uses. | |
| 436 | +.NH 2 | |
| 437 | +A Graphical "Hello World" | |
| 438 | +.LP | |
| 439 | +The following module creates and displays a window containing only | |
| 440 | +a button with the label ``hello, world'' as shown in the screen shot in Figure 1. | |
| 441 | +.P1 | |
| 442 | +implement Hello2; | |
| 443 | + | |
| 444 | +include "sys.m"; | |
| 445 | + sys: Sys; | |
| 446 | +include "draw.m"; | |
| 447 | + draw: Draw; | |
| 448 | +include "tk.m"; | |
| 449 | + tk: Tk; | |
| 450 | +include "tkclient.m"; | |
| 451 | + tkclient: Tkclient; | |
| 452 | + | |
| 453 | +Hello2: module | |
| 454 | +{ | |
| 455 | + init: fn(ctxt: ref Draw->Context, args: list of string); | |
| 456 | +}; | |
| 457 | + | |
| 458 | +init(ctxt: ref Draw->Context, args: list of string) | |
| 459 | +{ | |
| 460 | + sys = load Sys Sys->PATH; | |
| 461 | + tk = load Tk Tk->PATH; | |
| 462 | + tkclient = load Tkclient Tkclient->PATH; | |
| 463 | + | |
| 464 | + tkclient->init(); | |
| 465 | + | |
| 466 | + (t, nil) := tkclient->toplevel(ctxt, "", "Hello", Tkclient->Plain); | |
| 467 | + | |
| 468 | + tk->cmd(t, "button .b -text {hello, world}"); | |
| 469 | + tk->cmd(t, "pack .b"); | |
| 470 | + tk->cmd(t, "update"); | |
| 471 | + | |
| 472 | + tkclient->onscreen(t, nil); | |
| 473 | + | |
| 474 | + sys->sleep(10000); # wait 10 seconds | |
| 475 | +} | |
| 476 | +.P2 | |
| 477 | +.FG "f1.ps" 3i | |
| 478 | +.ce | |
| 479 | +.I "Figure 1. `Hello, world' button." | |
| 480 | +.fg | |
| 481 | +This is not very exciting, but it illustrates the absolute | |
| 482 | +minimum required to get a picture on the screen. | |
| 483 | +The | |
| 484 | +.CW "Tk" | |
| 485 | +module is modeled closely after John Ousterhout's Tk interface toolkit, | |
| 486 | +but Limbo is used as the programming language instead of Tcl. | |
| 487 | +The Inferno version | |
| 488 | +is similar in functionality to the original Tk | |
| 489 | +but it does not support any Tcl constructs, | |
| 490 | +such as variables, procedures, or expression evaluation, | |
| 491 | +since all processing is done using Limbo. | |
| 492 | +There are ten functions in the | |
| 493 | +.CW "Tk" | |
| 494 | +interface, only one of which | |
| 495 | +is used here: | |
| 496 | +.CW "cmd" , | |
| 497 | +which executes a command string. | |
| 498 | +(It is the most commonly used | |
| 499 | +.CW Tk | |
| 500 | +function.) | |
| 501 | +.LP | |
| 502 | +Tk itself displays graphics and handles mouse and keyboard interaction | |
| 503 | +within a window. | |
| 504 | +There can however be many different windows on a display. | |
| 505 | +A separate window manager, | |
| 506 | +.CW wm , | |
| 507 | +multiplexes control of input and output among those windows. | |
| 508 | +The module | |
| 509 | +.CW Tkclient | |
| 510 | +provides the interface between the window manager and Tk. | |
| 511 | +Its function | |
| 512 | +.CW "toplevel" , | |
| 513 | +used above, | |
| 514 | +makes a top-level window and returns a reference to it, for subsequent use by Tk. | |
| 515 | +The contents of the window are prepared by calls to | |
| 516 | +.CW tk->cmd | |
| 517 | +before the window is finally displayed by the call to | |
| 518 | +.CW onscreen . | |
| 519 | +(The second parameter to | |
| 520 | +.CW onscreen , | |
| 521 | +a string, | |
| 522 | +controls the position and style of window; | |
| 523 | +here we take the default by making that | |
| 524 | +.CW nil .) | |
| 525 | +.LP | |
| 526 | +Note that | |
| 527 | +.CW Tkclient | |
| 528 | +must also be explicitly initialized by calling its | |
| 529 | +.CW init | |
| 530 | +function after loading. | |
| 531 | +This is a common convention, although some modules do | |
| 532 | +not require it (typically those built in | |
| 533 | +to the system, such as | |
| 534 | +.CW Sys | |
| 535 | +or | |
| 536 | +.CW Tk ). | |
| 537 | +.LP | |
| 538 | +The | |
| 539 | +.CW "sleep" | |
| 540 | +delays exit for 10 seconds so the button can be seen. | |
| 541 | +If you try to interact with the window, for instance by pressing the button, | |
| 542 | +you will see no response. | |
| 543 | +That is because the program has not done what is required to receive mouse or keyboard input in the window. | |
| 544 | +In a real application, some action would also be bound to pressing the button. | |
| 545 | +Such actions are handled by setting up a connection (a `channel') from | |
| 546 | +the Tk module to one's own code, and processing the | |
| 547 | +messages (`events') that appear on this channel. | |
| 548 | +The Tk module and its interface to the window manager | |
| 549 | +is explained in more detail later, | |
| 550 | +as are a couple of other constructions, | |
| 551 | +after we have introduced processes and channels. | |
| 552 | +.NH 2 | |
| 553 | +Echo | |
| 554 | +.LP | |
| 555 | +The next example, | |
| 556 | +.CW "echo" , | |
| 557 | +prints its command-line arguments. | |
| 558 | +Declarations are the same as in the first | |
| 559 | +example, and have been omitted. | |
| 560 | +.P1 | |
| 561 | +# declarations omitted... | |
| 562 | + | |
| 563 | +init(ctxt: ref Draw->Context, args: list of string) | |
| 564 | +{ | |
| 565 | + sys = load Sys Sys->PATH; | |
| 566 | + | |
| 567 | + args = tl args; # skip over program name | |
| 568 | + for (s := ""; args != nil; args = tl args) | |
| 569 | + s += " " + hd args; | |
| 570 | + if (s != "") # something was stored in s | |
| 571 | + sys->print("%s\en", s[1:]); | |
| 572 | +} | |
| 573 | +.P2 | |
| 574 | +The arguments are stored in a | |
| 575 | +.CW "list" . | |
| 576 | +Lists may be of any type; | |
| 577 | +.CW "args" | |
| 578 | +is a | |
| 579 | +.CW "list" | |
| 580 | +.CW "of" | |
| 581 | +.CW "string" . | |
| 582 | +There are three list operators: | |
| 583 | +.CW "hd" | |
| 584 | +and | |
| 585 | +.CW "tl" | |
| 586 | +return the head and tail of a list, and | |
| 587 | +.CW "::" | |
| 588 | +adds a new element to the head. | |
| 589 | +In this example, the | |
| 590 | +.CW "for" | |
| 591 | +loop walks along the | |
| 592 | +.CW "args" | |
| 593 | +list until the end, | |
| 594 | +printing the head element | |
| 595 | +.CW "hd args" ), ( | |
| 596 | +then advancing | |
| 597 | +.CW "args = tl args" ). ( | |
| 598 | +.LP | |
| 599 | +The value | |
| 600 | +.CW "nil" | |
| 601 | +is the ``undefined'' or ``explicitly empty'' value | |
| 602 | +for non-numeric types. | |
| 603 | +.LP | |
| 604 | +The operator | |
| 605 | +.CW ":=" | |
| 606 | +combines the declaration of a variable and assignment of a value to it. | |
| 607 | +The type of the variable on the left of | |
| 608 | +.CW ":=" | |
| 609 | +is the type | |
| 610 | +of the expression on the right. | |
| 611 | +Thus, the expression | |
| 612 | +.P1 | |
| 613 | +s := "" | |
| 614 | +.P2 | |
| 615 | +in the | |
| 616 | +.CW "for" | |
| 617 | +statement | |
| 618 | +declares a string | |
| 619 | +.CW "s" | |
| 620 | +and initializes it to empty; | |
| 621 | +if after the loop, | |
| 622 | +.CW "s" | |
| 623 | +is not empty, | |
| 624 | +something has been written in it. | |
| 625 | +By the way, there is no distinction between the values | |
| 626 | +.CW "nil" | |
| 627 | +and | |
| 628 | +\f5""\fP | |
| 629 | +for strings. | |
| 630 | +.LP | |
| 631 | +The | |
| 632 | +.CW "+" | |
| 633 | +and | |
| 634 | +.CW "+=" | |
| 635 | +operators concatenate strings. | |
| 636 | +The expression | |
| 637 | +.CW "s[1:]" | |
| 638 | +is a | |
| 639 | +.I slice | |
| 640 | +of the string | |
| 641 | +.CW "s" | |
| 642 | +that starts at index 1 | |
| 643 | +(the second character of the string) and goes | |
| 644 | +to the end; this excludes the unwanted | |
| 645 | +blank at the beginning of | |
| 646 | +.CW "s" . | |
| 647 | +.NH 2 | |
| 648 | +Word Count | |
| 649 | +.LP | |
| 650 | +The word count program | |
| 651 | +.CW "wc" | |
| 652 | +reads its standard input | |
| 653 | +and counts the number of lines, words, and characters. | |
| 654 | +Declarations have again been omitted. | |
| 655 | +.P1 | |
| 656 | +# declarations omitted... | |
| 657 | + | |
| 658 | +init(nil: ref Draw->Context, args: list of string) | |
| 659 | +{ | |
| 660 | + sys = load Sys Sys->PATH; | |
| 661 | + buf := array[1] of byte; | |
| 662 | + | |
| 663 | + stdin := sys->fildes(0); | |
| 664 | + | |
| 665 | + OUT: con 0; | |
| 666 | + IN: con 1; | |
| 667 | + | |
| 668 | + state := OUT; | |
| 669 | + nl := 0; nw := 0; nc := 0; | |
| 670 | + for (;;) { | |
| 671 | + n := sys->read(stdin, buf, 1); | |
| 672 | + if (n <= 0) | |
| 673 | + break; | |
| 674 | + c := int buf[0]; | |
| 675 | + nc++; | |
| 676 | + if (c == '\en') | |
| 677 | + nl++; | |
| 678 | + if (c == ' ' || c == '\et' || c == '\en') | |
| 679 | + state = OUT; | |
| 680 | + else if (state == OUT) { | |
| 681 | + state = IN; | |
| 682 | + nw++; | |
| 683 | + } | |
| 684 | + } | |
| 685 | + sys->print("%d %d %d\en", nl, nw, nc); | |
| 686 | +} | |
| 687 | +.P2 | |
| 688 | +.LP | |
| 689 | +This program contains several instances of the | |
| 690 | +.CW ":=" | |
| 691 | +operator. | |
| 692 | +For example, the line | |
| 693 | +.P1 | |
| 694 | + nl := 0; nw := 0; nc := 0; | |
| 695 | +.P2 | |
| 696 | +declares three integer variables | |
| 697 | +and assigns zero to each. | |
| 698 | +.LP | |
| 699 | +A Limbo program starts with three open files for standard | |
| 700 | +input, standard output, and standard error, as in Unix. | |
| 701 | +The line | |
| 702 | +.P1 | |
| 703 | + stdin := sys->fildes(0); | |
| 704 | +.P2 | |
| 705 | +declares a variable | |
| 706 | +.CW "stdin" | |
| 707 | +and assigns the corresponding file descriptor to it. | |
| 708 | +The type of | |
| 709 | +.CW "stdin" | |
| 710 | +is whatever the type of | |
| 711 | +.CW "sys->fildes(0)" | |
| 712 | +is, and it's possible to get by without | |
| 713 | +ever knowing the name of that type. | |
| 714 | +(We will return to this shortly.) | |
| 715 | +.NE 3v | |
| 716 | +.LP | |
| 717 | +The lines | |
| 718 | +.P1 | |
| 719 | + OUT: con 0; | |
| 720 | + IN: con 1; | |
| 721 | +.P2 | |
| 722 | +declare two integer constants with values zero and one. | |
| 723 | +There is no | |
| 724 | +.CW "enum" | |
| 725 | +type in Limbo; the | |
| 726 | +.CW "con" | |
| 727 | +declaration is the closest equivalent. | |
| 728 | +When the values are arbitrary, a different form is normally used: | |
| 729 | +.P1 | |
| 730 | + OUT, IN: con iota; | |
| 731 | +.P2 | |
| 732 | +The operator | |
| 733 | +.CW "iota" , | |
| 734 | +when used in | |
| 735 | +.CW con | |
| 736 | +declarations will produce the sequence of values 0, 1, ...., | |
| 737 | +one value in turn for each name declared in the same declaration. | |
| 738 | +It can appear in more complex expressions: | |
| 739 | +.P1 | |
| 740 | + M1, M2, M4, M8: con 1 << iota; | |
| 741 | + N1, N3, N5, N7: con (2*iota)+1; | |
| 742 | +.P2 | |
| 743 | +The first example generates a set of bitmask values; the second generates a | |
| 744 | +sequence of odd numbers. | |
| 745 | +.LP | |
| 746 | +Given the declarations of | |
| 747 | +.CW "IN" | |
| 748 | +and | |
| 749 | +.CW "OUT" , | |
| 750 | +the line | |
| 751 | +.P1 | |
| 752 | + state := OUT; | |
| 753 | +.P2 | |
| 754 | +declares | |
| 755 | +.CW "state" | |
| 756 | +to be an integer with initial value zero. | |
| 757 | +.LP | |
| 758 | +The line | |
| 759 | +.P1 | |
| 760 | + buf := array[1] of byte; | |
| 761 | +.P2 | |
| 762 | +declares | |
| 763 | +.CW "buf" | |
| 764 | +to be a one-element array of | |
| 765 | +.CW "byte" s. | |
| 766 | +Arrays are indexed from zero, so | |
| 767 | +.CW "buf[0]" | |
| 768 | +is the only element. | |
| 769 | +Arrays in Limbo are dynamic, so this array is created at | |
| 770 | +the point of the declaration. | |
| 771 | +An alternative would be to declare the array and | |
| 772 | +create it in separate statements: | |
| 773 | +.P1 | |
| 774 | + buf : array of byte; # no size at declaration | |
| 775 | + | |
| 776 | + buf = array[1] of byte; # size needed at creation | |
| 777 | +.P2 | |
| 778 | +.LP | |
| 779 | +Limbo does no automatic coercions between types, | |
| 780 | +so an explicit coercion is required to convert the | |
| 781 | +single byte read from | |
| 782 | +.CW "stdin" | |
| 783 | +into an | |
| 784 | +.CW "int" | |
| 785 | +that can be used in subsequent comparisons with | |
| 786 | +.CW "int" 's; | |
| 787 | +this is done by the line | |
| 788 | +.P1 | |
| 789 | + c := int buf[0]; | |
| 790 | +.P2 | |
| 791 | +which declares | |
| 792 | +.CW "c" | |
| 793 | +and assigns the integer value of the input byte to it. | |
| 794 | +.NH 2 | |
| 795 | +Word Count Version 2 | |
| 796 | +.LP | |
| 797 | +The word count program above tacitly assumes that its input is | |
| 798 | +in the ASCII subset of Unicode, since it reads | |
| 799 | +input one byte at a time instead of one Unicode character | |
| 800 | +at a time. | |
| 801 | +If the input contains any multi-byte Unicode characters, | |
| 802 | +this code is plain wrong. | |
| 803 | +The assignment to | |
| 804 | +.CW "c" | |
| 805 | +is a specific example: the integer value of the first byte | |
| 806 | +of a multi-byte Unicode character is not the character. | |
| 807 | +.LP | |
| 808 | +There are several ways to address this shortcoming. | |
| 809 | +Among the possibilities are | |
| 810 | +rewriting to use the | |
| 811 | +.CW "Bufio" | |
| 812 | +module, which does string I/O, | |
| 813 | +or checking each input byte sequence to see if it is | |
| 814 | +a multi-byte character. | |
| 815 | +The second version of word counting uses | |
| 816 | +.CW "Bufio" . | |
| 817 | +This example will also illustrate rules for accessing objects | |
| 818 | +within modules. | |
| 819 | +.P1 | |
| 820 | +# declarations omitted... | |
| 821 | + | |
| 822 | +include "bufio.m"; | |
| 823 | + bufio: Bufio; | |
| 824 | + Iobuf: import bufio; | |
| 825 | + | |
| 826 | +init(nil: ref Draw->Context, nil: list of string) | |
| 827 | +{ | |
| 828 | + sys = load Sys Sys->PATH; | |
| 829 | + bufio = load Bufio Bufio->PATH; | |
| 830 | + if (bufio == nil) { | |
| 831 | + sys->fprint(sys->fildes(2), "wc: can't load %s: %r\en", Bufio->PATH); | |
| 832 | + raise "fail:load"; | |
| 833 | + } | |
| 834 | + | |
| 835 | + stdin := sys->fildes(0); | |
| 836 | + iob := bufio->fopen(stdin, bufio->OREAD); | |
| 837 | + if (iob == nil) { | |
| 838 | + sys->fprint(sys->fildes(2), "wc: can't open stdin: %r\en"); | |
| 839 | + raise "fail:open"; | |
| 840 | + } | |
| 841 | + | |
| 842 | + OUT, IN: con iota; | |
| 843 | + | |
| 844 | + state := OUT; | |
| 845 | + nl := big 0; nw := big 0; nc := big 0; | |
| 846 | + for (;;) { | |
| 847 | + c := iob.getc(); | |
| 848 | + if (c == Bufio->EOF) | |
| 849 | + break; | |
| 850 | + nc++; | |
| 851 | + if (c == '\en') | |
| 852 | + nl++; | |
| 853 | + if (c == ' ' || c == '\et' || c == '\en') | |
| 854 | + state = OUT; | |
| 855 | + else if (state == OUT) { | |
| 856 | + state = IN; | |
| 857 | + nw++; | |
| 858 | + } | |
| 859 | + } | |
| 860 | + sys->print("%bd %bd %bd\en", nl, nw, nc); | |
| 861 | +} | |
| 862 | +.P2 | |
| 863 | +The lines | |
| 864 | +.P1 | |
| 865 | +include "bufio.m"; | |
| 866 | + bufio: Bufio; | |
| 867 | +.P2 | |
| 868 | +include the declarations from | |
| 869 | +.CW "bufio.m" | |
| 870 | +and declare a variable | |
| 871 | +.CW "bufio" | |
| 872 | +that will serve as a handle when we load an implementation of the | |
| 873 | +.CW "Bufio" | |
| 874 | +module. | |
| 875 | +(The use of a module's type in lower case as the name of a loaded instance is a common convention in Limbo programs.) | |
| 876 | +With this handle, we can | |
| 877 | +refer to the functions and types | |
| 878 | +the module defines, which are in the file | |
| 879 | +.CW "/usr/inferno/module/bufio.m" | |
| 880 | +(the full name might be different on your system). | |
| 881 | +Parts of this declaration are shown here: | |
| 882 | +.P1 | |
| 883 | +Bufio: module # edited to fit your screen | |
| 884 | +{ | |
| 885 | + PATH: con "/dis/bufio.dis"; | |
| 886 | + EOF: con -1; | |
| 887 | + Iobuf: adt { | |
| 888 | + fd: ref Sys->FD; # the file | |
| 889 | + buffer: array of byte; # the buffer | |
| 890 | + # other variables omitted | |
| 891 | + getc: fn(b: self ref Iobuf) : int; | |
| 892 | + gets: fn(b: self ref Iobuf, sep: int) : string; | |
| 893 | + close: fn(b: self ref Iobuf); | |
| 894 | + }; | |
| 895 | + open: fn(name: string, mode: int) : ref Iobuf; | |
| 896 | + fopen: fn(fd: ref Sys->FD, mode: int) : ref Iobuf; | |
| 897 | +}; | |
| 898 | +.P2 | |
| 899 | +.LP | |
| 900 | +The | |
| 901 | +.CW "bufio" | |
| 902 | +module defines | |
| 903 | +.CW "open" | |
| 904 | +and | |
| 905 | +.CW "fopen" | |
| 906 | +functions that return references to an | |
| 907 | +.CW "Iobuf" ; | |
| 908 | +this is much like a | |
| 909 | +.CW "FILE*" | |
| 910 | +in the C standard I/O library. | |
| 911 | +A reference is necessary so that all uses | |
| 912 | +refer to the same entity, the object maintained by the module. | |
| 913 | +.LP | |
| 914 | +Given the name of a module (e.g., | |
| 915 | +.CW "Bufio" ), | |
| 916 | +how do we refer to its contents? | |
| 917 | +It is always possible to use fully-qualified names, | |
| 918 | +and the | |
| 919 | +.CW "import" | |
| 920 | +statement permits certain abbreviations. | |
| 921 | +We must also distinguish between the name of the module itself | |
| 922 | +and a specific implementation returned by | |
| 923 | +.CW "load" , | |
| 924 | +such as | |
| 925 | +.CW "bufio" . | |
| 926 | +.LP | |
| 927 | +The fully-qualified name of a type or constant from a module | |
| 928 | +is | |
| 929 | +.P1 | |
| 930 | +\fIModulename\fP->\fIname\fP | |
| 931 | +.P2 | |
| 932 | +as in | |
| 933 | +.CW "Bufio->Iobuf" | |
| 934 | +or | |
| 935 | +.CW "Bufio->EOF" . | |
| 936 | +To refer to members of an adt or functions or variables from a module, however, | |
| 937 | +it is necessary to use a module value instead of a module name: | |
| 938 | +although the interface | |
| 939 | +is always the same, the implementations of different instances | |
| 940 | +of a module will be different, and we must refer to a specific | |
| 941 | +implementation. | |
| 942 | +A fully-qualified name is | |
| 943 | +.P1 | |
| 944 | +\fImoduleval\fP->\fIfunctionname\fP | |
| 945 | +\fImoduleval\fP->\fIvariablename\fP | |
| 946 | +\fImoduleval\fP->\fIadtname\fP.\fImembername\fP | |
| 947 | +.P2 | |
| 948 | +where adt members can be variables or functions. | |
| 949 | +Thus: | |
| 950 | +.P1 | |
| 951 | +iob: ref bufio->Iobuf; | |
| 952 | +... | |
| 953 | +bufio->open(...) | |
| 954 | +bufio->iob.getc() | |
| 955 | +bufio->iob.fd | |
| 956 | +.P2 | |
| 957 | +It is also legal to refer to module types, constants, and variables | |
| 958 | +with a module handle, as in | |
| 959 | +.CW "bufio->EOF" . | |
| 960 | +.LP | |
| 961 | +An | |
| 962 | +.CW "import" | |
| 963 | +statement makes a specific list of names from | |
| 964 | +a module accessible without need for a fully-qualified name. | |
| 965 | +Each name must be imported explicitly, and adt member names | |
| 966 | +can not be imported. | |
| 967 | +Thus, the line | |
| 968 | +.P1 | |
| 969 | +Iobuf: import bufio; | |
| 970 | +.P2 | |
| 971 | +imports the adt name | |
| 972 | +.CW "Iobuf" , | |
| 973 | +which means that functions within that adt (like | |
| 974 | +.CW "getc)" | |
| 975 | +can be used | |
| 976 | +without module qualification, i.e., without | |
| 977 | +.CW "bufio->" . | |
| 978 | +(It is still necessary to say | |
| 979 | +.CW "iob.getc()" | |
| 980 | +for reasons given below.) | |
| 981 | +In all cases, imported names must be unique. | |
| 982 | +.LP | |
| 983 | +The second parameter of | |
| 984 | +.CW "load" | |
| 985 | +is a string giving the location of the module implementation, | |
| 986 | +typically a | |
| 987 | +.CW ".dis" | |
| 988 | +file. | |
| 989 | +(The string need not be static.) | |
| 990 | +Some modules are part of the system; | |
| 991 | +these have location names that begin with | |
| 992 | +.CW "$" | |
| 993 | +but are otherwise the same for users. | |
| 994 | +By convention, modules include a constant called | |
| 995 | +.CW "PATH" | |
| 996 | +that points to their default location. | |
| 997 | +.LP | |
| 998 | +The call to | |
| 999 | +.CW "bufio->fopen" | |
| 1000 | +attaches the I/O buffer to the already open file | |
| 1001 | +.CW "stdin" ; | |
| 1002 | +this is rather like | |
| 1003 | +.CW "freopen" | |
| 1004 | +in | |
| 1005 | +.CW "stdio" . | |
| 1006 | +.LP | |
| 1007 | +The function | |
| 1008 | +.CW "iob.getc" | |
| 1009 | +returns the next Unicode character, | |
| 1010 | +or | |
| 1011 | +.CW "bufio->EOF" | |
| 1012 | +if end of file was encountered. | |
| 1013 | +.LP | |
| 1014 | +A close look at the calls to | |
| 1015 | +.CW "sys->print" | |
| 1016 | +shows a new format conversion character, | |
| 1017 | +.CW "%r" , | |
| 1018 | +for which there is no corresponding argument in the | |
| 1019 | +expression list. | |
| 1020 | +The value of | |
| 1021 | +.CW "%r" | |
| 1022 | +is the text of the most recent system error message. | |
| 1023 | +.LP | |
| 1024 | +Several other small changes were made as realistic examples: | |
| 1025 | +it keeps the counts as | |
| 1026 | +.CW big | |
| 1027 | +to cope with larger files (hence the use of | |
| 1028 | +.CW %bd | |
| 1029 | +as the output format); | |
| 1030 | +it prints diagnostics on the standard error stream, | |
| 1031 | +.CW sys->fildes(2) , | |
| 1032 | +using | |
| 1033 | +.CW sys->fprint , | |
| 1034 | +a variant of | |
| 1035 | +.CW sys->print | |
| 1036 | +that takes an explicit file descriptor; | |
| 1037 | +and it returns an error status to its caller (typically the shell) by | |
| 1038 | +raising an exception. | |
| 1039 | +.NH 2 | |
| 1040 | +An Associative Array Module | |
| 1041 | +.LP | |
| 1042 | +This section describes a module that implements a conventional | |
| 1043 | +associative array (a hash table | |
| 1044 | +pointing to chained lists of name-value strings). | |
| 1045 | +This module is meant to be part of a larger program, | |
| 1046 | +not a standalone program like the previous examples. | |
| 1047 | +.LP | |
| 1048 | +The | |
| 1049 | +.CW "Hashtab" | |
| 1050 | +module stores a name-value pair as a tuple of | |
| 1051 | +.CW "(string," | |
| 1052 | +.CW "string)" . | |
| 1053 | +A tuple is a type consisting of an ordered collection | |
| 1054 | +of objects, each with its own type. | |
| 1055 | +The hash table implementation uses several different tuples. | |
| 1056 | +.LP | |
| 1057 | +The hash table module defines a type to hold the | |
| 1058 | +data, using an | |
| 1059 | +.CW "adt" | |
| 1060 | +declaration. | |
| 1061 | +An adt defines a type and optionally a set of functions | |
| 1062 | +that manipulate an object of that type. | |
| 1063 | +Since it provides only the ability to group variables and functions, | |
| 1064 | +it is like a really slimmed-down version of a C++ class, | |
| 1065 | +or a slightly fancier C | |
| 1066 | +.CW "struct" . | |
| 1067 | +In particular, an adt does not provide information hiding | |
| 1068 | +(all member names are visible if the adt itself is visible), | |
| 1069 | +does not support inheritance, | |
| 1070 | +and has no constructors, destructors or overloaded method names. | |
| 1071 | +It is different from C or C++, however: when an adt is declared by a | |
| 1072 | +.CW module | |
| 1073 | +declaration, the adt's implementation (the bodies of its functions) | |
| 1074 | +will be defined by the module's implementation, and there can be more than one. | |
| 1075 | +To create an instance of an adt, | |
| 1076 | +.P1 | |
| 1077 | +\fIadtvar\fP := \fIadtname\fP(\fIlist of values for all members, in order\fP); | |
| 1078 | +\fIadtvar\fP := ref \fIadtname\fP(\fIlist of values for all members, in order\fP); | |
| 1079 | +.P2 | |
| 1080 | +Technically these are casts, from tuple to adt; | |
| 1081 | +that is, the adt is created from a tuple that | |
| 1082 | +specifies all of its members in order. | |
| 1083 | +.LP | |
| 1084 | +The | |
| 1085 | +.CW "Hashtab" | |
| 1086 | +module contains an | |
| 1087 | +.CW "adt" | |
| 1088 | +declaration for a type | |
| 1089 | +.CW "Table" ; | |
| 1090 | +the operations are a function | |
| 1091 | +.CW "alloc" | |
| 1092 | +for initial allocation | |
| 1093 | +(in effect a constructor), | |
| 1094 | +a hash function, and methods to add and look up elements by name. | |
| 1095 | +Here is the module declaration, which is contained in file | |
| 1096 | +.CW "hashtab.m" : | |
| 1097 | +.nr dT 4 | |
| 1098 | +.nr dP \n(dP+1 | |
| 1099 | +.P1 | |
| 1100 | +Hashtab: module | |
| 1101 | +{ | |
| 1102 | + PATH: con "/usr/bwk/hashtab.dis"; # temporary name | |
| 1103 | + | |
| 1104 | + Table: adt { | |
| 1105 | + tab: array of list of (string, string); | |
| 1106 | + | |
| 1107 | + alloc: fn(n: int) : ref Table; | |
| 1108 | + | |
| 1109 | + hash: fn(ht: self ref Table, name: string) : int; | |
| 1110 | + add: fn(ht: self ref Table, name: string, val: string); | |
| 1111 | + lookup: fn(ht: self ref Table, name: string) : (int, string); | |
| 1112 | + }; | |
| 1113 | +}; | |
| 1114 | +.P2 | |
| 1115 | +.nr dT 8 | |
| 1116 | +.nr dP \n(dP-1 | |
| 1117 | +The implementation is in file | |
| 1118 | +.CW "hashtab.b" : | |
| 1119 | +.P1 | |
| 1120 | +implement Hashtab; | |
| 1121 | + | |
| 1122 | +include "hashtab.m"; | |
| 1123 | + | |
| 1124 | +Table.alloc(n: int) : ref Table | |
| 1125 | +{ | |
| 1126 | + return ref Table(array[n] of list of (string,string)); | |
| 1127 | +} | |
| 1128 | + | |
| 1129 | +Table.hash(ht: self ref Table, s: string) : int | |
| 1130 | +{ | |
| 1131 | + h := 0; | |
| 1132 | + for (i := 0; i < len s; i++) | |
| 1133 | + h = (h << 1) ^ int s[i]; | |
| 1134 | + h %= len ht.tab; | |
| 1135 | + if (h < 0) | |
| 1136 | + h += len ht.tab; | |
| 1137 | + return h; | |
| 1138 | +} | |
| 1139 | + | |
| 1140 | +Table.add(ht: self ref Table, name: string, val: string) | |
| 1141 | +{ | |
| 1142 | + h := ht.hash(name); | |
| 1143 | + for (p := ht.tab[h]; p != nil; p = tl p) { | |
| 1144 | + (tname, nil) := hd p; | |
| 1145 | + if (tname == name) { | |
| 1146 | + # illegal: hd p = (tname, val); | |
| 1147 | + return; | |
| 1148 | + } | |
| 1149 | + } | |
| 1150 | + ht.tab[h] = (name, val) :: ht.tab[h]; | |
| 1151 | +} | |
| 1152 | + | |
| 1153 | +Table.lookup(ht: self ref Table, name: string) : (int, string) | |
| 1154 | +{ | |
| 1155 | + h := ht.hash(name); | |
| 1156 | + for (p := ht.tab[h]; p != nil; p = tl p) { | |
| 1157 | + (tname, tval) := hd p; | |
| 1158 | + if (tname == name) | |
| 1159 | + return (1, tval); | |
| 1160 | + } | |
| 1161 | + return (0, ""); | |
| 1162 | +} | |
| 1163 | + | |
| 1164 | +.P2 | |
| 1165 | +This is intentionally simple-minded, to focus on the language | |
| 1166 | +rather than efficiency or flexibility. | |
| 1167 | +The function | |
| 1168 | +.CW "Table.alloc" | |
| 1169 | +creates and returns a | |
| 1170 | +.CW "Table" | |
| 1171 | +with a specified size and an array of elements, | |
| 1172 | +each of which is a list of | |
| 1173 | +.CW "(string," | |
| 1174 | +.CW "string)" . | |
| 1175 | +.LP | |
| 1176 | +The | |
| 1177 | +.CW "hash" | |
| 1178 | +function is trivial; the only interesting point | |
| 1179 | +is the | |
| 1180 | +.CW "len" | |
| 1181 | +operator, which returns the number of items in a string, array or list. | |
| 1182 | +For a string, | |
| 1183 | +.CW "len" | |
| 1184 | +.CW "s" | |
| 1185 | +is the number of Unicode characters. | |
| 1186 | +.LP | |
| 1187 | +The | |
| 1188 | +.CW "self" | |
| 1189 | +declaration says that the first | |
| 1190 | +argument of every call of this function is implicit, and refers to the | |
| 1191 | +value itself; this argument does not appear in the actual parameter list at any call site. | |
| 1192 | +.CW "Self" | |
| 1193 | +is similar to | |
| 1194 | +.CW "this" | |
| 1195 | +in C++. | |
| 1196 | +.LP | |
| 1197 | +The | |
| 1198 | +.CW "lookup" | |
| 1199 | +function searches down the appropriate list for | |
| 1200 | +an instance of the | |
| 1201 | +.CW "name" | |
| 1202 | +argument. | |
| 1203 | +If a match is found, | |
| 1204 | +.CW "lookup" | |
| 1205 | +returns a tuple consisting of 1 and the value field; | |
| 1206 | +if no match is found, it returns a tuple of 0 and an empty string. | |
| 1207 | +These return types match the function return type, | |
| 1208 | +.CW "(int," | |
| 1209 | +.CW "string)" . | |
| 1210 | +.LP | |
| 1211 | +The line | |
| 1212 | +.P1 | |
| 1213 | + (tname, tval) := hd p; | |
| 1214 | +.P2 | |
| 1215 | +shows a tuple on the left side of a declaration-assignment. | |
| 1216 | +This splits the pair of strings referred to by | |
| 1217 | +.CW "hd" | |
| 1218 | +.CW "p" | |
| 1219 | +into components and assigns them to the newly declared variables | |
| 1220 | +.CW "tname" | |
| 1221 | +and | |
| 1222 | +.CW "tval" . | |
| 1223 | +.LP | |
| 1224 | +The | |
| 1225 | +.CW "add" | |
| 1226 | +function is similar; | |
| 1227 | +it searches the right list for an instance of | |
| 1228 | +the name. | |
| 1229 | +If none is found, | |
| 1230 | +.P1 | |
| 1231 | + ht.tab[h] = (name, val) :: ht.tab[h]; | |
| 1232 | +.P2 | |
| 1233 | +combines the name and value into a tuple, then uses | |
| 1234 | +.CW "::" | |
| 1235 | +to stick it on the front of the proper list. | |
| 1236 | +.LP | |
| 1237 | +The line | |
| 1238 | +.P1 | |
| 1239 | + (tname, nil) := hd p; | |
| 1240 | +.P2 | |
| 1241 | +in the loop body is a less obvious use of a tuple. | |
| 1242 | +In this case, only the first component, the name, | |
| 1243 | +is assigned, to a variable | |
| 1244 | +.CW "tname" | |
| 1245 | +that is declared here. | |
| 1246 | +The other component is ``assigned'' to | |
| 1247 | +.CW "nil" , | |
| 1248 | +which causes it to be ignored. | |
| 1249 | +.LP | |
| 1250 | +The line | |
| 1251 | +.P1 | |
| 1252 | + # illegal: hd p = (tname, val); | |
| 1253 | +.P2 | |
| 1254 | +is commented out because it's illegal: | |
| 1255 | +Limbo does not permit the assignment of a new name-value | |
| 1256 | +to a list element; | |
| 1257 | +list elements are immutable. | |
| 1258 | +.LP | |
| 1259 | +To create a new | |
| 1260 | +.CW "Table" , | |
| 1261 | +add some values, then retrieve one, we can write: | |
| 1262 | +.P1 | |
| 1263 | + nvtab = Table.alloc(101); # make a Table | |
| 1264 | + | |
| 1265 | + nvtab.add("Rob", "Pike"); | |
| 1266 | + nvtab.add("Howard", "Trickey"); | |
| 1267 | + (p, phil) := nvtab.lookup("Phil"); | |
| 1268 | + (q, sean) := nvtab.lookup("Sean"); | |
| 1269 | +.P2 | |
| 1270 | +Note that the | |
| 1271 | +.CW "ref" | |
| 1272 | +.CW "Table" | |
| 1273 | +argument does not appear in these calls; | |
| 1274 | +the | |
| 1275 | +.CW "self" | |
| 1276 | +mechanism renders it unnecessary. | |
| 1277 | +Remember that a module using | |
| 1278 | +.CW Table | |
| 1279 | +must | |
| 1280 | +.CW import | |
| 1281 | +it from some instance of | |
| 1282 | +.CW Hashtab , | |
| 1283 | +or qualify all references to it by a module value. | |
| 1284 | +.NH 2 | |
| 1285 | +An AWK-like Input Module | |
| 1286 | +.LP | |
| 1287 | +This example presents a simple module based on Awk's input mechanism: | |
| 1288 | +it reads input a line at a time from a list of of files, | |
| 1289 | +splits each line into an array of | |
| 1290 | +.CW "NF+1" | |
| 1291 | +strings (the original input line and the individual fields), and | |
| 1292 | +sets | |
| 1293 | +.CW "NF" , | |
| 1294 | +.CW "NR" , | |
| 1295 | +and | |
| 1296 | +.CW "FILENAME" . | |
| 1297 | +It comes in the usual two parts, a module: | |
| 1298 | +.P1 | |
| 1299 | +.nr dP \n(dP+1 | |
| 1300 | +.nr dT 4 | |
| 1301 | +Awk: module | |
| 1302 | +{ | |
| 1303 | + PATH: con "/usr/bwk/awk.dis"; | |
| 1304 | + | |
| 1305 | + init: fn(args: list of string); | |
| 1306 | + getline: fn() : array of string; | |
| 1307 | + NR: fn() : int; | |
| 1308 | + NF: fn() : int; | |
| 1309 | + FILENAME: fn() : string; | |
| 1310 | +}; | |
| 1311 | +.P2 | |
| 1312 | +.nr dP \n(dP-1 | |
| 1313 | +.nr dT 8 | |
| 1314 | +and an implementation: | |
| 1315 | +.nr dP \n(dP+1 | |
| 1316 | +.nr dT 4 | |
| 1317 | +.P1 | |
| 1318 | +implement Awk; | |
| 1319 | + | |
| 1320 | +include "sys.m"; | |
| 1321 | + sys: Sys; | |
| 1322 | +include "bufio.m"; | |
| 1323 | + bufio: Bufio; | |
| 1324 | +Iobuf: import bufio; | |
| 1325 | + iobuf: ref Iobuf; | |
| 1326 | + | |
| 1327 | +include "awk.m"; | |
| 1328 | + | |
| 1329 | +_NR: int; | |
| 1330 | +_NF: int; | |
| 1331 | +_FILENAME: string; | |
| 1332 | +args: list of string; | |
| 1333 | + | |
| 1334 | +.P3 | |
| 1335 | +init(av: list of string) | |
| 1336 | +{ | |
| 1337 | + args = tl av; | |
| 1338 | + if (len args == 0) # no args => stdin | |
| 1339 | + args = "-" :: nil; | |
| 1340 | + | |
| 1341 | + sys = load Sys Sys->PATH; | |
| 1342 | + bufio = load Bufio Bufio->PATH; | |
| 1343 | +} | |
| 1344 | + | |
| 1345 | +.P3 | |
| 1346 | +getline() : array of string | |
| 1347 | +{ | |
| 1348 | + t := array[100] of string; | |
| 1349 | + fl: list of string; | |
| 1350 | + | |
| 1351 | + top: | |
| 1352 | + while (args != nil) { | |
| 1353 | + if (_FILENAME == nil) { # advance to next file | |
| 1354 | + _FILENAME = hd args; | |
| 1355 | + if (_FILENAME == "-") | |
| 1356 | + iobuf = bufio->fopen(sys->fildes(0), bufio->OREAD); | |
| 1357 | + else | |
| 1358 | + iobuf = bufio->open(_FILENAME, bufio->OREAD); | |
| 1359 | + if (iobuf == nil) { | |
| 1360 | + sys->fprint(sys->fildes(2), "can't open %s: %r\en", _FILENAME); | |
| 1361 | + args = nil; | |
| 1362 | + return nil; | |
| 1363 | + } | |
| 1364 | + } | |
| 1365 | + | |
| 1366 | +.P3 | |
| 1367 | + s := iobuf.gets('\en'); | |
| 1368 | + if (s == nil) { | |
| 1369 | + iobuf.close(); | |
| 1370 | + _FILENAME = nil; | |
| 1371 | + args = tl args; | |
| 1372 | + continue top; | |
| 1373 | + } | |
| 1374 | + | |
| 1375 | +.P3 | |
| 1376 | + t[0] = s[0:len s - 1]; | |
| 1377 | + _NR++; | |
| 1378 | + (_NF, fl) = sys->tokenize(t[0], " \et\en\er"); | |
| 1379 | + for (i := 1; fl != nil; fl = tl fl) | |
| 1380 | + t[i++] = hd fl; | |
| 1381 | + return t[0:i]; | |
| 1382 | + } | |
| 1383 | + return nil; | |
| 1384 | +} | |
| 1385 | + | |
| 1386 | +NR() : int { return _NR; } | |
| 1387 | +NF() : int { return _NF; } | |
| 1388 | +FILENAME() : string { return _FILENAME; } | |
| 1389 | +.P2 | |
| 1390 | +.nr dT 8 | |
| 1391 | +.nr dP \n(dP-1 | |
| 1392 | +Since | |
| 1393 | +.CW "NR" , | |
| 1394 | +.CW "NF" | |
| 1395 | +and | |
| 1396 | +.CW "FILENAME" | |
| 1397 | +should not be modified by users, they | |
| 1398 | +are accessed as functions; the actual variables have | |
| 1399 | +related names like | |
| 1400 | +.CW "_NF" . | |
| 1401 | +It would also be possible to make them ordinary variables | |
| 1402 | +in the | |
| 1403 | +.CW "Awk" | |
| 1404 | +module, and refer to them via a module value (i.e., | |
| 1405 | +.CW awk->NR ). | |
| 1406 | +.LP | |
| 1407 | +The | |
| 1408 | +.CW "tokenize" | |
| 1409 | +function in the line | |
| 1410 | +.P1 | |
| 1411 | + (_NF, fl) = sys->tokenize(t[0], " \et\en\er"); | |
| 1412 | +.P2 | |
| 1413 | +breaks the argument string | |
| 1414 | +.CW "t[0]" | |
| 1415 | +into tokens, as separated by the characters of the second argument. | |
| 1416 | +It returns a tuple consisting of a length and a list | |
| 1417 | +of tokens. | |
| 1418 | +Note that this module has an | |
| 1419 | +.CW "init" | |
| 1420 | +function that must be called explicitly before | |
| 1421 | +any of its other functions are called. | |
| 1422 | +.NH 2 | |
| 1423 | +A Simple Formatter | |
| 1424 | +.LP | |
| 1425 | +This program is a simple-minded text formatter, modeled after | |
| 1426 | +.CW "fmt" , | |
| 1427 | +that tests the Awk module: | |
| 1428 | +.P1 | |
| 1429 | +implement Fmt; | |
| 1430 | + | |
| 1431 | +include "sys.m"; | |
| 1432 | + sys: Sys; | |
| 1433 | +include "draw.m"; | |
| 1434 | + | |
| 1435 | +Fmt: module | |
| 1436 | +{ | |
| 1437 | + init: fn(nil: ref Draw->Context, args: list of string); | |
| 1438 | +}; | |
| 1439 | + | |
| 1440 | +include "awk.m"; | |
| 1441 | + awk: Awk; | |
| 1442 | + getline, NF: import awk; | |
| 1443 | + | |
| 1444 | +out: array of string; | |
| 1445 | +nout: int; | |
| 1446 | +length: int; | |
| 1447 | +linelen := 65; | |
| 1448 | + | |
| 1449 | +.P3 | |
| 1450 | +init(nil: ref Draw->Context, args: list of string) | |
| 1451 | +{ | |
| 1452 | + t: array of string; | |
| 1453 | + out = array[100] of string; | |
| 1454 | + | |
| 1455 | + sys = load Sys Sys->PATH; | |
| 1456 | + awk = load Awk Awk->PATH; | |
| 1457 | + if (awk == nil) { | |
| 1458 | + sys->fprint(sys->fildes(2), "fmt: can't load %s: %r\en", | |
| 1459 | + Awk->PATH); | |
| 1460 | + raise "fail:load"; | |
| 1461 | + } | |
| 1462 | + awk->init(args); | |
| 1463 | + | |
| 1464 | + nout = 0; | |
| 1465 | + length = 0; | |
| 1466 | + while ((t = getline()) != nil) { | |
| 1467 | + nf := NF(); | |
| 1468 | + if (nf == 0) { | |
| 1469 | + printline(); | |
| 1470 | + sys->print("\en"); | |
| 1471 | + } else for (i := 1; i <= nf; i++) { | |
| 1472 | + if (length + len t[i] > linelen) | |
| 1473 | + printline(); | |
| 1474 | + out[nout++] = t[i]; | |
| 1475 | + length += len t[i] + 1; | |
| 1476 | + } | |
| 1477 | + } | |
| 1478 | + printline(); | |
| 1479 | +} | |
| 1480 | +.P3 | |
| 1481 | +printline() | |
| 1482 | +{ | |
| 1483 | + if (nout == 0) | |
| 1484 | + return; | |
| 1485 | + for (i := 0; i < nout-1; i++) | |
| 1486 | + sys->print("%s ", out[i]); | |
| 1487 | + sys->print("%s\en", out[i]); | |
| 1488 | + nout = 0; | |
| 1489 | + length = 0; | |
| 1490 | +} | |
| 1491 | +.P2 | |
| 1492 | +The functions | |
| 1493 | +.CW "getline" | |
| 1494 | +and | |
| 1495 | +.CW "NF" | |
| 1496 | +have been imported so their names need no qualification. | |
| 1497 | +It is more usual Limbo style to use explicit references such as | |
| 1498 | +.CW sys->read | |
| 1499 | +or | |
| 1500 | +.CW Bufio->EOF | |
| 1501 | +for clarity, and import only adts (and perhaps commonly used constants). | |
| 1502 | +.NH 2 | |
| 1503 | +Channels and Communications | |
| 1504 | +.LP | |
| 1505 | +Another approach to a formatter is to use one process to fetch words and | |
| 1506 | +pass them to another process that formats and prints them. | |
| 1507 | +This is easily done with a channel, as in this | |
| 1508 | +alternative version: | |
| 1509 | +.P1 | |
| 1510 | +# declarations omitted... | |
| 1511 | + | |
| 1512 | +WORD, BREAK, EOF: con iota; | |
| 1513 | +wds: chan of (int, string); | |
| 1514 | + | |
| 1515 | +init(nil: ref Draw->Context, nil: list of string) | |
| 1516 | +{ | |
| 1517 | + sys = load Sys Sys->PATH; | |
| 1518 | + bufio = load Bufio Bufio->PATH; | |
| 1519 | + | |
| 1520 | + stdin := sys->fildes(0); | |
| 1521 | + iob = bufio->fopen(stdin, bufio->OREAD); | |
| 1522 | + | |
| 1523 | + wds = chan of (int, string); | |
| 1524 | + spawn getword(wds); | |
| 1525 | + putword(wds); | |
| 1526 | +} | |
| 1527 | + | |
| 1528 | +.P3 | |
| 1529 | +getword(wds: chan of (int, string)) | |
| 1530 | +{ | |
| 1531 | + while ((s := iob.gets('\en')) != nil) { | |
| 1532 | + (n, fl) := sys->tokenize(s, " \et\en"); | |
| 1533 | + if (n == 0) | |
| 1534 | + wds <-= (BREAK, ""); | |
| 1535 | + else for ( ; fl != nil; fl = tl fl) | |
| 1536 | + wds <-= (WORD, hd fl); | |
| 1537 | + } | |
| 1538 | + wds <-= (EOF, ""); | |
| 1539 | +} | |
| 1540 | + | |
| 1541 | +.P3 | |
| 1542 | +putword(wds: chan of (int, string)) | |
| 1543 | +{ | |
| 1544 | + for (length := 0;;) { | |
| 1545 | + (wd, s) := <-wds; | |
| 1546 | + case wd { | |
| 1547 | + BREAK => | |
| 1548 | + sys->print("\en\en"); | |
| 1549 | + length = 0; | |
| 1550 | + WORD => | |
| 1551 | + if (length + len s > 65) { | |
| 1552 | + sys->print("\en"); | |
| 1553 | + length = 0; | |
| 1554 | + } | |
| 1555 | + sys->print("%s ", s); | |
| 1556 | + length += len s + 1; | |
| 1557 | + EOF => | |
| 1558 | + sys->print("\en"); | |
| 1559 | + exit; | |
| 1560 | + } | |
| 1561 | + } | |
| 1562 | +} | |
| 1563 | +.P2 | |
| 1564 | +This omits declarations and error checking in the interest | |
| 1565 | +of brevity. | |
| 1566 | +.LP | |
| 1567 | +The channel passes a tuple of | |
| 1568 | +.CW "int" , ( | |
| 1569 | +.CW "string" ); | |
| 1570 | +the | |
| 1571 | +.CW "int" | |
| 1572 | +indicates what kind of string is present \- | |
| 1573 | +a real word, a break caused by an empty input line, | |
| 1574 | +or | |
| 1575 | +.CW "EOF" . | |
| 1576 | +.LP | |
| 1577 | +The | |
| 1578 | +.CW "spawn" | |
| 1579 | +statement creates a separate process by calling the specified function; | |
| 1580 | +except for its own stack, | |
| 1581 | +this process shares memory with the process that spawned it. | |
| 1582 | +Any synchronization between processes is handled by channels. | |
| 1583 | +.LP | |
| 1584 | +The operator | |
| 1585 | +.CW "<-=" | |
| 1586 | +sends an expression to a channel; | |
| 1587 | +the operator | |
| 1588 | +.CW "<-" | |
| 1589 | +receives from a channel. | |
| 1590 | +(Receive is combined here with | |
| 1591 | +.CW ":=" | |
| 1592 | +to receive a tuple, and assign its elements to newly-declared variables.) | |
| 1593 | +In this example, | |
| 1594 | +.CW "getword" | |
| 1595 | +and | |
| 1596 | +.CW "putword" | |
| 1597 | +alternate, because each input word | |
| 1598 | +is sent immediately on the shared channel, | |
| 1599 | +and no subsequent word is processed until the previous one has been | |
| 1600 | +received and printed. | |
| 1601 | +.LP | |
| 1602 | +The | |
| 1603 | +.CW "case" | |
| 1604 | +statement consists of a list of case values, | |
| 1605 | +which must be string or numeric constants, followed by | |
| 1606 | +.CW "=>" | |
| 1607 | +and associated code. | |
| 1608 | +The value | |
| 1609 | +.CW "*" | |
| 1610 | +(not used here) labels the default. | |
| 1611 | +Multiple labels can be used, separated by the | |
| 1612 | +.CW "or" | |
| 1613 | +operator, | |
| 1614 | +and ranges of values can appear delimited by | |
| 1615 | +.CW "to" , | |
| 1616 | +as in | |
| 1617 | +.P1 | |
| 1618 | + 'a' to 'z' or 'A' to 'Z' => | |
| 1619 | +.P2 | |
| 1620 | +Remember that control does not flow from one case arm to the next, unlike C, | |
| 1621 | +thus no | |
| 1622 | +.CW break | |
| 1623 | +statements appear. | |
| 1624 | +.NH 2 | |
| 1625 | +Tk and Interface Construction | |
| 1626 | +.LP | |
| 1627 | +Inferno supports a rather complete implementation of | |
| 1628 | +the Tk interface toolkit developed by John Ousterhout. | |
| 1629 | +In other environments, Tk is normally accessed from | |
| 1630 | +Tcl programs, although there are also versions for Perl, | |
| 1631 | +Scheme and other languages that call Ousterhout's C code. | |
| 1632 | +The Inferno Tk was implemented from scratch, and is meant to be called | |
| 1633 | +from Limbo programs. | |
| 1634 | +As we saw earlier, | |
| 1635 | +there is a module declaration | |
| 1636 | +.CW "tk.m" | |
| 1637 | +and a kernel module | |
| 1638 | +.CW "Tk" . | |
| 1639 | +.LP | |
| 1640 | +The | |
| 1641 | +.CW "Tk" | |
| 1642 | +module provides all the widgets of the original Tk | |
| 1643 | +with almost all their options, | |
| 1644 | +the | |
| 1645 | +.CW "pack" | |
| 1646 | +command for geometry management, | |
| 1647 | +and the | |
| 1648 | +.CW "bind" | |
| 1649 | +command for attaching code to user actions. | |
| 1650 | +It also provides a | |
| 1651 | +.CW grid | |
| 1652 | +command to simplify the common case of objects arranged in a matrix or grid. | |
| 1653 | +In this implementation | |
| 1654 | +.CW "Tk" | |
| 1655 | +commands are | |
| 1656 | +written as strings and presented to one function, | |
| 1657 | +.CW "tk->cmd" ; | |
| 1658 | +Limbo calls this function and captures | |
| 1659 | +its return value, which is the string that the Tk command produces. | |
| 1660 | +For example, widget creation commands like | |
| 1661 | +.CW "button" | |
| 1662 | +return the widget name, so this will be the string | |
| 1663 | +returned by | |
| 1664 | +.CW "tk->cmd" . | |
| 1665 | +.LP | |
| 1666 | +There is one unconventional aspect: | |
| 1667 | +the use of channels to send data and events from the interface | |
| 1668 | +into the Limbo program. | |
| 1669 | +To create a widget, as we saw earlier, one writes | |
| 1670 | +.P1 | |
| 1671 | +tk->cmd("button .b -text {Push me} -command {send cmd .bpush}"); | |
| 1672 | +.P2 | |
| 1673 | +to create a button | |
| 1674 | +.CW ".b" | |
| 1675 | +and attach a command to be executed when the button is pushed. | |
| 1676 | +That command sends | |
| 1677 | +the (arbitrary) string | |
| 1678 | +.CW ".bpush" | |
| 1679 | +on the channel named | |
| 1680 | +.CW "cmd" . | |
| 1681 | +The Limbo code that reads from this channel will look | |
| 1682 | +for the string | |
| 1683 | +.CW ".bpush" | |
| 1684 | +and act accordingly. | |
| 1685 | +The function | |
| 1686 | +.CW "tk->namechan" | |
| 1687 | +establishes a correspondence between a Limbo channel value | |
| 1688 | +and a channel named as a string in the Tk module. | |
| 1689 | +When an event occurs in a Tk widget with a | |
| 1690 | +.CW "-command" | |
| 1691 | +option, | |
| 1692 | +.CW "send" | |
| 1693 | +causes the string to be sent on the channel and the Limbo code | |
| 1694 | +can act on it. | |
| 1695 | +The program will often use a | |
| 1696 | +.CW "case" | |
| 1697 | +to process the strings that might appear on the channel, | |
| 1698 | +particularly when the same channel is used for several widgets. | |
| 1699 | +.LP | |
| 1700 | +We observed earlier that | |
| 1701 | +.CW Tk | |
| 1702 | +provides a user interface for an application's window, | |
| 1703 | +but there might be many windows on the screen. | |
| 1704 | +Normally, a graphical application is meant to run under | |
| 1705 | +the window manager | |
| 1706 | +.CW "wm" | |
| 1707 | +as a window that can be managed, | |
| 1708 | +reshaped, etc. | |
| 1709 | +This is done by calling functions in the module | |
| 1710 | +.CW "Tkclient" , | |
| 1711 | +which provides the interface between | |
| 1712 | +.CW Tk | |
| 1713 | +and | |
| 1714 | +.CW wm . | |
| 1715 | +.LP | |
| 1716 | +Several functions must be called to create a window, | |
| 1717 | +put it on the screen, and start giving it input. | |
| 1718 | +We have already seen | |
| 1719 | +.CW Tkclient 's | |
| 1720 | +.CW toplevel | |
| 1721 | +for window creation and | |
| 1722 | +.CW onscreen | |
| 1723 | +to give a window space on the screen. | |
| 1724 | +Input arrives from several sources: | |
| 1725 | +from the mouse and keyboard, from the | |
| 1726 | +higher-level Tk widgets such as buttons, | |
| 1727 | +and from the window manager itself. | |
| 1728 | +In Limbo, each input source is represented by a channel, either given to the program | |
| 1729 | +by the window manager, or associated with one by | |
| 1730 | +.CW namechan , | |
| 1731 | +as above. | |
| 1732 | +.LP | |
| 1733 | +This is all illustrated in the complete program below, which | |
| 1734 | +implements a trivial version of Etch-a-Sketch, shown in action in Figure 2. | |
| 1735 | +.FG "f3.ps" 4.8i | |
| 1736 | +.ce | |
| 1737 | +.I "Figure 2. Etch-a-Sketch display." | |
| 1738 | +.fg | |
| 1739 | +.nr dT 4 | |
| 1740 | +.nr dP \n(dP+1 | |
| 1741 | +.P1 | |
| 1742 | +implement Etch; | |
| 1743 | + | |
| 1744 | +include "sys.m"; | |
| 1745 | + sys: Sys; | |
| 1746 | +include "draw.m"; | |
| 1747 | +include "tk.m"; | |
| 1748 | + tk: Tk; | |
| 1749 | +include "tkclient.m"; | |
| 1750 | + tkclient: Tkclient; | |
| 1751 | + | |
| 1752 | +Etch: module | |
| 1753 | +{ | |
| 1754 | + init: fn(ctxt: ref Draw->Context, args: list of string); | |
| 1755 | +}; | |
| 1756 | +.P3 | |
| 1757 | +init(ctxt: ref Draw->Context, nil: list of string) | |
| 1758 | +{ | |
| 1759 | + sys = load Sys Sys->PATH; | |
| 1760 | + tk = load Tk Tk->PATH; | |
| 1761 | + tkclient = load Tkclient Tkclient->PATH; | |
| 1762 | + | |
| 1763 | + tkclient->init(); | |
| 1764 | + | |
| 1765 | + (t, winctl) := tkclient->toplevel(ctxt, nil, "Etch", Tkclient->Appl); | |
| 1766 | + | |
| 1767 | + cmd := chan of string; | |
| 1768 | + tk->namechan(t, cmd, "cmd"); | |
| 1769 | + tk->cmd(t, "canvas .c -height 400 -width 600 -background white"); | |
| 1770 | + tk->cmd(t, "frame .f"); | |
| 1771 | + tk->cmd(t, "button .f.c -text {Clear} -command {send cmd clear}"); | |
| 1772 | + tk->cmd(t, "button .f.d -text {Done} -command {send cmd quit}"); | |
| 1773 | + tk->cmd(t, "pack .f.c .f.d -side left -fill x -expand 1"); | |
| 1774 | + tk->cmd(t, "pack .c .f -side top -fill x"); | |
| 1775 | + tk->cmd(t, "bind .c <ButtonPress-1> {send cmd b1down %x %y}"); | |
| 1776 | + tk->cmd(t, "bind .c <Button-1-Motion> {send cmd b1motion %x %y}"); | |
| 1777 | + tk->cmd(t, "update"); | |
| 1778 | + | |
| 1779 | + tkclient->startinput(t, "ptr" :: "kbd" :: nil); | |
| 1780 | + tkclient->onscreen(t, nil); | |
| 1781 | + | |
| 1782 | + lastx, lasty: int; | |
| 1783 | + for (;;) { | |
| 1784 | + alt { | |
| 1785 | + s := <-cmd => | |
| 1786 | + (nil, cmdstr) := sys->tokenize(s, " \et\en"); | |
| 1787 | + case hd cmdstr { | |
| 1788 | + "quit" => | |
| 1789 | + exit; | |
| 1790 | + "clear" => | |
| 1791 | + tk->cmd(t, ".c delete all; update"); | |
| 1792 | + "b1down" => | |
| 1793 | + lastx = int hd tl cmdstr; | |
| 1794 | + lasty = int hd tl tl cmdstr; | |
| 1795 | + cstr := sys->sprint(".c create line %d %d %d %d -width 2", | |
| 1796 | + lastx, lasty, lastx, lasty); | |
| 1797 | + tk->cmd(t, cstr); | |
| 1798 | + "b1motion" => | |
| 1799 | + x := int hd tl cmdstr; | |
| 1800 | + y := int hd tl tl cmdstr; | |
| 1801 | + cstr := sys->sprint(".c create line %d %d %d %d -width 2", | |
| 1802 | + lastx, lasty, x, y); | |
| 1803 | + tk->cmd(t, cstr); | |
| 1804 | + lastx = x; lasty = y; | |
| 1805 | + } | |
| 1806 | + | |
| 1807 | + p := <-t.ctxt.ptr => | |
| 1808 | + tk->pointer(t, *p); | |
| 1809 | + | |
| 1810 | + c := <-t.ctxt.kbd => | |
| 1811 | + tk->keyboard(t, c); | |
| 1812 | + | |
| 1813 | + ctl := <-winctl or | |
| 1814 | + ctl = <-t.ctxt.ctl or | |
| 1815 | + ctl = <-t.wreq => | |
| 1816 | + tkclient->wmctl(t, ctl); | |
| 1817 | + } | |
| 1818 | + tk->cmd(t, "update"); | |
| 1819 | + } | |
| 1820 | +} | |
| 1821 | +.P2 | |
| 1822 | +.nr dT 8 | |
| 1823 | +.nr dP \n(dP-1 | |
| 1824 | +.LP | |
| 1825 | +The function | |
| 1826 | +.CW "toplevel" | |
| 1827 | +returns a tuple containing the | |
| 1828 | +.CW Tk->Toplevel | |
| 1829 | +for the new window and a channel upon which the | |
| 1830 | +window manager will send messages for events such as | |
| 1831 | +hitting the exit button. | |
| 1832 | +An earlier example assigned the channel value to | |
| 1833 | +.CW nil , | |
| 1834 | +discarding it; here it is assigned the name | |
| 1835 | +.CW winctl . | |
| 1836 | +The parameters to | |
| 1837 | +.CW toplevel | |
| 1838 | +includes a graphics context | |
| 1839 | +.CW ctxt | |
| 1840 | +where the window will be created, | |
| 1841 | +a configuration string (simply | |
| 1842 | +.CW nil | |
| 1843 | +here), | |
| 1844 | +the program name (which appears in the window's ``title bar'' if it has one), | |
| 1845 | +and a value | |
| 1846 | +.CW Tkclient->Appl | |
| 1847 | +that denotes a style of window suitable for most applications. | |
| 1848 | +Note that | |
| 1849 | +.CW ctxt | |
| 1850 | +was one of the arguments to | |
| 1851 | +.CW init . | |
| 1852 | +(We do not use the argument list for | |
| 1853 | +.CW init , | |
| 1854 | +and so declare it as | |
| 1855 | +.CW nil ). | |
| 1856 | +.LP | |
| 1857 | +The program creates a canvas for drawing, | |
| 1858 | +a button to clear the canvas, and a button to quit. | |
| 1859 | +The sequence of calls to | |
| 1860 | +.CW "tk->cmd" | |
| 1861 | +creates the picture and sets up the bindings. | |
| 1862 | +The buttons are created with a | |
| 1863 | +.CW -command | |
| 1864 | +to send a suitable string on channel | |
| 1865 | +.CW cmd , | |
| 1866 | +and two | |
| 1867 | +.CW bind | |
| 1868 | +commands make the same channel the target | |
| 1869 | +for messages about mouse button presses and movement in the canvas. | |
| 1870 | +Note the | |
| 1871 | +.CW %x | |
| 1872 | +and | |
| 1873 | +.CW %y | |
| 1874 | +parameters in the latter case to include the mouse's coordinates in the string. | |
| 1875 | +.LP | |
| 1876 | +The window manager sends keyboard and mouse input | |
| 1877 | +to the currently selected window using two more channels | |
| 1878 | +.CW t.ctxt.kbd | |
| 1879 | +and | |
| 1880 | +.CW t.ctxt.ptr . | |
| 1881 | +A further channel | |
| 1882 | +.CW t.wreq | |
| 1883 | +is used by the | |
| 1884 | +.CW Tk | |
| 1885 | +module itself to request changes to the window displaying | |
| 1886 | +.CW Toplevel | |
| 1887 | +.CW t . | |
| 1888 | +.LP | |
| 1889 | +Now there are many channels watching events: | |
| 1890 | +one for the buttons and canvas created by the drawing program | |
| 1891 | +itself, one for the mouse, | |
| 1892 | +and three for window management. | |
| 1893 | +We use an | |
| 1894 | +.CW "alt" | |
| 1895 | +statement to select from events on any of those channels. | |
| 1896 | +The expression | |
| 1897 | +.P1 | |
| 1898 | +s := <-cmd | |
| 1899 | +.P2 | |
| 1900 | +declares a variable | |
| 1901 | +.CW "s" | |
| 1902 | +of the type carried by the channel | |
| 1903 | +.CW "cmd" , | |
| 1904 | +i.e., a | |
| 1905 | +.CW "string" ; | |
| 1906 | +when a string is received on the channel, the assignment is executed, | |
| 1907 | +and the subsequent | |
| 1908 | +.CW case | |
| 1909 | +decodes the message. | |
| 1910 | +The channel | |
| 1911 | +.CW t.ctxt.ptr | |
| 1912 | +carries references to | |
| 1913 | +.CW Draw->Pointer | |
| 1914 | +values, which give the state and position of the pointing device | |
| 1915 | +(mouse or stylus). | |
| 1916 | +They are handed as received to | |
| 1917 | +.CW tk->pointer | |
| 1918 | +for processing by Tk. | |
| 1919 | +Similarly, Unicode characters from the keyboard are given to Tk using | |
| 1920 | +.CW tk->keyboard . | |
| 1921 | +Internally, Tk hands those values on to the various widgets for processing, possibly | |
| 1922 | +resulting in messages being sent on one of the other channels. | |
| 1923 | +Finally, a value received from any of the | |
| 1924 | +.CW "winctl" , | |
| 1925 | +.CW t.ctxt.ctl | |
| 1926 | +or | |
| 1927 | +.CW t.wreq | |
| 1928 | +channels is passed back to | |
| 1929 | +.CW Tkclient 's | |
| 1930 | +.CW "wmctl" | |
| 1931 | +function to be handled there. | |
| 1932 | +.LP | |
| 1933 | +As another example, | |
| 1934 | +here is the startup code for an implementation of | |
| 1935 | +Othello, adapted from a Java version | |
| 1936 | +by Muffy Barkocy, Arthur van Hoff, and Ben Fry. | |
| 1937 | +.nr dT 4 | |
| 1938 | +.nr dP \n(dP+1 | |
| 1939 | +.P1 | |
| 1940 | +init(ctxt: ref Draw->Context, args: list of string) | |
| 1941 | +{ | |
| 1942 | + sys = load Sys Sys->PATH; | |
| 1943 | + tk = load Tk Tk->PATH; | |
| 1944 | + tkclient = load Tkclient Tkclient->PATH; | |
| 1945 | + | |
| 1946 | + sys->pctl(Sys->NEWPGRP, nil); | |
| 1947 | + | |
| 1948 | + tkclient->init(); | |
| 1949 | +.P3 | |
| 1950 | + (t, winctl) := tkclient->toplevel(ctxt, nil, "Othello", Tkclient->Appl); | |
| 1951 | +.P3 | |
| 1952 | + cmd := chan of string; | |
| 1953 | + tk->namechan(t, cmd, "cmd"); | |
| 1954 | + tk->cmd(t, "canvas .c -height 400 -width 400 -background green"); | |
| 1955 | + tk->cmd(t, "frame .f"); | |
| 1956 | + tk->cmd(t, "label .f.l -text {Othello?} -background white"); | |
| 1957 | + tk->cmd(t, "button .f.c -text {Reset} -command {send cmd Reset}"); | |
| 1958 | + tk->cmd(t, "button .f.d -text {Quit} -command {send cmd Quit}"); | |
| 1959 | + tk->cmd(t, "pack .f.l .f.c .f.d -side left -fill x -expand 1"); | |
| 1960 | + tk->cmd(t, "pack .c .f -side top -fill x"); | |
| 1961 | + tk->cmd(t, "bind .c <ButtonRelease-1> {send cmd B1up %x %y}"); | |
| 1962 | + | |
| 1963 | + for (i := 1; i < 9; i++) | |
| 1964 | + for (j := 1; j < 9; j++) { | |
| 1965 | + coord := sys->sprint("%d %d %d %d", | |
| 1966 | + SQ*i, SQ*j, SQ*(i+1), SQ*(j+1)); | |
| 1967 | + tk->cmd(t, ".c create rectangle " + coord + | |
| 1968 | + " -outline black -width 2"); | |
| 1969 | + } | |
| 1970 | + tk->cmd(t, "update"); | |
| 1971 | + lasterror(t, "init"); | |
| 1972 | + tkclient->startinput(t, "ptr" :: "kbd" :: nil); | |
| 1973 | + tkclient->onscreen(t, nil); | |
| 1974 | + | |
| 1975 | + board = array[10] of {* => array[10] of int}; | |
| 1976 | + score = array[10] of {* => array[10] of int}; | |
| 1977 | + reinit(); | |
| 1978 | +.P3 | |
| 1979 | + for (;;) { | |
| 1980 | + alt { | |
| 1981 | + s := <- cmd => | |
| 1982 | + (n, l) := sys->tokenize(s, " \et"); | |
| 1983 | + case hd l { | |
| 1984 | + "Quit" => | |
| 1985 | + exit; | |
| 1986 | + "Reset" => | |
| 1987 | + reinit(); | |
| 1988 | + "B1up" => | |
| 1989 | + x := int hd tl l; | |
| 1990 | + y := int hd tl tl l; | |
| 1991 | + mouseUp(int x, int y); | |
| 1992 | + } | |
| 1993 | + | |
| 1994 | + p := <-t.ctxt.ptr => | |
| 1995 | + tk->pointer(t, *p); | |
| 1996 | + | |
| 1997 | + c := <-t.ctxt.kbd => | |
| 1998 | + tk->keyboard(t, c); | |
| 1999 | + | |
| 2000 | + ctl := <-winctl or | |
| 2001 | + ctl = <-t.ctxt.ctl or | |
| 2002 | + ctl = <-t.wreq => | |
| 2003 | + tkclient->wmctl(t, ctl); | |
| 2004 | + } | |
| 2005 | + } | |
| 2006 | +} | |
| 2007 | +.P2 | |
| 2008 | +.nr dP \n(dP-1 | |
| 2009 | +.nr dT 4 | |
| 2010 | +.FG "f2.ps" 4.8i | |
| 2011 | +.ce | |
| 2012 | +.I "Figure 3. Screen shot of Inferno display showing Othello window." | |
| 2013 | +.fg | |
| 2014 | +.LP | |
| 2015 | +If some call to the | |
| 2016 | +.CW "Tk" | |
| 2017 | +module results in an error, | |
| 2018 | +an error string is made available in a pseudo-variable | |
| 2019 | +.CW "lasterror" | |
| 2020 | +maintained by | |
| 2021 | +.CW "Tk" . | |
| 2022 | +When this variable is read, it is reset. | |
| 2023 | +The function | |
| 2024 | +.CW "lasterror" | |
| 2025 | +shows how to test and print this variable: | |
| 2026 | +.P1 | |
| 2027 | +lasterror(t: ref Tk->Toplevel, where: string) | |
| 2028 | +{ | |
| 2029 | + s := tk->cmd(t, "variable lasterror"); | |
| 2030 | + if (s != nil) | |
| 2031 | + sys->print("%s: tk error %s\en", where, s); | |
| 2032 | +} | |
| 2033 | +.P2 | |
| 2034 | +In general, the Inferno implementation of | |
| 2035 | +.CW "Tk" | |
| 2036 | +does not provide variables except for a few special ones like this. | |
| 2037 | +The most common instance is a variable that links | |
| 2038 | +a set of radiobuttons. | |
| 2039 | +.NH 2 | |
| 2040 | +Acknowledgements | |
| 2041 | +.LP | |
| 2042 | +I am very grateful to | |
| 2043 | +Steven Breitstein, | |
| 2044 | +Ken Clarkson, | |
| 2045 | +Sean Dorward, | |
| 2046 | +Eric Grosse, | |
| 2047 | +Doug McIlroy, | |
| 2048 | +Rob Pike, | |
| 2049 | +Jon Riecke, | |
| 2050 | +Dennis Ritchie, | |
| 2051 | +Howard Trickey, | |
| 2052 | +Phil Winterbottom, | |
| 2053 | +and | |
| 2054 | +Margaret Wright | |
| 2055 | +for explaining mysteries of Limbo and Inferno | |
| 2056 | +and for valuable suggestions on this paper. | |
Binary file not shown.
| @@ -0,0 +1,497 @@ | ||
| 1 | +.TL | |
| 2 | +Program Development under Inferno | |
| 3 | +.AU | |
| 4 | +Roger Peppé | |
| 5 | +rog@vitanuova.com | |
| 6 | +.SH | |
| 7 | +Introduction | |
| 8 | +.PP | |
| 9 | +Inferno provides a set of programs that, used in | |
| 10 | +combination, provide a powerful development environment | |
| 11 | +in which to write Limbo programs. | |
| 12 | +.I Limbo (1) | |
| 13 | +is the compiler for the Limbo language; there | |
| 14 | +are versions that run inside and outside the Inferno | |
| 15 | +environment. | |
| 16 | +.I Acme (1) | |
| 17 | +is an integrated window system and editor, and the | |
| 18 | +preferred source-code editing tool within Inferno. | |
| 19 | +The Limbo debugger, | |
| 20 | +.I wm-debug (1), | |
| 21 | +allows interactive inspection of running Limbo programs. | |
| 22 | +.I Stack (1) | |
| 23 | +allows a quick inspection of the execution stack of a | |
| 24 | +currently running process. | |
| 25 | +.SH | |
| 26 | +Getting started | |
| 27 | +.PP | |
| 28 | +This document assumes that you have already managed | |
| 29 | +to install Inferno and have managed to obtain an Inferno | |
| 30 | +window, running the Inferno window manager, | |
| 31 | +.I wm (1). | |
| 32 | +The document | |
| 33 | +\&``Installing Inferno'' in this volume has details on this. | |
| 34 | +If running within emu, it is worth giving Inferno | |
| 35 | +as large a window as possible, as it cannot be resized later. | |
| 36 | +This paper assumes that you are using a three-button mouse, as it is | |
| 37 | +not feasible to use Acme without a three-button mouse. | |
| 38 | +(if you have a two button mouse with a ``mouse wheel'', | |
| 39 | +the wheel can be used as the middle button). | |
| 40 | +The first thing to do is to get Acme going. By clicking | |
| 41 | +on the Vita Nuova logo at the bottom left of the window, | |
| 42 | +you can display a menu naming some preconfigured commands. | |
| 43 | +If this has an ``Acme'' entry, then just clicking on that entry | |
| 44 | +will start acme. If not, then click on the ``Shell'' entry, | |
| 45 | +and type | |
| 46 | +.P1 | |
| 47 | +acme | |
| 48 | +.P2 | |
| 49 | +to start it up. The Acme window should then appear, | |
| 50 | +filling most of the screen (the window manager toolbar | |
| 51 | +should still be visible). | |
| 52 | +.SH | |
| 53 | +Acme basics | |
| 54 | +.PP | |
| 55 | +For a general overview and the rationale behind Acme, see ``Acme: | |
| 56 | +A User Interface for Programmers'', elsewhere in this volume, | |
| 57 | +and for detailed documentation, see | |
| 58 | +.I acme (1). | |
| 59 | +The basics are as follows: | |
| 60 | +.PP | |
| 61 | +Acme windows are text-only and organised into columns. | |
| 62 | +A distinctive feature of Acme is that there are no graphical | |
| 63 | +title bars to windows; instead, each window (and additionally | |
| 64 | +each column, and the whole Acme window itself) has | |
| 65 | +a textual | |
| 66 | +.I tag , | |
| 67 | +which can be edited at will, and is initially primed to contain | |
| 68 | +a few appropriate commands. | |
| 69 | +.PP | |
| 70 | +An Acme command is just represented by text; any textual | |
| 71 | +command word may be executed simply by clicking with the middle | |
| 72 | +mouse button on the word. (See ``Acme mouse commands'', below). | |
| 73 | +If Acme recognizes the word that has been clicked on | |
| 74 | +as one of its internal commands (e.g. Put, Undo), then it will take the appropriate | |
| 75 | +action; otherwise it will run the text as a shell command. | |
| 76 | +(See | |
| 77 | +.I sh (1)). | |
| 78 | +.SH | |
| 79 | +Acme mouse commands | |
| 80 | +.PP | |
| 81 | +Mouse usage within Acme is somewhat more versatile | |
| 82 | +than in most other window systems. Each of the three | |
| 83 | +mouse buttons has its own action, and there are also | |
| 84 | +actions bound to | |
| 85 | +.I chords | |
| 86 | +of mouse buttons (i.e. mouse buttons depressed simultaneously). | |
| 87 | +Mouse buttons are numbered from left (1) to right (3). | |
| 88 | +Button 1 follows similar conventions to other window systems - | |
| 89 | +it selects text; a double click will select a line if at the beginning or end | |
| 90 | +of a line, or match brackets if on a bracket character, or select | |
| 91 | +a word otherwise. | |
| 92 | +Button 2, as mentioned above, executes an | |
| 93 | +Acme command; a single click with button 2 will execute | |
| 94 | +the single word under the click, otherwise the swept text | |
| 95 | +will be executed. | |
| 96 | +Button 3 is a general ``look'' operator; if the text under the | |
| 97 | +click represents a filename, then Acme will open a new | |
| 98 | +window for the file and read it in, otherwise it will search | |
| 99 | +within the current window for the next occurrence of the | |
| 100 | +text. | |
| 101 | +Clicking button 2 or button 3 on some text already selected | |
| 102 | +by button 1 causes the click to refer exactly to the text | |
| 103 | +selected, rather than gathering likely-looking characters | |
| 104 | +from around the click as is the default. | |
| 105 | +.PP | |
| 106 | +There are two mouse chord sequences which are | |
| 107 | +commonly used in Acme (and you will find that some | |
| 108 | +other programs in the system also recognise these sequences, | |
| 109 | +e.g. | |
| 110 | +.I wm-sh (1)). | |
| 111 | +They are both available once some text | |
| 112 | +has been selected by dragging the mouse with button 1, | |
| 113 | +but before the button has been released. At this point, | |
| 114 | +touching button 2 will delete the selected text and save | |
| 115 | +it in Acme's | |
| 116 | +.I snarf | |
| 117 | +buffer; clicking button 3 replaces the selected text with the contents | |
| 118 | +of the snarf buffer. Before button 1 has been released, | |
| 119 | +these two buttons reverse each other's actions, so, for | |
| 120 | +example, selecting some text with button 1, keeping button 1 | |
| 121 | +held down, then clicking button 2 and button 3 in succession, | |
| 122 | +will save the selected text in the snarf buffer while leaving the | |
| 123 | +original intact. | |
| 124 | +The following table summarises the mouse commands in | |
| 125 | +Acme: | |
| 126 | +.KS | |
| 127 | +.TS | |
| 128 | +center box; | |
| 129 | +l l . | |
| 130 | +B1 Select text. | |
| 131 | +B2 Execute text. | |
| 132 | +B3 Open file or search for text. | |
| 133 | +B1-B2 Cut text. | |
| 134 | +B1-B3 Paste text. | |
| 135 | +B2-B3 Cancel the pending B2 action. | |
| 136 | +B3-B2 Cancel the pending B3 action. | |
| 137 | +.TE | |
| 138 | +.ce | |
| 139 | +.I "Acme mouse command summary" | |
| 140 | +.KE | |
| 141 | + | |
| 142 | +.SH | |
| 143 | +Scrolling and resizing Acme windows | |
| 144 | +.PP | |
| 145 | +The scroll bars in Acme are somewhat different from | |
| 146 | +conventional scroll bars (including the scroll bars found | |
| 147 | +in other parts of Inferno). Clicking, or dragging, with | |
| 148 | +button-2 on the scrollbar acts the most like the conventional | |
| 149 | +behaviour, namely that the further down the scroll bar | |
| 150 | +you click, the further down the file you are shown. | |
| 151 | +.PP | |
| 152 | +True to form, however, Acme doesn't omit to make | |
| 153 | +the other buttons useful: button-1 and button-3 | |
| 154 | +move backwards and forwards through the file respectively. | |
| 155 | +The nearer the top of the scrollbar the mouse, the | |
| 156 | +slower the movement. Holding one of these buttons | |
| 157 | +down on the scrollbar will cause the scrolling motion | |
| 158 | +to auto-repeat, so it is easy to scroll gently through the | |
| 159 | +entire file, for instance. | |
| 160 | +.PP | |
| 161 | +The small square at the top left of each Acme window is | |
| 162 | +the handle for resizing the window. Dragging this square | |
| 163 | +from one place to another (within Acme) will move the | |
| 164 | +window to the new place. A single button click in this square | |
| 165 | +will grow the window: button 1 grows it a little bit; button 2 | |
| 166 | +grows it as much as possible without obscuring the other | |
| 167 | +window titles in the column; button 3 grows it so it covers | |
| 168 | +the whole column (all other windows in the column are | |
| 169 | +obscured). | |
| 170 | +.SH | |
| 171 | +Creating a new file | |
| 172 | +.PP | |
| 173 | +All Limbo programs are composed of | |
| 174 | +.I modules | |
| 175 | +and each module is stored in its own file. To write a Limbo | |
| 176 | +program, you need to write at least one module, | |
| 177 | +the Limbo | |
| 178 | +.I "source file" , | |
| 179 | +which will then be compiled into Dis code which can | |
| 180 | +then be run by the Inferno Virtual Machine (VM). | |
| 181 | +The first step is to decide where to store the file. | |
| 182 | +When Acme starts up, it creates a new window containing | |
| 183 | +a list of all the files in the directory in which it was started | |
| 184 | +(usually your home directory). As a consequence of the | |
| 185 | +mouse rules above, a click of button-3 on any of those | |
| 186 | +filenames in that window will open a new window | |
| 187 | +showing that file or, if it is a directory, a list of the | |
| 188 | +files and directories it contains. | |
| 189 | +.PP | |
| 190 | +An important aspect in Acme's mouse commands, is | |
| 191 | +that the command is interpreted | |
| 192 | +.I "relative to the window's current directory", | |
| 193 | +where the current directory is determined from | |
| 194 | +the filename in the window's tag. For instance, | |
| 195 | +Acme commands executed in the tag or body of | |
| 196 | +a window on the file | |
| 197 | +.CW "/usr/joebloggs/myfile.txt" | |
| 198 | +would run in the directory | |
| 199 | +.CW /usr/joebloggs . | |
| 200 | +.PP | |
| 201 | +So, to create a new file in Acme, first open the | |
| 202 | +directory in which to create the file. (If this is | |
| 203 | +your home directory, then it's probably already on the screen; | |
| 204 | +otherwise, you can just type (anywhere) the name of | |
| 205 | +the directory, and button-3 click on it. If the directory | |
| 206 | +does not exist, then no window will be created. | |
| 207 | +Then, within the directory's window or its tag, | |
| 208 | +choose a name, | |
| 209 | +.I filename , | |
| 210 | +for your file (I'll use | |
| 211 | +.CW myprog | |
| 212 | +from here on, | |
| 213 | +for explanatory convenience) | |
| 214 | +, type the text: | |
| 215 | +.P1 | |
| 216 | +New \fIfilename\fP.b | |
| 217 | +.P2 | |
| 218 | +select this text (the Escape key can also be used to highlight | |
| 219 | +text that you have just typed), and button-2 click on it. | |
| 220 | +This should create a new empty window in which you | |
| 221 | +can edit your Limbo source file. It will also create a | |
| 222 | +window giving a warning that the file does not | |
| 223 | +currently exist - you can get rid of this by clicking | |
| 224 | +with button-2 on the text | |
| 225 | +.CW Del | |
| 226 | +in the tag of that window. | |
| 227 | +.SH | |
| 228 | +Editing the source file | |
| 229 | +.PP | |
| 230 | +You can now edit text in the new window. | |
| 231 | +Type in the following program: | |
| 232 | +.P1 | |
| 233 | +implement Myprog; | |
| 234 | +include "sys.m"; | |
| 235 | + sys: Sys; | |
| 236 | +include "draw.m"; | |
| 237 | + | |
| 238 | +Myprog: module { | |
| 239 | + init: fn(nil: ref Draw->Context, argv: list of string); | |
| 240 | +}; | |
| 241 | + | |
| 242 | +init(nil: ref Draw->Context, argv: list of string) | |
| 243 | +{ | |
| 244 | + sys = load Sys Sys->PATH; | |
| 245 | + sys->print("Hello, world\en"); | |
| 246 | +} | |
| 247 | +.P2 | |
| 248 | +When typing it in, note that two new commands have appeared | |
| 249 | +in the tag of the new window: | |
| 250 | +.CW Put | |
| 251 | +and | |
| 252 | +.CW Undo . | |
| 253 | +.CW Put | |
| 254 | +saves the file; | |
| 255 | +.CW Undo | |
| 256 | +undoes the last change to the file, and successive | |
| 257 | +executions of | |
| 258 | +.CW Undo | |
| 259 | +will move further back in time. In case you move | |
| 260 | +too far back accidentally, there is also | |
| 261 | +.CW Redo , | |
| 262 | +which redoes a change that you have just undone. | |
| 263 | +Changes in the body of any window in Acme can be undone | |
| 264 | +this way. | |
| 265 | +.PP | |
| 266 | +Click with button-2 on the | |
| 267 | +.CW Put | |
| 268 | +command, and the file is now saved and ready to be | |
| 269 | +compiled. If you have problems at this point (say | |
| 270 | +Acme complains about not being able to write the | |
| 271 | +file), you have probably chosen an inappropriate | |
| 272 | +directory, one in which you do not have write permission, | |
| 273 | +in which to put the file. In this case you can change the | |
| 274 | +name of the file simply by editing its name in the window's | |
| 275 | +tag, and clicking on | |
| 276 | +.CW Put | |
| 277 | +again. | |
| 278 | +.SH | |
| 279 | +Compiling the source file | |
| 280 | +.PP | |
| 281 | +Now, you are in a position to compile the Limbo program. | |
| 282 | +Although you can execute the Limbo compiler directly | |
| 283 | +from the tag of the new file's window, it is usually more | |
| 284 | +convenient to do it from a shell window. To start a shell | |
| 285 | +window, type | |
| 286 | +.CW win '' `` | |
| 287 | +at the right of the tag of the new file's window, select | |
| 288 | +it, and click with button-2 on it. | |
| 289 | +A new window should appear showing a shell prompt (usually | |
| 290 | +.CW "; " '' `` | |
| 291 | +or | |
| 292 | +.CW "% " ''). `` | |
| 293 | +At this, you can type any of the commands mentioned | |
| 294 | +in Section 1 of the Programmer's Manual. | |
| 295 | +Note that, following Acme's usual rule, the shell has | |
| 296 | +started up in the same directory as the new file; | |
| 297 | +typing | |
| 298 | +.P1 | |
| 299 | +lc | |
| 300 | +.P2 | |
| 301 | +at the prompt will show all the files in the directory, | |
| 302 | +including hopefully the newly written Limbo file. | |
| 303 | +.PP | |
| 304 | +Type the following command to the shell: | |
| 305 | +.P1 | |
| 306 | +limbo -g myprog.b | |
| 307 | +.P2 | |
| 308 | +If you typed in the example program correctly, | |
| 309 | +then you'll get a short pause, and then another shell | |
| 310 | +prompt. This indicates a successful compilation (no | |
| 311 | +news is good news), in which case you will now have | |
| 312 | +two new files in the current directory, | |
| 313 | +.CW myprog.sbl | |
| 314 | +and | |
| 315 | +.CW myprog.dis . | |
| 316 | +The | |
| 317 | +.CW -g | |
| 318 | +option to the | |
| 319 | +.CW limbo | |
| 320 | +command directed it to produce the | |
| 321 | +.CW myprog.sbl | |
| 322 | +file, which contains symbolic information | |
| 323 | +relating the source code to the Dis executable file. | |
| 324 | +The | |
| 325 | +.CW myprog.dis | |
| 326 | +file contains the actual executable file. | |
| 327 | +At this point, if you type | |
| 328 | +.CW lc , | |
| 329 | +to get a listing of the files in the current directory, | |
| 330 | +and then click with button-2 on the | |
| 331 | +.CW myprog.dis | |
| 332 | +file, and you should see the output ``Hello, world''. | |
| 333 | +You could also just type | |
| 334 | +.CW myprog | |
| 335 | +at the shell prompt. | |
| 336 | +.PP | |
| 337 | +If you are normal, however, the above compilation | |
| 338 | +probably failed because of some mistyped characters | |
| 339 | +in the source code; and for larger newly created programs, | |
| 340 | +in my experience, this | |
| 341 | +is almost invariably the case. | |
| 342 | +If you got no errors in the above | |
| 343 | +compilation, try changing | |
| 344 | +.CW sys->print | |
| 345 | +to | |
| 346 | +.CW print , | |
| 347 | +saving the file again, | |
| 348 | +and continue with the next section. | |
| 349 | +.SH | |
| 350 | +Finding compilation errors | |
| 351 | +.PP | |
| 352 | +When the Limbo compiler finds errors, it prints | |
| 353 | +the errors, one per line, each one looking something | |
| 354 | +like the following: | |
| 355 | +.P1 | |
| 356 | +myprog.b:13: print is not declared | |
| 357 | +.P2 | |
| 358 | +This shows the filename where the error has occurred, | |
| 359 | +its line number in the file, and a description of the error. | |
| 360 | +Acme's button-3 mouse clicking makes it extremely easy | |
| 361 | +to see where in the source code the error has occurred. | |
| 362 | +Click with button-3 anywhere in the filename on the | |
| 363 | +line of the compilation error, and Acme will automatically | |
| 364 | +take the cursor to the file of that name and highlight | |
| 365 | +the correct line. | |
| 366 | +.PP | |
| 367 | +If there had been no currently appropriate open Acme | |
| 368 | +window representing the file, then a new one would | |
| 369 | +be created, and the appropriate line selected. | |
| 370 | +.PP | |
| 371 | +Edit | |
| 372 | +.CW myprog.b | |
| 373 | +until you have a program that compiles successfully | |
| 374 | +and produces the ``Hello, world'' output. | |
| 375 | +For a program as simple as this, that's all there | |
| 376 | +is to it - you now know the essential stages involved in | |
| 377 | +writing a Limbo program; there's just the small matter | |
| 378 | +of absorbing the Limbo language and familiarising | |
| 379 | +yourself with the libraries (``The Limbo Programming Language'' | |
| 380 | +elsewhere in this volume, | |
| 381 | +and | |
| 382 | +.I intro (2) | |
| 383 | +are the two essential starting points here). | |
| 384 | +.SH | |
| 385 | +Finding run-time errors | |
| 386 | +.PP | |
| 387 | +For larger programs, there is the problem of programs | |
| 388 | +that die unexpectedly with a run-time error. This | |
| 389 | +will happen when, for instance, a Limbo program uses a reference | |
| 390 | +that has not been initialised, or refers to an out-of-bounds | |
| 391 | +array element. | |
| 392 | +.PP | |
| 393 | +When a Limbo program dies with a run-time exception, | |
| 394 | +it does not go away completely, but remains hanging | |
| 395 | +around, dormant, in a | |
| 396 | +.I broken | |
| 397 | +state; the state that it was in when it died may | |
| 398 | +now be examined at leisure. To experiment with this, | |
| 399 | +edit the Myprog module above to delete the line | |
| 400 | +that loads the | |
| 401 | +.CW Sys | |
| 402 | +module | |
| 403 | +.CW "sys = load Sys" ...), ( | |
| 404 | +and recompile the program. | |
| 405 | +.PP | |
| 406 | +This time when you come to run | |
| 407 | +.CW myprog , | |
| 408 | +it will die, printing a message like: | |
| 409 | +.P1 | |
| 410 | +sh: 319 "Myprog":module not loaded | |
| 411 | +.P2 | |
| 412 | +The number | |
| 413 | +.CW 319 | |
| 414 | +is the | |
| 415 | +.I "process id" | |
| 416 | +(or just | |
| 417 | +.I pid ) | |
| 418 | +of the broken process. The command | |
| 419 | +.CW ps , | |
| 420 | +which shows all currently running processes, | |
| 421 | +can be used at this point - you will see a line like this: | |
| 422 | +.P1 | |
| 423 | + 319 245 rog broken 64K Myprog | |
| 424 | +.P2 | |
| 425 | +The first number is the pid of the process; | |
| 426 | +the second is the | |
| 427 | +.I "process group" | |
| 428 | +id of the process; the third field gives the | |
| 429 | +owner of the process; the fourth gives its state | |
| 430 | +(broken, in this case); the fifth shows the current | |
| 431 | +size of the process, and the last gives the name | |
| 432 | +of the module that the process is currently running. | |
| 433 | +.PP | |
| 434 | +The | |
| 435 | +.CW stack | |
| 436 | +command can be used to quickly find the line | |
| 437 | +at which the process has broken; type: | |
| 438 | +.P1 | |
| 439 | + stack \fIpid\fP | |
| 440 | +.P2 | |
| 441 | +where | |
| 442 | +.I pid | |
| 443 | +is the number mentioned in the ``module not loaded'' | |
| 444 | +message (319 in this case). | |
| 445 | +It produces something like the following output: | |
| 446 | +.P1 | |
| 447 | +init() myprog.b:12.1, 29 | |
| 448 | +unknown fn() Module /dis/sh.dis PC 1706 | |
| 449 | +.P2 | |
| 450 | +As usual, a quick button-3 click on the | |
| 451 | +.CW myprog.b | |
| 452 | +part of the first line takes you to the appropriate | |
| 453 | +part of the source file. The reason that the program | |
| 454 | +has died here is that, in Limbo, all external modules | |
| 455 | +must be explicitly loaded before they can be used; to | |
| 456 | +try to call an uninitialised module is an error | |
| 457 | +and causes an exception. | |
| 458 | +.SH | |
| 459 | +More sophisticated debugging | |
| 460 | +.PP | |
| 461 | +.CW Stack | |
| 462 | +is fine for getting a quick summary of the state | |
| 463 | +in which a program has died, but there are | |
| 464 | +times when such a simple post-mortem analysis | |
| 465 | +is inadequate. The | |
| 466 | +.CW wm/deb | |
| 467 | +(see | |
| 468 | +.I wm-deb\fR(1))\fP | |
| 469 | +command provides an interactive windowing | |
| 470 | +debugger for such occasions. | |
| 471 | +It runs outside Acme, | |
| 472 | +in the default window system. A convenient way | |
| 473 | +to start debugging an existing process is | |
| 474 | +to raise | |
| 475 | +.CW wm/task | |
| 476 | +(``Task Manager'' on the | |
| 477 | +main menu), select with the mouse the process | |
| 478 | +to debug, and click ``Debug''. This will start | |
| 479 | +.CW wm/deb | |
| 480 | +on that process. Before it can start, the debugger will ask | |
| 481 | +for the names of any source files that it has not been | |
| 482 | +able to find (usually this includes the source for | |
| 483 | +the shell, as the module being debugged is often | |
| 484 | +started by the shell, and so the top-level function will | |
| 485 | +be in the shell's module). | |
| 486 | +.PP | |
| 487 | +.CW Wm/deb | |
| 488 | +can be used to debug multiple threads, to inspect | |
| 489 | +the data structures in a thread, and to interactively | |
| 490 | +step through the running of a thread (single stepping). | |
| 491 | +See | |
| 492 | +.I wm-deb (1) | |
| 493 | +for details. | |
| 494 | + | |
| 495 | +\" further afield? | |
| 496 | +\" other development tools? | |
| 497 | +\" tools to come? | |
Binary file not shown.
| @@ -0,0 +1,1824 @@ | ||
| 1 | +.so /sys/lib/tmac/tmac.uni | |
| 2 | +.TL | |
| 3 | +Dis Virtual Machine Specification | |
| 4 | +.AU | |
| 5 | +.I "Lucent Technologies Inc" | |
| 6 | +.I "30 September 1999" | |
| 7 | + | |
| 8 | +.I "Extensively revised by Vita Nuova Limited" | |
| 9 | +.I "5 June 2000, 9 January 2003" | |
| 10 | +.NH 1 | |
| 11 | +Introduction | |
| 12 | +.LP | |
| 13 | +The Dis virtual machine provides the execution environment for programs running under the Inferno operating system. The virtual machine models a CISC-like, three operand, memory-to-memory architecture. Code can either be interpreted by a C library or compiled on-the-fly into machine code for the target architecture. | |
| 14 | +.LP | |
| 15 | +This paper defines the virtual machine informally. | |
| 16 | +A separate paper by Winterbottom and Pike[2] discusses its design. | |
| 17 | +The Dis object file format is also defined here. | |
| 18 | +Literals and keywords are in | |
| 19 | +.CW typewriter | |
| 20 | +typeface. | |
| 21 | +.NH 1 | |
| 22 | +Addressing Modes | |
| 23 | +.SH | |
| 24 | +Operand Size | |
| 25 | +.LP | |
| 26 | +Operand sizes are defined as follows: a byte is 8 bits, a word or pointer is 32 bits, a float is 64 bits, a big integer is 64 bits. The operand size of each instruction is encoded explicitly by the operand code. The operand size and type are specified by the last character of the instruction mnemonic: | |
| 27 | +.IP | |
| 28 | +.TS | |
| 29 | +lf(CW) lfR . | |
| 30 | +W word, 32-bit two's complement | |
| 31 | +B byte, 8-bit unsigned | |
| 32 | +F float, 64-bit IEEE format | |
| 33 | +L big, 64-bit two's complement | |
| 34 | +P pointer | |
| 35 | +C Unicode string encoded in UTF-8 | |
| 36 | +M memory | |
| 37 | +MP memory containing pointers | |
| 38 | +.TE | |
| 39 | +.LP | |
| 40 | +Two more operand types are defined to provide `short' | |
| 41 | +types for use by languages other than Limbo: | |
| 42 | +signed 16-bit integers, called `short word' | |
| 43 | +here, and 32-bit IEEE format floating-point numbers, called `short float' or `short real' here. | |
| 44 | +Support for them is limited to conversion to and from words or floats respectively; | |
| 45 | +the instructions are marked below with a dagger (†). | |
| 46 | +.SH | |
| 47 | +Memory Organization | |
| 48 | +.LP | |
| 49 | +Memory for a thread is divided into several separate regions. The code segment stores either a decoded virtual machine instruction stream suitable for execution by the interpreter or flash compiled native machine code for the host CPU. Neither type of code segment is addressable from the instruction set. At the object code level, PC values are offsets, counted in instructions, from the beginning of the code space. | |
| 50 | +.LP | |
| 51 | +Data memory is a linear array of bytes, addressed using 32-bit pointers. Words are stored in the native representation of the host CPU. Data types larger than a byte must be stored at addresses aligned to | |
| 52 | +a multiple of the data size. A thread executing a module has access to two regions of addressable data memory. A module pointer | |
| 53 | +.CW "mp" \& ( | |
| 54 | +register) defines a region of global storage for a particular module, a frame pointer | |
| 55 | +.CW "fp" \& ( | |
| 56 | +register) defines the current activation record or frame for the thread. Frames are allocated dynamically from a stack by function call and return instructions. The stack is extended automatically from the heap. | |
| 57 | +.LP | |
| 58 | +The | |
| 59 | +.CW mp | |
| 60 | +and | |
| 61 | +.CW fp | |
| 62 | +registers cannot be addressed directly, and therefore, can be modified only by call and return instructions. | |
| 63 | +.SH | |
| 64 | +Effective Addresses | |
| 65 | +.LP | |
| 66 | +Each instruction can potentially address three operands. The source and destination operands are general, but the middle operand can use any address mode except double indirect. If the middle operand of a three address instruction is omitted, it is assumed to be the same as the destination operand. | |
| 67 | +.LP | |
| 68 | +The general operands generate an effective address from three basic modes: immediate, indirect and double indirect. The assembler syntax for each mode is: | |
| 69 | +.IP | |
| 70 | +.TS | |
| 71 | +lf(CW) lfR . | |
| 72 | +10(fp) 30-bit signed indirect from fp | |
| 73 | +20(mp) 30-bit signed indirect from mp | |
| 74 | +$0x123 30-bit signed immediate value | |
| 75 | +10(20(fp)) two 16-bit unsigned offsets double indirect from fp | |
| 76 | +10(20(mp)) two 16-bit unsigned offsets double indirect from mp | |
| 77 | +.TE | |
| 78 | +.SH | |
| 79 | +Garbage Collection | |
| 80 | +.LP | |
| 81 | +The Dis machine performs both reference counted and real time mark and sweep garbage collection. This hyrbrid approach allows code to be generated in several styles: pure reference counted, mark and sweep, or a hybrid of the two approaches. Compiler writers have the freedom to choose how specific types are handled by the machine to optimize code for performance or language implementation. Instruction selection determines which algorithm will be applied to specific types. | |
| 82 | +.LP | |
| 83 | +When using reference counting, pointers are a special operand type and should only be manipulated using the pointer instructions in order to ensure the correct functioning of the garbage collector. Every memory location that stores a pointer must be known to the interpreter so that it can be initialized and deallocated correctly. The information is transmitted in the form of type descriptors in the object module. Each type descriptor contains a bit vector for a particular type where each bit corresponds to a word in memory. Type descriptors are generated automatically by the Limbo compiler. The assembler syntax for a type descriptor is: | |
| 84 | +.P1 | |
| 85 | +desc $10, 132, "001F" | |
| 86 | +.P2 | |
| 87 | +The first parameter is the descriptor number, the second is the size in bytes, and the third a pointer map. The map contains a list of hex bytes where each byte maps eight 32 bit words. The most significant bit represents the lowest memory address. | |
| 88 | +A one bit indicates a pointer in memory. The map need not have an entry for every byte and unspecified bytes are assumed zero. | |
| 89 | +.LP | |
| 90 | +Throughout this description, the symbolic constant | |
| 91 | +.CW H | |
| 92 | +refers to a nil pointer. | |
| 93 | +.NH 1 | |
| 94 | +Instruction Set | |
| 95 | +.SH | |
| 96 | +add\fIx\fP \- Add | |
| 97 | +.P1 | |
| 98 | +Syntax: addb src1, src2, dst | |
| 99 | + addf src1, src2, dst | |
| 100 | + addw src1, src2, dst | |
| 101 | + addl src1, src2, dst | |
| 102 | +Function: dst = src1 + src2 | |
| 103 | +.P2 | |
| 104 | +.LP | |
| 105 | +The | |
| 106 | +.CW "add" | |
| 107 | +instructions compute the sum of the operands addressed by | |
| 108 | +.CW "src1" | |
| 109 | +and | |
| 110 | +.CW "src2" | |
| 111 | +and stores the result in the | |
| 112 | +.CW " dst" | |
| 113 | +operand. For | |
| 114 | +.CW "addb" | |
| 115 | +the result is truncated to eight bits. | |
| 116 | +.SH | |
| 117 | +addc \- Add strings | |
| 118 | +.P1 | |
| 119 | +Syntax: addc src1, src2, dst | |
| 120 | +Function: dst = src1 + src2 | |
| 121 | +.P2 | |
| 122 | +.LP | |
| 123 | +The | |
| 124 | +.CW "addc" | |
| 125 | +instruction concatenates the two UTF strings pointed to by | |
| 126 | +.CW " src1" | |
| 127 | +and | |
| 128 | +.CW "src2" ; | |
| 129 | +the result is placed in the pointer addressed by | |
| 130 | +.CW "dst" . | |
| 131 | +If both pointers are | |
| 132 | +.CW "H" | |
| 133 | +the result will be a zero length string rather than | |
| 134 | +.CW "H" . | |
| 135 | +.SH | |
| 136 | +alt \- Alternate between communications | |
| 137 | +.P1 | |
| 138 | +Syntax: alt src, dst | |
| 139 | +.P2 | |
| 140 | +The | |
| 141 | +.CW "alt" | |
| 142 | +instruction selects between a set of channels ready to communicate. The | |
| 143 | +.CW src | |
| 144 | +argument is the address of a structure of the following form: | |
| 145 | +.P1 | |
| 146 | +struct Alt { | |
| 147 | + int nsend; /* Number of senders */ | |
| 148 | + int nrecv; /* Number of receivers */ | |
| 149 | + struct { | |
| 150 | + Channel* c; /* Channel */ | |
| 151 | + void* val; /* Address of lval/rval */ | |
| 152 | + } entry[]; | |
| 153 | +}; | |
| 154 | +.P2 | |
| 155 | +The vector is divided into two sections; the first lists the channels ready to send values, the second lists channels either ready to receive or an array of channels each of which may be ready to receive. The counts of the sender and receiver channels are stored as the first and second words addressed by | |
| 156 | +.CW src . | |
| 157 | +An | |
| 158 | +.CW "alt" | |
| 159 | +instruction proceeds by testing each channel for readiness to communicate. A ready channel is added to a list. If the list is empty after each channel has been considered, the thread blocks at the | |
| 160 | +.CW "alt" | |
| 161 | +instruction waiting for a channel to become ready; otherwise, a channel is picked at random from the ready set. | |
| 162 | +.LP | |
| 163 | +The | |
| 164 | +.CW "alt" | |
| 165 | +instruction then uses the selected channel to perform the communication using the | |
| 166 | +.CW "val" | |
| 167 | +address as either a source for send or a destination for receive. The numeric index of the selected vector element is placed in | |
| 168 | +.CW "dst" . | |
| 169 | +.SH | |
| 170 | +and\fIx\fP \- Logical AND | |
| 171 | +.P1 | |
| 172 | +Syntax: andb src1, src2, dst | |
| 173 | + andw src1, src2, dst | |
| 174 | + andl src1, src2, dst | |
| 175 | +Function: dst = src1 & src2 | |
| 176 | +.P2 | |
| 177 | +The instructions compute the bitwise AND of the two operands addressed by | |
| 178 | +.CW "src1" | |
| 179 | +and | |
| 180 | +.CW "src2" | |
| 181 | +and stores the result in the | |
| 182 | +.CW "dst" | |
| 183 | +operand. | |
| 184 | +.SH | |
| 185 | +beq\fIx\fP \- Branch equal | |
| 186 | +.P1 | |
| 187 | +Syntax: beqb src1, src2, dst | |
| 188 | + beqc src1, src2, dst | |
| 189 | + beqf src1, src2, dst | |
| 190 | + beqw src1, src2, dst | |
| 191 | + beql src1, src2, dst | |
| 192 | +Function: if src1 == src2 then pc = dst | |
| 193 | +.P2 | |
| 194 | +If the | |
| 195 | +.CW "src1" | |
| 196 | +operand is equal to the | |
| 197 | +.CW "src2" | |
| 198 | +operand, then control is transferred to the program counter specified by the | |
| 199 | +.CW "dst" | |
| 200 | +operand. | |
| 201 | +.SH | |
| 202 | +bge\fIx\fP \- Branch greater or equal | |
| 203 | +.P1 | |
| 204 | +Syntax: bgeb src1, src2, dst | |
| 205 | + bgec src1, src2, dst | |
| 206 | + bgef src1, src2, dst | |
| 207 | + bgew src1, src2, dst | |
| 208 | + bgel src1, src2, dst | |
| 209 | +Function: if src1 >= src2 then pc = dst | |
| 210 | +.P2 | |
| 211 | +If the | |
| 212 | +.CW "src1" | |
| 213 | +operand is greater than or equal to the | |
| 214 | +.CW "src2" | |
| 215 | +operand, then control is transferred to program counter specified by the | |
| 216 | +.CW "dst" | |
| 217 | +operand. This instruction performs a signed comparison. | |
| 218 | +.SH | |
| 219 | +bgt\fIx\fP \- Branch greater | |
| 220 | +.P1 | |
| 221 | +Syntax: bgtb src1, src2, dst | |
| 222 | + bgtc src1, src2, dst | |
| 223 | + bgtf src1, src2, dst | |
| 224 | + bgtw src1, src2, dst | |
| 225 | + bgtl src1, src2, dst | |
| 226 | +Function: if src1 > src2 then pc = dst | |
| 227 | +.P2 | |
| 228 | +If the | |
| 229 | +.CW "src1" | |
| 230 | +operand is greater than the | |
| 231 | +.CW "src2" | |
| 232 | +operand, then control is transferred to the program counter specified by the | |
| 233 | +.CW "dst" | |
| 234 | +operand. This instruction performs a signed comparison. | |
| 235 | +.SH | |
| 236 | +ble\fIx\fP \- Branch less than or equal | |
| 237 | +.P1 | |
| 238 | +Syntax: bleb src1, src2, dst | |
| 239 | + blec src1, src2, dst | |
| 240 | + blef src1, src2, dst | |
| 241 | + blew src1, src2, dst | |
| 242 | + blel src1, src2, dst | |
| 243 | +Function: if src1 <= src2 then pc = dst | |
| 244 | +.P2 | |
| 245 | +If the | |
| 246 | +.CW "src1" | |
| 247 | +operand is less than or equal to the | |
| 248 | +.CW "src2" | |
| 249 | +operand, then control is transferred to the program counter specified by the | |
| 250 | +.CW "dst" | |
| 251 | +operand. This instruction performs a signed comparison. | |
| 252 | +.SH | |
| 253 | +blt\fIx\fP \- Branch less than | |
| 254 | +.P1 | |
| 255 | +Syntax: bltb src1, src2, dst | |
| 256 | + bltc src1, src2, dst | |
| 257 | + bltf src1, src2, dst | |
| 258 | + bltw src1, src2, dst | |
| 259 | + bltl src1, src2, dst | |
| 260 | +Function: if src1 < src2 then pc = dst | |
| 261 | +.P2 | |
| 262 | +If the | |
| 263 | +.CW "src1" | |
| 264 | +operand is less than the | |
| 265 | +.CW "src2" | |
| 266 | +operand, then control is transferred to the program counter specified by the | |
| 267 | +.CW "dst" | |
| 268 | +operand. | |
| 269 | +.SH | |
| 270 | +bne\fIx\fP \- Branch not equal | |
| 271 | +.P1 | |
| 272 | +Syntax: bneb src1, src2, dst | |
| 273 | + bnec src1, src2, dst | |
| 274 | + bnef src1, src2, dst | |
| 275 | + bnew src1, src2, dst | |
| 276 | + bnel src1, src2, dst | |
| 277 | +Function: if src1 != src2 then pc = dst | |
| 278 | +.P2 | |
| 279 | +If the | |
| 280 | +.CW "src1" | |
| 281 | +operand is not equal to the | |
| 282 | +.CW "src2" | |
| 283 | +operand, then control is transferred to the program counter specified by the | |
| 284 | +.CW "dst" | |
| 285 | +operand. | |
| 286 | +.SH | |
| 287 | +call \- Call local function | |
| 288 | +.P1 | |
| 289 | +Syntax: call src, dst | |
| 290 | +Function: link(src) = pc | |
| 291 | + frame(src) = fp | |
| 292 | + mod(src) = 0 | |
| 293 | + fp = src | |
| 294 | + pc = dst | |
| 295 | +.P2 | |
| 296 | +The | |
| 297 | +.CW "call" | |
| 298 | +instruction performs a function call to a routine in the same module. The | |
| 299 | +.CW "src" | |
| 300 | +argument specifies a frame created by | |
| 301 | +.CW "new" . | |
| 302 | +The current value of | |
| 303 | +.CW "pc" | |
| 304 | +is stored in link(src), the current value of | |
| 305 | +.CW "fp" | |
| 306 | +is stored in frame(src) and the module link register is set to 0. The value of | |
| 307 | +.CW "fp" | |
| 308 | +is then set to | |
| 309 | +.CW "src" | |
| 310 | +and control is transferred to the program counter specified by | |
| 311 | +.CW dst . | |
| 312 | +.SH | |
| 313 | +case \- Case compare integer and branch | |
| 314 | +.P1 | |
| 315 | +Syntax: case src, dst | |
| 316 | +Function: pc = 0..i: dst[i].pc where | |
| 317 | + dst[i].lo >= src && dst[i].hi < src | |
| 318 | +.P2 | |
| 319 | +The | |
| 320 | +.CW "case" | |
| 321 | +instruction jumps to a new location specified by a range of values. The | |
| 322 | +.CW "dst" | |
| 323 | +operand points to a table in memory containing a table of | |
| 324 | +.CW "i" | |
| 325 | +values. Each value is three words long: the first word specifies a low value, the second word specifies a high value, and the third word specifies a program counter. The first word of the table gives the number of entries. The | |
| 326 | +.CW "case" | |
| 327 | +instruction searches the table for the first matching value where the | |
| 328 | +.CW "src" | |
| 329 | +operand is greater than or equal to the low word and less than the high word. Control is transferred to the program counter stored in the first word of the matching entry. | |
| 330 | +.SH | |
| 331 | +casec \- Case compare string and branch | |
| 332 | +.P1 | |
| 333 | +Syntax: casec src, dst | |
| 334 | +Function: pc = 0..i: dst[i].pc where | |
| 335 | + dst[i].lo >= src && dst[i].hi < src | |
| 336 | +.P2 | |
| 337 | +The | |
| 338 | +.CW "casec" | |
| 339 | +instruction jumps to a new location specified by a range of string constants. The table is the same as described for the | |
| 340 | +.CW case | |
| 341 | +instruction. | |
| 342 | +.SH | |
| 343 | +cons\fIx\fP \- Allocate new list element | |
| 344 | +.P1 | |
| 345 | +Syntax: consb src, dst | |
| 346 | + consc src, dst | |
| 347 | + consf src, dst | |
| 348 | + consl src, dst | |
| 349 | + consm src, dst | |
| 350 | + consmp src, dst | |
| 351 | + consp src, dst | |
| 352 | + consw src, dst | |
| 353 | +Function: p = new(src, dst) | |
| 354 | + dst = p | |
| 355 | +.P2 | |
| 356 | +The | |
| 357 | +.CW "cons" | |
| 358 | +instructions add a new element to the head of a list. A new list element is composed from the | |
| 359 | +.CW "src" | |
| 360 | +operand and a pointer to the head of an extant list specified by | |
| 361 | +.CW "dst" . | |
| 362 | +The resulting element is stored back into | |
| 363 | +.CW "dst" . | |
| 364 | +.SH | |
| 365 | +cvtac \- Convert byte array to string | |
| 366 | +.P1 | |
| 367 | +Syntax: cvtac src, dst | |
| 368 | +Function: dst = string(src) | |
| 369 | +.P2 | |
| 370 | +The | |
| 371 | +.CW "src" | |
| 372 | +operand must be an array of bytes, which is converted into a character string and stored in | |
| 373 | +.CW "dst" . | |
| 374 | +The new string is a copy of the bytes in | |
| 375 | +.CW "src" . | |
| 376 | +.SH | |
| 377 | +cvtbw \- Convert byte to word | |
| 378 | +.P1 | |
| 379 | +Syntax: cvtbw src, dst | |
| 380 | +Function: dst = src & 0xff | |
| 381 | +.P2 | |
| 382 | +A byte is fetched from the | |
| 383 | +.CW "src" | |
| 384 | +operand extended to the size of a word and then stored into | |
| 385 | +.CW "dst" . | |
| 386 | +.SH | |
| 387 | +cvtca \- Convert string to byte array | |
| 388 | +.P1 | |
| 389 | +Syntax: cvtca src, dst | |
| 390 | +Function: dst = array(src) | |
| 391 | +.P2 | |
| 392 | +The | |
| 393 | +.CW "src" | |
| 394 | +operand must be a string which is converted into an array of bytes and stored in | |
| 395 | +.CW "dst" . | |
| 396 | +The new array is a copy of the characters in src. | |
| 397 | +.SH | |
| 398 | +cvtcf \- Convert string to real | |
| 399 | +.P1 | |
| 400 | +Syntax: cvtcf src, dst | |
| 401 | +Function: dst = (float)src | |
| 402 | +.P2 | |
| 403 | +The string addressed by the | |
| 404 | +.CW "src" | |
| 405 | +operand is converted to a floating point value and stored in the | |
| 406 | +.CW "dst" | |
| 407 | +operand. Initial white space is ignored; conversion ceases at the first character in the string that is not part of the representation of the floating point value. | |
| 408 | +.SH | |
| 409 | +cvtcl \- Convert string to big | |
| 410 | +.P1 | |
| 411 | +Syntax: cvtcl src, dst | |
| 412 | +Function: dst = (big)src | |
| 413 | +.P2 | |
| 414 | +The string addressed by the | |
| 415 | +.CW "src" | |
| 416 | +operand is converted to a big integer and stored in the | |
| 417 | +.CW "dst" | |
| 418 | +operand. Initial white space is ignored; conversion ceases at the first non-digit in the string. | |
| 419 | +.SH | |
| 420 | +cvtcw \- Convert string to word | |
| 421 | +.P1 | |
| 422 | +Syntax: cvtcw src, dst | |
| 423 | +Function: dst = (int)src | |
| 424 | +.P2 | |
| 425 | +The string addressed by the | |
| 426 | +.CW "src" | |
| 427 | +operand is converted to a word and stored in the | |
| 428 | +.CW "dst" | |
| 429 | +operand. Initial white space is ignored; after a possible sign, conversion ceases at the first non-digit in the string. | |
| 430 | +.SH | |
| 431 | +cvtfc \- Convert real to string | |
| 432 | +.P1 | |
| 433 | +Syntax: cvtfc src, dst | |
| 434 | +Function: dst = string(src) | |
| 435 | +.P2 | |
| 436 | +The floating point value addressed by the | |
| 437 | +.CW "src" | |
| 438 | +operand is converted to a string and stored in the | |
| 439 | +.CW "dst" | |
| 440 | +operand. The string is a floating point representation of the value. | |
| 441 | +.SH | |
| 442 | +cvtfw \- Convert real to word | |
| 443 | +.P1 | |
| 444 | +Syntax: cvtfw src, dst | |
| 445 | +Function: dst = (int)src | |
| 446 | +.P2 | |
| 447 | +The floating point value addressed by | |
| 448 | +.CW "src" | |
| 449 | +is converted into a word and stored into | |
| 450 | +.CW "dst" . | |
| 451 | +The floating point value is rounded to the nearest integer. | |
| 452 | +.SH | |
| 453 | +cvtfl \- Convert real to big | |
| 454 | +.P1 | |
| 455 | +Syntax: cvtfl src, dst | |
| 456 | +Function: dst = (big)src | |
| 457 | +.P2 | |
| 458 | +The floating point value addressed by | |
| 459 | +.CW "src" | |
| 460 | +is converted into a big integer and stored into | |
| 461 | +.CW "dst" . | |
| 462 | +The floating point value is rounded to the nearest integer. | |
| 463 | +.SH | |
| 464 | +cvtfr \- Convert real to short real† | |
| 465 | +.P1 | |
| 466 | +Syntax: cvtfr src, dst | |
| 467 | +Function: dst = (short float)src | |
| 468 | +.P2 | |
| 469 | +The floating point value addressed by | |
| 470 | +.CW "src" | |
| 471 | +is converted to a short (32-bit) floating point value and stored into | |
| 472 | +.CW "dst" . | |
| 473 | +The floating point value is rounded to the nearest integer. | |
| 474 | +.SH | |
| 475 | +cvtlc \- Convert big to string | |
| 476 | +.P1 | |
| 477 | +Syntax: cvtlc src, dst | |
| 478 | +Function: dst = string(src) | |
| 479 | +.P2 | |
| 480 | +The big integer addressed by the | |
| 481 | +.CW "src" | |
| 482 | +operand is converted to a string and stored in the | |
| 483 | +.CW "dst" | |
| 484 | +operand. The string is the decimal representation of the big integer. | |
| 485 | +.SH | |
| 486 | +cvtlw \- Convert big to word | |
| 487 | +.P1 | |
| 488 | +Syntax: cvtlw src, dst | |
| 489 | +Function: dst = (int)src | |
| 490 | +.P2 | |
| 491 | +The big integer addressed by the | |
| 492 | +.CW "src" | |
| 493 | +operand is converted to a word and stored in the | |
| 494 | +.CW "dst" | |
| 495 | +operand. | |
| 496 | +.SH | |
| 497 | +cvtsw \- Convert short word to word† | |
| 498 | +.P1 | |
| 499 | +Syntax: cvtsw src, dst | |
| 500 | +Function: dst = (int)src | |
| 501 | +.P2 | |
| 502 | +The short word addressed by the | |
| 503 | +.CW "src" | |
| 504 | +operand is converted to a word and stored in the | |
| 505 | +.CW "dst" | |
| 506 | +operand. | |
| 507 | +.SH | |
| 508 | +cvtwb \- Convert word to byte | |
| 509 | +.P1 | |
| 510 | +Syntax: cvtwb src, dst | |
| 511 | +Function: dst = (byte)src; | |
| 512 | +.P2 | |
| 513 | +The | |
| 514 | +.CW "src" | |
| 515 | +operand is converted to a byte and stored in the | |
| 516 | +.CW "dst" | |
| 517 | +operand. | |
| 518 | +.SH | |
| 519 | +cvtwc \- Convert word to string | |
| 520 | +.P1 | |
| 521 | +Syntax: cvtwc src, dst | |
| 522 | +Function: dst = string(src) | |
| 523 | +.P2 | |
| 524 | +The word addressed by the | |
| 525 | +.CW "src" | |
| 526 | +operand is converted to a string and stored in the | |
| 527 | +.CW "dst" | |
| 528 | +operand. The string is the decimal representation of the word. | |
| 529 | +.SH | |
| 530 | +cvtwl \- Convert word to big | |
| 531 | +.P1 | |
| 532 | +Syntax: cvtwl src, dst | |
| 533 | +Function: dst = (big)src; | |
| 534 | +.P2 | |
| 535 | +The word addressed by the | |
| 536 | +.CW "src" | |
| 537 | +operand is converted to a big integer and stored in the | |
| 538 | +.CW "dst" | |
| 539 | +operand. | |
| 540 | +.SH | |
| 541 | +cvtwf \- Convert word to real | |
| 542 | +.P1 | |
| 543 | +Syntax: cvtwf src, dst | |
| 544 | +Function: dst = (float)src; | |
| 545 | +.P2 | |
| 546 | +The word addressed by the | |
| 547 | +.CW "src" | |
| 548 | +operand is converted to a floating point value and stored in the | |
| 549 | +.CW "dst" | |
| 550 | +operand. | |
| 551 | +.SH | |
| 552 | +cvtws \- Convert word to short word† | |
| 553 | +.P1 | |
| 554 | +Syntax: cvtws src, dst | |
| 555 | +Function: dst = (short)src; | |
| 556 | +.P2 | |
| 557 | +The word addressed by the | |
| 558 | +.CW "src" | |
| 559 | +operand is converted to a short word and stored in the | |
| 560 | +.CW "dst" | |
| 561 | +operand. | |
| 562 | +.SH | |
| 563 | +cvtlf \- Convert big to real | |
| 564 | +.P1 | |
| 565 | +Syntax: cvtlf src, dst | |
| 566 | +Function: dst = (float)src; | |
| 567 | +.P2 | |
| 568 | +The big integer addressed by the | |
| 569 | +.CW "src" | |
| 570 | +operand is converted to a floating point value and stored in the | |
| 571 | +.CW "dst" | |
| 572 | +operand. | |
| 573 | +.SH | |
| 574 | +cvtrf \- Convert short real to real† | |
| 575 | +.P1 | |
| 576 | +Syntax: cvtrf src, dst | |
| 577 | +Function: dst = (float)src; | |
| 578 | +.P2 | |
| 579 | +The short (32 bit) floating point value addressed by the | |
| 580 | +.CW "src" | |
| 581 | +operand is converted to a 64-bit floating point value and stored in the | |
| 582 | +.CW "dst" | |
| 583 | +operand. | |
| 584 | +.SH | |
| 585 | +div\fIx\fP \- Divide | |
| 586 | +.P1 | |
| 587 | +Syntax: divb src1, src2, dst | |
| 588 | + divf src1, src2, dst | |
| 589 | + divw src1, src2, dst | |
| 590 | + divl src1, src2, dst | |
| 591 | +Function: dst = src2/src1 | |
| 592 | +.P2 | |
| 593 | +The | |
| 594 | +.CW "src2" | |
| 595 | +operand is divided by the | |
| 596 | +.CW "src1" | |
| 597 | +operand and the quotient is stored in the | |
| 598 | +.CW "dst" | |
| 599 | +operand. Division by zero causes the thread to terminate. | |
| 600 | +.SH | |
| 601 | +exit \- Terminate thread | |
| 602 | +.P1 | |
| 603 | +Syntax: exit | |
| 604 | +Function: exit() | |
| 605 | +.P2 | |
| 606 | +The executing thread terminates. All resources held in the stack are deallocated. | |
| 607 | +.SH | |
| 608 | +frame \- Allocate frame for local call | |
| 609 | +.P1 | |
| 610 | +Syntax: frame src1, src2 | |
| 611 | +Function: src2 = fp + src1->size | |
| 612 | + initmem(src2, src1); | |
| 613 | +.P2 | |
| 614 | +The frame instruction creates a new stack frame | |
| 615 | +for a call to a function in the same module. The frame is initialized according to the type descriptor supplied as the | |
| 616 | +.CW src1 | |
| 617 | +operand. A pointer to the newly created frame is stored in the | |
| 618 | +.CW src2 | |
| 619 | +operand. | |
| 620 | +.SH | |
| 621 | +goto \- Computed goto | |
| 622 | +.P1 | |
| 623 | +Syntax: goto src, dst | |
| 624 | +Function: pc = dst[src] | |
| 625 | +.P2 | |
| 626 | +The | |
| 627 | +.CW "goto" | |
| 628 | +instruction performs a computed goto. The | |
| 629 | +.CW "src" | |
| 630 | +operand must be an integer index into a table of PC values specified by the | |
| 631 | +.CW "dst" | |
| 632 | +operand. | |
| 633 | +.SH | |
| 634 | +head\fIx\fP \- Head of list | |
| 635 | +.P1 | |
| 636 | +Syntax: headb src, dst | |
| 637 | + headf src, dst | |
| 638 | + headm src, dst | |
| 639 | + headmp src, dst | |
| 640 | + headp src, dst | |
| 641 | + headw src, dst | |
| 642 | + headl src, dst | |
| 643 | +Function: dst = hd src | |
| 644 | +.P2 | |
| 645 | +The | |
| 646 | +.CW "head" | |
| 647 | +instructions make a copy of the first data item stored in a list. The | |
| 648 | +.CW "src" | |
| 649 | +operand must be a list of the correct type. The first item is copied into the | |
| 650 | +.CW "dst" | |
| 651 | +operand. The list is not modified. | |
| 652 | +.SH | |
| 653 | +indc \- Index by character | |
| 654 | +.P1 | |
| 655 | +Syntax: indc src1, src2, dst | |
| 656 | +Function: dst = src1[src2] | |
| 657 | +.P2 | |
| 658 | +The | |
| 659 | +.CW "indc" | |
| 660 | +instruction indexes Unicode strings. The | |
| 661 | +.CW "src1" | |
| 662 | +instruction must be a string. The | |
| 663 | +.CW "src2" | |
| 664 | +operand must be an integer specifying the origin-0 index in | |
| 665 | +.CW src1 | |
| 666 | +of the (Unicode) character to store in the | |
| 667 | +.CW "dst" | |
| 668 | +operand. | |
| 669 | +.SH | |
| 670 | +indx \- Array index | |
| 671 | +.P1 | |
| 672 | +Syntax: indx src1, dst, src2 | |
| 673 | +Function: dst = &src1[src2] | |
| 674 | +.P2 | |
| 675 | +The | |
| 676 | +.CW "indx" | |
| 677 | +instruction computes the effective address of an array element. The | |
| 678 | +.CW "src1" | |
| 679 | +operand must be an array created by the | |
| 680 | +.CW "newa" | |
| 681 | +instruction. The | |
| 682 | +.CW "src2" | |
| 683 | +operand must be an integer. The effective address of the | |
| 684 | +.CW "src2" | |
| 685 | +element of the array is stored in the | |
| 686 | +.CW "dst" | |
| 687 | +operand. | |
| 688 | +.SH | |
| 689 | +ind\fIx\fP \- Index by type | |
| 690 | +.P1 | |
| 691 | +Syntax: indb src1, dst, src2 | |
| 692 | + indw src1, dst, src2 | |
| 693 | + indf src1, dst, src2 | |
| 694 | + indl src1, dst, src2 | |
| 695 | +Function: dst = src1[src2] | |
| 696 | +.P2 | |
| 697 | +The | |
| 698 | +.CW "indb" , | |
| 699 | +.CW "indw" , | |
| 700 | +.CW "indf" | |
| 701 | +and | |
| 702 | +.CW "indl" | |
| 703 | +instructions index arrays of the basic types. The | |
| 704 | +.CW "src1" | |
| 705 | +operand must be an array created by the | |
| 706 | +.CW "newa" | |
| 707 | +instruction. The | |
| 708 | +.CW "src2" | |
| 709 | +operand must be a non-negative integer index less than the array size. The value of the element at the index is loaded into the | |
| 710 | +.CW "dst" | |
| 711 | +operand. | |
| 712 | +.SH | |
| 713 | +insc \- Insert character into string | |
| 714 | +.P1 | |
| 715 | +Syntax: insc src1, src2, dst | |
| 716 | +Function: src1[src2] = dst | |
| 717 | +.P2 | |
| 718 | +The | |
| 719 | +.CW "insc" | |
| 720 | +instruction inserts a character into an existing string. | |
| 721 | +The index in | |
| 722 | +.CW "src2" | |
| 723 | +must be a non-negative integer less than the length of the string plus one. | |
| 724 | +(The character will be appended to the string if the index is equal to | |
| 725 | +the string's length.) | |
| 726 | +The | |
| 727 | +.CW "src1" | |
| 728 | +operand must be a string (or nil). | |
| 729 | +The character to insert must be a valid 16-bit unicode value represented as a word. | |
| 730 | +.SH | |
| 731 | +jmp \- Branch always | |
| 732 | +.P1 | |
| 733 | +Syntax: jmp dst | |
| 734 | +Function: pc = dst | |
| 735 | +.P2 | |
| 736 | +Control is transferred to the location specified by the | |
| 737 | +.CW "dst" | |
| 738 | +operand. | |
| 739 | +.SH | |
| 740 | +lea \- Load effective address | |
| 741 | +.P1 | |
| 742 | +Syntax: lea src, dst | |
| 743 | +Function: dst = &src | |
| 744 | +.P2 | |
| 745 | +The | |
| 746 | +.CW "lea" | |
| 747 | +instruction computes the effective address of the | |
| 748 | +.CW "src" | |
| 749 | +operand and stores it in the | |
| 750 | +.CW "dst" | |
| 751 | +operand. | |
| 752 | +.SH | |
| 753 | +lena \- Length of array | |
| 754 | +.P1 | |
| 755 | +Syntax: lena src, dst | |
| 756 | +Function: dst = nelem(src) | |
| 757 | +.P2 | |
| 758 | +The | |
| 759 | +.CW "lena" | |
| 760 | +instruction computes the length of the array specified by the | |
| 761 | +.CW "src" | |
| 762 | +operand and stores it in the | |
| 763 | +.CW "dst" | |
| 764 | +operand. | |
| 765 | +.SH | |
| 766 | +lenc \- Length of string | |
| 767 | +.P1 | |
| 768 | +Syntax: lenc src, dst | |
| 769 | +Function: dst = utflen(src) | |
| 770 | +.P2 | |
| 771 | +The | |
| 772 | +.CW "lenc" | |
| 773 | +instruction computes the number of characters in the UTF string addressed by the | |
| 774 | +.CW "src" | |
| 775 | +operand and stores it in the | |
| 776 | +.CW "dst" | |
| 777 | +operand. | |
| 778 | +.SH | |
| 779 | +lenl \- Length of list | |
| 780 | +.P1 | |
| 781 | +Syntax: lenl src, dst | |
| 782 | +Function: dst = 0; | |
| 783 | + for(l = src; l; l = tl l) | |
| 784 | + dst++; | |
| 785 | +.P2 | |
| 786 | +The | |
| 787 | +.CW "lenl" | |
| 788 | +instruction computes the number of elements in the list addressed by the | |
| 789 | +.CW "src" | |
| 790 | +operand and stores the result in the | |
| 791 | +.CW "dst" | |
| 792 | +operand. | |
| 793 | +.SH | |
| 794 | +load \- Load module | |
| 795 | +.P1 | |
| 796 | +Syntax: load src1, src2, dst | |
| 797 | +Function: dst = load src2 src1 | |
| 798 | +.P2 | |
| 799 | +The | |
| 800 | +.CW "load" | |
| 801 | +instruction loads a new module into the heap. The module might optionally be compiled into machine code depending on the module header. The | |
| 802 | +.CW "src1" | |
| 803 | +operand is a pathname to the file containing the object code for the module. The | |
| 804 | +.CW "src2" | |
| 805 | +operand specifies the address | |
| 806 | +of a linkage descriptor for the module (see below). | |
| 807 | +A reference to the newly loaded module is stored in the | |
| 808 | +.CW "dst" | |
| 809 | +operand. | |
| 810 | +If the module could not be loaded for any reason, then | |
| 811 | +.CW "dst" | |
| 812 | +will be set to | |
| 813 | +.CW H . | |
| 814 | +.LP | |
| 815 | +The linkage descriptor referenced by the | |
| 816 | +.CW src2 | |
| 817 | +operand is a table in data space that lists the functions | |
| 818 | +imported by the current module from the module to be loaded. | |
| 819 | +It has the following layout: | |
| 820 | +.P1 | |
| 821 | +int nentries; | |
| 822 | +struct { /* word aligned */ | |
| 823 | + int sig; | |
| 824 | + byte name[]; /* UTF encoded name, 0-terminated */ | |
| 825 | +} entry[]; | |
| 826 | +.P2 | |
| 827 | +The | |
| 828 | +.CW nentries | |
| 829 | +value gives the number of entries in the table and can be zero. | |
| 830 | +It is followed by that many linkage entries. | |
| 831 | +Each entry is aligned on a word boundary; there can therefore | |
| 832 | +be padding before each structure. | |
| 833 | +The entry names the imported function in the UTF-encoded string in | |
| 834 | +.CW name , | |
| 835 | +which is terminated by a byte containing zero. | |
| 836 | +The MD5 hash of the function's type signature is given in the value | |
| 837 | +.CW sig . | |
| 838 | +For each entry, | |
| 839 | +.CW load | |
| 840 | +instruction checks that a function with the same name in the newly loaded | |
| 841 | +exists, with the same signature. | |
| 842 | +Otherwise the load will fail and | |
| 843 | +.CW dst | |
| 844 | +will be set to | |
| 845 | +.CW H . | |
| 846 | +.LP | |
| 847 | +The entries in the linkage descriptor form an array of linkage records | |
| 848 | +(internal to the virtual machine) associated with the | |
| 849 | +module pointer returned in | |
| 850 | +.CW dst , | |
| 851 | +that is indexed by operators | |
| 852 | +.CW mframe , | |
| 853 | +.CW mcall | |
| 854 | +and | |
| 855 | +.CW mspawn | |
| 856 | +to refer to functions in that module. | |
| 857 | +The linkage scheme provides a level of indirection that allows | |
| 858 | +a module to be loaded using any module declaration that is a valid | |
| 859 | +subset of the implementation module's declaration, | |
| 860 | +and allows entry points to be added to modules without invalidating | |
| 861 | +calling modules. | |
| 862 | +.SH | |
| 863 | +lsr\fIx\fP \- Logical shift right | |
| 864 | +.P1 | |
| 865 | +Syntax: lsrw src1, src2, dst | |
| 866 | + lsrl src1, src2, dst | |
| 867 | +Function: dst = (unsigned)src2 >> src1 | |
| 868 | +.P2 | |
| 869 | +The | |
| 870 | +.CW "lsr" | |
| 871 | +instructions shift the | |
| 872 | +.CW "src2" | |
| 873 | +operand right by the number of bits specified by the | |
| 874 | +.CW "src1" | |
| 875 | +operand, replacing the vacated bits by 0, and store the result in the | |
| 876 | +.CW "dst" | |
| 877 | +operand. Shift counts less than 0 or greater than the number of bits in the object have undefined results. | |
| 878 | +This instruction is included for support of languages other than Limbo, | |
| 879 | +and is not used by the Limbo compiler. | |
| 880 | +.SH | |
| 881 | +mcall \- Inter-module call | |
| 882 | +.P1 | |
| 883 | +Syntax: mcall src1, src2, src3 | |
| 884 | +Function: link(src1) = pc | |
| 885 | + frame(src1) = fp | |
| 886 | + mod(src1) = current_moduleptr | |
| 887 | + current_moduleptr = src3->moduleptr | |
| 888 | + fp = src1 | |
| 889 | + pc = src3->links[src2]->pc | |
| 890 | +.P2 | |
| 891 | +The | |
| 892 | +.CW "mcall" | |
| 893 | +instruction calls a function in another module. The first argument specifies a new frame for the called procedure and must have been built using the | |
| 894 | +.CW "mframe" | |
| 895 | +instruction. | |
| 896 | +The | |
| 897 | +.CW "src3" | |
| 898 | +operand is a module reference generated by a successful | |
| 899 | +.CW "load" | |
| 900 | +instruction. | |
| 901 | +The | |
| 902 | +.CW "src2" | |
| 903 | +operand specifies the index for the called | |
| 904 | +function in the array of linkage records associated with that module reference | |
| 905 | +(see the | |
| 906 | +.CW load | |
| 907 | +instruction). | |
| 908 | +.SH | |
| 909 | +mframe \- Allocate inter-module frame | |
| 910 | +.P1 | |
| 911 | +Syntax: mframe src1, src2, dst | |
| 912 | +Function: dst = fp + src1->links[src2]->t->size | |
| 913 | + initmem(dst, src1->links[src2]) | |
| 914 | +.P2 | |
| 915 | +The | |
| 916 | +.CW mframe | |
| 917 | +instruction allocates a new frame for a procedure call into another module. The | |
| 918 | +.CW src1 | |
| 919 | +operand specifies the location of a module pointer created as the result of a successful load instruction. The | |
| 920 | +.CW src2 | |
| 921 | +operand specifies the index for the called function in | |
| 922 | +the array of linkage records associated | |
| 923 | +with that module pointer (see the | |
| 924 | +.CW load | |
| 925 | +instruction). | |
| 926 | +A pointer to the initialized frame is stored in | |
| 927 | +.CW dst . | |
| 928 | +The | |
| 929 | +.CW src2 | |
| 930 | +operand specifies the linkage number of the function to be called in the module specified by | |
| 931 | +.CW src1 . | |
| 932 | +.SH | |
| 933 | +mnewz \- Allocate object given type from another module | |
| 934 | +.P1 | |
| 935 | +Syntax: mnewz src1, src2, dst | |
| 936 | +Function: dst = malloc(src1->types[src2]->size) | |
| 937 | + initmem(dst, src1->types[src2]->map) | |
| 938 | +.P2 | |
| 939 | +The | |
| 940 | +.CW mnewz | |
| 941 | +instruction allocates and initializes storage to a new | |
| 942 | +area of memory. | |
| 943 | +The | |
| 944 | +.CW src1 | |
| 945 | +operand specifies the location of a module pointer created as the result of a successful load instruction. | |
| 946 | +The size of the new memory area and the location of | |
| 947 | +pointers within it are specified by the | |
| 948 | +.CW src2 | |
| 949 | +operand, which gives a | |
| 950 | +type descriptor number within that module. | |
| 951 | +Space not occupied by pointers is initialized to zero. | |
| 952 | +A pointer to the initialized object is stored in | |
| 953 | +.CW dst . | |
| 954 | +This instruction is not used by Limbo; it was added to implement other languages. | |
| 955 | +.SH | |
| 956 | +mod\fIx\fP \- Modulus | |
| 957 | +.P1 | |
| 958 | +Syntax: modb src1, src2, dst | |
| 959 | + modw src1, src2, dst | |
| 960 | + modl src1, src2, dst | |
| 961 | +Function: dst = src2 % src1 | |
| 962 | +.P2 | |
| 963 | +The modulus instructions compute the remainder of the | |
| 964 | +.CW "src2" | |
| 965 | +operand divided by the | |
| 966 | +.CW "src1" | |
| 967 | +operand and store the result in | |
| 968 | +.CW "dst" . | |
| 969 | +The operator preserves the condition that the absolute value of a%b is less than the absolute value of | |
| 970 | +.CW "b" ; | |
| 971 | +.CW "(a/b)*b + a%b" | |
| 972 | +is always equal to | |
| 973 | +.CW a . | |
| 974 | +.SH | |
| 975 | +mov\fIx\fP \- Move scalar | |
| 976 | +.P1 | |
| 977 | +Syntax: movb src, dst | |
| 978 | + movw src, dst | |
| 979 | + movf src, dst | |
| 980 | + movl src, dst | |
| 981 | +Function: dst = src | |
| 982 | +.P2 | |
| 983 | +The move operators perform assignment. The value specified by the | |
| 984 | +.CW "src" | |
| 985 | +operand is copied to the | |
| 986 | +.CW "dst" | |
| 987 | +operand. | |
| 988 | +.SH | |
| 989 | +movm \- Move memory | |
| 990 | +.P1 | |
| 991 | +Syntax: movm src1, src2, dst | |
| 992 | +Function: memmove(&dst, &src1, src2) | |
| 993 | +.P2 | |
| 994 | +The | |
| 995 | +.CW "movm" | |
| 996 | +instruction copies memory from the | |
| 997 | +.CW "src1" | |
| 998 | +operand to the | |
| 999 | +.CW "dst" | |
| 1000 | +operand for | |
| 1001 | +.CW "src2" | |
| 1002 | +bytes. The | |
| 1003 | +.CW "src1" | |
| 1004 | +and | |
| 1005 | +.CW "dst" | |
| 1006 | +operands specify the effective address of the memory rather than a pointer to the memory. | |
| 1007 | +.SH | |
| 1008 | +movmp \- Move memory and update reference counts | |
| 1009 | +.P1 | |
| 1010 | +Syntax: movmp src1, src2, dst | |
| 1011 | +Function: decmem(&dst, src2) | |
| 1012 | + memmove(&dst, &src1, src2->size) | |
| 1013 | + incmem(&src, src2) | |
| 1014 | +.P2 | |
| 1015 | +The | |
| 1016 | +.CW "movmp" | |
| 1017 | +instructions performs the same function as the | |
| 1018 | +.CW "movm" | |
| 1019 | +instruction but increments the reference count of pointers contained in the data type. For each pointer specified by the | |
| 1020 | +.CW "src2" | |
| 1021 | +type descriptor, the corresponding pointer reference count in the destination is decremented. The | |
| 1022 | +.CW "movmp" | |
| 1023 | +instruction then copies memory from the | |
| 1024 | +.CW "src1" | |
| 1025 | +operand to the | |
| 1026 | +.CW "dst" | |
| 1027 | +operand for the number of bytes described by the type descriptor. For each pointer specified by the type descriptor the corresponding pointer reference count in the source is incremented. | |
| 1028 | +.SH | |
| 1029 | +movp \- Move pointer | |
| 1030 | +.P1 | |
| 1031 | +Syntax: movp src, dst | |
| 1032 | +Function: destroy(dst) | |
| 1033 | + dst = src | |
| 1034 | + incref(src) | |
| 1035 | +.P2 | |
| 1036 | +The | |
| 1037 | +.CW "movp" | |
| 1038 | +instruction copies a pointer adjusting the reference counts to reflect the new pointers. | |
| 1039 | +.SH | |
| 1040 | +movpc \- Move program counter | |
| 1041 | +.P1 | |
| 1042 | +Syntax: movpc src, dst | |
| 1043 | +Function: dst = PC(src); | |
| 1044 | +.P2 | |
| 1045 | +The | |
| 1046 | +.CW "movpc" | |
| 1047 | +instruction computes the actual address of an immediate PC value. The | |
| 1048 | +.CW "dst" | |
| 1049 | +operand is set to the actual machine address of the instruction addressed by the | |
| 1050 | +.CW "src" | |
| 1051 | +operand. This instruction must be used to calculate PC values for computed branches. | |
| 1052 | +.SH | |
| 1053 | +mspawn \- Module spawn function | |
| 1054 | +.P1 | |
| 1055 | +Syntax: mspawn src1, src2, src3 | |
| 1056 | +Function: fork(); | |
| 1057 | + if(child){ | |
| 1058 | + link(src1) = 0 | |
| 1059 | + frame(src1) = 0 | |
| 1060 | + mod(src1) = src3->moduleptr | |
| 1061 | + current_moduleptr = src3->moduleptr | |
| 1062 | + fp = src1 | |
| 1063 | + pc = src3->links[src2]->pc | |
| 1064 | + } | |
| 1065 | +.P2 | |
| 1066 | +The | |
| 1067 | +.CW "mspawn" | |
| 1068 | +instruction creates a new thread, which starts executing a function in another module. | |
| 1069 | +The first argument specifies a new frame for the called procedure and must have been built using the | |
| 1070 | +.CW "mframe" | |
| 1071 | +instruction. | |
| 1072 | +The | |
| 1073 | +.CW "src3" | |
| 1074 | +operand is a module reference generated by a successful | |
| 1075 | +.CW "load" | |
| 1076 | +instruction. | |
| 1077 | +The | |
| 1078 | +.CW "src2" | |
| 1079 | +operand specifies the index for the called function in | |
| 1080 | +the array of linkage records associated with that module reference (see the | |
| 1081 | +.CW load | |
| 1082 | +instruction above). | |
| 1083 | +.SH | |
| 1084 | +mul\fIx\fP - Multiply | |
| 1085 | +.P1 | |
| 1086 | +Syntax: mulb src1, src2, dst | |
| 1087 | + mulw src1, src2, dst | |
| 1088 | + mulf src1, src2, dst | |
| 1089 | + mull src1, src2, dst | |
| 1090 | +Function: dst = src1 * src2 | |
| 1091 | +.P2 | |
| 1092 | +The | |
| 1093 | +.CW src1 | |
| 1094 | +operand is multiplied by the | |
| 1095 | +.CW src2 | |
| 1096 | +operand and the product is stored in the | |
| 1097 | +.CW dst | |
| 1098 | +operand. | |
| 1099 | +.SH | |
| 1100 | +nbalt \- Non blocking alternate | |
| 1101 | +.P1 | |
| 1102 | +Syntax: nbalt src, dst | |
| 1103 | +.P2 | |
| 1104 | +The | |
| 1105 | +.CW "nbalt" | |
| 1106 | +instruction has the same operands and function as | |
| 1107 | +.CW "alt" | |
| 1108 | +, except that if no channel is ready to communicate, the instruction does not block. When no channels are ready, control is transferred to the PC in the last element of the table addressed by | |
| 1109 | +.CW dst . | |
| 1110 | +.SH | |
| 1111 | +negf \- Negate real | |
| 1112 | +.P1 | |
| 1113 | +Syntax: negf src, dst | |
| 1114 | +Function: dst = -src | |
| 1115 | +.P2 | |
| 1116 | +The floating point value addressed by the | |
| 1117 | +.CW "src" | |
| 1118 | +operand is negated and stored in the | |
| 1119 | +.CW "dst" | |
| 1120 | +operand. | |
| 1121 | +.SH | |
| 1122 | +new, newz \- Allocate object | |
| 1123 | +.P1 | |
| 1124 | +Syntax: new src, dst | |
| 1125 | + newz src, dst | |
| 1126 | +Function: dst = malloc(src->size); | |
| 1127 | + initmem(dst, src->map); | |
| 1128 | +.P2 | |
| 1129 | +The | |
| 1130 | +.CW "new" | |
| 1131 | +instruction allocates and initializes storage to a new area of memory. The size and locations of pointers are specified by the type descriptor number given as the | |
| 1132 | +.CW "src" | |
| 1133 | +operand. A pointer to the newly allocated object is placed in | |
| 1134 | +.CW "dst" . | |
| 1135 | +Any space not occupied by pointers has undefined value. | |
| 1136 | +.LP | |
| 1137 | +The | |
| 1138 | +.CW "newz" | |
| 1139 | +instruction additionally guarantees that all non-pointer values are set to zero. | |
| 1140 | +It is not used by Limbo. | |
| 1141 | +.SH | |
| 1142 | +newa, newaz \- Allocate array | |
| 1143 | +.P1 | |
| 1144 | +Syntax: newa src1, src2, dst | |
| 1145 | + newaz src1, src2, dst | |
| 1146 | +Function: dst = malloc(src2->size * src1); | |
| 1147 | + for(i = 0; i < src1; i++) | |
| 1148 | + initmem(dst + i*src2->size, src2->map); | |
| 1149 | +.P2 | |
| 1150 | +The | |
| 1151 | +.CW "newa" | |
| 1152 | +instruction allocates and initializes an array. The number of elements is specified by the | |
| 1153 | +.CW "src1" | |
| 1154 | +operand. The type of each element is specified by the type descriptor number given as the | |
| 1155 | +.CW "src2" | |
| 1156 | +operand. | |
| 1157 | +Space not occupied by pointers has undefined value. | |
| 1158 | +The | |
| 1159 | +.CW newaz | |
| 1160 | +instruction additionally guarantees that all non-pointer values are set to zero; | |
| 1161 | +it is not used by Limbo. | |
| 1162 | +.SH | |
| 1163 | +newc\fIx\fP \- Allocate channel | |
| 1164 | +.P1 | |
| 1165 | +Syntax: newcw dst | |
| 1166 | + newcb dst | |
| 1167 | + newcl dst | |
| 1168 | + newcf dst | |
| 1169 | + newcp dst | |
| 1170 | + newcm src, dst | |
| 1171 | + newcmp src, dst | |
| 1172 | +Function: dst = new(Channel) | |
| 1173 | +.P2 | |
| 1174 | +The | |
| 1175 | +.CW "newc" | |
| 1176 | +instruction allocates a new channel of the specified type and stores a reference to the channel in | |
| 1177 | +.CW "dst" . | |
| 1178 | +For the | |
| 1179 | +.CW "newcm" | |
| 1180 | +instruction the source specifies the number of bytes of memory used by values sent on the channel (see the | |
| 1181 | +.CW movm | |
| 1182 | +instruction above). | |
| 1183 | +For the | |
| 1184 | +.CW "newcmp" | |
| 1185 | +instruction the first operand specifies a type descriptor giving the length of the structure and the location of pointers within the structure (see the | |
| 1186 | +.CW movmp | |
| 1187 | +instruction above). | |
| 1188 | +.SH | |
| 1189 | +or\fIx\fP \- Logical OR | |
| 1190 | +.P1 | |
| 1191 | +Syntax: orb src1, src2, dst | |
| 1192 | + orw src1, src2, dst | |
| 1193 | + orl src1, src2, dst | |
| 1194 | +Function: dst = src1 | src | |
| 1195 | +.P2 | |
| 1196 | +These instructions compute the bitwise OR of the two operands addressed by | |
| 1197 | +.CW "src1" | |
| 1198 | +and | |
| 1199 | +.CW "src2" | |
| 1200 | +and store the result in the | |
| 1201 | +.CW "dst" | |
| 1202 | +operand. | |
| 1203 | +.SH | |
| 1204 | +recv \- Receive from channel | |
| 1205 | +.P1 | |
| 1206 | +Syntax: recv src, dst | |
| 1207 | +Function: dst = <-src | |
| 1208 | +.P2 | |
| 1209 | +The | |
| 1210 | +.CW "recv" | |
| 1211 | +instruction receives a value from some other thread on the channel specified by the | |
| 1212 | +.CW "src" | |
| 1213 | +operand. Communication is synchronous, so the calling thread will block until a corresponding | |
| 1214 | +.CW "send" | |
| 1215 | +or | |
| 1216 | +.CW "alt" | |
| 1217 | +is performed on the channel. The type of the received value is determined by the channel type and the | |
| 1218 | +.CW "dst" | |
| 1219 | +operand specifies where to place the received value. | |
| 1220 | +.SH | |
| 1221 | +ret \- Return from function | |
| 1222 | +.P1 | |
| 1223 | +Syntax: ret | |
| 1224 | +Function: npc = link(fp) | |
| 1225 | + mod = mod(fp) | |
| 1226 | + fp = frame(fp) | |
| 1227 | + pc = npc | |
| 1228 | +.P2 | |
| 1229 | +The | |
| 1230 | +.CW "ret" | |
| 1231 | +instruction returns control to the instruction after the call of the current function. | |
| 1232 | +.SH | |
| 1233 | +send \- Send to channel | |
| 1234 | +.P1 | |
| 1235 | +Syntax: send src, dst | |
| 1236 | +Function: dst <-= src | |
| 1237 | +.P2 | |
| 1238 | +The | |
| 1239 | +.CW "send" | |
| 1240 | +instruction sends a value from this thread to some other thread on the channel specified by the | |
| 1241 | +.CW "dst" | |
| 1242 | +operand. Communication is synchronous so the calling thread will block until a corresponding | |
| 1243 | +.CW "recv" | |
| 1244 | +or | |
| 1245 | +.CW "alt" | |
| 1246 | +is performed on the channel. The type of the sent value is determined by the channel type and the | |
| 1247 | +.CW "dst" | |
| 1248 | +operand specifies where to retrieve the sent value. | |
| 1249 | +.SH | |
| 1250 | +shl\fIx\fP \- Shift left arithmetic | |
| 1251 | +.P1 | |
| 1252 | +Syntax: shlb src1, src2, dst | |
| 1253 | + shlw src1, src2, dst | |
| 1254 | + shll src1, src2, dst | |
| 1255 | +Function: dst = src2 << src1 | |
| 1256 | +.P2 | |
| 1257 | +The | |
| 1258 | +.CW "shl" | |
| 1259 | +instructions shift the | |
| 1260 | +.CW "src2" | |
| 1261 | +operand left by the number of bits specified by the | |
| 1262 | +.CW "src1" | |
| 1263 | +operand and store the result in the | |
| 1264 | +.CW "dst" | |
| 1265 | +operand. Shift counts less than 0 or greater than the number of bits in the object have undefined results. | |
| 1266 | +.SH | |
| 1267 | +shr\fIx\fP \- Shift right arithmetic | |
| 1268 | +.P1 | |
| 1269 | +Syntax: shrb src1, src2, dst | |
| 1270 | + shrw src1, src2, dst | |
| 1271 | + shrl src1, src2, dst | |
| 1272 | +Function: dst = src2 >> src1 | |
| 1273 | +.P2 | |
| 1274 | +The | |
| 1275 | +.CW "shr" | |
| 1276 | +instructions shift the | |
| 1277 | +.CW "src2" | |
| 1278 | +operand right by the number of bits specified by the | |
| 1279 | +.CW "src1" | |
| 1280 | +operand and store the result in the | |
| 1281 | +.CW "dst" | |
| 1282 | +operand. Shift counts less than 0 or greater than the number of bits in the object have undefined results. | |
| 1283 | +.SH | |
| 1284 | +slicea \- Slice array | |
| 1285 | +.P1 | |
| 1286 | +Syntax: slicea src1, src2, dst | |
| 1287 | +Function: dst = dst[src1:src2] | |
| 1288 | +.P2 | |
| 1289 | +The | |
| 1290 | +.CW "slicea" | |
| 1291 | +instruction creates a new array, which contains the elements from the index at | |
| 1292 | +.CW "src1" | |
| 1293 | +to the index | |
| 1294 | +.CW "src2-1" . | |
| 1295 | +The new array is a reference array which points at the elements in the initial array. The initial array will remain allocated until both arrays are no longer referenced. | |
| 1296 | +.SH | |
| 1297 | +slicec \- Slice string | |
| 1298 | +.P1 | |
| 1299 | +Syntax: slicec src1, src2, dst | |
| 1300 | +Function: dst = dst[src1:src2] | |
| 1301 | +.P2 | |
| 1302 | +The | |
| 1303 | +.CW "slicec" | |
| 1304 | +instruction creates a new string, which contains characters from the index at | |
| 1305 | +.CW "src1" | |
| 1306 | +to the index | |
| 1307 | +.CW "src2-1" . | |
| 1308 | +Unlike | |
| 1309 | +.CW "slicea" | |
| 1310 | +, the new string is a copy of the elements from the initial string. | |
| 1311 | +.SH | |
| 1312 | +slicela \- Assign to array slice | |
| 1313 | +.P1 | |
| 1314 | +Syntax: slicela src1, src2, dst | |
| 1315 | +Function: dst[src2:] = src1 | |
| 1316 | +.P2 | |
| 1317 | +The | |
| 1318 | +.CW "src1" | |
| 1319 | +and | |
| 1320 | +.CW "dst" | |
| 1321 | +operands must be arrays of equal types. The | |
| 1322 | +.CW "src2" | |
| 1323 | +operand is a non-negative integer index. The | |
| 1324 | +.CW "src1" | |
| 1325 | +array is assigned to the array slice | |
| 1326 | +.CW "dst[src2:]" ; | |
| 1327 | +.CW "src2 + nelem(src1)" | |
| 1328 | +must not exceed | |
| 1329 | +.CW "nelem(dst)" . | |
| 1330 | +.SH | |
| 1331 | +spawn \- Spawn function | |
| 1332 | +.P1 | |
| 1333 | +Syntax: spawn src, dst | |
| 1334 | +Function: fork(); | |
| 1335 | + if(child) | |
| 1336 | + dst(src); | |
| 1337 | +.P2 | |
| 1338 | +The | |
| 1339 | +.CW "spawn" | |
| 1340 | +instruction creates a new thread and calls the function specified by the | |
| 1341 | +.CW "dst" | |
| 1342 | +operand. The argument frame passed to the thread function is specified by the | |
| 1343 | +.CW "src" | |
| 1344 | +operand and should have been created by the | |
| 1345 | +.CW "frame" | |
| 1346 | +instruction. | |
| 1347 | +.SH | |
| 1348 | +sub\fIx\fP \- Subtract | |
| 1349 | +.P1 | |
| 1350 | +Syntax: subb src1, src2, dst | |
| 1351 | + subf src1, src2, dst | |
| 1352 | + subw src1, src2, dst | |
| 1353 | + subl src1, src2, dst | |
| 1354 | +Function: dst = src2 - src1 | |
| 1355 | +.P2 | |
| 1356 | +The | |
| 1357 | +.CW "sub" | |
| 1358 | +instructions subtract the operands addressed by | |
| 1359 | +.CW "src1" | |
| 1360 | +and | |
| 1361 | +.CW "src2" | |
| 1362 | +and stores the result in the | |
| 1363 | +.CW "dst" | |
| 1364 | +operand. For | |
| 1365 | +.CW "subb" , | |
| 1366 | +the result is truncated to eight bits. | |
| 1367 | +.SH | |
| 1368 | +tail \- Tail of list | |
| 1369 | +.P1 | |
| 1370 | +Syntax: tail src, dst | |
| 1371 | +Function: dst = src->next | |
| 1372 | +.P2 | |
| 1373 | +The | |
| 1374 | +.CW "tail" | |
| 1375 | +instruction takes the list specified by the | |
| 1376 | +.CW "src" | |
| 1377 | +operand and creates a reference to a new list with the head removed, which is stored in the | |
| 1378 | +.CW "dst" | |
| 1379 | +operand. | |
| 1380 | +.SH | |
| 1381 | +tcmp \- Compare types | |
| 1382 | +.P1 | |
| 1383 | +Syntax: tcmp src, dst | |
| 1384 | +Function: if(typeof(src) != typeof(dst)) | |
| 1385 | + error("typecheck"); | |
| 1386 | +.P2 | |
| 1387 | +The | |
| 1388 | +.CW "tcmp" | |
| 1389 | +instruction compares the types of the two pointers supplied by the | |
| 1390 | +.CW "src" | |
| 1391 | +and | |
| 1392 | +.CW "dst" | |
| 1393 | +operands. The comparison will succeed if the two pointers were created from the same type descriptor or the | |
| 1394 | +.CW "src" | |
| 1395 | +operand is | |
| 1396 | +.CW "nil" ; | |
| 1397 | +otherwise, the program will error. The | |
| 1398 | +.CW "dst" | |
| 1399 | +operand must be a valid pointer. | |
| 1400 | +.SH | |
| 1401 | +xor\fIx\fP \- Exclusive OR | |
| 1402 | +.P1 | |
| 1403 | +Syntax: xorb src1, src2, dst | |
| 1404 | + xorw src1, src2, dst | |
| 1405 | + xorl src1, src2, dst | |
| 1406 | +Function: dst = src1 ^ src2 | |
| 1407 | +.P2 | |
| 1408 | +These instructions compute the bitwise exclusive-OR of the two operands addressed by | |
| 1409 | +.CW "src1" | |
| 1410 | +and | |
| 1411 | +.CW "src2" | |
| 1412 | +and store the result in the | |
| 1413 | +.CW "dst" | |
| 1414 | +operand. | |
| 1415 | +.NH 1 | |
| 1416 | +Object File Format | |
| 1417 | +.LP | |
| 1418 | +An object file defines a single module. The file has the following structure: | |
| 1419 | +.P1 | |
| 1420 | +Objfile | |
| 1421 | +{ | |
| 1422 | + Header; | |
| 1423 | + Code_section; | |
| 1424 | + Type_section; | |
| 1425 | + Data_section; | |
| 1426 | + Module_name; | |
| 1427 | + Link_section; | |
| 1428 | +}; | |
| 1429 | +.P2 | |
| 1430 | +The following data types are used in the description of the file encoding: | |
| 1431 | +.IP | |
| 1432 | +.TS | |
| 1433 | +lf(CW) lw(4i)fR . | |
| 1434 | +OP T{ | |
| 1435 | +encoded integer operand, encoding selected by the two most significant bits as follows: | |
| 1436 | +.nf | |
| 1437 | +00 signed 7 bits, 1 byte | |
| 1438 | +.br | |
| 1439 | +10 signed 14 bits, 2 bytes | |
| 1440 | +.br | |
| 1441 | +11 signed 30 bits, 4 bytes | |
| 1442 | +T} | |
| 1443 | +B unsigned byte | |
| 1444 | +W 32 bit signed integer | |
| 1445 | +F canonicalized 64-bit IEEE754 floating point value | |
| 1446 | +SO 16 bit unsigned small offset from register | |
| 1447 | +SI 16 bit signed immediate value | |
| 1448 | +LO 30 bit signed large offset from register | |
| 1449 | +.TE | |
| 1450 | +.LP | |
| 1451 | +All binary values are encoded in two's complement format, most significant byte first. | |
| 1452 | +.SH | |
| 1453 | +The Header Section | |
| 1454 | +.P1 | |
| 1455 | +Header | |
| 1456 | +{ | |
| 1457 | + OP: magic_number; | |
| 1458 | + Signature; | |
| 1459 | + OP: runtime_flag; | |
| 1460 | + OP: stack_extent; | |
| 1461 | + OP: code_size; | |
| 1462 | + OP: data_size; | |
| 1463 | + OP: type_size; | |
| 1464 | + OP: link_size; | |
| 1465 | + OP: entry_pc; | |
| 1466 | + OP: entry_type; | |
| 1467 | +}; | |
| 1468 | +.P2 | |
| 1469 | +The magic number is defined as 819248 | |
| 1470 | +(symbolically | |
| 1471 | +.CW XMAGIC ), | |
| 1472 | +for modules that have not been signed cryptographically, and 923426 | |
| 1473 | +(symbolically | |
| 1474 | +.CW "SMAGIC" ), | |
| 1475 | +for modules that contain a signature. | |
| 1476 | +On the Inferno system, the symbolic names | |
| 1477 | +.CW "XMAGIC" | |
| 1478 | +and | |
| 1479 | +.CW SMAGIC | |
| 1480 | +are defined by the C include file | |
| 1481 | +.CW "/include/isa.h" | |
| 1482 | +and the Limbo module | |
| 1483 | +.CW /module/dis.m . | |
| 1484 | +.LP | |
| 1485 | +The signature field is only present if the magic number is | |
| 1486 | +.CW "SMAGIC" . | |
| 1487 | +It has the form: | |
| 1488 | +.P1 | |
| 1489 | +Signature | |
| 1490 | +{ | |
| 1491 | + OP: length; | |
| 1492 | + array[length] of byte: signature; | |
| 1493 | +}; | |
| 1494 | +.P2 | |
| 1495 | +A digital signature is defined by a length, followed by an array of untyped bytes. | |
| 1496 | +Data within the signature should identify the signing authority, algorithm, and data to be signed. | |
| 1497 | +.LP | |
| 1498 | +The | |
| 1499 | +.CW runtime_flag | |
| 1500 | +is a bit mask that defines various execution options for a Dis module. The flags currently defined are: | |
| 1501 | +.P1 | |
| 1502 | +MUSTCOMPILE = 1<<0 | |
| 1503 | +DONTCOMPILE = 1<<1 | |
| 1504 | +SHAREMP = 1<<2 | |
| 1505 | +.P2 | |
| 1506 | +The | |
| 1507 | +.CW "MUSTCOMPILE" | |
| 1508 | +flag indicates that a | |
| 1509 | +.CW "load" | |
| 1510 | +instruction should draw an error if the implementation is unable to compile the module into native instructions using a just-in-time compiler. | |
| 1511 | +.LP | |
| 1512 | +The | |
| 1513 | +.CW "DONTCOMPILE" | |
| 1514 | +flag indicates that the module should not be compiled into native instructions, even though it is the default for the runtime environment. This flag may be set to allow debugging or to save memory. | |
| 1515 | +.LP | |
| 1516 | +The | |
| 1517 | +.CW "SHAREMP" | |
| 1518 | +flag indicates that each instance of the module should use the same module data for all instances of the module. There is no implicit synchronization between threads using the shared data. | |
| 1519 | +.LP | |
| 1520 | +The | |
| 1521 | +.CW stack_extent | |
| 1522 | +value indicates the number of bytes by which the thread stack of this module should be extended in the event that procedure calls exhaust the allocated stack. While stack extension is transparent to programs, increasing this value may improve the efficiency of execution at the expense of using more memory. | |
| 1523 | +.LP | |
| 1524 | +The | |
| 1525 | +.CW code_size | |
| 1526 | +is a count of the number of instructions stored in the Code_section. | |
| 1527 | +.LP | |
| 1528 | +The | |
| 1529 | +.CW data_size | |
| 1530 | +gives the size in bytes of the module's global data, which is initialized | |
| 1531 | +by evaluating the contents of the data section. | |
| 1532 | +.LP | |
| 1533 | +The | |
| 1534 | +.CW type_size | |
| 1535 | +is a count of the number of type descriptors stored in the Type_section. | |
| 1536 | +.LP | |
| 1537 | +The | |
| 1538 | +.CW link_size | |
| 1539 | +is a count of the number of external linkage directives stored in the Link_section. | |
| 1540 | +.LP | |
| 1541 | +The | |
| 1542 | +.CW entry_pc | |
| 1543 | +is an integer index into the instruction stream that is the default entry point for this module. The | |
| 1544 | +.CW entry_pc | |
| 1545 | +should point to the first instruction of a function. Instructions are numbered from a program counter value of zero. | |
| 1546 | +.LP | |
| 1547 | +The | |
| 1548 | +.CW entry_type | |
| 1549 | +is the index of the type descriptor that corresponds to the function entry point set by | |
| 1550 | +.CW entry_pc . | |
| 1551 | +.SH | |
| 1552 | +The Code Section | |
| 1553 | +.LP | |
| 1554 | +The code section describes a sequence of instructions for the virtual machine. An instruction is encoded as follows: | |
| 1555 | +.P1 | |
| 1556 | +Instruction | |
| 1557 | +{ | |
| 1558 | + B: opcode; | |
| 1559 | + B: address_mode; | |
| 1560 | + Middle_data; | |
| 1561 | + Source_data; | |
| 1562 | + Dest_data; | |
| 1563 | +}; | |
| 1564 | +.P2 | |
| 1565 | +.LP | |
| 1566 | +The | |
| 1567 | +.CW opcode | |
| 1568 | +specifies the instruction to execute, encoded as follows: | |
| 1569 | +.IP | |
| 1570 | +.TS | |
| 1571 | +tab(:); | |
| 1572 | +l l l l l . | |
| 1573 | +00 nop:20 headb:40 mulw:60 blew:80 shrl | |
| 1574 | +01 alt:21 headw:41 mulf:61 bgtw:81 bnel | |
| 1575 | +02 nbalt:22 headp:42 divb:62 bgew:82 bltl | |
| 1576 | +03 goto:23 headf:43 divw:63 beqf:83 blel | |
| 1577 | +04 call:24 headm:44 divf:64 bnef:84 bgtl | |
| 1578 | +05 frame:25 headmp:45 modw:65 bltf:85 bgel | |
| 1579 | +06 spawn:26 tail:46 modb:66 blef:86 beql | |
| 1580 | +07 runt:27 lea:47 andb:67 bgtf:87 cvtlf | |
| 1581 | +08 load:28 indx:48 andw:68 bgef:88 cvtfl | |
| 1582 | +09 mcall:29 movp:49 orb:69 beqc:89 cvtlw | |
| 1583 | +0A mspawn:2A movm:4A orw:6A bnec:8A cvtwl | |
| 1584 | +0B mframe:2B movmp:4B xorb:6B bltc:8B cvtlc | |
| 1585 | +0C ret:2C movb:4C xorw:6C blec:8C cvtcl | |
| 1586 | +0D jmp:2D movw:4D shlb:6D bgtc:8D headl | |
| 1587 | +0E case:2E movf:4E shlw:6E bgec:8E consl | |
| 1588 | +0F exit:2F cvtbw:4F shrb:6F slicea:8F newcl | |
| 1589 | +10 new:30 cvtwb:50 shrw:70 slicela:90 casec | |
| 1590 | +11 newa:31 cvtfw:51 insc:71 slicec:91 indl | |
| 1591 | +12 newcb:32 cvtwf:52 indc:72 indw:92 movpc | |
| 1592 | +13 newcw:33 cvtca:53 addc:73 indf:93 tcmp | |
| 1593 | +14 newcf:34 cvtac:54 lenc:74 indb:94 mnewz | |
| 1594 | +15 newcp:35 cvtwc:55 lena:75 negf:95 cvtrf | |
| 1595 | +16 newcm:36 cvtcw:56 lenl:76 movl:96 cvtfr | |
| 1596 | +17 newcmp:37 cvtfc:57 beqb:77 addl:97 cvtws | |
| 1597 | +18 send:38 cvtcf:58 bneb:78 subl:98 cvtsw | |
| 1598 | +19 recv:39 addb:59 bltb:79 divl:99 lsrw | |
| 1599 | +1A consb:3A addw:5A bleb:7A modl:9A lsrl | |
| 1600 | +1B consw:3B addf:5B bgtb:7B mull:9B eclr | |
| 1601 | +1C consp:3C subb:5C bgeb:7C andl:9C newz | |
| 1602 | +1D consf:3D subw:5D beqw:7D orl:9D newaz | |
| 1603 | +1E consm:3E subf:5E bnew:7E xorl | |
| 1604 | +1F consmp:3F mulb:5F bltw:7F shll | |
| 1605 | +.TE | |
| 1606 | +.LP | |
| 1607 | +The | |
| 1608 | +.CW address_mode | |
| 1609 | +byte specifies the addressing mode of each of the three operands: middle, source and destination. The source and destination operands are encoded by three bits and the middle operand by two bits. The bits are packed as follows: | |
| 1610 | +.P1 | |
| 1611 | +bit 7 6 5 4 3 2 1 0 | |
| 1612 | + m1 m0 s2 s1 s0 d2 d1 d0 | |
| 1613 | +.P2 | |
| 1614 | +The middle operand is encoded as follows: | |
| 1615 | +.IP | |
| 1616 | +.TS | |
| 1617 | +lf(CW) lf(CW) lw(3i)fR . | |
| 1618 | +00 \fInone\fP no middle operand | |
| 1619 | +01 $SI small immediate | |
| 1620 | +10 SO(FP) small offset indirect from FP | |
| 1621 | +11 SO(MP) small offset indirect from MP | |
| 1622 | +.TE | |
| 1623 | +.LP | |
| 1624 | +The source and destination operands are encoded as follows: | |
| 1625 | +.IP | |
| 1626 | +.TS | |
| 1627 | +lf(CW) lf(CW) lw(3i)fR . | |
| 1628 | +000 LO(MP) offset indirect from MP | |
| 1629 | +001 LO(FP) offset indirect from FP | |
| 1630 | +010 $OP 30 bit immediate | |
| 1631 | +011 \fInone\fP no operand | |
| 1632 | +100 SO(SO(MP)) double indirect from MP | |
| 1633 | +101 SO(SO(FP)) double indirect from FP | |
| 1634 | +110 \fIreserved\fP | |
| 1635 | +111 \fIreserved\fP | |
| 1636 | +.TE | |
| 1637 | +.LP | |
| 1638 | +The | |
| 1639 | +.CW middle_data | |
| 1640 | +field is only present if the middle operand specifier of the address_mode is not `none'. | |
| 1641 | +If the field is present it is encoded as an | |
| 1642 | +.CW "OP" . | |
| 1643 | +.LP | |
| 1644 | +The | |
| 1645 | +.CW source_data | |
| 1646 | +and | |
| 1647 | +.CW dest_data | |
| 1648 | +fields are present only if the corresponding | |
| 1649 | +.CW address_mode | |
| 1650 | +field is not `none'. | |
| 1651 | +For offset indirect and immediate modes the field contains a single | |
| 1652 | +.CW "OP" . | |
| 1653 | +For double indirect modes the values are encoded as two | |
| 1654 | +.CW "OP" | |
| 1655 | +values: the first value is the register indirect offset, and the second value is the final indirect offset. The offsets for double indirect addressing cannot be larger than 16 bits. | |
| 1656 | +.SH | |
| 1657 | +The Type Section | |
| 1658 | +.LP | |
| 1659 | +The type section contains type descriptors describing the layout of pointers within data types. The format of each descriptor is: | |
| 1660 | +.P1 | |
| 1661 | +Type_descriptor | |
| 1662 | +{ | |
| 1663 | + OP: desc_number; | |
| 1664 | + OP: size; | |
| 1665 | + OP: number_ptrs; | |
| 1666 | + array[number_ptrs] of B: map; | |
| 1667 | +}; | |
| 1668 | +.P2 | |
| 1669 | +.LP | |
| 1670 | +The | |
| 1671 | +.CW desc_number | |
| 1672 | +is a small integer index used to identify the descriptor to instructions such as | |
| 1673 | +.CW "new" . | |
| 1674 | +.LP | |
| 1675 | +The | |
| 1676 | +.CW "size" | |
| 1677 | +field is the size in bytes of the memory described by this type. | |
| 1678 | +.LP | |
| 1679 | +The | |
| 1680 | +.CW number_ptrs | |
| 1681 | +field gives the size in bytes of the | |
| 1682 | +.CW "map" | |
| 1683 | +array. | |
| 1684 | +.LP | |
| 1685 | +The | |
| 1686 | +.CW "map" | |
| 1687 | +array is a bit vector where each bit corresponds to a word in memory. | |
| 1688 | +The most significant bit corresponds to the lowest address. | |
| 1689 | +For each bit in the map, | |
| 1690 | +the word at the corresponding offset in the type is a pointer iff the bit is set to 1. | |
| 1691 | +.SH | |
| 1692 | +The Data Section | |
| 1693 | +.LP | |
| 1694 | +The data section encodes the contents of the | |
| 1695 | +.CW "MP" | |
| 1696 | +data for the module. The section contains a sequence of items; each item contains | |
| 1697 | +a control byte and an offset into the section, | |
| 1698 | +followed by one or more data items. | |
| 1699 | +A control byte of zero marks the end of the data section. | |
| 1700 | +Otherwise, it gives the type of data to be loaded and selects between | |
| 1701 | +two representations of an item: | |
| 1702 | +.P1 | |
| 1703 | +Short_item | |
| 1704 | +{ | |
| 1705 | + B: code; | |
| 1706 | + OP: offset; | |
| 1707 | + array[code & 16rF] of type[code>>4]: data; | |
| 1708 | +}; | |
| 1709 | +.P3 | |
| 1710 | +Long_item | |
| 1711 | +{ | |
| 1712 | + B: code; | |
| 1713 | + OP: count; | |
| 1714 | + OP: offset; | |
| 1715 | + array[ndata] of type[code>>4]: data; | |
| 1716 | +}; | |
| 1717 | +.P2 | |
| 1718 | +A | |
| 1719 | +.CW Short_item | |
| 1720 | +is generated for 15 or fewer items, otherwise a | |
| 1721 | +.CW "Long_item" | |
| 1722 | +is generated. In a | |
| 1723 | +.CW "Long_item" | |
| 1724 | +the count field (bottom 4 bits of code) is set to zero and the count follows as an | |
| 1725 | +.CW "OP" . | |
| 1726 | +The top 4 bits of code determine the type of the datum. | |
| 1727 | +The defined values are: | |
| 1728 | +.IP | |
| 1729 | +.TS | |
| 1730 | +lf(CW) lw(3i)f(R) . | |
| 1731 | +0001 8 bit bytes | |
| 1732 | +0010 32 bit words | |
| 1733 | +0011 utf encoded string | |
| 1734 | +0100 real value IEEE754 canonical representation | |
| 1735 | +0101 Array | |
| 1736 | +0110 Set array address | |
| 1737 | +0111 Restore load address | |
| 1738 | +1000 64 bit big | |
| 1739 | +.TE | |
| 1740 | +.LP | |
| 1741 | +The byte, word, real and big operands are encoded as sequences | |
| 1742 | +of bytes (of appropriate length) in big-endian form, converted to native | |
| 1743 | +format before being stored in the data space. | |
| 1744 | +The `string' code takes a UTF-encoded sequence of | |
| 1745 | +.CW count | |
| 1746 | +bytes, which is converted to an array of 16-bit Unicode values stored in an | |
| 1747 | +implementation-dependent structure on | |
| 1748 | +the heap; a 4-byte pointer to the string descriptor is stored in the data space. | |
| 1749 | +The `array' code takes two 4-byte operands: the first is the index of the array's type | |
| 1750 | +descriptor in the type section; the second is the length of the array to be created. | |
| 1751 | +The result in memory is a 4-byte pointer to an implementation-dependent | |
| 1752 | +array descriptor in the heap. | |
| 1753 | +.LP | |
| 1754 | +Each item's data is stored at the address formed by adding the | |
| 1755 | +.CW offset | |
| 1756 | +in that item to a base address maintained by the loader. | |
| 1757 | +Initially that address is the base of the data space of the module instance. | |
| 1758 | +A new base for loading subsequent items can be set or restored by | |
| 1759 | +the following operations, used to initialize arrays. | |
| 1760 | +The `set array index' item must appear immediately following an `array' | |
| 1761 | +item. | |
| 1762 | +Its operand is a 4-byte big-endian integer that gives an index into that | |
| 1763 | +array, at which address subsequent data should be loaded; the | |
| 1764 | +previous load address is stacked internally. | |
| 1765 | +Subsequent data will be loaded at offsets from the new base address. | |
| 1766 | +The `restore load address' item has no operands; it pops a load address | |
| 1767 | +from the internal address stack and makes that the new | |
| 1768 | +base address. | |
| 1769 | +.SH | |
| 1770 | +The Module Name | |
| 1771 | +.LP | |
| 1772 | +The module name immediately follows the data section. | |
| 1773 | +It contains the name of the implementation module, in UTF encoding, | |
| 1774 | +terminated by a zero byte. | |
| 1775 | +.SH | |
| 1776 | +The Link Section | |
| 1777 | +.LP | |
| 1778 | +The link section contains an array of external linkage items: | |
| 1779 | +the list of functions exported by this module. | |
| 1780 | +Each item describes one exported function in the following form: | |
| 1781 | +.P1 | |
| 1782 | +Linkage_item | |
| 1783 | +{ | |
| 1784 | + OP: pc; | |
| 1785 | + OP: desc_number; | |
| 1786 | + W: sig; | |
| 1787 | + array[] of byte: name; | |
| 1788 | +}; | |
| 1789 | +.P2 | |
| 1790 | +The | |
| 1791 | +.CW pc | |
| 1792 | +is the instruction number of the function's entry point. | |
| 1793 | +The | |
| 1794 | +.CW desc_number | |
| 1795 | +is the index, in the type section, of the type descriptor for the function's stack frame. | |
| 1796 | +The | |
| 1797 | +.CW sig | |
| 1798 | +word is a 32-bit hash of the function's type signature. | |
| 1799 | +Finally, | |
| 1800 | +the name of the function is stored as a variable length array of bytes | |
| 1801 | +in UTF-8 encoding, | |
| 1802 | +with the end of the array marked by a zero byte. | |
| 1803 | +The names of member functions of an exported adt are qualified | |
| 1804 | +by the name of the adt. | |
| 1805 | +The next linkage item, if any, follows immediately. | |
| 1806 | +.NH 1 | |
| 1807 | +Symbol Table File Format | |
| 1808 | +.LP | |
| 1809 | +The object file format does not include type information for debuggers. | |
| 1810 | +The Limbo compiler can optionally produce a separate symbol table file. | |
| 1811 | +Its format is defined in the entry | |
| 1812 | +.I sbl (6) | |
| 1813 | +of [1]. | |
| 1814 | +.NH 1 | |
| 1815 | +References | |
| 1816 | +.IP 1. | |
| 1817 | +.I "Inferno Programmer's Manual" | |
| 1818 | +(Third Edition), | |
| 1819 | +Volume 1 (`the manual'), | |
| 1820 | +Vita Nuova Holdings Limited, June 2000. | |
| 1821 | +.IP 2. | |
| 1822 | +P Winterbottom and R Pike, | |
| 1823 | +``The Design of the Inferno Virtual Machine'', | |
| 1824 | +reprinted in this volume. | |
Binary file not shown.
| @@ -0,0 +1,389 @@ | ||
| 1 | +.TL | |
| 2 | +Navigating Large XML Documents on Small Devices | |
| 3 | +.AU | |
| 4 | +Roger Peppe | |
| 5 | +.AI | |
| 6 | +Vita Nuova | |
| 7 | +.br | |
| 8 | +April 2002 | |
| 9 | +.AB | |
| 10 | +Browsing eBooks on platforms with limited memory presents an | |
| 11 | +interesting problem: how can memory usage be bounded despite | |
| 12 | +the need to view documents that may be much larger than the | |
| 13 | +available memory. A simple interface to an XML parser enables | |
| 14 | +this whilst retaining much of the ease of access afforded | |
| 15 | +by XML parsers that read all of a document into memory at once. | |
| 16 | +.AE | |
| 17 | +.SH | |
| 18 | +Introduction | |
| 19 | +.LP | |
| 20 | +The Open Ebook Publication Structure was devised by the Open Ebook Forum | |
| 21 | +in order to ``provide a specification for representing the content of electronic | |
| 22 | +books''. It is based on many existing standards, notably XML and HTML. | |
| 23 | +An Open eBook publication consists of a set of documents bound together | |
| 24 | +with an Open eBook package file which enumerates all the documents, | |
| 25 | +pictures and other items that make up the book | |
| 26 | +.LP | |
| 27 | +The underlying document format is essentially HTML compatible, | |
| 28 | +which is where the first problem arises: HTML was not designed to | |
| 29 | +make it easy to view partial sections of a document. Conventionally | |
| 30 | +an entire HTML document is read in at once and rendered onto | |
| 31 | +the device. When viewing an eBook on a limited-memory device, | |
| 32 | +however, this may not be possible; books tend to be fairly large. | |
| 33 | +For such a device, the ideal format would keep the book itself | |
| 34 | +in non-volatile storage (e.g. flash or disk) and make it possible | |
| 35 | +for reader to seek to an arbitrary position in the book and render | |
| 36 | +what it finds there. | |
| 37 | +.LP | |
| 38 | +This is not possible in an HTML or XML document, as the | |
| 39 | +arbitrarily nested nature of the format means that every | |
| 40 | +position in the document has some unknown surrounding context, | |
| 41 | +which cannot be discovered without reading sequentially through | |
| 42 | +the document from the beginning. | |
| 43 | +.SH | |
| 44 | +SAX and DOM | |
| 45 | +.LP | |
| 46 | +There are two conventional programming interfaces to an XML | |
| 47 | +parser. A SAX parser provides a stream of XML entities, leaving | |
| 48 | +it up to the application to maintain the context. It is not possible | |
| 49 | +to rewind the stream, except, perhaps, to the beginning. | |
| 50 | +Using a SAX parser is | |
| 51 | +fairly straightforward, but awkward: the stream-like nature | |
| 52 | +of the interface does not map well to the tree-like structure | |
| 53 | +that is XML. A DOM parser reads a whole document into an internal | |
| 54 | +data structure representation, so a program can treat it exactly | |
| 55 | +as a tree. This also enables a program to access parts of the | |
| 56 | +document in an arbitrary order. | |
| 57 | +The DOM approach is all very well for small documents, but for large | |
| 58 | +documents the memory usage can rapidly grow to exceed | |
| 59 | +the available memory capacity. For eBook documents, this is unacceptable. | |
| 60 | +.SH | |
| 61 | +A different approach | |
| 62 | +.LP | |
| 63 | +The XML parser used in the eBook browser is akin to a SAX parser, | |
| 64 | +in that only a little of the XML structure is held in memory at one time. | |
| 65 | +The first significant difference is that the XML entities returned are | |
| 66 | +taken from one level of the tree - if the program does not wish to | |
| 67 | +see the contents of a particular XML tag, it is trivial to skip over. | |
| 68 | +The second significant difference is that random access is possible. | |
| 69 | +This possibility comes from the observation that if we have visited | |
| 70 | +a part of the document we can record the context that we found there | |
| 71 | +and restore it later if necessary. In this scheme, if we wish to return later to | |
| 72 | +a part of a document that we are currently at, we can create a ``mark'', | |
| 73 | +a token that holds the current context; at some later time we can use | |
| 74 | +that mark to return to this position. | |
| 75 | +.LP | |
| 76 | +The eBook browser uses this technique to enable random access | |
| 77 | +to the document on a page-by-page basis. Moreover a mark | |
| 78 | +can be written to external storage, thus allowing an external | |
| 79 | +``index'' into the document so it is not always necessary to | |
| 80 | +read the entire document from the start in order to jump to a particular | |
| 81 | +page in that document. | |
| 82 | +.SH | |
| 83 | +The programming interface | |
| 84 | +.LP | |
| 85 | +The interface is implemented by a module named | |
| 86 | +.CW Xml , | |
| 87 | +which provides a | |
| 88 | +.CW Parser | |
| 89 | +adt which gives access to the contents of an XML document. | |
| 90 | +Xml items are represented by an | |
| 91 | +.CW Item | |
| 92 | +pick adt with one branch of the pick corresponding to each | |
| 93 | +type of item that might be encountered. | |
| 94 | +.LP | |
| 95 | +The interface to the parser looks like this: | |
| 96 | +.P1 | |
| 97 | +open: fn(f: string, warning: chan of (Locator, string)): (ref Parser, string); | |
| 98 | +Parser: adt { | |
| 99 | + next: fn(p: self ref Parser): ref Item; | |
| 100 | + down: fn(p: self ref Parser); | |
| 101 | + up: fn(p: self ref Parser); | |
| 102 | + mark: fn(p: self ref Parser): ref Mark; | |
| 103 | + atmark: fn(p: self ref Parser, m: ref Mark): int; | |
| 104 | + goto: fn(p: self ref Parser, m: ref Mark); | |
| 105 | + str2mark: fn(p: self ref Parser, s: string): ref Mark; | |
| 106 | +}; | |
| 107 | +.P2 | |
| 108 | +To start parsing an XML document, it must first be | |
| 109 | +.CW open ed; | |
| 110 | +.CW warning | |
| 111 | +is a channel on which non-fatal error messages will be sent | |
| 112 | +if they are encountered during the parsing of the document. | |
| 113 | +It can be nil, in which case warnings are ignored. | |
| 114 | +If the document is opened successfully, a new | |
| 115 | +.CW Parser | |
| 116 | +adt, say | |
| 117 | +.I p , | |
| 118 | +is returned. | |
| 119 | +Calling | |
| 120 | +.CW \fIp\fP.next | |
| 121 | +returns the next XML item at the current level of the tree. If there | |
| 122 | +are no more items in the current branch at the current level, it | |
| 123 | +returns | |
| 124 | +.CW nil . | |
| 125 | +When a | |
| 126 | +.CW Tag | |
| 127 | +item is returned, | |
| 128 | +.CW \fIp\fP.down | |
| 129 | +can be used to descend ``into'' that tag; subsequent calls of | |
| 130 | +.CW \fIp\fP.next | |
| 131 | +will return XML items contained within the tag, | |
| 132 | +and | |
| 133 | +.CW \fIp\fP.up | |
| 134 | +returns to the previous level. | |
| 135 | +.LP | |
| 136 | +An | |
| 137 | +.CW Item | |
| 138 | +is a pick adt: | |
| 139 | +.P1 | |
| 140 | +Item: adt { | |
| 141 | + fileoffset: int; | |
| 142 | + pick { | |
| 143 | + Tag => | |
| 144 | + name: string; | |
| 145 | + attrs: Attributes; | |
| 146 | + Text => | |
| 147 | + ch: string; | |
| 148 | + ws1, ws2: int; | |
| 149 | + Process => | |
| 150 | + target: string; | |
| 151 | + data: string; | |
| 152 | + Doctype => | |
| 153 | + name: string; | |
| 154 | + public: int; | |
| 155 | + params: list of string; | |
| 156 | + Stylesheet => | |
| 157 | + attrs: Attributes; | |
| 158 | + Error => | |
| 159 | + loc: Locator; | |
| 160 | + msg: string; | |
| 161 | + } | |
| 162 | +}; | |
| 163 | +.P2 | |
| 164 | +.CW Item.Tag | |
| 165 | +represents a XML tag, empty or not. The XML | |
| 166 | +fragments | |
| 167 | +.CW "<tag></tag>" '' `` | |
| 168 | +and | |
| 169 | +.CW "<tag />" '' `` | |
| 170 | +look identical from the point of view of this interface. | |
| 171 | +A | |
| 172 | +.CW Text | |
| 173 | +item holds text found in between tags, with adjacent whitespaces merged | |
| 174 | +and whitespace at the beginning and end of the text elided. | |
| 175 | +.CW Ws1 | |
| 176 | +and | |
| 177 | +.CW ws2 | |
| 178 | +are non-zero if there was originally whitespace at the beginning | |
| 179 | +or end of the text respectively. | |
| 180 | +.CW Process | |
| 181 | +represents an XML processing request, as found between | |
| 182 | +.CW "<?....?>" '' `` | |
| 183 | +delimiters. | |
| 184 | +.CW Doctype | |
| 185 | +and | |
| 186 | +.CW Stylesheet | |
| 187 | +are items found in an XML document's prolog, the | |
| 188 | +former representing a | |
| 189 | +.CW "<!DOCTYPE...>" '' `` | |
| 190 | +document type declaration, and the latter an XML | |
| 191 | +stylesheet processing request. | |
| 192 | +.LP | |
| 193 | +When most applications are processing documents, they | |
| 194 | +will wish to ignore all items other than | |
| 195 | +.CW Tag | |
| 196 | +and | |
| 197 | +.CW Text . | |
| 198 | +To this end, it is conventional to define a ``front-end'' function | |
| 199 | +to return desired items, discard others, and take an appropriate | |
| 200 | +action when an error is encountered. Here's an example: | |
| 201 | +.P1 | |
| 202 | +nextitem(p: ref Parser): ref Item | |
| 203 | +{ | |
| 204 | + while ((gi := p.next()) != nil) { | |
| 205 | + pick i := gi { | |
| 206 | + Error => | |
| 207 | + sys->print("error at %s:%d: %s\n", | |
| 208 | + i.loc.systemid, i.loc.line, i.msg); | |
| 209 | + exit; | |
| 210 | + Process => | |
| 211 | + ; # ignore | |
| 212 | + Stylesheet => | |
| 213 | + ; # ignore | |
| 214 | + Doctype => | |
| 215 | + ; # ignore | |
| 216 | + * => | |
| 217 | + return gi; | |
| 218 | + } | |
| 219 | + } | |
| 220 | + return nil; | |
| 221 | +} | |
| 222 | +.P2 | |
| 223 | +When | |
| 224 | +.CW nextitem | |
| 225 | +encounters an error, it exits; it might instead handle the | |
| 226 | +error another way, say by raising an exception to be caught at the | |
| 227 | +outermost level of the parsing code. | |
| 228 | +.SH | |
| 229 | +A small example | |
| 230 | +.LP | |
| 231 | +Suppose we have an XML document that contains some data that we would | |
| 232 | +like to extract, ignoring the rest of the document. For this example we will | |
| 233 | +assume that the data is held within | |
| 234 | +.CW <data> | |
| 235 | +tags, which contain zero or more | |
| 236 | +.CW <item> | |
| 237 | +tags, holding the actual data as text within them. | |
| 238 | +Tags that we do not recognize we choose to ignore. | |
| 239 | +So for example, given the following XML document: | |
| 240 | +.P1 | |
| 241 | +<metadata> | |
| 242 | + <a>hello</a> | |
| 243 | + <b>goodbye</b> | |
| 244 | +</metadata> | |
| 245 | +<data> | |
| 246 | + <item>one</item> | |
| 247 | + <item>two</item> | |
| 248 | + <item>three</item> | |
| 249 | +</data> | |
| 250 | +<data> | |
| 251 | + <item>four</item> | |
| 252 | +</data> | |
| 253 | +.P2 | |
| 254 | +we wish to extract all the data items, but ignore everything inside | |
| 255 | +the | |
| 256 | +.CW <metadata> | |
| 257 | +tag. First, let us define another little convenience function to get | |
| 258 | +the next XML tag, ignoring extraneous items: | |
| 259 | +.P1 | |
| 260 | +nexttag(p: ref Parser): ref Item.Tag | |
| 261 | +{ | |
| 262 | + while ((gi := nextitem(p)) != nil) { | |
| 263 | + pick i := gi { | |
| 264 | + Tag => | |
| 265 | + return i; | |
| 266 | + } | |
| 267 | + } | |
| 268 | + return nil; | |
| 269 | +} | |
| 270 | +.P2 | |
| 271 | +Assuming that the document has already been opened, | |
| 272 | +the following function scans through the document, looking | |
| 273 | +for top level | |
| 274 | +.CW <data> | |
| 275 | +tags, and ignoring others: | |
| 276 | +.P1 | |
| 277 | +document(p: ref Parser) | |
| 278 | +{ | |
| 279 | + while ((i := nexttag(p)) != nil) { | |
| 280 | + if (i.name == "data") { | |
| 281 | + p.down(); | |
| 282 | + data(p); | |
| 283 | + p.up(); | |
| 284 | + } | |
| 285 | + } | |
| 286 | +} | |
| 287 | +.P2 | |
| 288 | +The function to parse a | |
| 289 | +.CW <data> | |
| 290 | +tag is almost as straightforward; it scans for | |
| 291 | +.CW <item> | |
| 292 | +tags and extracts any textual data contained therein: | |
| 293 | +.P1 | |
| 294 | +data(p: ref Parser) | |
| 295 | +{ | |
| 296 | + while ((i := nexttag(p)) != nil) { | |
| 297 | + if (i.name == "item") { | |
| 298 | + p.down(); | |
| 299 | + if ((gni := p.next()) != nil) { | |
| 300 | + pick ni := gni { | |
| 301 | + Text => | |
| 302 | + sys->print("item data: %s\n", ni.ch); | |
| 303 | + } | |
| 304 | + } | |
| 305 | + p.up(); | |
| 306 | + } | |
| 307 | + } | |
| 308 | +} | |
| 309 | +.P2 | |
| 310 | +The above program is all very well and works fine, but | |
| 311 | +suppose that the document that we are parsing is very | |
| 312 | +large, with data items scattered through its length, and that | |
| 313 | +we wish to access those items in an order that is not necessarily | |
| 314 | +that in which they appear in the document. | |
| 315 | +This is quite straightforward; every time we see a | |
| 316 | +data item, we record the current position with a mark. | |
| 317 | +Assuming the global declaration: | |
| 318 | +.P1 | |
| 319 | +marks: list of ref Mark; | |
| 320 | +.P2 | |
| 321 | +the | |
| 322 | +.CW document | |
| 323 | +function might become: | |
| 324 | +.P1 | |
| 325 | +document(p: ref Parser) | |
| 326 | +{ | |
| 327 | + while ((i := nexttag(p)) != nil) { | |
| 328 | + if (i.name == "data") { | |
| 329 | + p.down(); | |
| 330 | + marks = p.mark() :: marks; | |
| 331 | + p.up(); | |
| 332 | + } | |
| 333 | + } | |
| 334 | +} | |
| 335 | +.P2 | |
| 336 | +At some later time, we can access the data items arbitrarily, | |
| 337 | +for instance: | |
| 338 | +.P1 | |
| 339 | + for (m := marks; m != nil; m = tl m) { | |
| 340 | + p.goto(hd m); | |
| 341 | + data(p); | |
| 342 | + } | |
| 343 | +.P2 | |
| 344 | +If we wish to store the data item marks in some external index | |
| 345 | +(in a file, perhaps), the | |
| 346 | +.CW Mark | |
| 347 | +adt provides a | |
| 348 | +.CW str | |
| 349 | +function which returns a string representation of the mark. | |
| 350 | +.CW Parser 's | |
| 351 | +.CW str2mark | |
| 352 | +function can later be used to recover the mark. Care must | |
| 353 | +be taken that the document it refers to has not been changed, | |
| 354 | +otherwise it is likely that the mark will be invalid. | |
| 355 | +.SH | |
| 356 | +The eBook implementation | |
| 357 | +.LP | |
| 358 | +The Open eBook reader software uses the primitives described above | |
| 359 | +to maintain display-page-based access to arbitrarily large documents | |
| 360 | +while trying to bound memory usage. | |
| 361 | +Unfortunately it is difficult to unconditionally bound memory usage, | |
| 362 | +given that any element in an XML document may be arbitrarily | |
| 363 | +large. For instance a perfectly legal document might have 100MB | |
| 364 | +of continuous text containing no tags whatsoever. The described | |
| 365 | +interface would attempt to put all this text in one single item, rapidly | |
| 366 | +running out of memory! Similar types of problems can occur when | |
| 367 | +gathering the items necessary to format a particular tag. | |
| 368 | +For instance, to format the first row of a table, it is necessary to lay out | |
| 369 | +the entire table to determine the column widths. | |
| 370 | +.LP | |
| 371 | +I chose to make the simplifying assumption that top-level items within | |
| 372 | +the document would be small enough to fit into memory. | |
| 373 | +From the point of view of the display module, the document | |
| 374 | +looks like a simple sequence of items, one after another. | |
| 375 | +One item might cover more than one page, in which case a different | |
| 376 | +part of it will be displayed on each of those pages. | |
| 377 | +.LP | |
| 378 | +One difficulty is that the displayed size of an item depends on many | |
| 379 | +factors, such as stylesheet parameters, size of installed fonts, etc. | |
| 380 | +When a document is read, the page index must have been created | |
| 381 | +from the same document with the same parameters. It is difficult in | |
| 382 | +general to enumerate all the relevant parameters; they would need | |
| 383 | +to be stored inside, or alongside the index; any change would invalidate | |
| 384 | +the index. Instead of doing this, as the document is being displayed, | |
| 385 | +the eBook display program constantly checks to see if the results | |
| 386 | +it is getting from the index match with the results it is getting | |
| 387 | +when actually laying out the document. If the results differ, the | |
| 388 | +index is remade; the discrepancy will hopefully not be noticed by | |
| 389 | +the user! | |
Binary file not shown.
| @@ -0,0 +1,8 @@ | ||
| 1 | +# mkfile rules to get fonts in Lucida Sans. | |
| 2 | +# if you don't have Lucida fonts, change this next line to | |
| 3 | +# FONTS='' | |
| 4 | +FONTS='.fp 1 R LucidaSans | |
| 5 | +.fp 2 I LucidaSansI | |
| 6 | +.fp 3 B LucidaSansB | |
| 7 | +.fp 5 CW LucidaCW | |
| 8 | +' | |
| @@ -0,0 +1,9 @@ | ||
| 1 | +# mkfile rules to get fonts in Lucida Sans. | |
| 2 | +# if you don't have Lucida fonts, change this next line to | |
| 3 | +# FONTS='' | |
| 4 | +FONTS='.fp 1 R PA | |
| 5 | +.fp 2 I PI | |
| 6 | +.fp 3 B PB | |
| 7 | +.fp 4 PX | |
| 8 | +....fp 5 L LucidaCW | |
| 9 | +' | |
Binary file not shown.
| @@ -0,0 +1,136 @@ | ||
| 1 | +.FP palatino | |
| 2 | +.TL | |
| 3 | +Installing the Vita Nuova grid software | |
| 4 | +.AU | |
| 5 | +Vita Nuova | |
| 6 | +.br | |
| 7 | +5 May 2005 | |
| 8 | +.NH 1 | |
| 9 | +Package contents | |
| 10 | +.LP | |
| 11 | +The installation CD contains software for both grid client and the server (scheduler), | |
| 12 | +in separate directories in the root directory of the CD: | |
| 13 | +.B client | |
| 14 | +and | |
| 15 | +.B server . | |
| 16 | +.NH 1 | |
| 17 | +Client software | |
| 18 | +.LP | |
| 19 | +The grid client software will be installed on Windows NT4/2000/XP machines, | |
| 20 | +in the directory (folder) | |
| 21 | +.CW C:\eVNClient . | |
| 22 | +.IP 1. | |
| 23 | +On a Windows machine with the CD loaded, | |
| 24 | +use Windows Explorer (or equivalent) to move to the directory named | |
| 25 | +.CW \eclient\einstall | |
| 26 | +on the CD. | |
| 27 | +.IP 2. | |
| 28 | +Double-click | |
| 29 | +.CW setup.exe | |
| 30 | +in that directory. | |
| 31 | +It will display a new window that prompts for a destination directory. | |
| 32 | +The directory need not exist but if it does, it should be empty. | |
| 33 | +The default should be | |
| 34 | +.CW C:\eVNClient . | |
| 35 | +You can change the name if required (eg, because | |
| 36 | +.CW C: | |
| 37 | +lacks space), but | |
| 38 | +you will then need to edit several files, as discussed below, | |
| 39 | +and make appropriate changes to the instructions below. | |
| 40 | +Hit the | |
| 41 | +.SM ENTER | |
| 42 | +key to start installation. | |
| 43 | +The program will prompt for permission to create the directory if it does not already exist. | |
| 44 | +It will then populate it with all files required by the client. | |
| 45 | +.IP 3. | |
| 46 | +Move in Explorer to the directory | |
| 47 | +.CW C:\eVNClient\egrid\eslave . | |
| 48 | +Check that the file | |
| 49 | +.CW schedaddr | |
| 50 | +contains the right address for your scheduler machine. | |
| 51 | +If you changed the drive letter, you must also change the | |
| 52 | +four | |
| 53 | +.CW .bat | |
| 54 | +files in the directory to replace the | |
| 55 | +.CW C: | |
| 56 | +drive letter by the one you used. | |
| 57 | +.IP 4. | |
| 58 | +You can now add the grid client as a Windows service by running the appropriate | |
| 59 | +.CW .bat | |
| 60 | +file on the client. | |
| 61 | +Use | |
| 62 | +.RS | |
| 63 | +.IP | |
| 64 | +\f5install_service.bat\fP | |
| 65 | +for Windows 2000 and Windows XP | |
| 66 | +.IP \fIOR\fP | |
| 67 | +\f5install_service_nt4.bat\fP | |
| 68 | +for Windows NT4 | |
| 69 | +.LP | |
| 70 | +Just double-clicking in Explorer on the chosen name should install the service. | |
| 71 | +.RE | |
| 72 | +.LP | |
| 73 | +Once installed as a service the client software will start automatically when | |
| 74 | +the client machine next boots. | |
| 75 | +You can start it manually using the Windows Services Manager in the usual way. | |
| 76 | +There are two | |
| 77 | +.CW .bat | |
| 78 | +files to remove the service (when desired): \f5remove_service.bat\fP | |
| 79 | +for 2000/XP and \f5remove_service_nt4.bat\fP for NT4. | |
| 80 | +.LP | |
| 81 | +The manual page | |
| 82 | +.I scheduler-intro (1) | |
| 83 | +in the PDF file | |
| 84 | +.CW \escheduler.pdf | |
| 85 | +on the CD gives more details on running and configuring the client software. | |
| 86 | +The manual page | |
| 87 | +.I scheduler-monitor (1) | |
| 88 | +in the same PDF file describes the use of the Client Monitor software. | |
| 89 | +.LP | |
| 90 | +On Windows machines you can remove the directory | |
| 91 | +.CW C:\eVNClient\eLinux | |
| 92 | +to reduce the space required on Windows clients. | |
| 93 | +.NH 1 | |
| 94 | +Server software | |
| 95 | +.LP | |
| 96 | +The grid server software will be installed on Linux (Redhat 8 or 9), in the directory | |
| 97 | +.CW /grid/inferno , | |
| 98 | +which should either not exist or be empty. | |
| 99 | +.LP | |
| 100 | +Linux will usually mount the CD at | |
| 101 | +.CW /mnt/cdrom . | |
| 102 | +.IP 1. | |
| 103 | +In a shell (`New Terminal') window, type the following command: | |
| 104 | +.P1 | |
| 105 | +sh /mnt/cdrom/server/install/Linux-grid-386.sh | |
| 106 | +.P2 | |
| 107 | +Assuming it has permission to do so, it will populate | |
| 108 | +.CW /grid/inferno | |
| 109 | +with the Inferno distribution, including the grid scheduler components. | |
| 110 | +.IP 2. | |
| 111 | +The file | |
| 112 | +.CW /mnt/cdrom/server/install/gridsched.sh | |
| 113 | +contains a Bourne shell script that can be copied to an appropriate | |
| 114 | +place on your system, or used as the basis for one of your own, | |
| 115 | +to simplify starting the scheduler. | |
| 116 | +In particular it sets the right bin directory in | |
| 117 | +.CW PATH | |
| 118 | +to find Inferno's | |
| 119 | +.I emu , | |
| 120 | +and starts | |
| 121 | +.I emu | |
| 122 | +with the right parameters to find the | |
| 123 | +.CW /grid/inferno | |
| 124 | +directory and start the scheduler in the right environment. | |
| 125 | +.LP | |
| 126 | +Now check that | |
| 127 | +.CW /grid/inferno/grid/master/config | |
| 128 | +contains the right network address for your scheduler. | |
| 129 | +The manual pages | |
| 130 | +.I scheduler-intro (1) | |
| 131 | +and | |
| 132 | +.I scheduler (1) | |
| 133 | +in | |
| 134 | +.CW scheduler.pdf | |
| 135 | +on the CD give more details on invoking the scheduler in | |
| 136 | +different ways. | |
Binary file not shown.
| @@ -0,0 +1,125 @@ | ||
| 1 | +.TL | |
| 2 | +The design of the Inferno virtual machine | |
| 3 | +.AU | |
| 4 | +.I "Phil Winterbottom" | |
| 5 | +.I "Rob Pike" | |
| 6 | +.AI | |
| 7 | +.I "Bell Labs, Lucent Technologies" | |
| 8 | +.FS | |
| 9 | +Originally appeared in | |
| 10 | +.I "IEEE Compcon 97 Proceedings" , | |
| 11 | +1997. | |
| 12 | +.FE | |
| 13 | +.SP .22i exactly | |
| 14 | +.AB | |
| 15 | +Virtual machines are an important component of modern portable environments such as Inferno and Java because they provide an architecture-independent representation of executable code. Their performance is critical to the success of such environments, but they are difficult to design well because they are subject to conflicting goals. On the one hand, they offer a way to hide the differences between instruction architectures; on the other, they must be implemented efficiently on a variety of underlying machines. A comparison of the engineering and evolution of the Inferno and Java virtual machines provides insight into the tradeoffs in their design and implementation. We argue that the design of virtual machines should be rooted in the nature of modern processors, not language interpreters, with an eye towards on-the-fly compilation rather than interpretation or special-purpose silicon. | |
| 16 | +.AE | |
| 17 | +.SH | |
| 18 | +Dis, the Inferno Virtual Machine | |
| 19 | +.LP | |
| 20 | +In early 1995, we set out to apply the ideas of the Plan 9 operating system [1] to a wider range of devices and networks. The resulting system, Inferno [2], is a small operating system and execution environment that supports application portability across a wide variety of processors and operating systems. Unaware of the contemporary work to establish Java [3] from the technology of the Oak project, we independently concluded that a virtual machine (VM) was a necessary component of such a system [4]. Because of improvements in processor speed and the feasibility of on-the-fly compilers, a VM can execute quickly enough to be economically viable. | |
| 21 | +.LP | |
| 22 | +The Inferno virtual machine, called Dis, has several unusual aspects to its design: the instruction set, the module system, and the garbage collector. | |
| 23 | +.LP | |
| 24 | +The Dis instruction set provides a close match to the architecture of existing processors. Instructions are of the form | |
| 25 | +.DS | |
| 26 | +.ft I | |
| 27 | +OP src1, src2, dst | |
| 28 | +.ft P | |
| 29 | +.DE | |
| 30 | +The | |
| 31 | +.I "src1" | |
| 32 | +and | |
| 33 | +.I "dst" | |
| 34 | +operands specify general addresses or arbitrary-sized constants, while the | |
| 35 | +.I "src2" | |
| 36 | +operand is restricted to smaller constants and stack offsets to reduce code space. Each operand specifies an address either in the stack frame of the executing procedure or in the global data of its module. | |
| 37 | +.LP | |
| 38 | +The types of operands are set by the instructions. Basic types are | |
| 39 | +.CW "word" | |
| 40 | +(32-bit signed), | |
| 41 | +.CW "big" | |
| 42 | +(64-bit signed), | |
| 43 | +.CW "byte" | |
| 44 | +(8-bit unsigned), | |
| 45 | +.CW "real" | |
| 46 | +(64-bit IEEE floating point), and pointer (implementation-dependent). The instruction set follows the example of CISC processors, providing three-operand memory-to-memory operations for arithmetic, data motion, and so on. It also has instructions to allocate memory, to load modules, and to create, synchronize, and communicate between processes. | |
| 47 | +.LP | |
| 48 | +A module is the unit of dynamically loaded code and data. Modules are loaded by a VM instruction that returns a pointer to a method table for the module. That pointer is managed by the VM's garbage collector, so code and data for the module are garbage collected like any other memory. Type safety is preserved by checking method types at module load time using an MD5 signature of the type. | |
| 49 | +.LP | |
| 50 | +Memory management is intimately tied to the instruction set of the VM. Dis uses a hybrid garbage collection scheme: most garbage is collected by simple reference counting, while a real-time coloring collector gathers cyclic data. Because reference counting is an exact rather than conservative form of garbage collection, the type of all data items must be known to the VM run-time system. For this reason, the language-to-VM compiler generates a type descriptor for all compound types. This descriptor reports the location of all pointers within the type, allowing the VM to track references as items are copied. | |
| 51 | +.SH | |
| 52 | +Garbage collection | |
| 53 | +.LP | |
| 54 | +Memory dominates the cost of small systems, so the VM should be designed to keep memory usage as small as possible. Through reference-counted garbage collection, Dis reclaims memory the moment it becomes unused. Reference counting also eliminates the need for a large arena as required for efficient mark-and-sweep collection. Both these results reduce the memory requirements of the VM and its applications. | |
| 55 | +.LP | |
| 56 | +Compare this to the Java VM, whose instruction set makes it difficult to track references as objects are copied. This biases against reference counting, so JVM implementations choose lazier techniques such as mark-and-sweep, inducing a larger arena and delayed collection, both of which increase the memory use and therefore the cost of the overall system. | |
| 57 | +.SH | |
| 58 | +Issues in compiling | |
| 59 | +.LP | |
| 60 | +It is easy to interpret the individual instructions of a stack-based virtual machine (SM) such as the Java virtual machine (JVM), because most operands are implicit. However, a high-level language implementation of the interpreter generates more memory traffic than the equivalent set of instructions in a memory transfer machine (MM) such as Dis. Consider the code to execute | |
| 61 | +.P1 | |
| 62 | +c = a + b; | |
| 63 | +.P2 | |
| 64 | +An SM would execute this by a code burst such as this, which we have annotated with its memory traffic using | |
| 65 | +.I L | |
| 66 | +for load and | |
| 67 | +.I S | |
| 68 | +for store: | |
| 69 | +.P1 | |
| 70 | +push a # \fILS\fP | |
| 71 | +push b # \fILS\fP | |
| 72 | +add # \fILLS\fP | |
| 73 | +store c # \fILS\fP | |
| 74 | +.P2 | |
| 75 | +The corresponding MM code burst would be the plain three-operand instruction | |
| 76 | +.P1 | |
| 77 | +add a,b,c # \fILLS\fP | |
| 78 | +.P2 | |
| 79 | +When interpreting, the extra memory traffic of the SM is masked by the time saved by not decoding any operand fields. The operand fields are implicit in the SM instructions, while the MM they are explicit: three operand fields must be decoded in every instruction, even those without operands. | |
| 80 | +.LP | |
| 81 | +When compiling, the tradeoffs are different. Clearly, either design can produce the same native instructions from its just-in-time compiler (JIT), but in the SM case most of the work must be done in the JIT, whereas in the MM design the front end has done most of the work and the JIT can be substantially simpler and faster. | |
| 82 | +.LP | |
| 83 | +A JIT for an SM is forced to do most of the work of register allocation in the JIT itself. Because the types of stack cells change as the program executes, the JIT must track their types as it compiles. In an MM, however, the architecture maps well to native instructions. This produces a continuum of register allocation strategies from none, to simple mapping of known cells to registers, to flow-based register allocation. Most of the work of any of these strategies can be done in the language-to-VM compiler. It can generate code for an infinite-register machine, and the JIT can then allocate as many as are available in the native architecture. Again, this distribution of work keeps the JIT simple. | |
| 84 | +.SH | |
| 85 | +Processors | |
| 86 | +.LP | |
| 87 | +The same issues that face the JIT writer also face the designer of special-purpose processors to support a VM. Register allocation in the JIT is analogous to register relabeling in silicon, and an SM design adds unnecessary complexity to an already difficult problem. One might argue that a stack-based processor design would mitigate the difficulties, but our experience with the implementation of a stack machine in the AT&T Crisp microprocessor [5] leads us to believe that stack architectures are inherently slower than register-based machines. Their design lengthens the critical path by replacing simple registers with a complex stack cache mechanism. | |
| 88 | +.LP | |
| 89 | +In other words, it is a better idea to match the design of the VM to the processor than the other way around. | |
| 90 | +.LP | |
| 91 | +Dis fits this criterion better, but we do not plan to implement Dis in silicon. The idea of a VM is to be architecture-independent; offering a special processor to run it negates the original goal by favoring one instruction set. Ignoring that for the moment, though, there could still be two reasons to consider designing silicon for Dis: performance and cost. | |
| 92 | +.LP | |
| 93 | +On performance, history shows that language-specific CPUs are not competitive. The investment in the special design takes energy away from the systems issues that ultimately dominate performance. Performance gains realized through language-specific support tend to be offset by parallel improvements in general-purpose processors during the life cycle of the CPU. | |
| 94 | +.LP | |
| 95 | +Dis compiles quickly into native code that runs only 30-50% slower than native C. At the current rate of processor improvement, that is only a few months of processor design time. It is wiser to focus on improving execution on commodity, general purpose processors than on inventing a new architecture. | |
| 96 | +.LP | |
| 97 | +The issue of cost is more subtle. Dis is close enough to familiar architectures that a special chip with high integration of systems facilities could be cost-effective on small platforms. The real reason for that, though, is that the memory management design of the virtual machine makes it easy to implement Dis in small memory. By contrast, whatever cost gains an integrated Java processor might realize will likely be lost in the extra memory required by its conservative garbage collection scheme [6]. | |
| 98 | +.SH | |
| 99 | +References | |
| 100 | +.nr PS -1 | |
| 101 | +.nr VS -1 | |
| 102 | +.IP 1. | |
| 103 | +R. Pike, D. Presotto, S. Dorward, B. Flandrena, K. Thompson, H. Trickey, and P. Winterbottom. ``Plan 9 from Bell Labs'', | |
| 104 | +.I "J. Computing Systems" | |
| 105 | +8:3, Summer 1995, pp. 221-254. | |
| 106 | +.IP 2. | |
| 107 | +Dorward, S., et al., ``Inferno'', | |
| 108 | +.I "IEEE Compcon 97 Proceedings" , | |
| 109 | +1997. | |
| 110 | +.IP 3. | |
| 111 | +Arnold, K. and Gosling, J., | |
| 112 | +.I "The Java Programming Language" , | |
| 113 | +Addison-Wesley, 1996. | |
| 114 | +.IP 4. | |
| 115 | +Nori, K. V., Ammann, U., Nabeli, H. H., and Jacobi, Ch., ``Pascal P Implementation notes'', in Barron, D. W. (ed.), | |
| 116 | +.I "Pascal\-The Language and its Implementation" , | |
| 117 | +Wiley, 1981, pp. 125-170. | |
| 118 | +.IP 5. | |
| 119 | +Ditzel, D. R. and McLellan, R., ``Register Allocation for Free: The C Machine Stack Cache'', | |
| 120 | +.I "Proc. of Symp. on Arch. Supp. for Prog. Lang. and Op. Sys." , | |
| 121 | +March, 1982, pp. 48-56. | |
| 122 | +.IP 6. | |
| 123 | +Case, B., ``Implementing the Java Virtual Machine'', | |
| 124 | +.I "Microprocessor Report" , | |
| 125 | +March 25, 1996, pp. 12-17. | |
Binary file not shown.
| @@ -0,0 +1,1423 @@ | ||
| 1 | +.de EX | |
| 2 | +.nr x \\$1v | |
| 3 | +\\!h0c n \\nx 0 | |
| 4 | +.. | |
| 5 | +.de FG \" start figure caption: .FG filename.ps verticalsize | |
| 6 | +.KF | |
| 7 | +.BP \\$1 \\$2 | |
| 8 | +.sp .5v | |
| 9 | +.EX \\$2v | |
| 10 | +.ps -1 | |
| 11 | +.vs -1 | |
| 12 | +.. | |
| 13 | +.de fg \" end figure caption (yes, it is clumsy) | |
| 14 | +.ps | |
| 15 | +.vs | |
| 16 | +.br | |
| 17 | +\l'1i' | |
| 18 | +.KE | |
| 19 | +.. | |
| 20 | +\" step numbers | |
| 21 | +.nr ,s 0 1 | |
| 22 | +.af ,s a | |
| 23 | +.am NH | |
| 24 | +.nr ,s 0 1 | |
| 25 | +.. | |
| 26 | +.de Sn \" .Sn "step" | |
| 27 | +•\ Step \\n(H1\\n+(,s: \\$1 | |
| 28 | +.. | |
| 29 | +.de Ss | |
| 30 | +.P1 | |
| 31 | +.B | |
| 32 | +.Sn "\\$1" | |
| 33 | +.P2 | |
| 34 | +.. | |
| 35 | +.TL | |
| 36 | +Installing the Inferno Software | |
| 37 | +.AU | |
| 38 | +Vita Nuova | |
| 39 | +.br | |
| 40 | +support@vitanuova.com | |
| 41 | +.br | |
| 42 | +12 June 2003 | |
| 43 | +.SP 4 | |
| 44 | +.LP | |
| 45 | +Inferno can run as either a native operating system, in the usual way, or as a | |
| 46 | +.I hosted | |
| 47 | +virtual operating system, | |
| 48 | +running as an application on another operating system. | |
| 49 | +This paper explains how to install Inferno from the distribution media | |
| 50 | +to a hosted environment and how to configure the system for | |
| 51 | +basic networking. | |
| 52 | +.LP | |
| 53 | +Inferno can run as a hosted virtual operating system on top of | |
| 54 | +Plan 9, Unix or Windows. | |
| 55 | +In this paper, the term | |
| 56 | +.I Unix | |
| 57 | +is used to cover all supported variants, currently FreeBSD, Linux, HP/UX, Irix and Solaris, | |
| 58 | +and the term | |
| 59 | +.I Windows | |
| 60 | +covers Microsoft Windows (98, Me, Nt, 2000, and XP). | |
| 61 | +(Windows 98 might first require installation of the Unicode layer update from Microsoft.) | |
| 62 | +.NH | |
| 63 | +Preparation | |
| 64 | +.LP | |
| 65 | +You should ensure at least 150 Mbytes of free space on the filesystem. | |
| 66 | +The installation program will copy files from the distribution CD to a | |
| 67 | +directory on the filesystem called the | |
| 68 | +.I inferno_root | |
| 69 | +directory. | |
| 70 | +You can choose the location of this directory. | |
| 71 | +If you are installing to a multiuser filesystem outside your control a subdirectory of your home | |
| 72 | +directory might be most sensible. If you plan to share the Inferno | |
| 73 | +system with other users then common choices for | |
| 74 | +.I inferno_root | |
| 75 | +are | |
| 76 | +.CW /usr/inferno | |
| 77 | +on Unix and Plan 9 systems, and | |
| 78 | +.CW c:\einferno | |
| 79 | +on Windows systems. | |
| 80 | +Where these appear in examples in this paper you should substitute | |
| 81 | +your own | |
| 82 | +.I inferno_root | |
| 83 | +directory. | |
| 84 | +.Ss "Choose the \fIinferno_root\fP directory." | |
| 85 | +Ensure that the user who will run the installation program has | |
| 86 | +appropriate filesystem permissions to create the | |
| 87 | +.I inferno_root | |
| 88 | +directory and | |
| 89 | +files and subdirectories beneath it. | |
| 90 | +.NH | |
| 91 | +Copying Files | |
| 92 | +.LP | |
| 93 | +On all platforms the files will be owned by the user doing the installation, | |
| 94 | +except for installation onto a FAT file system (eg, on Windows), where the files | |
| 95 | +appear to be owned by | |
| 96 | +.CW Everyone | |
| 97 | +because FAT does not record ownership. | |
| 98 | +.Ss "Insert the distribution CD into the CD drive." | |
| 99 | +On Unix and Plan 9, | |
| 100 | +mount the CD to a suitable location on the filesystem, call this location | |
| 101 | +.I cd_path . | |
| 102 | +On Windows, note the drive letter of the CD, call this drive letter | |
| 103 | +.I cd_drive . | |
| 104 | +The files will be copied by an Inferno hosted installation program which runs | |
| 105 | +directly from the CD. | |
| 106 | +The directory | |
| 107 | +.CW /install | |
| 108 | +on the CD contains an installation program for each supported platform \- a shell | |
| 109 | +script for Unix and Plan 9 and an executable for Windows. | |
| 110 | +The Plan 9 install script is called | |
| 111 | +.CW Plan9.rc | |
| 112 | +and determines the CPU type from the environment variable | |
| 113 | +.CW cputype . | |
| 114 | +The Unix install scripts all have names of the form | |
| 115 | +.CW \fIhost_os\fP-\fIhost_arch\fP.sh | |
| 116 | +where | |
| 117 | +.I host_os | |
| 118 | +will be one of: | |
| 119 | +.CW FreeBSD , | |
| 120 | +.CW Linux , | |
| 121 | +or | |
| 122 | +.CW Solaris | |
| 123 | +and | |
| 124 | +.I host_arch | |
| 125 | +will be one of: | |
| 126 | +.CW 386 , | |
| 127 | +.CW mips , | |
| 128 | +.CW power | |
| 129 | +or | |
| 130 | +.CW sparc . | |
| 131 | +Most platforms offer just the one obvious combination. | |
| 132 | +The Windows installation program is called | |
| 133 | +.CW setup.exe ; | |
| 134 | +it is used on all varieties of Windows. | |
| 135 | +The next step describes how to begin the installation by running the program | |
| 136 | +that corresponds to your host system. | |
| 137 | +.Ss "Run the installation script." | |
| 138 | +The installation program will copy files from the CD to the filesystem. | |
| 139 | +The Windows installation program will also create registry entries and add | |
| 140 | +an Inferno item to the Windows | |
| 141 | +.I start | |
| 142 | +menu. | |
| 143 | +On Plan 9, run | |
| 144 | +.P1 | |
| 145 | +rc \fIcd_path\fP/install/Plan9.rc \fIinferno_root\fP | |
| 146 | +.P2 | |
| 147 | +Where | |
| 148 | +.I inferno_root | |
| 149 | +is the path to the chosen Inferno root directory. The CPU architecture | |
| 150 | +will be inferred from the environment variable | |
| 151 | +.CW cputype . | |
| 152 | +On Unix, run | |
| 153 | +.P1 | |
| 154 | +sh \fIcd_path\fP/install/\fIhost-os\fP-\fIhost_arch\fP.sh \fIinferno_root\fP | |
| 155 | +.P2 | |
| 156 | +Where | |
| 157 | +.I host_os | |
| 158 | +is the Unix variant name | |
| 159 | +.CW FreeBSD , ( | |
| 160 | +.CW Irix , | |
| 161 | +.CW Linux | |
| 162 | +or | |
| 163 | +.CW Solaris ). | |
| 164 | +.I host_arch | |
| 165 | +is the CPU type (eg, | |
| 166 | +.CW 386 ), | |
| 167 | +and | |
| 168 | +.I inferno_root | |
| 169 | +is the path to the chosen Inferno directory. | |
| 170 | +On Windows, run | |
| 171 | +.P1 | |
| 172 | +\fIcd_drive\f(CW:\einstall\esetup.exe | |
| 173 | +.P2 | |
| 174 | +The Windows installation program will ask you to choose the location of the installation | |
| 175 | +directory on the hard disk. | |
| 176 | +.LP | |
| 177 | +On all platforms, a copy of Inferno | |
| 178 | +on the CD will install from various installation packages on the CD to the | |
| 179 | +.I inferno_root | |
| 180 | +subtree on the filesystem. | |
| 181 | +On any platform it installs support for all. | |
| 182 | +.LP | |
| 183 | +Inferno is now installed, but it needs to be configured | |
| 184 | +for your site. | |
| 185 | +The process acts as a quick tour of parts of the system. | |
| 186 | +The main tasks are to add local parameters to the network data base, | |
| 187 | +and to set up the authentication system. | |
| 188 | +If you are going to run Inferno standalone, for instance to experiment with Limbo | |
| 189 | +and the file serving interface, | |
| 190 | +most of what follows can be deferred indefinitely. | |
| 191 | +It is still worthwhile skimming through it, because the first few sections tell how | |
| 192 | +to start up Inferno with correct parameters (eg, root directory and graphics resolution). | |
| 193 | +(A configuration program that runs under the window system would be more convenient, | |
| 194 | +and fairly easy to do, but that has not yet been done.) | |
| 195 | +.NH | |
| 196 | +Running Inferno | |
| 197 | +.LP | |
| 198 | +Inferno host executables are all kept in a single directory corresponding | |
| 199 | +to the combination of host operating system and CPU architecture \- the Inferno | |
| 200 | +.CW bin | |
| 201 | +directory. | |
| 202 | +.P1 | |
| 203 | +\fIinferno_root\fP/\fIhost_os\fP/\fIhost_arch\fP/bin | |
| 204 | +.P2 | |
| 205 | +(On Windows the path might need | |
| 206 | +.CW \e | |
| 207 | +not | |
| 208 | +.CW / | |
| 209 | +of course.) | |
| 210 | +That directory can be added to the search path of the host system's command interpreter, | |
| 211 | +and that process will be described first, although as discussed later one can use a script | |
| 212 | +instead and that is sometimes more convenient. | |
| 213 | +(Of course, the script will still need to refer to that directory.) | |
| 214 | +.LP | |
| 215 | +.I "Plan 9:\ \ " | |
| 216 | +Plan 9 users should add a line to their | |
| 217 | +.CW lib/profile | |
| 218 | +file that binds this directory after their | |
| 219 | +.CW /bin | |
| 220 | +directory. | |
| 221 | +.P1 | |
| 222 | +bind -a /usr/inferno/Plan9/$cputype/bin /bin | |
| 223 | +.P2 | |
| 224 | +The bind is done after the existing | |
| 225 | +.I bin | |
| 226 | +directory to avoid hiding the existing Plan 9 compilers. | |
| 227 | +If, at a later stage, you build either the hosted or native Inferno kernels for ARM or StrongARM | |
| 228 | +you should ensure that the Inferno compilers are used rather than | |
| 229 | +the Plan 9 compilers, since they differ in the implementation of | |
| 230 | +floating-point instructions (the Plan 9 ARM suite uses a byte order that is more plausible | |
| 231 | +than the order ARM dictates but therefore wrong). | |
| 232 | +That difference is likely to be resolved at some point but it has not yet been done. | |
| 233 | +.LP | |
| 234 | +.I "Windows:\ \" | |
| 235 | +The | |
| 236 | +.I host_os | |
| 237 | +is always | |
| 238 | +.CW Nt | |
| 239 | +(even for Windows 98, 2000 or XP) | |
| 240 | +and | |
| 241 | +.I host_arch | |
| 242 | +is always | |
| 243 | +.CW 386 | |
| 244 | +and the installation program will create an entry on the | |
| 245 | +.I "start menu" | |
| 246 | +to invoke Inferno. | |
| 247 | +For Unix systems or Windows systems in which Inferno will be started | |
| 248 | +from a command shell, the environment variable | |
| 249 | +.CW PATH | |
| 250 | +should be set to include the Inferno | |
| 251 | +.CW bin | |
| 252 | +directory. | |
| 253 | +For Windows 95 and Windows 98 this should be done in the | |
| 254 | +.CW \eautoexec.bat | |
| 255 | +file by adding a line like | |
| 256 | +.P1 | |
| 257 | +PATH=c:\einferno\eNt\e386\ebin;%PATH% | |
| 258 | +.P2 | |
| 259 | +You will need to reboot Windows to have the system reread the | |
| 260 | +.CW \eautoexec.bat | |
| 261 | +file. | |
| 262 | +For Windows NT and Windows 2000 modify the | |
| 263 | +.CW Path | |
| 264 | +environment variable through | |
| 265 | +.I "Control Panel -> System -> Environment" . | |
| 266 | +.LP | |
| 267 | +If you are using an MKS or Cygwin Unix-like shell environment, | |
| 268 | +you might instead set: | |
| 269 | +.P1 | |
| 270 | +PATH="c:/inferno/Nt/386/bin;$PATH" | |
| 271 | +.P2 | |
| 272 | +and export it if necessary. | |
| 273 | +.LP | |
| 274 | +.I "Unix:\ \" | |
| 275 | +For Unix systems, for | |
| 276 | +.CW sh | |
| 277 | +derivatives, the environment variable | |
| 278 | +.CW PATH | |
| 279 | +should be set to include the Inferno | |
| 280 | +.CW bin | |
| 281 | +directory. | |
| 282 | +This might be done in your | |
| 283 | +.CW .profile | |
| 284 | +file by adding a line like | |
| 285 | +.P1 | |
| 286 | +PATH="/usr/inferno/Linux/386/bin:$PATH" | |
| 287 | +.P2 | |
| 288 | +Don't forget to ensure that | |
| 289 | +.CW PATH | |
| 290 | +is exported. | |
| 291 | +You may need to log out and back in again for the changes to take effect. | |
| 292 | +.KS | |
| 293 | +.Ss "Start Inferno." | |
| 294 | +Hosted inferno is run by invoking an executable called | |
| 295 | +.I emu . | |
| 296 | +.KE | |
| 297 | +On Windows, select the Inferno option from the | |
| 298 | +.I "start menu" . | |
| 299 | +This will invoke | |
| 300 | +.I emu | |
| 301 | +with appropriate arguments to find its files in | |
| 302 | +.I inferno_root . | |
| 303 | +If you need to change any of the options passed to | |
| 304 | +.I emu | |
| 305 | +when invoked from the | |
| 306 | +.I "start menu" | |
| 307 | +you need to do this by clicking the right mouse button | |
| 308 | +on the Windows task bar and choosing | |
| 309 | +.I "Properties -> Start Menu Programs -> Advanced" | |
| 310 | +to modify the shortcut used for Inferno. | |
| 311 | +For Unix and Plan 9, you will need to tell | |
| 312 | +.I emu | |
| 313 | +where to find the Inferno file tree by passing it the | |
| 314 | +.CW -r\fIrootpath\f(CW | |
| 315 | +command line option. For example | |
| 316 | +.P1 | |
| 317 | +emu -r/usr/john/inferno | |
| 318 | +.P2 | |
| 319 | +Without the | |
| 320 | +.CW -r | |
| 321 | +option it will look for the file tree in | |
| 322 | +.CW /usr/inferno | |
| 323 | +on Plan 9 and Unix and, when invoked from the command line on WIndows, | |
| 324 | +the default is | |
| 325 | +.CW \einferno | |
| 326 | +on the current drive. | |
| 327 | +(The Windows start menu by contrast has already been set to use the right directory by the installation software.) | |
| 328 | +.LP | |
| 329 | +When using graphics, | |
| 330 | +.I emu | |
| 331 | +will use a window with a resolution of 640 x 480 pixels by default. To use a larger resolution | |
| 332 | +you will need to pass | |
| 333 | +.I emu | |
| 334 | +an option | |
| 335 | +.CW -g\fIXsize\f(CWx\fIYsize\f(CW | |
| 336 | +on the command line. So, for example, to invoke | |
| 337 | +.I emu | |
| 338 | +as above but with a resolution of 1024 x 768 pixels the full command line | |
| 339 | +would be | |
| 340 | +.P1 | |
| 341 | +emu -r/usr/john/inferno -g1024x768 | |
| 342 | +.P2 | |
| 343 | +When invoked in this way | |
| 344 | +.I emu | |
| 345 | +displays a command window running the Inferno shell | |
| 346 | +.CW /dis/sh.dis . | |
| 347 | +To avoid typing the command line options each time you invoke | |
| 348 | +.I emu | |
| 349 | +you can store them in the environment variable | |
| 350 | +.CW EMU | |
| 351 | +which is interrogated when | |
| 352 | +.I emu | |
| 353 | +is started and might as well be set along side the | |
| 354 | +.CW PATH | |
| 355 | +environment variable if the same configuration options are to be used on | |
| 356 | +each invocation. | |
| 357 | +.P1 | |
| 358 | +set EMU="-rd:\eDocuments and Settings\ejohn\einferno -g1024x768" | |
| 359 | +.P2 | |
| 360 | +for Windows. | |
| 361 | +.P1 | |
| 362 | +EMU=(-r/usr/john/inferno -g1024x768) | |
| 363 | +.P2 | |
| 364 | +for Plan 9, and | |
| 365 | +.P1 | |
| 366 | +EMU="-r/usr/john/inferno -g1024x768" | |
| 367 | +.P2 | |
| 368 | +for Unix. | |
| 369 | +An alternative to using the | |
| 370 | +.CW EMU | |
| 371 | +environment variable is to place the correct invocation in a | |
| 372 | +script file (or batch file, for Windows) and invoke that instead | |
| 373 | +of running | |
| 374 | +.I emu | |
| 375 | +directly. | |
| 376 | +It is important to note that for Windows the | |
| 377 | +.CW -r | |
| 378 | +option also serves to indicate both the drive and directory on to which the software | |
| 379 | +has been installed. Without a drive letter the system will assume the | |
| 380 | +current drive and will fail if the user changes to an alternative drive. | |
| 381 | +Once the environment variables or scripts are set up, as described above, invoking plain | |
| 382 | +.P1 | |
| 383 | +emu | |
| 384 | +.P2 | |
| 385 | +or the appropriate script file, | |
| 386 | +should result in it starting up Inferno's command interpreter | |
| 387 | +.I sh (1), | |
| 388 | +which prompts with a semicolon: | |
| 389 | +.P1 | |
| 390 | +; | |
| 391 | +.P2 | |
| 392 | +You can add a further option | |
| 393 | +.CW -c1 | |
| 394 | +to start up | |
| 395 | +.I emu | |
| 396 | +in a | |
| 397 | +mode in which the system compiles a module's | |
| 398 | +Dis operations to native machine instructions when a module | |
| 399 | +is loaded. | |
| 400 | +(See the | |
| 401 | +.I emu (1) | |
| 402 | +manual page.) | |
| 403 | +In | |
| 404 | +.I compile | |
| 405 | +mode programs that do significant computation will run much faster. | |
| 406 | +Whether in compiled or interpreted mode you should now have a functional | |
| 407 | +hosted Inferno system. | |
| 408 | +When Inferno starts the initial | |
| 409 | +.CW /dis/sh.dis | |
| 410 | +it reads commands from the file | |
| 411 | +.CW /lib/sh/profile | |
| 412 | +before becoming interactive. See the manual pages for the shell | |
| 413 | +.I sh (1) | |
| 414 | +to learn more about tailoring the initial environment. | |
| 415 | +.LP | |
| 416 | +The semicolon is the default shell prompt. From this command window | |
| 417 | +you should be able to see the installed Inferno files and directories | |
| 418 | +.P1 | |
| 419 | +lc / | |
| 420 | +.P2 | |
| 421 | +The command | |
| 422 | +.I lc | |
| 423 | +presents the contents of its directory argument in columnar fashion to standard | |
| 424 | +output in the command window. | |
| 425 | +.P1 | |
| 426 | +; lc / | |
| 427 | +FreeBSD/ Unixware/ icons/ libkern/ man/ prof/ | |
| 428 | +Hp/ acme/ include/ libkeyring/ mkconfig prog/ | |
| 429 | +Inferno/ appl/ keydb/ libmath/ mkfile services/ | |
| 430 | +Irix/ asm/ legal/ libmemdraw/ mkfiles/ tmp/ | |
| 431 | +LICENCE chan/ lib/ libmemlayer/ mnt/ tools/ | |
| 432 | +Linux/ dev/ lib9/ libtk/ module/ usr/ | |
| 433 | +MacOSX/ dis/ libbio/ licencedb/ n/ utils/ | |
| 434 | +NOTICE doc/ libcrypt/ limbo/ net/ wrap/ | |
| 435 | +Nt/ emu/ libdraw/ locale/ nvfs/ | |
| 436 | +Plan9/ env/ libfreetype/ mail/ o/ | |
| 437 | +Solaris/ fonts/ libinterp/ makemk.sh os/ | |
| 438 | +; | |
| 439 | +.P2 | |
| 440 | +Only the files and directories in and below the | |
| 441 | +.I inferno_root | |
| 442 | +directory on the host filesystem are immediately visible to an Inferno process; | |
| 443 | +these files are made visible in the root of the Inferno file namespace. | |
| 444 | +If you wish to import or export files | |
| 445 | +from and to the host filesystem you will need to use tools on your | |
| 446 | +host to move them in or out of the Inferno visible portion of your host | |
| 447 | +filesystem (see the manual pages | |
| 448 | +.I os (1) | |
| 449 | +and | |
| 450 | +.I cmd (3) | |
| 451 | +for an interface to host commands). | |
| 452 | +(We plan to make such access direct, but the details are still being worked out.) | |
| 453 | +From this point onwards in this paper all file paths not qualified with | |
| 454 | +.I inferno_root | |
| 455 | +are assumed to be in the Inferno namespace. | |
| 456 | +Files created in the host filesystem will be created with the user id of | |
| 457 | +the user that started | |
| 458 | +.I emu | |
| 459 | +and on Unix systems with that user's group id. | |
| 460 | +.NH | |
| 461 | +Setting the site's time zone | |
| 462 | +.LP | |
| 463 | +Time zone settings are defined by | |
| 464 | +files in the directory | |
| 465 | +.CW /locale/timezone . | |
| 466 | +The setting affects only how the time is displayed; the internal representation does not vary. | |
| 467 | +For instance, the file | |
| 468 | +.CW /locale/GMT | |
| 469 | +defines Greenwich Mean Time, | |
| 470 | +.CW /locale/GB-Eire | |
| 471 | +defines time zones for Great Britain and the Irish Republic | |
| 472 | +(GMT and British Summer Time), and | |
| 473 | +.CW /locale/US_Eastern | |
| 474 | +defines United States | |
| 475 | +Eastern Standard Time and Eastern Daylight Time. | |
| 476 | +The time zone settings used by applications are read | |
| 477 | +(by | |
| 478 | +.I daytime (2)) | |
| 479 | +from the file | |
| 480 | +.CW /locale/timezone , | |
| 481 | +which is initially a copy of | |
| 482 | +.CW /locale/GB-Eire . | |
| 483 | +If displaying time as the time in London is adequate, you need change nothing. | |
| 484 | +To set a different time zone for the whole site, | |
| 485 | +copy the appropriate time zone file into | |
| 486 | +.CW /locale/timezone : | |
| 487 | +.P1 | |
| 488 | +cp /locale/US_Eastern /locale/timezone | |
| 489 | +.P2 | |
| 490 | +To set a different time zone for a user or window, | |
| 491 | +.I bind (1) | |
| 492 | +the file containing the time zone setting over | |
| 493 | +.CW /locale/timezone , | |
| 494 | +either in the user's profile or in a name space description file: | |
| 495 | +.P1 | |
| 496 | +bind /locale/US_Eastern /locale/timezone | |
| 497 | +.P2 | |
| 498 | +.NH | |
| 499 | +Running the | |
| 500 | +Window Manager | |
| 501 | +.I wm | |
| 502 | +.LP | |
| 503 | +Graphical Inferno programs normally run under the window manager | |
| 504 | +.I wm (1). | |
| 505 | +Inferno has a simple editor, | |
| 506 | +.I wm/edit , | |
| 507 | +that can be used to edit the inferno configuration files. | |
| 508 | +The `power environment' for editing and program development is | |
| 509 | +.I acme (1), | |
| 510 | +but rather that throwing you in at the deep end, we shall stick to | |
| 511 | +the simpler one for now. | |
| 512 | +If you already know Acme from | |
| 513 | +Plan 9, however, or perhaps Wily from Unix, feel free to use Inferno's | |
| 514 | +.I acme | |
| 515 | +instead of | |
| 516 | +.I edit . | |
| 517 | +.Ss "Start the window manager." | |
| 518 | +Invoke | |
| 519 | +.I wm | |
| 520 | +by typing | |
| 521 | +.P1 | |
| 522 | +wm/wm | |
| 523 | +.P2 | |
| 524 | +You should see a new window open with a blue-grey background and a small | |
| 525 | +.I "Vita Nuova" | |
| 526 | +logo in the bottom left hand corner. Click on the logo with mouse button 1 | |
| 527 | +to reveal a small menu. | |
| 528 | +Selecting the | |
| 529 | +.I Edit | |
| 530 | +entry will start | |
| 531 | +.I wm/edit . | |
| 532 | +In common with most | |
| 533 | +.I wm | |
| 534 | +programs the editor has three small buttons in a line at its top right hand corner. | |
| 535 | +Clicking on the X button, the rightmost button, | |
| 536 | +will close the program down. The leftmost of the three buttons will allow the window | |
| 537 | +to be resized \- after clicking it drag the window from a point near to either one of its | |
| 538 | +edges or one of its corners. The middle button will minimise the window, creating | |
| 539 | +an entry for it in the application bar along the bottom of the main | |
| 540 | +.I wm | |
| 541 | +window. You can restore a minimised window by clicking on its entry in the application bar. | |
| 542 | +The initial | |
| 543 | +.I wm | |
| 544 | +configuration is determined by the contents of the shell | |
| 545 | +script | |
| 546 | +.CW /lib/wmsetup | |
| 547 | +(see | |
| 548 | +.I toolbar (1) | |
| 549 | +and | |
| 550 | +.I sh (1)). | |
| 551 | +.Ss "Open a shell window." | |
| 552 | +Choose the | |
| 553 | +.I shell | |
| 554 | +option from the menu to open up a shell window. The configuration of Inferno | |
| 555 | +will be done from this shell window. | |
| 556 | +.NH | |
| 557 | +Manual Pages | |
| 558 | +.LP | |
| 559 | +Manual pages for all of the system commands are available from a shell | |
| 560 | +window. Use the | |
| 561 | +.I man | |
| 562 | +or | |
| 563 | +.I wm/man | |
| 564 | +commands. For example, | |
| 565 | +.P1 | |
| 566 | +man wm | |
| 567 | +.P2 | |
| 568 | +will give information about | |
| 569 | +.I wm . | |
| 570 | +And | |
| 571 | +.P1 | |
| 572 | +man man | |
| 573 | +.P2 | |
| 574 | +will give information about using | |
| 575 | +.I man . | |
| 576 | +.I Wm/man | |
| 577 | +makes use of the Tk text widget to produce slightly more | |
| 578 | +attractive output than the plain command | |
| 579 | +.I man . | |
| 580 | +Here, and in other Inferno documentation you will see references to manual page | |
| 581 | +entries of the form \fIcommand\f(CW(\fIsection\f(CW)\fR. | |
| 582 | +You can display the manual page for the command by running | |
| 583 | +.P1 | |
| 584 | +man \fIcommand\fP | |
| 585 | +.P2 | |
| 586 | +or | |
| 587 | +.P1 | |
| 588 | +man \fIsection\fP \fIcommand\fP | |
| 589 | +.P2 | |
| 590 | +if the manual page appears in more than one section. | |
| 591 | +.NH | |
| 592 | +Initial Namespace | |
| 593 | +.LP | |
| 594 | +The initial Inferno namespace is built | |
| 595 | +by placing the root device '#/' (see | |
| 596 | +.I root (3)) | |
| 597 | +at the root of the namespace and binding | |
| 598 | +.nr ,i 0 1 | |
| 599 | +.af ,i i | |
| 600 | +.IP \n+(,i) | |
| 601 | +the host filesystem device '#U' (see | |
| 602 | +.I fs (3)) | |
| 603 | +containing the | |
| 604 | +.I inferno_root | |
| 605 | +subtree of the host filesystem at the root of the Inferno filesystem, | |
| 606 | +.IP \n+(,i) | |
| 607 | +the console device '#c' (see | |
| 608 | +.I cons (3)) | |
| 609 | +in | |
| 610 | +.CW /dev , | |
| 611 | +.IP \n+(,i) | |
| 612 | +the prog device '#p' (see | |
| 613 | +.I prog (3)) | |
| 614 | +onto | |
| 615 | +.CW /prog , | |
| 616 | +.IP \n+(,i) | |
| 617 | +the IP device '#I' (see | |
| 618 | +.I ip (3)) | |
| 619 | +in | |
| 620 | +.CW /net , | |
| 621 | +and | |
| 622 | +.IP \n+(,i) | |
| 623 | +the environment device '#e' (see | |
| 624 | +.I env (3)) | |
| 625 | +at | |
| 626 | +.CW /dev/env . | |
| 627 | +.rr ,i | |
| 628 | +.LP | |
| 629 | +You can see the sequence of commands required to construct the current namespace | |
| 630 | +by running | |
| 631 | +.P1 | |
| 632 | +ns | |
| 633 | +.P2 | |
| 634 | +.NH | |
| 635 | +Inferno's network | |
| 636 | +.LP | |
| 637 | +If you are just going to use Inferno for local Limbo programming, and not use its | |
| 638 | +networking interface, you can skip to the section ``Adding new users'' at the end of this document. | |
| 639 | +You can always come back to this step later. | |
| 640 | +.LP | |
| 641 | +To use IP networking, the IP device | |
| 642 | +.I ip (3)) ( | |
| 643 | +must have been bound into | |
| 644 | +.CW /net . | |
| 645 | +Typing | |
| 646 | +.P1 | |
| 647 | +ls -l /net | |
| 648 | +.P2 | |
| 649 | +(see | |
| 650 | +.I ls (1)) | |
| 651 | +should result in something like | |
| 652 | +.P1 | |
| 653 | +--rw-rw-r-- I 0 network john 0 May 31 07:11 /net/arp | |
| 654 | +--rw-rw-r-- I 0 network john 0 May 31 07:11 /net/ndb | |
| 655 | +d-r-xr-xr-x I 0 network john 0 May 31 07:11 /net/tcp | |
| 656 | +d-r-xr-xr-x I 0 network john 0 May 31 07:11 /net/udp | |
| 657 | +.P2 | |
| 658 | +There might be many more names on some systems. | |
| 659 | +.LP | |
| 660 | +A system running Inferno, whether native or hosted, can by agreement attach to any or all resources that | |
| 661 | +are in the name space of another Inferno system (or even its own). | |
| 662 | +That requires: | |
| 663 | +.IP • | |
| 664 | +the importing system must know where to find them | |
| 665 | +.IP • | |
| 666 | +the exporting system must agree to export them | |
| 667 | +.IP • | |
| 668 | +the two systems must authenticate the access (not all resources will be permitted to all systems or users) | |
| 669 | +.IP • | |
| 670 | +the conversation can be encrypted to keep it safe from prying eyes and interference | |
| 671 | +.LP | |
| 672 | +On an Inferno network, there is usually one secure machine that acts as authentication server. | |
| 673 | +All other systems variously play the rôles of server and client as required: any system can import some resources (or none) | |
| 674 | +and export others (or none), simultaneously, and differently in different name spaces. | |
| 675 | +In following sections, we shall write as though there were three distinct machines: | |
| 676 | +authentication server (signer); server (exporting resources); and client (importing resources). | |
| 677 | +With Inferno, you can achieve a similar effect on a single machine by starting up distinct | |
| 678 | +instances of | |
| 679 | +.I emu | |
| 680 | +instead. | |
| 681 | +That is the easiest way to become familiar with the process (and also avoids having to install | |
| 682 | +the system on several machines to start). | |
| 683 | +It is still worthwhile setting up a secured | |
| 684 | +authentication server later, especially if you are using Windows on a FAT file system | |
| 685 | +where the host system's file protections are limited. | |
| 686 | +.LP | |
| 687 | +We shall now configure Inferno to allow each of the functions listed above: | |
| 688 | +.IP • | |
| 689 | +change the network database to tell where to find local network resources | |
| 690 | +.IP • | |
| 691 | +set up the authentication system, specifically the authentication server or `signer' | |
| 692 | +.IP • | |
| 693 | +start network services (two distinct sets: one for the authentication services and the other for | |
| 694 | +all other network services) | |
| 695 | +.NH | |
| 696 | +Network database files | |
| 697 | +.LP | |
| 698 | +In both hosted and native modes, Inferno uses a collection of text files | |
| 699 | +of a particular form to store all details of network and service configuration. | |
| 700 | +When running hosted, Inferno typically gets most of its data from the host operating system, | |
| 701 | +and the database contains mainly Inferno-specific data. | |
| 702 | +.LP | |
| 703 | +The file | |
| 704 | +.CW /lib/ndb/local | |
| 705 | +is the root of the collection of network database files. | |
| 706 | +The format is defined by | |
| 707 | +.I ndb (6), | |
| 708 | +but essentially it is a collection of groups of attribute/value pairs of the form | |
| 709 | +\fIattribute\fP\f(CW=\fP\fIvalue\fP. | |
| 710 | +Attribute names and most values are case-sensitive. | |
| 711 | +.LP | |
| 712 | +Related attribute/value pairs are grouped into database `entries'. | |
| 713 | +An entry can span one or more | |
| 714 | +lines: the first line starts with a non-blank character, | |
| 715 | +and any subsequent lines in that entry start | |
| 716 | +with white space (blank or tab). | |
| 717 | +.NH 2 | |
| 718 | +Site parameters | |
| 719 | +.LP | |
| 720 | +The version of | |
| 721 | +.CW /lib/ndb/local | |
| 722 | +at time of writing looks like this: | |
| 723 | +.P1 | |
| 724 | +database= | |
| 725 | + file=/lib/ndb/local | |
| 726 | + file=/lib/ndb/dns | |
| 727 | + file=/lib/ndb/inferno | |
| 728 | + file=/lib/ndb/common | |
| 729 | + | |
| 730 | +infernosite= | |
| 731 | + #dnsdomain=your.domain.com | |
| 732 | + #dns=1.2.3.4 # resolver | |
| 733 | + SIGNER=your_Inferno_signer_here | |
| 734 | + FILESERVER=your_Inferno_fileserver_here | |
| 735 | + smtp=your_smtpserver_here | |
| 736 | + pop3=your_pop3server_here | |
| 737 | + registry=your_registry_server | |
| 738 | +.P2 | |
| 739 | +The individual files forming the data base are listed in order in the | |
| 740 | +.CW database | |
| 741 | +entry. | |
| 742 | +They can be ignored for the moment. | |
| 743 | +The entry labelled | |
| 744 | +.CW infernosite= | |
| 745 | +defines a mapping from symbolic host names of the form | |
| 746 | +.CW $\fIservice\f(CW | |
| 747 | +to a host name, domain name, or a numeric Internet address. | |
| 748 | +For instance, an application that needs an authentication service | |
| 749 | +will refer to | |
| 750 | +.CW $SIGNER | |
| 751 | +and an Inferno naming service will translate that at run-time to the appropriate network name for | |
| 752 | +that environment. | |
| 753 | +Consequently, | |
| 754 | +the entries above need to be customised for a given site. | |
| 755 | +(The items that are commented out are not needed when the host's own DNS resolver is used instead | |
| 756 | +of Inferno's own | |
| 757 | +.I dns (8).) | |
| 758 | +For example, our | |
| 759 | +.CW infernosite | |
| 760 | +entry in the | |
| 761 | +.CW local | |
| 762 | +file might look something like this | |
| 763 | +.P1 | |
| 764 | +infernosite= | |
| 765 | + dnsdomain=vitanuova.com | |
| 766 | + dns=200.1.1.11 # resolver | |
| 767 | + SIGNER=doppio | |
| 768 | + FILESERVER=doppio | |
| 769 | + smtp=doppio | |
| 770 | + pop3=doppio | |
| 771 | + registry=doppio | |
| 772 | +.P2 | |
| 773 | +where | |
| 774 | +.CW doppio | |
| 775 | +is the host name of a machine that is offering the given services to Inferno, | |
| 776 | +and | |
| 777 | +.CW 200.1.1.11 | |
| 778 | +is the Internet address of a local DNS resolver. | |
| 779 | +.Ss "Enter defaults for your site" | |
| 780 | +.LP | |
| 781 | +The only important names initially are: | |
| 782 | +.IP \f(CWSIGNER\fP 20 | |
| 783 | +the host or domain name, or address of the machine that will act as signer | |
| 784 | +.IP \f(CWregistry\fP | |
| 785 | +the name or address of a machine that provides the local dynamic service | |
| 786 | +.I registry (4) | |
| 787 | +.IP \f(CWFILESERVER\fP | |
| 788 | +the primary file server (actually needed only by clients with no storage of their own) | |
| 789 | +.LP | |
| 790 | +All others are used by specific applications such as | |
| 791 | +.I acme (1) | |
| 792 | +mail or | |
| 793 | +.I ftpfs (4). | |
| 794 | +.LP | |
| 795 | +If you are using a single machine for signer and server/client, put its name in those three entries. | |
| 796 | +.NH 2 | |
| 797 | +Connection server | |
| 798 | +.I cs (8) | |
| 799 | +and name translation | |
| 800 | +.LP | |
| 801 | +The connection server | |
| 802 | +.I cs (8) | |
| 803 | +uses the network database | |
| 804 | +and other | |
| 805 | +data (such as that provided by the host system and | |
| 806 | +the Internet DNS servers) to translate symbolic network names and services into instructions | |
| 807 | +for connecting to a given service. | |
| 808 | +In hosted mode, | |
| 809 | +network and service names are passed through to the host for conversion to numeric IP | |
| 810 | +addresses and port numbers. If the host is unable to convert a service name | |
| 811 | +the connection server will attempt to convert the name using mappings | |
| 812 | +of service and protocol names to Internet port numbers | |
| 813 | +in the file | |
| 814 | +.CW /lib/ndb/inferno : | |
| 815 | +.P1 | |
| 816 | +tcp=infgamelogin port=6660 # inferno games login service | |
| 817 | +tcp=styx port=6666 # main file service | |
| 818 | +tcp=mpeg port=6667 # mpeg stream | |
| 819 | +tcp=rstyx port=6668 # remote invocation | |
| 820 | +tcp=infdb port=6669 # database server | |
| 821 | +tcp=infweb port=6670 # inferno web server | |
| 822 | +tcp=infsigner port=6671 # inferno signing services | |
| 823 | +tcp=infcsigner port=6672 # inferno countersigner | |
| 824 | +tcp=inflogin port=6673 # inferno credential service | |
| 825 | +tcp=infsds port=6674 # software download | |
| 826 | +tcp=registry port=6675 # registry(4) | |
| 827 | +udp=virgil port=2202 # naming service | |
| 828 | +.P2 | |
| 829 | +For the moment, leave that file as it is. | |
| 830 | +You will only need to modify this file if in future | |
| 831 | +you add new statically-configured services to Inferno. | |
| 832 | +(Services that come and go dynamically might use | |
| 833 | +.I registry (4) | |
| 834 | +instead, a registry manager that allows a service to be found | |
| 835 | +using a description of it.) | |
| 836 | +.NH | |
| 837 | +Configuring a Signer | |
| 838 | +.LP | |
| 839 | +Before an Inferno machine can authenticate establish a secure connection to an Inferno | |
| 840 | +service on another machine, each system needs to obtain a certificate from a common signer.† | |
| 841 | +We talk here as though there is only one `signer' per site but in fact there can be application- or | |
| 842 | +group-specific ones. | |
| 843 | +For instance, a version of the Inferno games server automatically starts its own signing service to | |
| 844 | +keep the identities and keys used for game service separate from those of the primary | |
| 845 | +system, allowing users to set up their own gaming groups without fuss. | |
| 846 | +.FS | |
| 847 | +.FA | |
| 848 | +†The authentication system will shortly expand to a rôle-based one allowing a chain of certificates to be used, | |
| 849 | +from several signers, with delegation etc. | |
| 850 | +.FE | |
| 851 | +To use authenticated connections for the primary | |
| 852 | +file services we need to set up a signer to generate | |
| 853 | +certificates for users (see | |
| 854 | +.I createsignerkey (8) | |
| 855 | +and | |
| 856 | +.I logind (8)). | |
| 857 | +.LP | |
| 858 | +Choose an Inferno machine to become the signer. | |
| 859 | +If this is the first or only | |
| 860 | +Inferno machine on your network then make this machine the signer. | |
| 861 | +(It is more realistic if you start up a separate copy of | |
| 862 | +.I emu | |
| 863 | +and leave it in `console' mode without starting the window system.) | |
| 864 | +You can always move the function elsewhere later. | |
| 865 | +.Ss "Empty the secret file of secrets." | |
| 866 | +The authentication server verifies a user's identity by checking that the user knows a shared secret. | |
| 867 | +(In fact the secret is not used directly, but instead a scrambled value that was derived from it.) | |
| 868 | +The file | |
| 869 | +.CW /keydb/keys | |
| 870 | +holds those secrets; it is encrypted using a secret password or phrase known only to the | |
| 871 | +manager of the authentication server. | |
| 872 | +Having just installed Inferno, the file | |
| 873 | +should exist and be readable only by you (or the user as which the authentication service will run). | |
| 874 | +On the signer machine, type | |
| 875 | +.P1 | |
| 876 | +ls -l /keydb/keys | |
| 877 | +.P2 | |
| 878 | +You should see something like: | |
| 879 | +.P1 | |
| 880 | +--rw------- M 7772 yourname inf 0 Jun 12 03:08 /keydb/keys | |
| 881 | +.P2 | |
| 882 | +You should see something like the above. | |
| 883 | +If the file does not exist or is not empty or has the wrong mode, use: | |
| 884 | +.P1 | |
| 885 | +cp /dev/null /keydb/keys; chmod 600 /keydb/keys | |
| 886 | +.P2 | |
| 887 | +to set it right. | |
| 888 | +.Ss "Generate a signer key." | |
| 889 | +Next on the signer machine, run | |
| 890 | +.P1 | |
| 891 | +auth/createsignerkey \fIname\fP | |
| 892 | +.P2 | |
| 893 | +In place of | |
| 894 | +.I name | |
| 895 | +enter the network name of the signer. A fully-qualified domain name of a | |
| 896 | +host or individual is fine. | |
| 897 | +This value will appear as the signer name in each | |
| 898 | +certificate generated by the signer. | |
| 899 | +.I Createsignerkey | |
| 900 | +creates public and private keys that are used by the signer when generating | |
| 901 | +certificates. | |
| 902 | +They are stored in | |
| 903 | +.CW /keydb/signerkey ; | |
| 904 | +check that it has permissions that limit access to the user that will run the | |
| 905 | +authentication services: | |
| 906 | +.P1 | |
| 907 | +; ls -l /keydb/signerkey | |
| 908 | +--rw------- M 32685 secrets inf 1010 Jul 07 2000 /keydb/signerkey | |
| 909 | +.P2 | |
| 910 | +Use | |
| 911 | +.I chmod (1) | |
| 912 | +to set the mode to read/write only for the owner if necessary: | |
| 913 | +.P1 | |
| 914 | +chmod 600 /keydb/signerkey | |
| 915 | +.P2 | |
| 916 | +.Ss "Start the authentication network services" | |
| 917 | +Still at the signer console, type | |
| 918 | +.P1 | |
| 919 | +svc/auth | |
| 920 | +.P2 | |
| 921 | +That script (see | |
| 922 | +.I svc (8)) | |
| 923 | +will check that the | |
| 924 | +.CW /keydb/keys | |
| 925 | +and | |
| 926 | +.CW /keydb/signerkey | |
| 927 | +files exist, and then | |
| 928 | +start the program | |
| 929 | +.I keyfs (4), | |
| 930 | +which manages the | |
| 931 | +.CW keys | |
| 932 | +file. | |
| 933 | +It will prompt for the password (pass phrase) you wish to use to protect the | |
| 934 | +.CW keys | |
| 935 | +file, now and on subsequent runs: | |
| 936 | +.P1 | |
| 937 | +; svc/auth | |
| 938 | +Key: | |
| 939 | +Confirm key: | |
| 940 | +.P2 | |
| 941 | +It prompts twice to confirm it. | |
| 942 | +If successfully confirmed, it will then | |
| 943 | +start the | |
| 944 | +network services used by Inferno to authenticate local and remote users and hosts. | |
| 945 | +(If confirmation fails, retry by running | |
| 946 | +.CW svc/auth | |
| 947 | +again.) | |
| 948 | +.LP | |
| 949 | +You can check that they are running by typing: | |
| 950 | +.P1 | |
| 951 | +ps | |
| 952 | +.P2 | |
| 953 | +which should show something like the following: | |
| 954 | +.P1 | |
| 955 | + 1 1 john release 74K Sh[$Sys] | |
| 956 | + 3 2 john alt 15K Cs | |
| 957 | + 10 9 john recv 25K Keyfs | |
| 958 | + 11 9 john release 44K Styx[$Sys] | |
| 959 | + 12 9 john recv 25K Keyfs | |
| 960 | + 14 1 john alt 8K Listen | |
| 961 | + 16 1 john release 8K Listen[$Sys] | |
| 962 | + 18 1 john alt 9K Listen | |
| 963 | + 20 1 john release 9K Listen[$Sys] | |
| 964 | + 22 1 john alt 9K Listen | |
| 965 | + 24 1 john release 9K Listen[$Sys] | |
| 966 | + 26 1 john alt 8K Listen | |
| 967 | + 28 1 john release 8K Listen[$Sys] | |
| 968 | + 29 1 john ready 73K Ps[$Sys] | |
| 969 | +.P2 | |
| 970 | +There should be | |
| 971 | +.CW Keyfs | |
| 972 | +and | |
| 973 | +.CW Listen | |
| 974 | +processes. | |
| 975 | +.Ss "Enter user names and secrets." | |
| 976 | +For each user to be authenticated by the signer run | |
| 977 | +.P1 | |
| 978 | +auth/changelogin \fIusername\fP | |
| 979 | +.P2 | |
| 980 | +You will be prompted to supply a secret (ie, password or pass phrase) and expiration date. | |
| 981 | +The expiration date will be used | |
| 982 | +as the maximum expiration date of authentication certificates granted to that user. | |
| 983 | +.I Changelogin | |
| 984 | +(see | |
| 985 | +.I changelogin (8)) | |
| 986 | +accesses the name space generated by | |
| 987 | +.I keyfs (4), | |
| 988 | +which has just been started above by | |
| 989 | +.CW svc/auth . | |
| 990 | +A user can later change the stored secret using the | |
| 991 | +.I passwd (1) | |
| 992 | +command. | |
| 993 | +For the signer to generate a certificate there must be at least one entry in the | |
| 994 | +password file. | |
| 995 | +If you are not sure at this stage of the names of the users that you want to | |
| 996 | +authenticate then create an entry for the user | |
| 997 | +.CW inferno | |
| 998 | +and yourself. | |
| 999 | +.NH | |
| 1000 | +Establishing a Secure Connection | |
| 1001 | +.LP | |
| 1002 | +To establish a secure connection between two Inferno machines, each needs to present a public key with | |
| 1003 | +a certificate signed by a common signer. | |
| 1004 | +We shall make two public/private key sets, one for the server and one for a client | |
| 1005 | +(they differ only in where they are stored). | |
| 1006 | +We shall do the server first, because the usual network services require | |
| 1007 | +the server possess some keys before they can start. | |
| 1008 | +We shall then start those services, and finally sort out the client. | |
| 1009 | +.Ss "Start the connection service." | |
| 1010 | +The server still needs to make contact with the signer, so we need to start the basic connection service | |
| 1011 | +.I cs (8). | |
| 1012 | +If you are using the same instance of | |
| 1013 | +.I emu | |
| 1014 | +in which you invoked | |
| 1015 | +.CW svc/auth | |
| 1016 | +above, you should skip this step. | |
| 1017 | +To check, you should see a new file in the | |
| 1018 | +.CW /net | |
| 1019 | +directory called | |
| 1020 | +.CW cs . | |
| 1021 | +Run the command | |
| 1022 | +.P1 | |
| 1023 | +ls /net | |
| 1024 | +.P2 | |
| 1025 | +You should see at least the following names in the output: | |
| 1026 | +.P1 | |
| 1027 | +/net/cs | |
| 1028 | +/net/ndb | |
| 1029 | +/net/tcp | |
| 1030 | +/net/udp | |
| 1031 | +.P2 | |
| 1032 | +Otherwise, type | |
| 1033 | +.P1 | |
| 1034 | +ndb/cs | |
| 1035 | +.P2 | |
| 1036 | +That starts | |
| 1037 | +.I cs (8). | |
| 1038 | +Try the | |
| 1039 | +.CW "ls /net" | |
| 1040 | +again to check that the | |
| 1041 | +.CW cs | |
| 1042 | +file has appeared. | |
| 1043 | +.LP | |
| 1044 | +.Ss "Generate a server key set." | |
| 1045 | +On the server machine (or in the `server' window), | |
| 1046 | +use | |
| 1047 | +.I getauthinfo (8) | |
| 1048 | +to obtain a certificate and save it in a file named | |
| 1049 | +.CW default | |
| 1050 | +by running | |
| 1051 | +.P1 | |
| 1052 | +getauthinfo default | |
| 1053 | +.P2 | |
| 1054 | +.I Getauthinfo | |
| 1055 | +will prompt for the address of your signer (you can often | |
| 1056 | +just use its host name or even | |
| 1057 | +.CW localhost ) | |
| 1058 | +and for a remote username and password | |
| 1059 | +combination. | |
| 1060 | +.I Getauthinfo | |
| 1061 | +will connect to the | |
| 1062 | +.I inflogin | |
| 1063 | +service on the signer and authenticate you against its user and password database, | |
| 1064 | +.CW /keydb/keys , | |
| 1065 | +using the username and password that you entered above. | |
| 1066 | +Answer | |
| 1067 | +.CW yes | |
| 1068 | +to the question that asks if you want to save the certificate in a file. | |
| 1069 | +.I Getauthinfo | |
| 1070 | +will save a certificate in the file | |
| 1071 | +.CW /usr/\fIuser\f(CW/keyring/default | |
| 1072 | +where | |
| 1073 | +.I user | |
| 1074 | +is the name in | |
| 1075 | +.CW /dev/user . | |
| 1076 | +.NH | |
| 1077 | +Network Services | |
| 1078 | +.LP | |
| 1079 | +As mentioned above, in a full Inferno network | |
| 1080 | +the authentication services will usually be run on a secured machine of their own (the signer), | |
| 1081 | +and the ordinary network services such as file service are not run on a signer. | |
| 1082 | +If you are, however, using one machine for all functions, you can get the right | |
| 1083 | +effect by starting another instance of | |
| 1084 | +.I emu , | |
| 1085 | +to act as an Inferno host that is not a signer. | |
| 1086 | +This one will run the services of a primary file server | |
| 1087 | +and the site | |
| 1088 | +.I registry (4). | |
| 1089 | +.LP | |
| 1090 | +Commands described in | |
| 1091 | +.I svc (8) | |
| 1092 | +start listeners for various local network services. | |
| 1093 | +(The commands are actually shell scripts.) | |
| 1094 | +As we saw above, | |
| 1095 | +.CW svc/auth | |
| 1096 | +starts the services on a signer. | |
| 1097 | +.LP | |
| 1098 | +Here we shall start the usual set of services. | |
| 1099 | +.KS | |
| 1100 | +.Ss "Start the network listener services." | |
| 1101 | +Type | |
| 1102 | +.P1 | |
| 1103 | +svc/net | |
| 1104 | +.P2 | |
| 1105 | +.KE | |
| 1106 | +Various network services will (should!) now be running. To confirm this type | |
| 1107 | +.P1 | |
| 1108 | +ps | |
| 1109 | +.P2 | |
| 1110 | +which should show something like the following: | |
| 1111 | +.P1 | |
| 1112 | +; ps | |
| 1113 | + 1 1 inferno release 74K Sh[$Sys] | |
| 1114 | + 7 6 inferno alt 15K Cs | |
| 1115 | + 13 1 inferno recv 15K Registry | |
| 1116 | + 14 1 inferno release 44K Styx[$Sys] | |
| 1117 | + 15 1 inferno recv 15K Registry | |
| 1118 | + 17 1 inferno alt 8K Listen | |
| 1119 | + 19 1 inferno release 8K Listen[$Sys] | |
| 1120 | + 22 1 inferno alt 8K Listen | |
| 1121 | + 24 1 inferno release 8K Listen[$Sys] | |
| 1122 | + 25 1 inferno ready 74K Ps[$Sys] | |
| 1123 | +.P2 | |
| 1124 | +There should be a few | |
| 1125 | +.CW Listen | |
| 1126 | +processes and perhaps a | |
| 1127 | +.CW Registry . | |
| 1128 | +.LP | |
| 1129 | +You can also try | |
| 1130 | +.P1 | |
| 1131 | +netstat | |
| 1132 | +.P2 | |
| 1133 | +.I Netstat | |
| 1134 | +prints information about network connections. You should see | |
| 1135 | +several lines of output, each one describing an announced TCP or UDP service. | |
| 1136 | +Depending upon the contents of the network configuration files we included on the CD, | |
| 1137 | +you might see output something like this: | |
| 1138 | +.P1 | |
| 1139 | +tcp/1 Announced inferno 200.1.1.89!6668 ::!0 | |
| 1140 | +tcp/2 Announced inferno 200.1.1.89!6666 ::!0 | |
| 1141 | +tcp/3 Announced inferno 200.1.1.89!6675 ::!0 | |
| 1142 | +.P2 | |
| 1143 | +Each line corresponds to a network connection: | |
| 1144 | +the connection name, the name of the user running the server, | |
| 1145 | +the address of the local end of the connection, | |
| 1146 | +the address of the remote end of the connection, | |
| 1147 | +and the connection status. | |
| 1148 | +The connection name is actually the protocol and conversation directory | |
| 1149 | +in | |
| 1150 | +.CW /net . | |
| 1151 | +The connection addresses are all of the form \fIhost\f(CW!\fIport\fR | |
| 1152 | +for these IP based services, and the remote addresses are not filled in | |
| 1153 | +because they all represent listening services that are in the | |
| 1154 | +.CW Announced | |
| 1155 | +state. | |
| 1156 | +In this example the fourth line shows a TCP service listening on port 6673. | |
| 1157 | +Examining | |
| 1158 | +.CW /lib/ndb/inferno | |
| 1159 | +with | |
| 1160 | +.CW grep | |
| 1161 | +(see | |
| 1162 | +.I grep (1)) | |
| 1163 | +shows that the listener on port 6675 is the Inferno registry service | |
| 1164 | +.P1 | |
| 1165 | +grep 6675 /lib/ndb/inferno | |
| 1166 | +.P2 | |
| 1167 | +gives | |
| 1168 | +.P1 | |
| 1169 | +tcp=registry port=6675 # default registry | |
| 1170 | +.P2 | |
| 1171 | +.LP | |
| 1172 | +Now the server is ready but we need a client. | |
| 1173 | +.LP | |
| 1174 | +Either use a third machine or (more likely at first) simply start another | |
| 1175 | +.I emu | |
| 1176 | +instance in a new window. | |
| 1177 | +Start its connection server, again by typing | |
| 1178 | +.P1 | |
| 1179 | +ndb/cs | |
| 1180 | +.P2 | |
| 1181 | +The connection server is fundamental to the Inferno network. | |
| 1182 | +Once networking is set up, when subsequently starting up | |
| 1183 | +a client you should start | |
| 1184 | +.I cs | |
| 1185 | +before starting the window system. | |
| 1186 | +Note that if you are running the Inferno instance as a server, or combined | |
| 1187 | +server and client, | |
| 1188 | +the | |
| 1189 | +.CW svc/net | |
| 1190 | +that starts the network services | |
| 1191 | +automatically starts | |
| 1192 | +.I cs , | |
| 1193 | +and you need not do so explicitly. | |
| 1194 | +.LP | |
| 1195 | +.Ss "Generate a client certificate." | |
| 1196 | +Obtain a certificate for the client in the same way as on the server. | |
| 1197 | +We shall obtain a certificate for use with a specific server | |
| 1198 | +by storing | |
| 1199 | +it in a file whose name exactly matches the network address of the server | |
| 1200 | +.P1 | |
| 1201 | +getauthinfo tcp!\fIhostname\fP | |
| 1202 | +.P2 | |
| 1203 | +Use the current machine's | |
| 1204 | +.I hostname . | |
| 1205 | +.I Getauthinfo | |
| 1206 | +stores the certificate in the file | |
| 1207 | +.CW /usr/\fIuser\fP/keyring/\fIkeyname\fP | |
| 1208 | +where | |
| 1209 | +.I user | |
| 1210 | +is the name in | |
| 1211 | +.CW /dev/user | |
| 1212 | +and | |
| 1213 | +.I keyname | |
| 1214 | +is the argument given to | |
| 1215 | +.I getauthinfo . | |
| 1216 | +Again, | |
| 1217 | +answer | |
| 1218 | +.CW yes | |
| 1219 | +to the question that asks if you want to save the certificate in a file. | |
| 1220 | +.LP | |
| 1221 | +Now that both client and server have a certificate obtained from the same signer | |
| 1222 | +it is possible to establish a secure connection between them. | |
| 1223 | +Note that getting keys and certificates with | |
| 1224 | +.I getauthinfo | |
| 1225 | +is normally done just once (or at most once per server when the | |
| 1226 | +.CW default | |
| 1227 | +key is not used). | |
| 1228 | +In short, all the work done up to now need not be repeated. | |
| 1229 | +After this, provided the keys were saved to a keyring file, | |
| 1230 | +as many authenticated connections can be made as desired | |
| 1231 | +until the certificate expires (which by default is whenever the password entry | |
| 1232 | +was set to expire). | |
| 1233 | +Also note that the certificates for different machines can have | |
| 1234 | +different signers, and one can even use different certificates for the same machine | |
| 1235 | +when the remote user name is to differ | |
| 1236 | +(the | |
| 1237 | +.CW -f | |
| 1238 | +option of | |
| 1239 | +.I getauthinfo | |
| 1240 | +can then be useful to force an appropriate keyring name). | |
| 1241 | +.Ss "Make an authenticated connection." | |
| 1242 | +The script | |
| 1243 | +.CW svc/net | |
| 1244 | +on the server started fundamental name services and also a Styx file service. | |
| 1245 | +That can also be started separately using | |
| 1246 | +.CW svc/styx . | |
| 1247 | +In either case the namespace that is served | |
| 1248 | +is the one in which the command was invoked. | |
| 1249 | +Now you can test the service. | |
| 1250 | +.LP | |
| 1251 | +Confirm that | |
| 1252 | +.CW /n/remote | |
| 1253 | +is an empty directory by typing | |
| 1254 | +.P1 | |
| 1255 | +lc /n/remote | |
| 1256 | +.P2 | |
| 1257 | +You can now mount the server's name space | |
| 1258 | +onto the client's directory | |
| 1259 | +.CW /n/remote | |
| 1260 | +by typing | |
| 1261 | +.P1 | |
| 1262 | +mount \fIserveraddr\fP /n/remote | |
| 1263 | +.P2 | |
| 1264 | +Where | |
| 1265 | +.I serveraddr | |
| 1266 | +is the IP address of the server or a name that the host can resolve to the | |
| 1267 | +IP address of the server. | |
| 1268 | +Now | |
| 1269 | +.P1 | |
| 1270 | +lc /n/remote | |
| 1271 | +.P2 | |
| 1272 | +should reveal the files and directories in the namespace being served by the server. | |
| 1273 | +Those files are now also visible in the namespace of your shell. | |
| 1274 | +You will notice that these changes only affect the shell in which you ran the | |
| 1275 | +.I mount | |
| 1276 | +command \- other windows are unaffected. | |
| 1277 | +You can create, remove or modify files and directories in and under | |
| 1278 | +.CW /n/remote | |
| 1279 | +much as you can any other file or directory in your namespace. | |
| 1280 | +In fact, in general, a process does not need to know whether a file | |
| 1281 | +actually resides locally or remotely. | |
| 1282 | +You can unmount the mounted directory with | |
| 1283 | +.I unmount . | |
| 1284 | +Type | |
| 1285 | +.P1 | |
| 1286 | +unmount /n/remote | |
| 1287 | +.P2 | |
| 1288 | +You can confirm that it has gone by running | |
| 1289 | +.P1 | |
| 1290 | +ls /n/remote | |
| 1291 | +.P2 | |
| 1292 | +All connections made by Inferno are authenticated. The default connection | |
| 1293 | +made by | |
| 1294 | +.I mount | |
| 1295 | +is authenticated but uses neither encryption nor secure digests. | |
| 1296 | +You can pass an argument to | |
| 1297 | +.I mount | |
| 1298 | +to specify | |
| 1299 | +a more secure connection: | |
| 1300 | +its | |
| 1301 | +.CW -C | |
| 1302 | +option gives it a hashing and an encryption algorithm to be applied to | |
| 1303 | +the connection. | |
| 1304 | +.KS | |
| 1305 | +.Ss "Make a secure authenticated connection." | |
| 1306 | +For example, | |
| 1307 | +.P1 | |
| 1308 | +mount -C sha1/rc4_256 \fIserveraddr\fP /n/remote | |
| 1309 | +.P2 | |
| 1310 | +makes an authenticated connection to the machine given by | |
| 1311 | +.I serveraddr , | |
| 1312 | +then engages SHA1 hashing for message digesting and 256-bit RC4 for encryption. | |
| 1313 | +.KE | |
| 1314 | +It mounts the namespace served by | |
| 1315 | +.I serveraddr 's | |
| 1316 | +Styx service on the local Inferno directory | |
| 1317 | +.CW /n/remote . | |
| 1318 | +.NH | |
| 1319 | +Adding new users | |
| 1320 | +.LP | |
| 1321 | +Every inferno process has an associated | |
| 1322 | +.I "user name" . | |
| 1323 | +At boot time the user name is set equal to your login name on the host | |
| 1324 | +operating system. | |
| 1325 | +The user name is used by | |
| 1326 | +.I wm/logon | |
| 1327 | +to select the home directory, and | |
| 1328 | +by other programs like | |
| 1329 | +.I mount | |
| 1330 | +when it searches for certificates. | |
| 1331 | +(It can also control permission for file access on the local system in native Inferno | |
| 1332 | +and some hosted Inferno configurations.) | |
| 1333 | +When you attach to a server on another | |
| 1334 | +system the user name in the authenticating certificate can be used by | |
| 1335 | +the remote file service to set the user name appropriately there.† | |
| 1336 | +.FS | |
| 1337 | +.FA | |
| 1338 | +†The details are system-dependent and currently subject to change. | |
| 1339 | +.FE | |
| 1340 | +.LP | |
| 1341 | +To create a new user, copy the directory | |
| 1342 | +.CW /usr/inferno | |
| 1343 | +into | |
| 1344 | +\f(CW/usr/\fP\fIusername\fP. | |
| 1345 | +If the user is to have access to services on the network, | |
| 1346 | +make an authentication server entry using | |
| 1347 | +.I changelogin (8). | |
| 1348 | +The user can change the stored secret using | |
| 1349 | +.I passwd (1), | |
| 1350 | +if desired. | |
| 1351 | +Having logged in for the first time, the user should generate | |
| 1352 | +a default public/private key set using | |
| 1353 | +.I getauthinfo (8). | |
| 1354 | +(The authentication services must be running somewhere.) | |
| 1355 | +.LP | |
| 1356 | +The | |
| 1357 | +.I wm | |
| 1358 | +window manager program | |
| 1359 | +.I wm/logon | |
| 1360 | +allows a user to login to the local Inferno system as an Inferno | |
| 1361 | +user (different from the host user name). | |
| 1362 | +Its use is shown next. | |
| 1363 | +.Ss "Re-start Inferno." | |
| 1364 | +You should now close down any instances of | |
| 1365 | +.I emu | |
| 1366 | +that you are currently running. | |
| 1367 | +The quickest way to do this is to | |
| 1368 | +type | |
| 1369 | +.I control-c | |
| 1370 | +in the emu window in which you ran | |
| 1371 | +.I wm/wm . | |
| 1372 | +Start a new | |
| 1373 | +.I emu , | |
| 1374 | +as before, by either running | |
| 1375 | +.P1 | |
| 1376 | +emu | |
| 1377 | +.P2 | |
| 1378 | +or by choosing the appropriate entry from your start menu on | |
| 1379 | +Windows machines. This time, start network services | |
| 1380 | +.P1 | |
| 1381 | +svc/net | |
| 1382 | +.P2 | |
| 1383 | +and then run | |
| 1384 | +.P1 | |
| 1385 | +wm/wm wm/logon | |
| 1386 | +.P2 | |
| 1387 | +and log in as user | |
| 1388 | +.I inferno . | |
| 1389 | +When you log in, | |
| 1390 | +.I wm/logon | |
| 1391 | +will change directory to | |
| 1392 | +.CW /usr/inferno | |
| 1393 | +and then write the name | |
| 1394 | +.CW inferno | |
| 1395 | +to | |
| 1396 | +.CW /dev/user . | |
| 1397 | +If the file | |
| 1398 | +.CW /usr/inferno/namespace | |
| 1399 | +exists it will be used to construct a new namespace for the user | |
| 1400 | +based on the commands that it contains (see | |
| 1401 | +.I newns (2)). | |
| 1402 | +.NH | |
| 1403 | +What next | |
| 1404 | +.LP | |
| 1405 | +You should now have a fully functional Inferno system. | |
| 1406 | +You will need to have a three button mouse to use | |
| 1407 | +.I acme , | |
| 1408 | +.I wm , | |
| 1409 | +or | |
| 1410 | +.I plumbing . | |
| 1411 | +.LP | |
| 1412 | +To learn more you could start with the manual pages for: | |
| 1413 | +.I intro (1), | |
| 1414 | +.I emu (1), | |
| 1415 | +.I wm (1), | |
| 1416 | +.I wm-misc (1), | |
| 1417 | +.I sh (1), | |
| 1418 | +.I acme (1), | |
| 1419 | +and | |
| 1420 | +.I limbo (1) | |
| 1421 | +and also the papers in sections 1, 2 and 3 | |
| 1422 | +of Volume 2 of | |
| 1423 | +.I "The Inferno Programmer's Manual" . | |
Binary file not shown.
| @@ -0,0 +1,642 @@ | ||
| 1 | +.TL | |
| 2 | +Styx-on-a-Brick | |
| 3 | +.AU | |
| 4 | +Chris Locke | |
| 5 | +.br | |
| 6 | +chris@vitanuova.com | |
| 7 | +.AI | |
| 8 | +Vita Nuova | |
| 9 | +.br | |
| 10 | +June 2000 | |
| 11 | +.SH | |
| 12 | +Background | |
| 13 | +.LP | |
| 14 | +The aim of the Vita-Nuova ``styx-on-a-brick'' project was | |
| 15 | +to demonstrate the simplicity of the Styx protocol and the ease | |
| 16 | +with which a Styx `stub' can be implemented on tiny devices. | |
| 17 | +We also aimed to demonstrate the effectiveness of a protocol based approach | |
| 18 | +to resource management and sharing, whether the resource be a physical device | |
| 19 | +or a software service. | |
| 20 | +.LP | |
| 21 | +Adopting a protocol-centric view of resource and service management, as opposed to | |
| 22 | +a language-centric approach (as emphasised for instance by Jini™ with Java) | |
| 23 | +greatly eased the software burden on our tiny target device \- | |
| 24 | +implementing a simple protocol in firmware required much less work than trying to | |
| 25 | +implement a virtual machine. We are confident that if we had adopted a language-centric | |
| 26 | +approach, we would not have completed the project within our aggressive space and implementation time constraints.† | |
| 27 | +.FS | |
| 28 | +.FA | |
| 29 | +†Indeed, we later discovered that in the application of Jini to load code into an RCX robot no part | |
| 30 | +of Jini was actually on the brick. | |
| 31 | +.FE | |
| 32 | +.LP | |
| 33 | +The project took 2 weeks from start to finish. | |
| 34 | +In this time the firmware was developed and all client software | |
| 35 | +was written: firmware download, IR-link protocol support, | |
| 36 | +clockface application and worldclock application. | |
| 37 | +Two people worked on the project, one full-time, the other (Nigel Roles) part-time. | |
| 38 | +.LP | |
| 39 | +The demo was then taken on a Press Conference tour of the US | |
| 40 | +and later appeared at the Usenix2000 Plan 9/Inferno BOF at the request | |
| 41 | +of Dennis Ritchie. | |
| 42 | +.LP | |
| 43 | +I should stress that the project was a demonstration of the ease of | |
| 44 | +supporting Styx on small devices \- it was not a demo of robotics! | |
| 45 | +(Indeed, the design of the IR-link protocol, Styx name space and the | |
| 46 | +services provided by the firmware would be considerably different for | |
| 47 | +serious robotics.) | |
| 48 | +.LP | |
| 49 | +The project used a standard Lego™ Mindstorms™ robotics kit \- | |
| 50 | +the ``Robotics Invention System''. This consists of the RCX brick, | |
| 51 | +2 motors, 2 button sensors, a light sensor and a whole load of | |
| 52 | +lego pieces \- including wheels, gears and axles; which all adds up | |
| 53 | +to a whole load of fun! | |
| 54 | +.LP | |
| 55 | +The RCX brick is an Hitachi H8 microcontroller with 32K of RAM and | |
| 56 | +a 16K ROM BIOS. The RCX provides 3 motor outputs and 3 sensor inputs. | |
| 57 | +Communication with the RCX is via IR. An IR tower is supplied with the | |
| 58 | +``Robotics Invention System'' that connects to a PC via a serial port. | |
| 59 | +.SH | |
| 60 | +Acknowledgements | |
| 61 | +.LP | |
| 62 | +Before going any further I must acknowledge the work of Kekoa Proudfoot at | |
| 63 | +Stanford and Russ Nelson at Crynwr Software. | |
| 64 | +Without their valiant efforts we would not have been able to pursue this project. | |
| 65 | +Our work relied on the documents and librcx suite provided by Kekoa: | |
| 66 | +.P1 | |
| 67 | +http://graphics.stanford.edu/~kekoa/rcx/ | |
| 68 | +.P2 | |
| 69 | +and on information from Russ Nelson's web site | |
| 70 | +.P1 | |
| 71 | +http://www.crynwr.com/lego-robotics/ | |
| 72 | +.P2 | |
| 73 | +.SH | |
| 74 | +Files | |
| 75 | +.LP | |
| 76 | +The files in the | |
| 77 | +.CW legostyx.tar | |
| 78 | +file are shown in Table 1. | |
| 79 | +.KF | |
| 80 | +.TS | |
| 81 | +center; | |
| 82 | +lf(CW) lfR . | |
| 83 | +llp.h Link level protocol constants | |
| 84 | +styx.c The firmware implementation | |
| 85 | +styx.srec The firmware image (S-record format) | |
| 86 | +styx_abp.srec The firmware with the alternating bit part of the link protocol enabled | |
| 87 | +send.b Test app \- sends RCX op codes to the brick | |
| 88 | +firmdl.b Firmware download app | |
| 89 | +rcxsend.m Util module header | |
| 90 | +rcxsend.b Util module \- supports RCX ROM message format on serial link | |
| 91 | +timers.m Timer module header | |
| 92 | +timers.b Util module \- general purpose timers | |
| 93 | +legolink.b Implements the link protocol via a limbo file2chan() | |
| 94 | +clockface.b The controller app for our Clockface robot | |
| 95 | +.TE | |
| 96 | +.fi | |
| 97 | +.ce 10 | |
| 98 | +.I "Table 1.\ "\c | |
| 99 | +Files in the Styx-on-a-Brick package | |
| 100 | +.ce 0 | |
| 101 | +.KE | |
| 102 | +.SH | |
| 103 | +Project details | |
| 104 | +.NH 1 | |
| 105 | +Firmware Download | |
| 106 | +.LP | |
| 107 | +The RCX brick comes supplied with Lego firmware to be downloaded into the RAM via | |
| 108 | +the IR link. The ROM implements a monitor which provides for the firmware download, | |
| 109 | +as well as other 'op-codes'. | |
| 110 | +.LP | |
| 111 | +We wrote our own firmware in C using the GNU H8 compiler suite on a FreeBSD machine. | |
| 112 | +The code used Kekoa's | |
| 113 | +.CW librcx | |
| 114 | +library for interfacing to the RCX ROM routines. | |
| 115 | +(We should have liked to have done an H8 code generator for our own compiler suite, | |
| 116 | +but time did not permit this!) | |
| 117 | +The | |
| 118 | +.CW gnuh8 | |
| 119 | +list is accessible via: | |
| 120 | +.P1 | |
| 121 | +http://www.pcserv.demon.co.uk/ | |
| 122 | +.P2 | |
| 123 | +First up we had to write a Limbo application to communicate with the ROM, via | |
| 124 | +the IR tower in order that we could get our firmware downloaded onto the RCX. | |
| 125 | +This is the firmdl application. Source files: | |
| 126 | +.CW firmdl.b , | |
| 127 | +.CW rcxsend.b | |
| 128 | +and | |
| 129 | +.CW timers.b | |
| 130 | +.NH 1 | |
| 131 | +Styx Comms Link | |
| 132 | +.LP | |
| 133 | +Having got a means of installing our firmware we needed a means of delivering | |
| 134 | +Styx messages to and from the Brick. | |
| 135 | +.LP | |
| 136 | +Styx makes certain demands of its transport media: | |
| 137 | +.TS | |
| 138 | +l l . | |
| 139 | +Reliable messages must not get 'lost' | |
| 140 | +Ordered messages must not get transposed | |
| 141 | +.TE | |
| 142 | +The RCX ROM provides a couple of functions for IR comms \- a routine to check | |
| 143 | +for message reception and a routine for message delivery. | |
| 144 | +The message reception routine receives the data of a RCX "Transfer Data" | |
| 145 | +message (RCX op-code 0x45) | |
| 146 | +.LP | |
| 147 | +We chose to use this facility as a means of delivering Styx messages to our Firmware | |
| 148 | +on the Brick. But it did not provide the Transport properties that Styx requires. | |
| 149 | +To meet the Styx requirements we implemented a simple 'alternating bit' protocol whose | |
| 150 | +payload was the Styx messages themselves. These Link protocol messages become the | |
| 151 | +payload of the RCX "Transfer Data" messages. | |
| 152 | +.LP | |
| 153 | +The IR link is very slow, the baud rate of the IR tower serial link is 2400 | |
| 154 | +and the ROM message format requires that every byte of a message be doubled up with | |
| 155 | +its complement. (e.g. the byte 0x7e is transmitted as 0x7e, 0x81) | |
| 156 | +This is because of the simple way that the RCX ROM and hardware handle elimination | |
| 157 | +of the ambient IR signal level \- all message have the same number of 1s and 0s so | |
| 158 | +the ambient IR level can be negated by subtracting the average level. | |
| 159 | +All RCX messages are also prefixed by a header and suffixed with a checksum: | |
| 160 | +.P1 | |
| 161 | +0x55 0xff 0x00 \fID1 ~D1 D2 ~D2 ... Dn ~Dn C ~C\fP | |
| 162 | +.P2 | |
| 163 | +where | |
| 164 | +.I D1 | |
| 165 | +\&... | |
| 166 | +.I Dn | |
| 167 | +are the bytes in the message body and \fIC = D1+D2+ ... Dn\fP. | |
| 168 | +.LP | |
| 169 | +Therefore, the effective data rate is considerably less than 1200 baud. | |
| 170 | +.LP | |
| 171 | +We noted that many Styx messages, especially | |
| 172 | +.CW Twstat | |
| 173 | +and | |
| 174 | +.CW Rstat , | |
| 175 | +contained a high | |
| 176 | +proportion of 0 byte values.† | |
| 177 | +.FS | |
| 178 | +.FA | |
| 179 | +The protocol has since been revised to reduce that. | |
| 180 | +.FE | |
| 181 | +Consequently, we decided to incorporate a 0-run-length | |
| 182 | +compression scheme in our simple link protocol. | |
| 183 | +.LP | |
| 184 | +Within the payload of the link messages: | |
| 185 | +.TS | |
| 186 | +l l . | |
| 187 | +0x88 0x00 represents 0x88 | |
| 188 | +0x88 n represents n + 2 0's | |
| 189 | +others represent themselves | |
| 190 | +.TE | |
| 191 | +.LP | |
| 192 | +An additional burden is that communication with the Brick via the IR tower has to be strictly | |
| 193 | +synchronous. The IR tower echoes back all data transmitted to it on the serial link | |
| 194 | +as well as any data received on the IR link. Therefore the brick must not send IR data | |
| 195 | +while the PC is sending serial data to the tower. In order to achieve this a 'ping-pong' | |
| 196 | +communication scheme must be employed. The PC is the master, the brick is the slave. | |
| 197 | +The master sends a request and waits for the reply from the slave. | |
| 198 | +Only the master is allowed to start an exchange. | |
| 199 | +.LP | |
| 200 | +The problem with the master/slave style of communication is that a Styx Server | |
| 201 | +implements blocking requests, e.g. reads and writes, by simply not responding to the | |
| 202 | +request until the operation is completed. This does not fit with the link protocol | |
| 203 | +requirement that the server (slave) always respond and the requirement that the brick | |
| 204 | +cannot instigate a data exchange. | |
| 205 | +The firmware could simply reply with an empty Link protocol message but it then has no | |
| 206 | +way of giving timely notification of the completion of a pending Styx request as it is not | |
| 207 | +allowed to start a link-protocol message exchange. | |
| 208 | +.LP | |
| 209 | +To get around the pending Styx reply problem, the link protocol header incorporates a flag | |
| 210 | +that the slave (brick) can set to indicate that it is holding outstanding requests and that the | |
| 211 | +master (PC) should continue to poll the slave in order to receive their replies in a timely | |
| 212 | +fashion. | |
| 213 | +.LP | |
| 214 | +The link protocol message format is as follows. | |
| 215 | +Request from Master (PC) to Slave (RCX): | |
| 216 | +.LP | |
| 217 | +.TS | |
| 218 | +l l . | |
| 219 | +0x45/4d RCX Transfer Data op-code (including RCX alternating bit) | |
| 220 | +0 LSB of "Data" block number | |
| 221 | +0 MSB of "Data" block number | |
| 222 | +* LSB of "Data" payload length (lost to ROM firmware) | |
| 223 | +* MSB of "Data" payload length (lost to ROM firmware) (n+2) | |
| 224 | +* LSB of Link protocol payload length | |
| 225 | +* MSB of Link protocol payload length (n+1) | |
| 226 | +* Link protocol header | |
| 227 | +*[n-1] Link protocol payload (0 or 1 Styx messages) | |
| 228 | +* "Transfer Data" cksum (Last byte of Link protocol payload) | |
| 229 | +.TE | |
| 230 | +.LP | |
| 231 | +Note that the 0x45 ROM op-code ("Transfer Data") message incorporates a checksum byte at the | |
| 232 | +end, but the ROM doesn't bother to check it so we moved the last byte of the Link protocol | |
| 233 | +payload (or the link header if the payload is empty) into the checksum position of | |
| 234 | +the ROM message. | |
| 235 | +.LP | |
| 236 | +Reply from Slave to Master: | |
| 237 | +.LP | |
| 238 | +.TS | |
| 239 | +l l . | |
| 240 | +? Junk from ROM | |
| 241 | +* LSB of Link protocol payload length | |
| 242 | +* MSB of Link protocol payload length (n+1) | |
| 243 | +* Link protocol header | |
| 244 | +*[n] Link protocol payload | |
| 245 | +.TE | |
| 246 | +.LP | |
| 247 | +The Link protocol header has the following flags: | |
| 248 | +.LP | |
| 249 | +.TS | |
| 250 | +l l . | |
| 251 | +bit 0 Alternating bit | |
| 252 | +bit 1 Poll immediate (requested by slave) | |
| 253 | +bit 2 Poll periodic (requested by slave) | |
| 254 | +bit 3 compressed (payload is 0-run-length compressed) | |
| 255 | +bits 4-7 reserved (should be 0) | |
| 256 | +.TE | |
| 257 | +.LP | |
| 258 | +The master flips the | |
| 259 | +.I Alternating | |
| 260 | +.I bit | |
| 261 | +for every message that it successfully delivers. | |
| 262 | +If a slave reply is lost or corrupted the master will re-send the message using the same | |
| 263 | +alternating bit value. The slave should not act on a repeated message but should | |
| 264 | +re-send it's last response. The value of the alternating bit in the slave response | |
| 265 | +is the same as in the request from the master. | |
| 266 | +.LP | |
| 267 | +The | |
| 268 | +.I Poll | |
| 269 | +.I immediate | |
| 270 | +bit indicates that the slave has more data to send to the master. | |
| 271 | +The master should immediately send another Link-protocol message, even if it has no | |
| 272 | +data to send, so as the slave can reply with its pending data. | |
| 273 | +.LP | |
| 274 | +The | |
| 275 | +.I Poll | |
| 276 | +.I periodic | |
| 277 | +bit indicates that the slave has pending (blocked) requests that | |
| 278 | +it will reply to sometime in the future. The master should periodically poll the | |
| 279 | +slave, even if the master has no data to send. The polling period should be small | |
| 280 | +enough that reply latencies are acceptable. | |
| 281 | +.NH 1 | |
| 282 | +The name space | |
| 283 | +.LP | |
| 284 | +We now have a means of getting Styx messages to and from the brick. | |
| 285 | +But what does the name space provided by the firmware on the brick look like? | |
| 286 | +.LP | |
| 287 | +We wanted a generic name space; one that reflected the functions of the brick, not | |
| 288 | +the model attached to it, so that the same firmware could be used with many | |
| 289 | +different robots. | |
| 290 | +.LP | |
| 291 | +The brick has 3 motor outputs and 3 sensor inputs. | |
| 292 | +The motors can be run forwards or reverse with 8 different power settings. | |
| 293 | +They can be stalled, also with 8 power levels, and they can be left 'floating' | |
| 294 | +[A stalled motor presents resistance to turning proportional to the stall power level] | |
| 295 | +.LP | |
| 296 | +There are 2 types of sensor \- buttons and light-sensors. | |
| 297 | +[You can also get a 'rotation sensor', but we had not got one in our kit!] | |
| 298 | +.LP | |
| 299 | +We decided on a name space comprised of 2 directories, | |
| 300 | +.CW motor | |
| 301 | +and | |
| 302 | +.CW sensor . | |
| 303 | +We didn't need to use subdirectories for our name space but it was easy, so we did! | |
| 304 | +.LP | |
| 305 | +The motor directory contains 4 files \- | |
| 306 | +.CW 0 , | |
| 307 | +.CW 1 , | |
| 308 | +.CW 2 | |
| 309 | +and | |
| 310 | +.CW 012 . | |
| 311 | +The files | |
| 312 | +.CW 0 , | |
| 313 | +.CW 1 | |
| 314 | +and | |
| 315 | +.CW 2 | |
| 316 | +represent the individual motor outputs and | |
| 317 | +accept command messages of the form | |
| 318 | +.I 'XP' | |
| 319 | +where | |
| 320 | +.I X | |
| 321 | +is a direction and | |
| 322 | +.I P | |
| 323 | +is the power level. | |
| 324 | +.LP | |
| 325 | +.I X | |
| 326 | +can be one of | |
| 327 | +.TS | |
| 328 | +l l . | |
| 329 | +f forward | |
| 330 | +r reverse | |
| 331 | +s stall | |
| 332 | +F float | |
| 333 | +.TE | |
| 334 | +.LP | |
| 335 | +.I P | |
| 336 | +is a digit in the range | |
| 337 | +.CW '0..7' | |
| 338 | +.LP | |
| 339 | +The file | |
| 340 | +.CW 012 | |
| 341 | +takes messages of the form | |
| 342 | +.I 'XPXPXP' | |
| 343 | +enabling the state of all the motors to be modified with a single message. | |
| 344 | +The first | |
| 345 | +.I XP | |
| 346 | +pair affects motor 0, the middle pair affects motor 1 and the | |
| 347 | +last pair affects motor 2. | |
| 348 | +.I XP | |
| 349 | +can be | |
| 350 | +.CW '--' | |
| 351 | +indicating that the state should remain the same as before. | |
| 352 | +.LP | |
| 353 | +.LP | |
| 354 | +The sensor directory contains three files | |
| 355 | +.CW 0 , | |
| 356 | +.CW 1 | |
| 357 | +and | |
| 358 | +.CW 2 , | |
| 359 | +corresponding to the three sensor inputs on the brick. | |
| 360 | +.LP | |
| 361 | +Before a sensor file can be read it must be configured by writing a configuration | |
| 362 | +message to the file. These message take the form | |
| 363 | +.I 'Tv*' | |
| 364 | +where | |
| 365 | +.I T | |
| 366 | +is the sensor type and | |
| 367 | +.I v* | |
| 368 | +is a threshold value. | |
| 369 | +The idea of the threshold value is that reads of the sensor file wil block until | |
| 370 | +the threshold value has been achieved. | |
| 371 | +.LP | |
| 372 | +Reads of a sensor file return its current value. | |
| 373 | +When a sensor file is configured any pending reads of the sensor are | |
| 374 | +failed with the error message | |
| 375 | +.CW 'reset' . | |
| 376 | +.LP | |
| 377 | +The available sensor types are: | |
| 378 | +.LP | |
| 379 | +.TS | |
| 380 | +l l . | |
| 381 | +b button | |
| 382 | +l light sensor | |
| 383 | +.TE | |
| 384 | +.LP | |
| 385 | +The threshold value for a button sensor is a click count. | |
| 386 | +So the control message | |
| 387 | +.CW 'b0' | |
| 388 | +configures a sensor to be a button and subsequent reads | |
| 389 | +of the file will yield the current click count. | |
| 390 | +.br | |
| 391 | +The message | |
| 392 | +.CW 'b20' | |
| 393 | +will cause subsequent reads to block until the click count reaches | |
| 394 | +20 or more. | |
| 395 | +.LP | |
| 396 | +The threshold value for a light sensor is a raw sensor value qualified by | |
| 397 | +.CW '<' | |
| 398 | +or | |
| 399 | +.CW '>' . | |
| 400 | +.LP | |
| 401 | +The control message | |
| 402 | +.CW 'l>600' | |
| 403 | +configures the input to be a light sensor and subsequent | |
| 404 | +reads will block until the sensor value exceeds 600. | |
| 405 | +If the | |
| 406 | +.CW '<' | |
| 407 | +qualifier is used, reads block until the value drops below the threshold. | |
| 408 | +.SH | |
| 409 | +Using the Styx firmware | |
| 410 | +.NH 1 | |
| 411 | +Download the firmware | |
| 412 | +.LP | |
| 413 | +Use the | |
| 414 | +.CW firmdl | |
| 415 | +command to download the firmware to the brick | |
| 416 | +.P1 | |
| 417 | +% firmdl 0 styx.srec | |
| 418 | +% | |
| 419 | +.P2 | |
| 420 | +.LP | |
| 421 | +The first argument is the number of the inferno serial port ( | |
| 422 | +.CW /dev/eia0 | |
| 423 | +in this example). | |
| 424 | +The second argument is the file containing the firmware image in s-record format. | |
| 425 | +.LP | |
| 426 | +The firmdl app prints the response code from the ROM. | |
| 427 | +On successful download the ROM reports: | |
| 428 | +.P1 | |
| 429 | +Just a bit off the block! | |
| 430 | +.P2 | |
| 431 | +.LP | |
| 432 | +Once the firmware is downloaded it is immediately run. | |
| 433 | +The RCX display should be showing the 'running man' symbol. | |
| 434 | +If at any time the Styx firmware encounters an error, the 'running man' | |
| 435 | +is changed to a 'standing man' and the source code line number of the error | |
| 436 | +is displayed on the LCD. | |
| 437 | +The firmware doesn't stay resident: it monitors the on/off button and | |
| 438 | +restarts the ROM monitor when it is pressed. | |
| 439 | +.NH 1 | |
| 440 | +Start the link protocol | |
| 441 | +.LP | |
| 442 | +.P1 | |
| 443 | +% legolink 0 | |
| 444 | +% | |
| 445 | +.P2 | |
| 446 | +.LP | |
| 447 | +The legolink argument is the serial port over which to run the link protocol. | |
| 448 | +This will be the same as the first argument to the firmdl command. | |
| 449 | +.LP | |
| 450 | +Once started the legolink command creates the file | |
| 451 | +.CW /net/legolink | |
| 452 | +in the Inferno | |
| 453 | +name space. Any reads/writes of this file are the payload data of the link protocol. | |
| 454 | +.NH 1 | |
| 455 | +Mount the brick name space | |
| 456 | +.LP | |
| 457 | +.P1 | |
| 458 | +% mount -o -A /net/legolink /n/remote | |
| 459 | +.P2 | |
| 460 | +.LP | |
| 461 | +The | |
| 462 | +.CW -A | |
| 463 | +flag to mount prevents the command from trying to | |
| 464 | +do authentication | |
| 465 | +on the link before running the Styx protocol over it. | |
| 466 | +The | |
| 467 | +.CW -o | |
| 468 | +option uses an older version of Styx. | |
| 469 | +The second argument to mount is the the file over which the Styx protocol will be run. | |
| 470 | +Raw Styx messages are written to and read from this file. | |
| 471 | +The third argument is the directory on which to mount the name space presented by the | |
| 472 | +Styx server on the other end of the link \- the firmware on the Brick. | |
| 473 | +.NH 1 | |
| 474 | +Explore the name space | |
| 475 | +.LP | |
| 476 | +.P1 | |
| 477 | +% cd /n/remote | |
| 478 | +% ls | |
| 479 | +motor | |
| 480 | +sensor | |
| 481 | +% ls motor | |
| 482 | +motor/0 | |
| 483 | +motor/1 | |
| 484 | +motor/2 | |
| 485 | +motor/012 | |
| 486 | +% ls sensor | |
| 487 | +sensor/0 | |
| 488 | +sensor/1 | |
| 489 | +sensor/2 | |
| 490 | +% | |
| 491 | +.P2 | |
| 492 | +.LP | |
| 493 | +Attach a motor to the first output and a button sensor to the first input | |
| 494 | +and then try the following... | |
| 495 | +.LP | |
| 496 | +Start motor... | |
| 497 | +.P1 | |
| 498 | +% cd motor | |
| 499 | +% echo -n f7 > 0 | |
| 500 | +% | |
| 501 | +.P2 | |
| 502 | +.LP | |
| 503 | +Reverse the motor... | |
| 504 | +.P1 | |
| 505 | +% echo -n r7 > 0 | |
| 506 | +% | |
| 507 | +.P2 | |
| 508 | +.LP | |
| 509 | +Stop the motor (float)... | |
| 510 | +.P1 | |
| 511 | +% echo -n F0 > 0 | |
| 512 | +% | |
| 513 | +.P2 | |
| 514 | +.LP | |
| 515 | +Notice the need for the | |
| 516 | +.CW -n | |
| 517 | +flag to echo. The firmware is a bit touchy about | |
| 518 | +the format of the motor control messages \- they have to be 2 bytes long. | |
| 519 | +.LP | |
| 520 | +Run the motor for (a little more than) 5 seconds... | |
| 521 | +.P1 | |
| 522 | +% echo -n r7 > 0; sleep 5; echo -n F0 > 0 | |
| 523 | +% | |
| 524 | +.P2 | |
| 525 | +.LP | |
| 526 | +It takes time on the slow link to open the file for the control message to | |
| 527 | +stop the motor. It should be possible to reduce the delay by keeping the file open: | |
| 528 | +.P1 | |
| 529 | +% {echo -n r7; sleep 5; echo -n F0} > 0 | |
| 530 | +% | |
| 531 | +.P2 | |
| 532 | +but the firmware only accepts command messages written to file offset 0. | |
| 533 | +.br | |
| 534 | +[Fixing this is left as an exercise for the reader!] | |
| 535 | +.LP | |
| 536 | +Ok, lets play with a sensor... | |
| 537 | +.P1 | |
| 538 | +% cd /n/remote/sensor | |
| 539 | +% echo b0 > 0 | |
| 540 | +% cat 0 | |
| 541 | +0% | |
| 542 | +.P2 | |
| 543 | +.LP | |
| 544 | +Note that the sensor file isn't as fussy about its message format as the motor file. | |
| 545 | +.LP | |
| 546 | +Click the button a few times and then try reading the sensor file again | |
| 547 | +.P1 | |
| 548 | +% cat 0 | |
| 549 | +4% | |
| 550 | +.P2 | |
| 551 | +.LP | |
| 552 | +Let's try a blocking read on the sensor | |
| 553 | +.P1 | |
| 554 | +% echo b5 > 0 | |
| 555 | +% cat 0 | |
| 556 | +\fR[click the button 5 times]\fP | |
| 557 | +5% | |
| 558 | +.P2 | |
| 559 | +.LP | |
| 560 | +Ok, we're done playing \- unmount the brick name space | |
| 561 | +.P1 | |
| 562 | +% cd | |
| 563 | +% ls /n/remote | |
| 564 | +/n/remote/motor | |
| 565 | +/n/remote/sensor | |
| 566 | +% unmount /n/remote | |
| 567 | +% ls /n/remote | |
| 568 | +% | |
| 569 | +.P2 | |
| 570 | +.SH | |
| 571 | +The Clockface robot | |
| 572 | +.LP | |
| 573 | +So we have a means of controlling the brick via Styx. | |
| 574 | +We now needed to design a robot suitable for demonstrating the software. | |
| 575 | +.LP | |
| 576 | +The robot needed to be static; the IR link needs to maintain line-of-sight contact | |
| 577 | +between the IR tower and the brick. | |
| 578 | +The operation of the robot needed to be clearly visible to a group of people in a | |
| 579 | +conference room. | |
| 580 | +We also wanted a robot that we could layer services on top of each other to demonstrate | |
| 581 | +the versatility of Inferno name spaces. | |
| 582 | +.LP | |
| 583 | +We decided on a clock robot. The robot is static; it doesn't move around the room! | |
| 584 | +The clockface would be visible and its operation obvious | |
| 585 | +to a group of people in a reasonably large room. | |
| 586 | +.LP | |
| 587 | +The clockface robot also allowed us to layer services: | |
| 588 | +.LP | |
| 589 | +Initially we just mount the Brick name space. | |
| 590 | +This name space represents the services of the brick \- nothing is known of the | |
| 591 | +robot model that is attached to the brick. | |
| 592 | +.LP | |
| 593 | +We then start the clockface service. This knows how to use the name space of | |
| 594 | +the brick to control the motors and sensors of the clockface model. | |
| 595 | +The clockface service provides a | |
| 596 | +.CW clockface | |
| 597 | +file which accepts | |
| 598 | +time values (e.g. | |
| 599 | +.CW '14:35' ), | |
| 600 | +the service then runs motors and reads sensors | |
| 601 | +to set the hands of the robot to the specified time. | |
| 602 | +.LP | |
| 603 | +On top of the clockface service we can run a world-clock service. | |
| 604 | +This periodically reads the system clock and writes time messages to the | |
| 605 | +.CW clockface | |
| 606 | +file resented by the clockface service. | |
| 607 | +The world-clock service also provides a configuration file so that the user | |
| 608 | +can set the time zone of the clock display. Writing a time zone abbreviation into | |
| 609 | +the control file causes the world-clock service to write new time messages into | |
| 610 | +the | |
| 611 | +.CW clockface | |
| 612 | +file to reflect the new time zone setting. | |
| 613 | +.LP | |
| 614 | +By using Inferno's ability to export a name space, any of the clock services | |
| 615 | +could be running anywhere in the network. | |
| 616 | +The Lego brick could be attached to machine A. | |
| 617 | +Machine B could be running the legolink application using | |
| 618 | +.CW /dev/eia0 | |
| 619 | +imported from machine A. | |
| 620 | +Machine C could mount the | |
| 621 | +.CW /net/legolink | |
| 622 | +file imported from machine B's | |
| 623 | +name space. | |
| 624 | +Machine D could then run the clockface service over the brick's name space | |
| 625 | +imported from machine C, etc. etc. | |
| 626 | +.LP | |
| 627 | +The source of the clockface service is | |
| 628 | +.CW clockface.b . | |
| 629 | +.br | |
| 630 | +The source of the world-clock service is | |
| 631 | +.CW worldclock.b . | |
| 632 | +.SH | |
| 633 | +Final Notes | |
| 634 | +.LP | |
| 635 | +The firmware could do with some more work on it, such as the overly strict | |
| 636 | +length restriction on motor control messages, or the fact that control messages | |
| 637 | +must be written at offset 0. | |
| 638 | +.LP | |
| 639 | +Please feel free to fix problems and make modifications. I am more than happy | |
| 640 | +to discuss the software and answer any questions you may have. | |
| 641 | +.LP | |
| 642 | +Have Fun! | |
Binary file not shown.
| @@ -0,0 +1,495 @@ | ||
| 1 | +.TL | |
| 2 | +Addendum to | |
| 3 | +.I "The Limbo Programming Language" | |
| 4 | +.AU | |
| 5 | +Vita Nuova | |
| 6 | +.br | |
| 7 | +30 March 2005 | |
| 8 | +.NH 1 | |
| 9 | +Introduction | |
| 10 | +.LP | |
| 11 | +This addendum provides a brief summary of several language changes to | |
| 12 | +Limbo since | |
| 13 | +.I "The Limbo Programming Language" | |
| 14 | +was last revised: | |
| 15 | +.RS | |
| 16 | +.IP • | |
| 17 | +buffered channels | |
| 18 | +.IP • | |
| 19 | +unrestricted \f5alt\f1 | |
| 20 | +.IP • | |
| 21 | +function references | |
| 22 | +.IP • | |
| 23 | +exceptions | |
| 24 | +.IP • | |
| 25 | +exponentiation | |
| 26 | +.IP • | |
| 27 | +fixed-point types | |
| 28 | +.RE | |
| 29 | +.NH 1 | |
| 30 | +Buffered channels | |
| 31 | +.LP | |
| 32 | +A buffered channel can now be declared: | |
| 33 | +.P1 | |
| 34 | +c := chan[1] of int; | |
| 35 | +.P2 | |
| 36 | +Here the buffer size is 1. A send on this channel will succeed immediately | |
| 37 | +if there is a receiver waiting or if the buffer is empty. A receive on this | |
| 38 | +channel will succeed immediately if there is a data item in the buffer. This allows us to | |
| 39 | +write a very simple locking mechanism: | |
| 40 | +.P1 | |
| 41 | +acquire(c: chan of int) | |
| 42 | +{ | |
| 43 | + c <-= 0; | |
| 44 | +} | |
| 45 | + | |
| 46 | +release(c: chan of int) | |
| 47 | +{ | |
| 48 | + <-c; | |
| 49 | +} | |
| 50 | + | |
| 51 | +new(): chan of int | |
| 52 | +{ | |
| 53 | + return chan[1] of int; | |
| 54 | +} | |
| 55 | +.P2 | |
| 56 | +The declaration | |
| 57 | +.P1 | |
| 58 | +c := chan[0] of int; | |
| 59 | +.P2 | |
| 60 | +is equivalent to | |
| 61 | +.P1 | |
| 62 | + c := chan of int; | |
| 63 | +.P2 | |
| 64 | +An attempt to create a channel with a negative buffer size will raise | |
| 65 | +an exception. An attempt to create a channel with a very large buffer | |
| 66 | +may result in an immediate memory exception if there is not enough | |
| 67 | +room for the buffer. | |
| 68 | +.NH 1 | |
| 69 | +Unrestricted | |
| 70 | +.B alt | |
| 71 | +.LP | |
| 72 | +The implementation has changed to remove the restriction that only one process can be | |
| 73 | +waiting in an | |
| 74 | +.CW alt | |
| 75 | +to send or receive on a particular channel. | |
| 76 | +The busy exception never occurs now. Thus you can do | |
| 77 | +.P1 | |
| 78 | +i() | |
| 79 | +{ | |
| 80 | + c := chan of int; | |
| 81 | + c1 := chan of int; | |
| 82 | + spawn p(c, c1); | |
| 83 | + <-c; | |
| 84 | + spawn p(c, c1); | |
| 85 | + <-c; | |
| 86 | + for(i := 0; i < 20; i++) | |
| 87 | + c1 <-= i; | |
| 88 | +} | |
| 89 | + | |
| 90 | +p(c: chan of int, c1: chan of int) | |
| 91 | +{ | |
| 92 | + c <-= 0; | |
| 93 | + for(;;) | |
| 94 | + alt{ | |
| 95 | + i := <-c1 => | |
| 96 | + ; | |
| 97 | + } | |
| 98 | +} | |
| 99 | +.P2 | |
| 100 | +The two spawned processes can both wait on | |
| 101 | +.CW c1 | |
| 102 | +without fuss. | |
| 103 | +Processes are queued on a strict FIFO basis so, in | |
| 104 | +the example above, the two processes receive on | |
| 105 | +.CW c1 | |
| 106 | +alternately. | |
| 107 | +.NH 1 | |
| 108 | +Function references | |
| 109 | +.LP | |
| 110 | +Function references may be declared as follows: | |
| 111 | +.P1 | |
| 112 | +fp: ref fn(s1: string, s2: string): int; | |
| 113 | +.P2 | |
| 114 | +Given the function | |
| 115 | +.P1 | |
| 116 | +cmp(s1: string, s2: string): int | |
| 117 | +{ | |
| 118 | + if(s1 < s2) | |
| 119 | + return -1; | |
| 120 | + if(s1 > s2) | |
| 121 | + return 1; | |
| 122 | + return 0; | |
| 123 | +} | |
| 124 | +.P2 | |
| 125 | +a reference to it can be created by assignment: | |
| 126 | +.P1 | |
| 127 | +fp = cmp; | |
| 128 | +.P2 | |
| 129 | +where the name can be qualified by an explicit module reference as usual: | |
| 130 | +.P1 | |
| 131 | +fp = mod->cmp; | |
| 132 | +.P2 | |
| 133 | +or it can be returned from a function: | |
| 134 | +.P1 | |
| 135 | +Cmp: type ref fn(s1: string, s2: string): int; | |
| 136 | + | |
| 137 | +rcmp(s1: string, s2: string): int | |
| 138 | +{ | |
| 139 | + return -cmp(s1, s2); | |
| 140 | +} | |
| 141 | + | |
| 142 | +choose(i: int): Cmp | |
| 143 | +{ | |
| 144 | + if(i) | |
| 145 | + return rcmp; | |
| 146 | + return cmp; | |
| 147 | +} | |
| 148 | +.P2 | |
| 149 | +(the declaration of the synonym | |
| 150 | +.CW Cmp | |
| 151 | +was done only for clarity). | |
| 152 | +They may be declared and passed as parameters: | |
| 153 | +.P1 | |
| 154 | +sort(a: array of string, f: ref fn(s1, s2: string): int): array of string | |
| 155 | +{ | |
| 156 | + # ... | |
| 157 | +} | |
| 158 | + # ... | |
| 159 | +b := sort(a, cmp); | |
| 160 | +c := sort(a, rcmp); | |
| 161 | +.P2 | |
| 162 | +The function is called via the reference by | |
| 163 | +.P1 | |
| 164 | + r := fp("fred", "bloggs"); | |
| 165 | +.P2 | |
| 166 | +Otherwise function references behave just like any other reference type. | |
| 167 | +.NH 1 | |
| 168 | +Exceptions | |
| 169 | +.LP | |
| 170 | +Both string exceptions and user defined exceptions are now provided. | |
| 171 | +The | |
| 172 | +.CW Sys | |
| 173 | +module interface to exceptions | |
| 174 | +has been removed and replaced by new language constructs in limbo. | |
| 175 | +.NH 2 | |
| 176 | +String exceptions | |
| 177 | +.LP | |
| 178 | +Simple string exceptions can be raised as follows | |
| 179 | +.P1 | |
| 180 | +raise \fIs\fP; | |
| 181 | +.P2 | |
| 182 | +where | |
| 183 | +.I s | |
| 184 | +is any value of type string (it need not be constant). | |
| 185 | +.LP | |
| 186 | +Exception handlers may be attached to a block (or sequence of statements) :- | |
| 187 | +.P1 | |
| 188 | +{ | |
| 189 | + foo(); | |
| 190 | + bar(); | |
| 191 | +} exception e { | |
| 192 | +"a" or "b" => | |
| 193 | + sys->print("caught %s\en", e); | |
| 194 | + raise; | |
| 195 | +"ab*" => | |
| 196 | + sys->print("caught %s\en", e); | |
| 197 | + exit; | |
| 198 | +"abcd*" => | |
| 199 | + sys->print("caught %s\en", e); | |
| 200 | + raise e; | |
| 201 | +"a*" => | |
| 202 | + sys->print("caught %s\en", e); | |
| 203 | + raise "c"; | |
| 204 | +"*" => | |
| 205 | + sys->print("caught %s\en", e); | |
| 206 | +} | |
| 207 | +LL: | |
| 208 | +.P2 | |
| 209 | +.LP | |
| 210 | +Any exception occurring within the block (and in nested function calls within the block) can | |
| 211 | +potentially be caught by the exception handler. An exception is caught by a guard exactly | |
| 212 | +maching the exception string or by a guard | |
| 213 | +\f5\&"\fP\fIs\fP\f5*"\fP | |
| 214 | +where | |
| 215 | +.I s | |
| 216 | +is a prefix of the exception string. | |
| 217 | +The most specific match is used. Thus a raise of "a" will be caught by the first | |
| 218 | +guard and not by the fourth guard. A raise of "abcde" is caught by the third and not the second | |
| 219 | +or fourth. If a match is found, the sequence of statements following the guard are executed. | |
| 220 | +If not, the system searches for a handler at a higher level. | |
| 221 | +.LP | |
| 222 | +As shown above, the exception is available through the exception identifier (e in this case) if given following the exception keyword. | |
| 223 | +.LP | |
| 224 | +The exception is reraised using | |
| 225 | +.P1 | |
| 226 | +raise; | |
| 227 | +.P2 | |
| 228 | +or | |
| 229 | +.P1 | |
| 230 | +raise e; | |
| 231 | +.P2 | |
| 232 | +.LP | |
| 233 | +Both the block and the exception code will fall through to the statement labelled | |
| 234 | +LL unless, of course, they do an explicit exit, return or raise first. | |
| 235 | +.NH 2 | |
| 236 | +User-defined exceptions | |
| 237 | +.LP | |
| 238 | +You can declare your own exceptions: | |
| 239 | +.P1 | |
| 240 | +implement Fibonacci; | |
| 241 | + | |
| 242 | +include "sys.m"; | |
| 243 | +include "draw.m"; | |
| 244 | + | |
| 245 | +Fibonacci: module | |
| 246 | +{ | |
| 247 | + init: fn(nil: ref Draw->Context, argv: list of string); | |
| 248 | +}; | |
| 249 | +.P3 | |
| 250 | + | |
| 251 | +init(nil: ref Draw->Context, nil: list of string) | |
| 252 | +{ | |
| 253 | + sys := load Sys Sys->PATH; | |
| 254 | + for(i := 0; ; i++){ | |
| 255 | + f := fibonacci(i); | |
| 256 | + if(f < 0) | |
| 257 | + break; | |
| 258 | + sys->print("F(%d) = %d\en", i, f); | |
| 259 | + } | |
| 260 | +} | |
| 261 | +.P3 | |
| 262 | + | |
| 263 | +FIB: exception(int, int); | |
| 264 | +.P3 | |
| 265 | + | |
| 266 | +fibonacci(n: int): int | |
| 267 | +{ | |
| 268 | + { | |
| 269 | + fib(1, n, 1, 1); | |
| 270 | + }exception e{ | |
| 271 | + FIB => | |
| 272 | + (x, nil) := e; | |
| 273 | + return x; | |
| 274 | + "*" => | |
| 275 | + sys->print("unexpected string exception %s raised\en", e); | |
| 276 | + * => | |
| 277 | + sys->print("unexpected exception raised\en"); | |
| 278 | + } | |
| 279 | + return 0; | |
| 280 | +} | |
| 281 | +.P3 | |
| 282 | + | |
| 283 | +fib(n: int, m: int, x: int, y: int) raises (FIB) | |
| 284 | +{ | |
| 285 | + if(n >= m) | |
| 286 | + raise FIB(x, y); | |
| 287 | + | |
| 288 | + { | |
| 289 | + fib(n+1, m, x, y); | |
| 290 | + }exception e{ | |
| 291 | + FIB => | |
| 292 | + (x, y) = e; | |
| 293 | + x = x+y; | |
| 294 | + y = x-y; | |
| 295 | + raise FIB(x, y); | |
| 296 | + } | |
| 297 | +} | |
| 298 | +.P2 | |
| 299 | +.LP | |
| 300 | +.CW FIB | |
| 301 | +is a declared exception that returns two integers. The values are supplied when raising the exception: | |
| 302 | +.P1 | |
| 303 | +raise FIB(3, 4); | |
| 304 | +.P2 | |
| 305 | +When caught the values can be recovered by treating the declared exception identifier | |
| 306 | +as if it were a tuple of 2 integers: | |
| 307 | +.P1 | |
| 308 | +(x, y) = e; | |
| 309 | +.P2 | |
| 310 | +In general each exception alternative treats the exception identifier appropriately : as a string | |
| 311 | +when the exception qualifier is a string, as the relevant tuple when the exception is declared. | |
| 312 | +.LP | |
| 313 | +If you do | |
| 314 | +.P1 | |
| 315 | +"abcde" or FIB => | |
| 316 | + (x, y) = e; | |
| 317 | + sys->print("%s\en", e); | |
| 318 | +.P2 | |
| 319 | +you will get a compiler error as | |
| 320 | +.CW e 's | |
| 321 | +type is indeterminate within this alternative. | |
| 322 | +.LP | |
| 323 | +Reraising is the same as in the case of string exceptions. | |
| 324 | +.LP | |
| 325 | +Note also the difference between the string guard | |
| 326 | +\&\f5"*"\fP and the guard | |
| 327 | +.CW * | |
| 328 | +in | |
| 329 | +the function fibonacci. | |
| 330 | +The former will match any string exception, the latter any exception. If a | |
| 331 | +string exception does occur it matches the former as it is the most specific. | |
| 332 | +If an unexpected user defined | |
| 333 | +exception occurs it matches the latter. | |
| 334 | +.LP | |
| 335 | +The main difference between declared exceptions and string exceptions is | |
| 336 | +that the former must be caught by the immediate caller of a function that | |
| 337 | +raises them, otherwise they turn into a string exception whose name is derived | |
| 338 | +from that of the exception declaration. | |
| 339 | +.NH 2 | |
| 340 | +The | |
| 341 | +.CW raises | |
| 342 | +clause | |
| 343 | +.LP | |
| 344 | +The definition of the function fib in the above example also lists the user defined exceptions it can raise via the use of a | |
| 345 | +.CW raises | |
| 346 | +clause. In this case there is just the one exception (\f5FIB\f1). These | |
| 347 | +clauses (if given) must be compatible between any declaration and definition of the function. | |
| 348 | +.LP | |
| 349 | +The compiler reports instances of functions which either raise some exception which | |
| 350 | +is not mentioned in their raises clause or does not raise some exception which is | |
| 351 | +mentioned in their raises clause. Currently the report is a warning. | |
| 352 | +.NH 1 | |
| 353 | +Exponentiation | |
| 354 | +.LP | |
| 355 | +The exponentiation operator (written as | |
| 356 | +.CW ** ) | |
| 357 | +is now part of the Limbo language. | |
| 358 | +Its precedence is above that of multiplication, division and modulus but below | |
| 359 | +that of the unary operators. It is right associative. Thus | |
| 360 | +.P1 | |
| 361 | +3**4*2 = (3**4)*2 = 81*2 = 162 | |
| 362 | +-3**4 = (-3)**4 = 81 | |
| 363 | +2**3**2 = 2**(3**2) = 2**9 = 512 | |
| 364 | +.P2 | |
| 365 | +The type of the left operand must be | |
| 366 | +.CW int , | |
| 367 | +.CW big | |
| 368 | +or | |
| 369 | +.CW real . | |
| 370 | +The type of the right operand must be | |
| 371 | +.CW int . | |
| 372 | +The type of the result is the type of the left operand. | |
| 373 | +.NH 1 | |
| 374 | +Fixed point types | |
| 375 | +.LP | |
| 376 | +A declaration of the form | |
| 377 | +.P1 | |
| 378 | +x: fixed(0.2, 12345.0); | |
| 379 | +.P2 | |
| 380 | +declares | |
| 381 | +.CW x | |
| 382 | +to be a variable of a fixed point type. The scale of the type is | |
| 383 | +1/5 and the maximum absolute value of the type is 12345.0. | |
| 384 | +.LP | |
| 385 | +Similarly | |
| 386 | +.P1 | |
| 387 | +x: fixed(0.125, 4096.0) | |
| 388 | +.P2 | |
| 389 | +specifies a scale of 0.125 and a maximum absolute value of 4096. | |
| 390 | +This requires only 17 bits so the underlying type will be | |
| 391 | +.CW int | |
| 392 | +and the compiler | |
| 393 | +is free to allocate the remaining 15 bits to greater range or greater | |
| 394 | +accuracy. In fact the compiler always chooses the latter. | |
| 395 | +.LP | |
| 396 | +The maximum absolute value is optional :- | |
| 397 | +.P1 | |
| 398 | +x: fixed(0.125); | |
| 399 | +.P2 | |
| 400 | +is equivalent to | |
| 401 | +.P1 | |
| 402 | +x: fixed(0.125, 2147483647.0 * 0.125); | |
| 403 | +.P2 | |
| 404 | +and ensures the underlying type is exactly an int ie the compiler has | |
| 405 | +no scope to add any extra bits for more accuracy. | |
| 406 | +.LP | |
| 407 | +A binary fixed point type with 8 bits before the binary point and 24 after | |
| 408 | +might therefore be declared as | |
| 409 | +.P1 | |
| 410 | +x: fixed(2.0**-24); | |
| 411 | +.P2 | |
| 412 | +.LP | |
| 413 | +The scale must be static: its value known at compile time and | |
| 414 | +it must be positive and real; similarly for the maximum absolute | |
| 415 | +value when specified. | |
| 416 | +.LP | |
| 417 | +Currently the only underlying base type supported is | |
| 418 | +.CW int . | |
| 419 | +.LP | |
| 420 | +A shorthand for fixed point types is available through the use of | |
| 421 | +.CW type | |
| 422 | +declarations: | |
| 423 | +.P1 | |
| 424 | +fpt: type fixed(2.0**-16); | |
| 425 | +.P2 | |
| 426 | +We can then do | |
| 427 | +.P1 | |
| 428 | +x, y, z: fpt; | |
| 429 | +zero: con fpt(0); | |
| 430 | + | |
| 431 | +x = fpt(3.21); | |
| 432 | +y = fpt(4.678); | |
| 433 | +z = fpt(16r1234.5678); | |
| 434 | +z = -x; | |
| 435 | +z = x+y; | |
| 436 | +z = x-y; | |
| 437 | +z = x*y; | |
| 438 | +z = x/y; | |
| 439 | +sys->print("z=%f", real z); | |
| 440 | +.P2 | |
| 441 | +There is no implicit numerical casting in Limbo so we have to use explicit | |
| 442 | +casts to initialize fixed point variables. Note the use of a base to | |
| 443 | +initialize | |
| 444 | +.CW z | |
| 445 | +using a new literal representation. | |
| 446 | +.LP | |
| 447 | +Given | |
| 448 | +.P1 | |
| 449 | +fpt1: type fixed(0.12345); | |
| 450 | +x: fpt1; | |
| 451 | +fpt2: type fixed(0.1234); | |
| 452 | +y: fpt2; | |
| 453 | +fpt3: type fixed(0.123); | |
| 454 | +z: fpt3; | |
| 455 | +.P2 | |
| 456 | +then | |
| 457 | +.P1 | |
| 458 | +z = x*y; | |
| 459 | +.P2 | |
| 460 | +is illegal. We must add casts and do | |
| 461 | +.P1 | |
| 462 | +z = fpt3(x)*fpt3(y); | |
| 463 | +.P2 | |
| 464 | +ie type equivalence between fixed point types requires equivalence of scale | |
| 465 | +(and of maximum absolute value when specified). | |
| 466 | +.LP | |
| 467 | +Fixed point types may be used where any other numerical type (byte, int, big, real) can be used. So you can compare them, have a list of them, have a channel of them, cast them to or from string and so on. | |
| 468 | +.LP | |
| 469 | +You cannot use complement(~), not(!), and(&), or(|), xor(^) or modulus(%) on them as fixed point types are basically a form of real type. | |
| 470 | +.NH 2 | |
| 471 | +Accuracy | |
| 472 | +.LP | |
| 473 | +A fixed point value is a multiple of its scale. Given fixed point values X, Y and | |
| 474 | +Z of scale s, t and u respectively, we can write | |
| 475 | +.P1 | |
| 476 | +X = sx | |
| 477 | +Y = ty | |
| 478 | +Z = uz | |
| 479 | +.P2 | |
| 480 | +where x, y and z are integers. | |
| 481 | +.LP | |
| 482 | +For the multiplication Z = X*Y the accuracy achieved is given by | |
| 483 | +.P1 | |
| 484 | +| z - (st/u)xy | < 1 | |
| 485 | +.P2 | |
| 486 | +and for the division Z = X/Y | |
| 487 | +.P1 | |
| 488 | +| z - (s/(tu))x/y | < 1 | |
| 489 | +.P2 | |
| 490 | +That is, the result is always within the result scale of the correct real value. | |
| 491 | +.LP | |
| 492 | +This also applies when casting a fixed point type to another, casting an | |
| 493 | +integer to a fixed point type and casting a fixed point type to an integer. These | |
| 494 | +are all examples of the multiplication law with t = y = 1 since an | |
| 495 | +integer may be thought of as a fixed point type with a scale of 1. | |
Binary file not shown.
| @@ -0,0 +1,5070 @@ | ||
| 1 | +...FP lucidasans | |
| 2 | +...FP palatino | |
| 3 | +.FP palatino | |
| 4 | +." .fp 6 RR R | |
| 5 | +.nr PI 2n | |
| 6 | +.de P1 | |
| 7 | +.DS L | |
| 8 | +.ft CW | |
| 9 | +.ps -1 | |
| 10 | +.vs -1u | |
| 11 | +.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i 6.75i 7.5i | |
| 12 | +.. | |
| 13 | +.de P2 | |
| 14 | +.ft R | |
| 15 | +.ps +1 | |
| 16 | +.vs +1u | |
| 17 | +.DE | |
| 18 | +.. | |
| 19 | +.de s1 | |
| 20 | +.DS | |
| 21 | +.br | |
| 22 | +.ft I | |
| 23 | +.. | |
| 24 | +.de s2 | |
| 25 | +.br | |
| 26 | +.DE | |
| 27 | +.ft R | |
| 28 | +.. | |
| 29 | +...ds CF "Copyright 2000 Lucent Technologies Inc. Modifications Vita Nuova Limited. | |
| 30 | +.TL | |
| 31 | +The Limbo Programming Language | |
| 32 | +.AU | |
| 33 | +Dennis M. Ritchie | |
| 34 | +.br | |
| 35 | +(Revised 2005 by Vita Nuova) | |
| 36 | +.SP .5i exactly | |
| 37 | +.PP | |
| 38 | +Limbo is a programming language intended for applications | |
| 39 | +running distributed systems on small computers. | |
| 40 | +It supports modular programming, | |
| 41 | +strong type checking at compile- and run-time, | |
| 42 | +interprocess communication over typed channels, | |
| 43 | +automatic garbage collection, | |
| 44 | +and simple abstract data types. | |
| 45 | +It is designed for safe execution even on | |
| 46 | +small machines without hardware memory protection. | |
| 47 | +.PP | |
| 48 | +In its implementation for the Inferno operating system, | |
| 49 | +object programs generated by the Limbo compiler run | |
| 50 | +using an interpreter for a fixed virtual machine. | |
| 51 | +Inferno and its accompanying virtual machine run either stand-alone | |
| 52 | +on bare hardware | |
| 53 | +or as an application under conventional operating systems like | |
| 54 | +Unix, Windows 2000, Linux, FreeBSD, MacOSX, and Plan 9. | |
| 55 | +For most architectures, including | |
| 56 | +Intel x86, ARM, PowerPC, MIPS and Sparc, Limbo object programs | |
| 57 | +are transformed on-the-fly into instructions for the underlying hardware. | |
| 58 | +.NH 1 | |
| 59 | +Overview and introduction | |
| 60 | +.PP | |
| 61 | +A Limbo application consists of one or more | |
| 62 | +.I modules , | |
| 63 | +each of which supplies an interface declaration and | |
| 64 | +an implementation part. | |
| 65 | +A module that uses another module | |
| 66 | +includes its declaration part. | |
| 67 | +During | |
| 68 | +execution, a module dynamically attaches another module by | |
| 69 | +stating the other module's type identifier and a place from which to load | |
| 70 | +the object code for its implementation. | |
| 71 | +.PP | |
| 72 | +A module declaration specifies the functions and data it will make visible, | |
| 73 | +its data types, and constants. | |
| 74 | +Its implementation part defines the functions and data visible at its interface and | |
| 75 | +any functions associated with its data types; | |
| 76 | +it may also contain definitions for functions used only internally and | |
| 77 | +for data local to the module. | |
| 78 | +.PP | |
| 79 | +Here is a simple module to illustrate the flavour of the language. | |
| 80 | +.P1 | |
| 81 | +1 implement Command; | |
| 82 | + | |
| 83 | +2 include "sys.m"; | |
| 84 | +3 include "draw.m"; | |
| 85 | + | |
| 86 | +4 sys: Sys; | |
| 87 | + | |
| 88 | +5 Command: module | |
| 89 | + { | |
| 90 | +6 init: fn (ctxt: ref Draw->Context, argv: list of string); | |
| 91 | +7 }; | |
| 92 | +.P2 | |
| 93 | +.P1 | |
| 94 | +8 # The canonical "Hello world" program, enhanced | |
| 95 | +9 init(ctxt: ref Draw->Context, argv: list of string) | |
| 96 | +10 { | |
| 97 | +11 sys = load Sys Sys->PATH; | |
| 98 | +12 sys->print("hello world\en"); | |
| 99 | +13 for (; argv!=nil; argv = tl argv) | |
| 100 | +14 sys->print("%s ", hd argv); | |
| 101 | +15 sys->print("\en"); | |
| 102 | +16 } | |
| 103 | +.P2 | |
| 104 | +A quick glance at the program reveals that | |
| 105 | +the syntax of Limbo is influenced by C in its expressions, | |
| 106 | +statements, and some conventions (for example, look at lines 13-14), | |
| 107 | +and also by Pascal and its successors (the declarations on lines 4, 6, 9). | |
| 108 | +When executed in the Inferno environment, the program writes | |
| 109 | +.CW hello | |
| 110 | +.CW world | |
| 111 | +somewhere, then echoes its arguments. | |
| 112 | +.PP | |
| 113 | +Let's look at the program line-by-line. | |
| 114 | +It begins (line 1) by saying that this is the implementation of module | |
| 115 | +.CW Command . | |
| 116 | +Line 2 includes a file (found in a way analogous to C's | |
| 117 | +.CW #include | |
| 118 | +mechanism) named | |
| 119 | +.CW sys.m . | |
| 120 | +This file defines the interface to module | |
| 121 | +.CW Sys ; | |
| 122 | +.ds CF | |
| 123 | +it says, in part, | |
| 124 | +.P1 | |
| 125 | +Sys: module { | |
| 126 | + PATH: con "$Sys"; | |
| 127 | + . . . | |
| 128 | + print: fn (s: string, *): int; | |
| 129 | + . . . | |
| 130 | +}; | |
| 131 | +.P2 | |
| 132 | +This declares | |
| 133 | +.CW Sys | |
| 134 | +to be the type name for a module containing among other things a | |
| 135 | +function named | |
| 136 | +.CW print ; | |
| 137 | +the first argument of | |
| 138 | +.CW print | |
| 139 | +is a string. | |
| 140 | +The | |
| 141 | +.CW * | |
| 142 | +in the argument list specifies that further arguments, of | |
| 143 | +unspecified type, may be given. | |
| 144 | +.PP | |
| 145 | +Line 3 includes | |
| 146 | +.CW draw.m ; | |
| 147 | +only one piece of information, mentioned below, | |
| 148 | +is used from it. | |
| 149 | +Line 4 declares the variable | |
| 150 | +.CW sys | |
| 151 | +to be of type | |
| 152 | +.CW Sys ; | |
| 153 | +its name will be visible throughout the remainder of the file | |
| 154 | +describing this module. | |
| 155 | +It will be used later to refer to an instance of the | |
| 156 | +.CW Sys | |
| 157 | +module. | |
| 158 | +This declaration initializes it to | |
| 159 | +.CW nil ; | |
| 160 | +it still needs to be set to a useful value. | |
| 161 | +.PP | |
| 162 | +Lines 5-7 constitute the declaration of | |
| 163 | +.CW Command , | |
| 164 | +the module being implemented. | |
| 165 | +It contains only a function named | |
| 166 | +.CW init , | |
| 167 | +with two arguments, a | |
| 168 | +.CW ref | |
| 169 | +.CW Draw->Context | |
| 170 | +and a list of strings, | |
| 171 | +and it doesn't | |
| 172 | +return any value. | |
| 173 | +The | |
| 174 | +.CW ref | |
| 175 | +.CW Draw->Context | |
| 176 | +argument would be used if the program did any | |
| 177 | +graphics; it is a data type defined in | |
| 178 | +.CW draw.m | |
| 179 | +and refers to the display. | |
| 180 | +Since the program just writes text, it won't be used. | |
| 181 | +The | |
| 182 | +.CW init | |
| 183 | +function isn't special to the Limbo language, | |
| 184 | +but it is conventional in the environment, | |
| 185 | +like | |
| 186 | +.CW main | |
| 187 | +in C. | |
| 188 | +.PP | |
| 189 | +In a module designed to be useful | |
| 190 | +to other modules in an application, it would be wise to | |
| 191 | +take the module declaration for | |
| 192 | +.CW Command | |
| 193 | +out, put it in a separate file called | |
| 194 | +.CW command.m | |
| 195 | +and use | |
| 196 | +.CW "include | |
| 197 | +.CW command.m | |
| 198 | +to allow this module and others to refer to it. | |
| 199 | +It is called, for example, by the program loader in the Inferno | |
| 200 | +system to start the execution of applications. | |
| 201 | +.PP | |
| 202 | +Line 8 is a comment; everything from the | |
| 203 | +.CW # | |
| 204 | +to the end of line is ignored. | |
| 205 | +.PP | |
| 206 | +Line 9 begins the definition for the | |
| 207 | +.CW init | |
| 208 | +function that was promised in the module's declaration | |
| 209 | +(line 6). | |
| 210 | +The argument that is a list of strings is named | |
| 211 | +.CW argv . | |
| 212 | +.PP | |
| 213 | +Line 11 connects the program | |
| 214 | +being written to the | |
| 215 | +.CW Sys | |
| 216 | +module. | |
| 217 | +The first token after | |
| 218 | +.CW load | |
| 219 | +is the target module's name as defined by its interface | |
| 220 | +(here found in the | |
| 221 | +.CW include | |
| 222 | +on line 2) | |
| 223 | +The next token is the place | |
| 224 | +where the code for the module can be found; it is a string | |
| 225 | +that usually names a file. | |
| 226 | +Conventionally, in the Inferno system, | |
| 227 | +each module contains a constant declaration for the name | |
| 228 | +.CW PATH | |
| 229 | +as a string that names the file where | |
| 230 | +the object module can be found. | |
| 231 | +Loading the file is performed dynamically during | |
| 232 | +execution except for a few modules built | |
| 233 | +into the execution environment. | |
| 234 | +(These include | |
| 235 | +.CW Sys ; | |
| 236 | +this accounts for the peculiar file name | |
| 237 | +.CW "$Sys" | |
| 238 | +as | |
| 239 | +the value of | |
| 240 | +.CW PATH .) | |
| 241 | +.PP | |
| 242 | +The value of | |
| 243 | +.CW load | |
| 244 | +is a reference to the | |
| 245 | +named module; line 11 assigns it | |
| 246 | +to the variable | |
| 247 | +.CW sys | |
| 248 | +for later use. | |
| 249 | +The | |
| 250 | +.CW load | |
| 251 | +operator dynamically loads the code for the named | |
| 252 | +module if it is not already present and instantiates | |
| 253 | +a new instance of it. | |
| 254 | +.PP | |
| 255 | +Line 12 starts the work by printing a familiar message, | |
| 256 | +using the facilities provided by module | |
| 257 | +.CW Sys | |
| 258 | +through its handle | |
| 259 | +.CW sys ; | |
| 260 | +the notation | |
| 261 | +.CW sys->print(...) | |
| 262 | +means to call the | |
| 263 | +.CW print | |
| 264 | +function of the module referred to by | |
| 265 | +.CW sys . | |
| 266 | +The interface of | |
| 267 | +.CW Sys | |
| 268 | +resembles a binding to some of | |
| 269 | +the mechanisms of Unix and the ISO/ANSI C library. | |
| 270 | +.PP | |
| 271 | +The loop at lines 13-14 takes the | |
| 272 | +.CW "list | |
| 273 | +.CW of | |
| 274 | +.CW string | |
| 275 | +argument to | |
| 276 | +.CW init | |
| 277 | +and iterates over it using the | |
| 278 | +.CW hd | |
| 279 | +(head) and | |
| 280 | +.CW tl | |
| 281 | +(tail) operators. | |
| 282 | +When executed, this module combines the | |
| 283 | +traditional `Hello world' and | |
| 284 | +.CW echo . | |
| 285 | +.NH 1 | |
| 286 | +Lexical conventions | |
| 287 | +.PP | |
| 288 | +There are several kinds of tokens: | |
| 289 | +keywords, identifiers, constants, strings, expression operators, | |
| 290 | +and other separators. | |
| 291 | +White space (blanks, tabs, new-lines) is ignored except that | |
| 292 | +it serves to separate tokens; sometimes it is required | |
| 293 | +to separate tokens. | |
| 294 | +If the input has been parsed into tokens up to a particular | |
| 295 | +character, the next token is taken to include the longest | |
| 296 | +string of characters that could constitute a token. | |
| 297 | +.PP | |
| 298 | +The native character set of Limbo is Unicode, | |
| 299 | +which is identical with the first 16-bit plane of the ISO 10646 standard. | |
| 300 | +Any Unicode character may be used in comments, or in strings | |
| 301 | +and character constants. | |
| 302 | +The implementation assumes that source files use the UTF-8 representation, | |
| 303 | +in which 16-bit Unicode characters are represented as sequences | |
| 304 | +of one, two, or three bytes. | |
| 305 | +.NH 2 | |
| 306 | +Comments | |
| 307 | +.PP | |
| 308 | +Comments begin with the | |
4762 more lines aren’t shown here.
Binary file not shown.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 336 lines aren’t shown here.
This diff is large: its 1249 lines aren’t shown here.
This diff is large: its 35504 lines aren’t shown here.
This diff is large: its 515 lines aren’t shown here.
Binary file not shown.
This diff is large: its 1540 lines aren’t shown here.
Binary file not shown.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 983 lines aren’t shown here.
Binary file not shown.
This diff is large: its 612 lines aren’t shown here.
Binary file not shown.
This diff is large: its 2068 lines aren’t shown here.
Binary file not shown.
This diff is large: its 738 lines aren’t shown here.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 25 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
This diff is large: its 66 lines aren’t shown here.
Binary file not shown.
Empty file added.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 9 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 9 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 9 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 5 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Empty file added.
This diff is large: its 206 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 218 lines aren’t shown here.
This diff is large: its 548 lines aren’t shown here.
This diff is large: its 234 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 219 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 202 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 587 lines aren’t shown here.
Empty file added.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 399 lines aren’t shown here.
Empty file added.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 529 lines aren’t shown here.
Empty file added.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 537 lines aren’t shown here.
Empty file added.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 120 lines aren’t shown here.
This diff is large: its 630 lines aren’t shown here.
Empty file added.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 579 lines aren’t shown here.
Empty file added.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 314 lines aren’t shown here.
Empty file added.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 433 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 682 lines aren’t shown here.
Empty file added.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
Empty file added.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
Empty file added.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 526 lines aren’t shown here.
Empty file added.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 581 lines aren’t shown here.
Empty file added.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 131 lines aren’t shown here.
Empty file added.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 305 lines aren’t shown here.
Empty file added.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 654 lines aren’t shown here.
Empty file added.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 72 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 729 lines aren’t shown here.
Empty file added.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 845 lines aren’t shown here.
Empty file added.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 398 lines aren’t shown here.
Empty file added.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
Empty file added.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 119 lines aren’t shown here.
Empty file added.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 276 lines aren’t shown here.
Empty file added.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
Empty file added.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 97 lines aren’t shown here.
Empty file added.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 204 lines aren’t shown here.
This diff is large: its 100 lines aren’t shown here.
Empty file added.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 324 lines aren’t shown here.
Empty file added.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
Empty file added.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 294 lines aren’t shown here.
Empty file added.
This diff is large: its 32 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This diff is large: its 93 lines aren’t shown here.
This diff is large: its 101 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
Empty file added.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 390 lines aren’t shown here.
Empty file added.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
Empty file added.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 118 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
Empty file added.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
Empty file added.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 115 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
Empty file added.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 194 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
Empty file added.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 242 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
Empty file added.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
Empty file added.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
Empty file added.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
Empty file added.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
Binary file not shown.
Binary file not shown.
This diff is large: its 115 lines aren’t shown here.
This diff is large: its 443 lines aren’t shown here.
This diff is large: its 231 lines aren’t shown here.
This diff is large: its 443 lines aren’t shown here.
This diff is large: its 157 lines aren’t shown here.
This diff is large: its 627 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 151 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
Empty file added.
Empty file added.
This diff is large: its 560 lines aren’t shown here.
This diff is large: its 340 lines aren’t shown here.
This diff is large: its 451 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 238 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 1114 lines aren’t shown here.
This diff is large: its 330 lines aren’t shown here.
This diff is large: its 332 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 2460 lines aren’t shown here.
This diff is large: its 13259 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 730 lines aren’t shown here.
This diff is large: its 733 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 2247 lines aren’t shown here.
This diff is large: its 977 lines aren’t shown here.
This diff is large: its 880 lines aren’t shown here.
This diff is large: its 743 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 488 lines aren’t shown here.
This diff is large: its 700 lines aren’t shown here.
This diff is large: its 122 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 122 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
Binary file not shown.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
Binary file not shown.
This diff is large: its 366 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
Binary file not shown.
This diff is large: its 157 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 6589 lines aren’t shown here.
This diff is large: its 173 lines aren’t shown here.
This diff is large: its 4308 lines aren’t shown here.
This diff is large: its 16352 lines aren’t shown here.
This diff is large: its 598 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 29759 lines aren’t shown here.
This diff is large: its 212 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 4 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 2 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 189 lines aren’t shown here.
This diff is large: its 72 lines aren’t shown here.
This diff is large: its 313 lines aren’t shown here.
This diff is large: its 1204 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 426 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 241 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 277 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 443 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 106 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 203 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 222 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 183 lines aren’t shown here.
This diff is large: its 173 lines aren’t shown here.
This diff is large: its 137 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 205 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 183 lines aren’t shown here.
This diff is large: its 62 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 450 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 96 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 219 lines aren’t shown here.
This diff is large: its 238 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 144 lines aren’t shown here.
This diff is large: its 137 lines aren’t shown here.
This diff is large: its 636 lines aren’t shown here.
This diff is large: its 183 lines aren’t shown here.
This diff is large: its 213 lines aren’t shown here.
This diff is large: its 224 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 273 lines aren’t shown here.
This diff is large: its 209 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 587 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 174 lines aren’t shown here.
This diff is large: its 150 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 79 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 940 lines aren’t shown here.
This diff is large: its 418 lines aren’t shown here.
This diff is large: its 130 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 158 lines aren’t shown here.
This diff is large: its 262 lines aren’t shown here.
This diff is large: its 179 lines aren’t shown here.
This diff is large: its 132 lines aren’t shown here.
This diff is large: its 558 lines aren’t shown here.
This diff is large: its 187 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 257 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 119 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 211 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 155 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 96 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 131 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 217 lines aren’t shown here.
This diff is large: its 248 lines aren’t shown here.
This diff is large: its 275 lines aren’t shown here.
This diff is large: its 93 lines aren’t shown here.
This diff is large: its 350 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 438 lines aren’t shown here.
This diff is large: its 202 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 128 lines aren’t shown here.
This diff is large: its 412 lines aren’t shown here.
This diff is large: its 264 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 374 lines aren’t shown here.
This diff is large: its 315 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 128 lines aren’t shown here.
This diff is large: its 232 lines aren’t shown here.
This diff is large: its 336 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 436 lines aren’t shown here.
This diff is large: its 702 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 288 lines aren’t shown here.
This diff is large: its 176 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 184 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 107 lines aren’t shown here.
This diff is large: its 106 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 118 lines aren’t shown here.
This diff is large: its 669 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 228 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 267 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 790 lines aren’t shown here.
This diff is large: its 403 lines aren’t shown here.
This diff is large: its 483 lines aren’t shown here.
This diff is large: its 107 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 62 lines aren’t shown here.
This diff is large: its 151 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 126 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 171 lines aren’t shown here.
This diff is large: its 365 lines aren’t shown here.
This diff is large: its 612 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 190 lines aren’t shown here.
This diff is large: its 494 lines aren’t shown here.
This diff is large: its 237 lines aren’t shown here.
This diff is large: its 169 lines aren’t shown here.
This diff is large: its 622 lines aren’t shown here.
This diff is large: its 238 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 319 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 160 lines aren’t shown here.
This diff is large: its 133 lines aren’t shown here.
This diff is large: its 368 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 97 lines aren’t shown here.
This diff is large: its 223 lines aren’t shown here.
This diff is large: its 383 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 355 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 489 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 318 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 269 lines aren’t shown here.
This diff is large: its 168 lines aren’t shown here.
This diff is large: its 390 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 112 lines aren’t shown here.
This diff is large: its 910 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 175 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 250 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 147 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 152 lines aren’t shown here.
This diff is large: its 158 lines aren’t shown here.
This diff is large: its 335 lines aren’t shown here.
This diff is large: its 255 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 297 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 91 lines aren’t shown here.
This diff is large: its 148 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 107 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 206 lines aren’t shown here.
This diff is large: its 147 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 114 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 543 lines aren’t shown here.
This diff is large: its 292 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 263 lines aren’t shown here.
This diff is large: its 469 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 96 lines aren’t shown here.
This diff is large: its 342 lines aren’t shown here.
This diff is large: its 226 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 109 lines aren’t shown here.
This diff is large: its 319 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 251 lines aren’t shown here.
This diff is large: its 163 lines aren’t shown here.
This diff is large: its 158 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 227 lines aren’t shown here.
This diff is large: its 363 lines aren’t shown here.
This diff is large: its 562 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 447 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 605 lines aren’t shown here.
This diff is large: its 130 lines aren’t shown here.
This diff is large: its 629 lines aren’t shown here.
This diff is large: its 106 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 178 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 417 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 903 lines aren’t shown here.
This diff is large: its 181 lines aren’t shown here.
This diff is large: its 303 lines aren’t shown here.
This diff is large: its 202 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 248 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 62 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 159 lines aren’t shown here.
This diff is large: its 72 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 272 lines aren’t shown here.
This diff is large: its 95 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 284 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 271 lines aren’t shown here.
This diff is large: its 230 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 274 lines aren’t shown here.
This diff is large: its 108 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 350 lines aren’t shown here.
This diff is large: its 383 lines aren’t shown here.
This diff is large: its 101 lines aren’t shown here.
This diff is large: its 236 lines aren’t shown here.
This diff is large: its 91 lines aren’t shown here.
This diff is large: its 296 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 267 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 170 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 93 lines aren’t shown here.
This diff is large: its 274 lines aren’t shown here.
This diff is large: its 313 lines aren’t shown here.
This diff is large: its 385 lines aren’t shown here.
This diff is large: its 817 lines aren’t shown here.
This diff is large: its 146 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 137 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 158 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 115 lines aren’t shown here.
This diff is large: its 186 lines aren’t shown here.
This diff is large: its 95 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 945 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 261 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 137 lines aren’t shown here.
This diff is large: its 151 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 312 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 195 lines aren’t shown here.
This diff is large: its 93 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 109 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 277 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 180 lines aren’t shown here.
This diff is large: its 144 lines aren’t shown here.
This diff is large: its 248 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 407 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 128 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 718 lines aren’t shown here.
This diff is large: its 118 lines aren’t shown here.
This diff is large: its 149 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 176 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 333 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 197 lines aren’t shown here.
This diff is large: its 196 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 630 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 160 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 79 lines aren’t shown here.
This diff is large: its 251 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 310 lines aren’t shown here.
This diff is large: its 104 lines aren’t shown here.
This diff is large: its 187 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 188 lines aren’t shown here.
This diff is large: its 488 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 179 lines aren’t shown here.
This diff is large: its 171 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 110 lines aren’t shown here.
This diff is large: its 249 lines aren’t shown here.
This diff is large: its 163 lines aren’t shown here.
This diff is large: its 220 lines aren’t shown here.
This diff is large: its 164 lines aren’t shown here.
This diff is large: its 154 lines aren’t shown here.
This diff is large: its 127 lines aren’t shown here.
This diff is large: its 386 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 237 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 130 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 4 lines aren’t shown here.
This diff is large: its 188 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 238 lines aren’t shown here.
This diff is large: its 164 lines aren’t shown here.
This diff is large: its 114 lines aren’t shown here.
This diff is large: its 335 lines aren’t shown here.
This diff is large: its 205 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 118 lines aren’t shown here.
This diff is large: its 157 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 128 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
This diff is large: its 100 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 182 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 95 lines aren’t shown here.
This diff is large: its 711 lines aren’t shown here.
This diff is large: its 112 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 105 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 118 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
This diff is large: its 245 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 195 lines aren’t shown here.
This diff is large: its 134 lines aren’t shown here.
This diff is large: its 1359 lines aren’t shown here.
This diff is large: its 194 lines aren’t shown here.
This diff is large: its 149 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 317 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 333 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 305 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 462 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 245 lines aren’t shown here.
This diff is large: its 228 lines aren’t shown here.
This diff is large: its 122 lines aren’t shown here.
This diff is large: its 193 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 199 lines aren’t shown here.
This diff is large: its 253 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 1189 lines aren’t shown here.
This diff is large: its 148 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is larger than a page shows: the files after these aren’t listed. Clone the repository to see all of it.