Add basic documentation on function modeling (#386)

* Add basic models docs

* Phrasing

* Minor fixes

docs/api.rst

@@ -1,5 +1,5 @@
-API
-===
+API Reference
+=============
 
 
 This API is under active development, and should be considered unstable.

docs/index.rst

@@ -8,6 +8,7 @@ Manticore is a prototyping tool for dynamic binary analysis, with support for sy
    :caption: Contents:
 
    api
+   models
 
 
 Indices and tables

docs/models.rst

@@ -0,0 +1,29 @@
+Function Models
+===============
+
+The Manticore function modeling API can be used to override a certain
+function in the target program with a custom implementation in Python.
+This can greatly increase performance.
+
+Manticore comes with implementations of function models for some common library routines (core models),
+and also offers a user API for defining user-defined models.
+
+To use a core model, use the :meth:`~manticore.core.state.State.invoke_model` API. The
+available core models are documented in the API Reference::
+
+    from manticore.models import strcmp
+    addr_of_strcmp = 0x400510
+    @m.hook(addr_of_strcmp)
+    def strcmp_model(state):
+        state.invoke_model(strcmp)
+
+To implement a user-defined model, implement your model as a Python function, and pass it to
+:meth:`~manticore.core.state.State.invoke_model`. See the
+:meth:`~manticore.core.state.State.invoke_model` documentation for more. The
+`core models <https://github.com/trailofbits/manticore/blob/master/manticore/models.py>`_
+are also good examples to look at and use the same external user API.
+
+
+
+
+

manticore/core/state.py

@@ -359,6 +359,8 @@ class State(object):
         function, the following arguments correspond to the arguments of the C function
         being modeled. If the `model` models a variadic function, the following argument
         is a generator object, which can be used to access function arguments dynamically.
+        The `model` callable should simply return the value that should be returned by the
+        native function being modeled.
 
         :param callable model: Model to invoke
         '''