Skip to content
This repository
Browse code

Add the Readme as well as the formatted ops.pod.

  • Loading branch information...
commit 3489f9806257d9f4b5791274c981982a512a30de 1 parent 2ded2c9
Jon Gentle authored October 21, 2010

Showing 2 changed files with 1,477 additions and 0 deletions. Show diff stats Hide diff stats

  1. 38  Readme.pod
  2. 1,439  ops.pod
38  Readme.pod
Source Rendered
... ...
@@ -0,0 +1,38 @@
  1
+=head1 Lorito - A minimal VM prototype
  2
+
  3
+This is Lorito, a minimal VM prototype.  It was started as a refactoring of
  4
+the core of ParrotVM.
  5
+
  6
+=head2 Building Lorito
  7
+
  8
+Lorito is written in C.  The Lorito assembler is written in perl.
  9
+Today, Lorito is not written at all portable.  It assumes 32-bit, x86 linux.
  10
+That will change eventually.
  11
+A simple F<Makefile> is included, so running C<make> will produce the lorito
  12
+executable.
  13
+
  14
+=head2 Running Lorito
  15
+
  16
+  lasm.pl < file.lasm > file.ito
  17
+  lorito file.ito
  18
+
  19
+Currently Lorito is a two step process.  First you have to take an lasm file
  20
+and produce a Lorito Bytecode file (C<.ito>).  This is done with the lasm.pl
  21
+tool.  Once you have an C<.ito> you can use the compiled lorito executable
  22
+to run the bytecode.
  23
+
  24
+=head2 Other Documentation
  25
+
  26
+=over
  27
+
  28
+=item L<Design|design.pod>
  29
+
  30
+=item L<Opcodes|ops.pod>
  31
+
  32
+=back
  33
+
  34
+=head2 And remember
  35
+
  36
+Less magic == More magic
  37
+
  38
+=cut
1,439  ops.pod
Source Rendered
... ...
@@ -0,0 +1,1439 @@
  1
+=pod
  2
+
  3
+=head1 Lorito Opcode Definitions
  4
+
  5
+
  6
+=for comment
  7
+********************** WARNING **********************
  8
+******************** DO NOT EDIT ********************
  9
+THIS FILE IS AUTOMATICALLY GENERATED BY verify_ops.pl
  10
+You  probably want  to make  changes in  ops_skel.pod
  11
+********************** WARNING **********************
  12
+
  13
+=head2 Execution Ops
  14
+
  15
+
  16
+=head3 noop
  17
+
  18
+=over
  19
+
  20
+=item Valid Forms:
  21
+
  22
+Any
  23
+
  24
+=item Registers
  25
+
  26
+
  27
+None
  28
+
  29
+
  30
+=item Description
  31
+
  32
+
  33
+Do nothing.  Waste a cycle.
  34
+
  35
+
  36
+=item Reason
  37
+
  38
+
  39
+Sometimes, you just need to be lazy.
  40
+
  41
+
  42
+=back
  43
+
  44
+=head3 end
  45
+
  46
+=over
  47
+
  48
+=item Valid Forms:
  49
+
  50
+Any
  51
+
  52
+=item Registers
  53
+
  54
+
  55
+None
  56
+
  57
+
  58
+=item Description
  59
+
  60
+
  61
+Stop the interperter, cleanly.
  62
+
  63
+
  64
+=item Reason
  65
+
  66
+
  67
+Although this could be dangerous, code should have the ablity to stop
  68
+execution.
  69
+
  70
+
  71
+=back
  72
+
  73
+=head3 add
  74
+
  75
+=over
  76
+
  77
+=item Valid Forms:
  78
+
  79
+INT
  80
+
  81
+=item Registers
  82
+
  83
+
  84
+$dest, $src1, $src2
  85
+
  86
+
  87
+=item Description
  88
+
  89
+
  90
+Add $src1 and $src2 and store result in $dest.
  91
+
  92
+
  93
+=item Reason
  94
+
  95
+
  96
+Math becomes very difficult without being able to add.
  97
+
  98
+
  99
