Permalink
Browse files

add some likely-incomplete docs on adding ops to m0

  • Loading branch information...
1 parent 8d65bf2 commit 5322196ac65bd8416bd9ac44ef34ec189e5e56db @cotto cotto committed Jun 6, 2012
Showing with 74 additions and 0 deletions.
  1. +74 −0 src/m0/adding_ops.pod
View
74 src/m0/adding_ops.pod
@@ -0,0 +1,74 @@
+# Copyright (C) 2012, Parrot Foundation.
+
+=head1 NAME
+
+src/m0/adding_ops.pod - how to add ops to M0
+
+=head1 When to add ops
+
+M0 is designed to be a minimal VM. It's not generally out of the question to
+add a new op, but think carefully before doing so. Ops can be added under one
+or more of the following circumstancxes:
+
+=over
+
+=item * The M0 VM is not capable of performing an operation with a new op with reasonable efficiency.
+
+=item * Probably some other reasons.
+
+=back
+
+=head1 How to add ops
+
+The canonical list of M0 ops lives in src/m0/m0.ops. Wherever possible, m0
+assemblers and interpreters should use the ops and ordering of that file.
+Currently some do and some don't. Patches are welcome. In the meantime, not
+that not everything is consistent.
+
+=over
+
+=item * Add your op to the spec in docs/pdd/drafts/pdd32_m0.pod.
+
+If you have questions as to whether the op is a good idea, ask cotto or
+dukeleto. If they're not available, ask someone else or add it anyway.
+
+=item * Add your op to src/m0/m0.ops.
+
+=item * Run tools/dev/m0_opcheck.pl
+
+This currently updates the Perl 5 assembler and interpreter to ensure that op
+ordering is consistent. The Perl 5 assembler needs no further changes.
+
+=item * Add op functions to the Perl 5 interpreter.
+
+m0_opcheck.pl adds a reference to the m0 op function that should exist. Its
+name will be in the form "m0_opfunc_x", where x is the name of the new op. Add
+a sub with that name and the implementation of the function.
+
+=item * Add a test.
+
+Add a test for the new op to t/m0/integraton/. Cover basic functionality and
+any edge cases you can think of. Register name aliases can be used to make the
+test more readable and easier to write.
+
+t/m0_integration.t will test all .m0 files in t/m0/integration. If your test
+doesn't require any special invocation (e.g. passing arguments), adding it to
+t/m0_integration is sufficient to get it tested as part of the m0_tests
+makefile target.
+
+=item * Make the test pass.
+
+Run make m0_tests to test the Perl 5 implementation.
+
+=item * Update C-m0.
+
+The c-m0 ops enum is in src/m0/c/m0.h . The op functions and runloop live in
+src/m0/c/ops.c. The C-m0 runloop is switch-based, so look for a switch to see
+where to add the new op. The runloop uses the M0_EXEC_OP macro, so looking for
+the op function name won't be of much help.
+
+=item * Make the C-m0 tests pass.
+
+Run make m0_c_tests to run the m0 test suite against C-m0.
+
+=cut

0 comments on commit 5322196

Please sign in to comment.