+/* Returns a pointer to a memory area representing a window into the
+ * resource's data.
+ *
+ * This may or may not be the _actual_ memory area of the resource. However
+ * when calling nouveau_buffer_transfer_unmap, if it wasn't the actual memory
+ * area, the contents of the returned map are copied over to the resource.
+ *
+ * The usage indicates what the caller plans to do with the map:
+ *
+ * WRITE means that the user plans to write to it
+ *
+ * READ means that the user plans on reading from it
+ *
+ * DISCARD_WHOLE_RESOURCE means that the whole resource is going to be
+ * potentially overwritten, and even if it isn't, the bits that aren't don't
+ * need to be maintained.
+ *
+ * DISCARD_RANGE means that all the data in the specified range is going to
+ * be overwritten.
+ *
+ * The strategy for determining what kind of memory area to return is complex,
+ * see comments inside of the function.
+ */