+=back
  100
+
  101
+=head3 sub
  102
+
  103
+=over
  104
+
  105
+=item Valid Forms:
  106
+
  107
+INT
  108
+
  109
+=item Registers
  110
+
  111
+
  112
+$dest, $src1, $src2
  113
+
  114
+
  115
+=item Description
  116
+
  117
+
  118
+Subtract $src1 and $src2 and store result in $dest.
  119
+
  120
+
  121
+=item Reason
  122
+
  123
+
  124
+Likewise, subtraction is vital to quick and efficient math.
  125
+
  126
+
  127
+=back
  128
+
  129
+=head3 mul
  130
+
  131
+=over
  132
+
  133
+=item Valid Forms:
  134
+
  135
+INT
  136
+
  137
+=item Registers
  138
+
  139
+
  140
+$dest, $src1, $src2
  141
+
  142
+
  143
+=item Description
  144
+
  145
+
  146
+Multiply $src1 and $src2 and store the result into $dest
  147
+
  148
+
  149
+=item Reason
  150
+
  151
+
  152
+Making multiplication a addition loop is unadvisable, no matter how minimal
  153
+you're trying to be
  154
+
  155
+
  156
+=back
  157
+
  158
+=head3 div
  159
+
  160
+=over
  161
+
  162
+=item Valid Forms:
  163
+
  164
+INT
  165
+
  166
+=item Registers
  167
+
  168
+
  169
+$dest, $src1, $src2
  170
+
  171
+
  172
+=item Description
  173
+
  174
+
  175
+Divide $src1 by $src2 and store the result in $dest.  With the Int form, only
  176
+the quotient is stored in $dest.
  177
+
  178
+
  179
+=item Reason
  180
+
  181
+
  182
+A loop of subtractions would be possible to emulate a div, but that's kind
  183
+of silly.
  184
+
  185
+
  186
+=back
  187
+
  188
+=head3 mod
  189
+
  190
+=over
  191
+
  192
+=item Valid Forms:
  193
+
  194
+INT
  195
+
  196
+=item Registers
  197
+
  198
+
  199
+$dest, $src1, $src2
  200
+
  201
+
  202
+=item Description
  203
+
  204
+
  205
+Divide $src1 by $src2 and store the remainder in $dest.
  206
+
  207
+
  208
+=item Reason
  209
+
  210
+
  211
+It's up to debate to include this instead of forcing a divide, cast, multiply
  212
+and subtract.  The speed up given by this instruction over how often some
  213
+common problems need this operator outweighs reducing the operators by one.
  214
+
  215
+
  216
+=back
  217
+
  218
+=head3 and
  219
+
  220
+=over
  221
+
  222
+=item Valid Forms:
  223
+
  224
+INT
  225
+
  226
+=item Registers
  227
+
  228
+
  229
+$dest, $src1, $src2
  230
+
  231
+
  232
+=item Description
  233
+
  234
+
  235
+Performs a binary AND on $src1 and $src2.  The result is stored in $dest.
  236
+
  237
+
  238
+=item Reason
  239
+
  240
+
  241
+AND is a basic building block of all logic.  Not including this opcode would
  242
+needlessly complicate all logic.
  243
+
  244
+
  245
+=back
  246
+
  247
+=head3 or
  248
+
  249
+=over
  250
+
  251
+=item Valid Forms:
  252
+
  253
+INT
  254
+
  255
+=item Registers
  256
+
  257
+
  258
+$dest, $src1, $src2
  259
+
  260
+
  261
+=item Description
  262
+
  263
+
  264
+Perfoms a binary OR on $src1 and $src2.  The result is stored in $dest.
  265
+
  266
+
  267
+=item Reason
  268
+
  269
+
  270
+Just like AND, OR is a basic logic building block, removing it would be
  271
+burdensome to users.
  272
+
  273
+
  274
+=back
  275
+
  276
+=head3 xor
  277
+
  278
+=over
  279
+
  280
+=item Valid Forms:
  281
+
  282
+INT
  283
+
  284
+=item Registers
  285
