st/xvmc: fix library installation dir

[mesa.git] / src / glsl / README

diff --git a/src/glsl/README b/src/glsl/README
index 7e97b48059cb41944c86b67c4a2c63c47f88c0f7..dd80a53d4763614c5e25e0526014433335a3c780 100644 (file)
--- a/src/glsl/README
+++ b/src/glsl/README
@@ -189,3 +189,41 @@ You may also need to update the backends if they will see the new expr type:
 You can then use the new expression from builtins (if all backends
 would rather see it), or scan the IR and convert to use your new
 expression type (see ir_mod_to_fract, for example).
 You can then use the new expression from builtins (if all backends
 would rather see it), or scan the IR and convert to use your new
 expression type (see ir_mod_to_fract, for example).

+
+Q: How is memory management handled in the compiler?
+
+The hierarchical memory allocator "talloc" developed for the Samba
+project is used, so that things like optimization passes don't have to
+worry about their garbage collection so much.  It has a few nice
+features, including low performance overhead and good debugging
+support that's trivially available.
+
+Generally, each stage of the compile creates a talloc context and
+allocates its memory out of that or children of it.  At the end of the
+stage, the pieces still live are stolen to a new context and the old
+one freed, or the whole context is kept for use by the next stage.
+
+For IR transformations, a temporary context is used, then at the end
+of all transformations, reparent_ir reparents all live nodes under the
+shader's IR list, and the old context full of dead nodes is freed.
+When developing a single IR transformation pass, this means that you
+want to allocate instruction nodes out of the temporary context, so if
+it becomes dead it doesn't live on as the child of a live node.  At
+the moment, optimization passes aren't passed that temporary context,
+so they find it by calling talloc_parent() on a nearby IR node.  The
+talloc_parent() call is expensive, so many passes will cache the
+result of the first talloc_parent().  Cleaning up all the optimization
+passes to take a context argument and not call talloc_parent() is left
+as an exercise.
+
+Q: What is the file naming convention in this directory?
+
+Initially, there really wasn't one.  We have since adopted one:
+
+ - Files that implement code lowering passes should be named lower_*
+   (e.g., lower_noise.cpp).
+ - Files that implement optimization passes should be named opt_*.
+ - Files that implement a class that is used throught the code should
+   take the name of that class (e.g., ir_hierarchical_visitor.cpp).
+ - Files that contain code not fitting in one of the previous
+   categories should have a sensible name (e.g., glsl_parser.ypp).