+
  286
+
  287
+$dest, $src1, $src2
  288
+
  289
+
  290
+=item Description
  291
+
  292
+
  293
+Perfoms a binary XOR on $src1 and $src2.  The result is stored in $dest.
  294
+
  295
+
  296
+=item Reason
  297
+
  298
+
  299
+XOR is not as fundemental as AND and OR, but simplifies a lot of operations
  300
+that would otherwise be complicated and happen often and.
  301
+
  302
+
  303
+=back
  304
+
  305
+=head3 not
  306
+
  307
+=over
  308
+
  309
+=item Valid Forms:
  310
+
  311
+INT
  312
+
  313
+=item Registers
  314
+
  315
+
  316
+$dest, $src1
  317
+
  318
+
  319
+=item Description
  320
+
  321
+
  322
+Perfoms a binary NOT on $src1.  The result is stored in $dest.
  323
+
  324
+
  325
+=item Reason
  326
+
  327
+
  328
+NOT could be emulated with XOR, and in a fairly simple manner.  It would be
  329
+replaced by two operations instead of one, a load constant and an xor.
  330
+
  331
+
  332
+=back
  333
+
  334
+=head3 shl
  335
+
  336
+=over
  337
+
  338
+=item Valid Forms:
  339
+
  340
+INT
  341
+
  342
+=item Registers
  343
+
  344
+
  345
+$dest, $src1, $src2
  346
+
  347
+
  348
+=item Description
  349
+
  350
+
  351
+Shifts the bits in $src1 by $src2 bits to the left and stores the result in
  352
+$dest.
  353
+
  354
+
  355
+=item Reason
  356
+
  357
+
  358
+=back
  359
+
  360
+=head3 shr
  361
+
  362
+=over
  363
+
  364
+=item Valid Forms:
  365
+
  366
+INT
  367
+
  368
+=item Registers
  369
+
  370
+
  371
+$dest, $src1, $src2
  372
+
  373
+
  374
+=item Description
  375
+
  376
+
  377
+Shifts the bits in $src1 by $src2 bits to the right and stores the result in
  378
+$dest.
  379
+
  380
+
  381
+=item Reason
  382
+
  383
+
  384
+=back
  385
+
  386
+=head2 Comparison Ops
  387
+
  388
+
  389
+=head3 iseq
  390
+
  391
+=over
  392
+
  393
+=item Valid Forms:
  394
+
  395
+STR
  396
+INT
  397
+
  398
+=item Registers
  399
+
  400
+
  401
+INT($dest), $src1, $src2
  402
+
  403
+
  404
+=item Description
  405
+
  406
+
  407
+This is the equals operator.  It takes $src1 and $src2 and checks if they are
  408
+equal and sets INT($dest) to 1 or 0, depending if they are equal or not.
  409
+For INT and NUM, it does a mathmatical equavalance.  For STR, it will return
  410
+1 if the two STRs are identical.  For PMC, the two PMCs must point to the
  411
+exact same PMC.
  412
+
  413
+
  414
+=item Reason
  415
+
  416
+
  417
+We could use a logical operator for the INT version of iseq, but that would not
  418
+work for NUM, STR and PMC.
  419
+
  420
+
  421
+=back
  422
+
  423
+=head3 isgt
  424
+
  425
+=over
  426
+
  427
+=item Valid Forms:
  428
+
  429
+INT
  430
+
  431
+=item Registers
  432
+
  433
+
  434
+INT($dest), $src1, $src2
  435
+
  436
+
  437
+=item Description
  438
+
  439
+
  440
+Comparse $src1 and $src2.  If $src1 is greater than $src2, it sets INT($dest)
  441
+to 1, otherwise it sets INT($dest) to 0.
  442
+
  443
+
  444
+=item Reason
  445
+
  446
+
  447
+This really has no alternative but to be included.  The less than version has
  448
+been left out since it can be reasonably done by simply reversing $src1 and
  449
+$src2.
  450
+
  451
+
  452
+=back
  453
+
  454
+=head3 isge
  455
+
  456
+=over
  457
+
  458
+=item Valid Forms:
  459
+
  460
+INT
  461
+
  462
+=item Registers
  463
+
  464
+
  465
+INT($dest), $src1, $src2
  466
+
  467
+
  468
+=item Description
  469
+
  470
+
  471
+This operator is identical to isgt, except it will also set INT($dest) to 1
  472
+if $src1 and $src2 are equal.
  473
+
  474
+
  475
+=item Reason
  476
+
  477
+
  478
+This might have been left out in favor of checking isgt and iseq.  But that
  479
+would be ineffecient compared to adding one more op to the group.
  480
+
  481
+Just like isgt, isle is not included since it is easy to emulate by reversing
  482
+$src1 and $src2.
  483
+
  484
+
  485
+=back
  486
+
  487
+=head2 Flow Control Ops
  488
+
  489
+
  490
+=head3 goto
  491
+
  492
+=over
  493
+
  494
+=item Valid Forms:
  495
+
  496
+Any
  497
+
  498
+=item Registers
  499
+
  500
+
  501
+$imm
  502
+
  503
+
  504
+=item Description
  505
+
  506
+
  507
+Takes an $imm address and moves the program counter there.  Execution will
  508
+start there as the next instruction.
  509
+
  510
+Note that this does not cross code block bounds.
  511
+
  512
+
  513
+=item Reason
  514
+
  515
+
  516
+The machine needs to be able to branch unconditionaly.  While it might be
  517
+possible to get away with only if, goto gives some optimzation possiblities.
  518
+
  519
+
  520
+=back
  521
+
  522
+=head3 if
  523
+
  524
+=over
  525
+
  526
+=item Valid Forms:
  527
+
  528
+INT
  529
+
  530
+=item Registers
  531
+
  532
+
  533
+$src1, $imm
  534
+
  535
+
  536
+=item Description
  537
+
  538
+
  539
+Checks $src1 to be 0.  If it is 0, the program counter is unchanged, otherwise
  540
+the program counter is changed to the value in $imm.
  541
+
  542
+
  543
+=item Reason
  544
+
  545
+
  546
+Without doing very complicated things with call, this is the only other way
  547
+to do conditional branching.  Therfore, it is extremely vital.
  548
+
  549
+
  550
+=back
  551
+
  552
+=head2 Register Manipulation Ops
  553
+
  554
+
  555
+=head3 set
  556
+
  557
+=over
  558
+
  559
+=item Valid Forms:
  560
+
  561
+PMC
  562
+STR
  563
+NUM
  564
+INT
  565
+
  566
+=item Registers
  567
+
  568
+
  569
+=item Description
  570
+
  571
+
  572
+=item Reason
  573
+
  574
+
  575
+=back
  576
+
  577
+=head3 load_const
  578
+
  579
+=over
  580
+
  581
+=item Valid Forms:
  582
+
  583
+STR
  584
+INT
  585
+
  586
+=item Registers
  587
+
  588
+
  589
+$dest, INT($src1), INT($src2), $imm
  590
+
  591
+
  592
+=item Description
  593
+
  594
+
  595
+This operator will load data from the context data block into a register.
  596
+The data loaded will start at $src1+$imm and will read $src2 bytes and store
  597
+the results into $dest.
  598
+
  599
+In the case that INT($src2) is 0, the "natural" length will be read.  For
  600
+STR, the number of bytes until the first null charecter that is found is used 
  601
+as the length.  For INT, the natueral length is 4 bytes, and NUM is 8 bytes.
  602
+
  603
+
  604
+=item Example
  605
+
  606
+
  607
+  $S1 = STR LOAD_CONST :[method_ok]
  608
+
  609
+This will take the string starting at method_ok in the data block and read
  610
+the entire string until a null charecter or the end of the block into the
  611
+$S1 register.
  612
+
  613
+  $I1 = INT LOAD_IMM :4;
  614
+  $I2 = INT LOAD_IMM :2;
  615
+  $I3 = INT LOAD_CONST $I1, $I2;
  616
+
  617
+This will load the first two bytes ($I2) starting at the fourth byte ($I1)
  618
+of the data block and store the integer into $I3.
  619
+
  620
+
  621
+=item Reason
  622
+
  623
+
  624
+Loading constants from the data block is the only way that you can do useful
  625
+stuff with by any manner of effenceny.
  626
+
  627
+However, this might be obsolete with a constant PMC that you can load from
  628
+the context.
  629
+
  630
+
  631
+=back
  632
+
  633
+=head3 load_imm
  634
+
  635
+=over
  636
+
  637
+=item Valid Forms:
  638
+
  639
+INT
  640
+
  641
+=item Registers
  642
+
  643
+
  644
+$dest, $imm
  645
+
  646
+
  647
+=item Description
  648
+
  649
+
  650
+Loads an immediate value from $imm into a register.  Because of the size of
  651
+$imm, the only registers you can load this way are INT types.
  652
+
  653
+
  654
+=item Example
  655
+
  656
+
  657
+  $I1 = INT LOAD_IMM :4;
  658
+
  659
+Loads the number 4 into the register $I1.
  660
+
  661
+
  662
+=item Reason
  663
+
  664
+
  665
+Without the ablity to have and load immediate values, loading data into
  666
+registers becomes cumbersome, difficult and complex.
  667
+
  668
+
  669
+=back
  670
+
  671
+=head3 coerce_int
  672
+
  673
+=over
  674
+
  675
+=item Valid Forms:
  676
+
  677
+PMC
  678
+INT
  679
+
  680
+=item Registers
  681
+
  682
+
  683
+$dest, INT($src1)
  684
+
  685
+
  686
+=item Description
  687
+
  688
+
  689
+Convert the int in INT($src1) into the form of $dest and stores the result into
  690
+$dest.
  691
+
  692
+Can also be used to copy data between registers.
  693
+
  694
+
  695
+=item Example
  696
+
  697
+
  698
+  $P1 = PMC COERCE_INT $I1;
  699
+
  700
+$P1 will contain a boxed integer.
  701
+
  702
+
  703
+=item Reason
  704
+
  705
+
  706
+This is the basic form of integer casting.  In order to load data from another
  707
+type, some kind of basic casting is required.  Without this, there would be
  708
+no way to do any kind of casting.
  709
+
  710
+
  711
+=back
  712
+
  713
+=head3 coerce_num
  714
+
  715
+=over
  716
+
  717
+=item Valid Forms:
  718
+
  719
+Any
  720
+
  721
+=item Registers
  722
+
  723
+
  724
+$dest, NUM($src1)
  725
+
  726
+
  727
+=item Description
  728
+
  729
+
  730
+Convert the floating point number in NUM($src1) into the form of $dest and
  731
+stores the result into $dest.
  732
+
  733
+Can also be used to copy data between registers.
  734
+
  735
+
  736
+=item Example
  737
+
  738
+
  739
+  $S1 = STR COERCE_NUM $N1;
  740
+
  741
+$N1 will contain string version of $N1.
  742
+
  743
+
  744
+=item Reason
  745
+
  746
+
  747
+Just like the integer casting, we need a way to cast from a number to any
  748
+other type.
  749
+
  750
+
  751
+=back
  752
+
  753
+=head3 coerce_str
  754
+
  755
+=over
  756
+
  757
+=item Valid Forms:
  758
+
  759
+Any
  760
+
  761
+=item Registers
  762
+
  763
+
  764
+$dest, STR($src1)
  765
+
  766
+
  767
+=item Description
  768
+
  769
+
  770
+Convert the string in STR($src1) into the form of $dest and stores the result
  771
+into $dest.
  772
+
  773
+Can also be used to copy data between registers.
  774
+
  775
+
  776
+=item Example
  777
+
  778
+
  779
+  $I1 = NUM COERCE_STR $S1;
  780
+
  781
+$I1 will contain the integer version of $S1.
  782
+
  783
+
  784
+=item Reason
  785
+
  786
+
  787
+Just like the integer casting, we need a way to cast from a string to any
  788
+other type.
  789
+
  790
+
  791
+=back
  792
+
  793
+=head2 PMC Ops
  794
+
  795
+
  796
+=head3 new
  797
+
  798
+=over
  799
+
  800
+=item Valid Forms:
  801
+
  802
+PMC
  803
+INT
  804
+
  805
+=item Registers
  806
+
  807
+
  808
+PMC($dest), $src1, $imm
  809
+
  810
+
  811
+=item Description
  812
+
  813
+
  814
+This creates a new PMC.  The operation of creating the PMC depends on the 
  815
+type of $src1:
  816
+
  817
+
  818
+
  819
+=item Reason
  820
+
  821
+
  822
+This operator is required since there is no other reasonable way to create new
  823
+PMCs without it.
  824
+
  825
+
  826
+=back
  827
+
  828
+=head3 store
  829
+
  830
+=over
  831
+
  832
+=item Valid Forms:
  833
+
  834
+PMC
  835
+NUM
  836
+INT
  837
+
  838
+=item Registers
  839
+
  840
+
  841
+PMC($dest), $src1, INT($src2), $imm
  842
+
  843
+
  844
+=item Description
  845
+
  846
+
  847
+Store a register into a PMC at a particular address.  The first $imm bytes of
  848
+of the data in $src1 is placed into the $dest PMC at address $src2.  If the
  849
+type of $src1 is an INT or NUM, the INT or NUM is stored.  If $src1 is a PMC,
  850
+a refrence to the PMC is stored in the pmc_ptr table and the slot number used
  851
+is written.
  852
+
  853
+
  854
+=item Example
  855
+
  856
+
  857
+  $I1 = INT LOAD_IMM :4;
  858
+  $P1 = INT STORE $I1, $I1, :2;
  859
+
  860
+Store the first 2 bytes of the integer 4 at address 4 of $P1 data area.
  861
+
  862
+  $I1 = INT LOAD_IMM :8;
  863
+  $P2 = PMC STORE $P1, $I1;
  864
+ 
  865
+Stores $P1 into the pmc_ptr table and stores the slot number starting at byte
  866
+8 of $P2 data area.
  867
+
  868
+
  869
+=item Reason
  870
+
  871
+
  872
+A fundamental part of the operation of PMCs is the ablity to treat them as
  873
+simple chunks of data.  There has to be a fast, effecient way to store data
  874
+into a PMC.
  875
+
  876
+
  877
+=back
  878
+
  879
+=head3 load
  880
+
  881
+=over
  882
+
  883
+=item Valid Forms:
  884
+
  885
+PMC
  886
+NUM
  887
+INT
  888
+
  889
+=item Registers
  890
+
  891
+
  892
+$dest, PMC($src1), INT($src2), $imm
  893
+
  894
+
  895
+=item Description
  896
+
  897
+
  898
+Load data in a PMC into a register.  This is the opposite of a store.  The
  899
+first $imm bytes of the data in $src1 at offset $src2 are loaded into $dest.
  900
+If $dest is an INT or NUM, the INT or NUM is loaded into the register.  If
  901
+$dest is a PMC, length is ignored and the integer at offset $src2 is used to
  902
+lookup the PMC in the pmc_ptr table, and is loaded into $dest.
  903
+
  904
+
  905
+=item Example
  906
+
  907
+
  908
+  $I1 = INT LOAD_IMM :4;
  909
+  $I2 = INT LOAD $P1, $I1, :2;
  910
+
  911
+Load the first 2 bytes of $P1 at address 4 into $I2.
  912
+
  913
+  $I1 = INT LOAD_IMM :8;
  914
+  $P2 = PMC LOAD $P1, $I1;
  915
+
  916
+Loads the PMC refrenced in the pmc_ptr by the integer stored at byte 8 in $P1
  917
+into $P2.
  918
+
  919
+
  920
+=item Reason
  921
+
  922
+
  923
+If it's possible to put data into a PMC, then it is only reasonable to be
  924
+able to get the data back out in a quick and effecient manner.
  925
+
  926
+
  927
+=back
  928
+
  929
+=head3 push_arg
  930
+
  931
+=over
  932
+
  933
+=item Valid Forms:
  934
+
  935
+PMC
  936
+INT
  937
+
  938
+=item Registers
  939
+
  940
+
  941
+PMC($src1), $src2
  942
+
  943
+
  944
+=item Description
  945
+
  946
+
  947
+Take $src2, box it as a PMC, and push it onto the argument stack for the
  948
+context PMC($src1).  If PMC($src1) is null, the current context is used.  The 
  949
+argument stack should be used for arguments and return values.
  950
+
  951
+
  952
+=item Reason
  953
+
  954
+
  955
+There were two options for passing arguments between function calls.  Either
  956
+arguments are passed in registers or passed on a stack.  Since passing 
  957
+arguments in registers meant that register pools are leaked between function
  958
+calls, that's less than desirable.  So, the decision was to make everything
  959
+a PMC and have an argument stack.
  960
+
  961
+
  962
+=back
  963
+
  964
+=head3 pop_arg
  965
+
  966
+=over
  967
+
  968
+=item Valid Forms:
  969
+
  970
+PMC
  971
+STR
  972
+INT
  973
+
  974
+=item Registers
  975
+
  976
+
  977
+$dest, PMC($src1)
  978
+
  979
+
  980
+=item Description
  981
+
  982
+
  983
+Pop the next argument off the top of the argument stack for the context in
  984
+PMC($src1) and store it in $dest, unboxing it if it is not a PMC.  If 
  985
+PMC($src1) is null, the current context is used.
  986
+
  987
+
  988
+=item Reason
  989
+
  990
+
  991
+This operator exists since push_arg exists.  What use is an argument stack
  992
+if you can never retrieve the arguments.
  993
+
  994
+
  995
+=back
  996
+
  997
+=head3 call
  998
+
  999
+=over
  1000
+
  1001
+=item Valid Forms:
  1002
+
  1003
+Any
  1004
+
  1005
+=item Registers
  1006
+
  1007
+
  1008
+PMC($src1)
  1009
+
  1010
+
  1011
+=item Description
  1012
+
  1013
+
  1014
+Invoke the context in PMC($src1) by setting it as the current context.
  1015
+
  1016
+
  1017
+=item Reason
  1018
+
  1019
+
  1020
+This is the key operator that allows changing of current context, and thus
  1021
+the ablity to change which code block is running.
  1022
+
  1023
+
  1024
+=back
  1025
+
  1026
+=head2 Environment Ops
  1027
+
  1028
+
  1029
+=head3 loadlib
  1030
+
  1031
+=over
  1032
+
  1033
+=item Valid Forms:
  1034
+
  1035
+Any
  1036
+
  1037
+=item Registers
  1038
+
  1039
+
  1040
+PMC($dest), $src1
  1041
+
  1042
+
  1043
+=item Description
  1044
+
  1045
+
  1046
+Take the library refrenced by $src1, make sure it has been loaded into the
  1047
+virtual machine, and put a refrence to the file PMC in PMC($dest).
  1048
+
  1049
+At this point, $src2 is the file name of the library.
  1050
+
  1051
+
  1052
+=item Reason
  1053
+
  1054
+
  1055
+This allows the loading and inspection of outside libraries.
  1056
+
  1057
+
  1058
+=back
  1059
+
  1060
+=head3 read
  1061
+
  1062
+=over
  1063
+
  1064
+=item Valid Forms:
  1065
+
  1066
+Any
  1067
+
  1068
+=item Registers
  1069
+
  1070
+
  1071
+$dest
  1072
+
  1073
+
  1074
+=item Description
  1075
+
  1076
+
  1077
+Read from the input and put the value read into $dest.
  1078
+
  1079
+
  1080
+=item Reason
  1081
+
  1082
+
  1083
+This is a bootstrap op, and may not be available long term.
  1084
+
  1085
+
  1086
+=back
  1087
+
  1088
+=head3 write
  1089
+
  1090
+=over
  1091
+
  1092
+=item Valid Forms:
  1093
+
  1094
+STR
  1095
+INT
  1096
+
  1097
+=item Registers
  1098
+
  1099
+
  1100
+$src1
  1101
+
  1102
+
  1103
+=item Description
  1104
+
  1105
+
  1106
+Print the value in $src1 to the output device.
  1107
+
  1108
+
  1109
+=item Reason
  1110
+
  1111
+
  1112
+This is a bootstrap op, and may not be available long term.
  1113
+
  1114
+
  1115
+=back
  1116
+
  1117
+=head3 say
  1118
+
  1119
+=over
  1120
+
  1121
+=item Valid Forms:
  1122
+
  1123
+STR
  1124
+INT
  1125
+
  1126
+=item Registers
  1127
+
  1128
+
  1129
+$src1
  1130
+
  1131
+
  1132
+=item Description
  1133
+
  1134
+
  1135
+Print the value in $src1, along with a line terminator, to the output device.
  1136
+
  1137
+
  1138
+=item Reason
  1139
+
  1140
+
  1141
+This is a bootstrap op, and may not be available long term.
  1142
+
  1143
+
  1144
+=back
  1145
+
  1146
+=head3 gripe
  1147
+
  1148
+=over
  1149
+
  1150
+=item Valid Forms:
  1151
+
  1152
+STR
  1153
+INT
  1154
+
  1155
+=item Registers
  1156
+
  1157
+
  1158
+$src1
  1159
+
  1160
+
  1161
+=item Description
  1162
+
  1163
+
  1164
+Print the value in $src1 to the error device.
  1165
+
  1166
+
  1167
+=item Reason
  1168
+
  1169
+
  1170
+This is a bootstrap op, and may not be available long term.
  1171
+
  1172
+
  1173
+=back
  1174
+
  1175
+=head2 PMC Ops
  1176
+
  1177
+
  1178
+=head3 lookup
  1179
+
  1180
+=over
  1181
+
  1182
+=item Valid Forms:
  1183
+
  1184
+STR
  1185
+
  1186
+=item Registers
  1187
+
  1188
+
  1189
+PMC($dest), PMC($src1), $src2
  1190
+
  1191
+
  1192
+=item Description
  1193
+
  1194
+
  1195
+Perform a lookup on the PMC in $src1.  This will invoke the lookup function 
  1196
+that is associated with the PMC.  This function will be passed the PMC, the
  1197
+vtable saved in the PMC and the boxed paramater passed in $src2.  Once the
  1198
+lookup function returns, $dest will hold a code PMC.
  1199
+
  1200
+
  1201
+=item Example
  1202
+
  1203
+
  1204
+  $S1 = STR LOAD_CONST :[method_a];
  1205
+  $P2 = STR LOOKUP $P1, $S1;
  1206
+
  1207
+This loads the constant string of method_a into $S1 and uses it to lookup
  1208
+up the method by that name in $P1.  $P2 is the method by that name, or null.
  1209
+
  1210
+
  1211
+=item Reason
  1212
+
  1213
+
  1214
+Lorito should not force a particular object model, so a simple compromise
  1215
+was made.  Whichever object model is used for a PMC is able to install and
  1216
+use a custom lookup method by implementing this call on a PMC.  This gives
  1217
+all users of the PMC the ablity to invoke any method of a PMC/object without
  1218
+having to know and understand the object model.  
  1219
+
  1220
+Also, lookups happen a lot in a dynamic language.  As such, having this
  1221
+operator simplifies and speeds up the process of doing method lookups.
  1222
+
  1223
+
  1224
+=back
  1225
+
  1226
+=head3 ctx
  1227
+
  1228
+=over
  1229
+
  1230
+=item Valid Forms:
  1231
+
  1232
+PMC
  1233
+
  1234
+=item Registers
  1235
+
  1236
+
  1237
+$dest
  1238
+
  1239
+
  1240
+=item Description
  1241
+
  1242
+
  1243
+Retrieve the current context PMC and puts it into $dest.
  1244
+
  1245
+
  1246
+=item Reason