[Scummvm-cvs-logs] SF.net SVN: scummvm:[52124] scummvm/branches/gsoc2010-plugins/backends/ plugins

[toneman1138 at users.sourceforge.net]

Revision: 52124
          http://scummvm.svn.sourceforge.net/scummvm/?rev=52124&view=rev
Author:   toneman1138
Date:     2010-08-16 16:32:06 +0000 (Mon, 16 Aug 2010)

Log Message:
-----------
Added doxygen comments for a few different plugin-related classes

Modified Paths:
--------------
    scummvm/branches/gsoc2010-plugins/backends/plugins/elf-loader.h
    scummvm/branches/gsoc2010-plugins/backends/plugins/elf-provider.h
    scummvm/branches/gsoc2010-plugins/backends/plugins/shorts-segment-manager.h

Modified: scummvm/branches/gsoc2010-plugins/backends/plugins/elf-loader.h
===================================================================
--- scummvm/branches/gsoc2010-plugins/backends/plugins/elf-loader.h	2010-08-16 16:01:31 UTC (rev 52123)
+++ scummvm/branches/gsoc2010-plugins/backends/plugins/elf-loader.h	2010-08-16 16:32:06 UTC (rev 52124)
@@ -32,6 +32,13 @@
 #include "common/stream.h"
 #include "backends/plugins/dynamic-plugin.h"
 
+/**
+ * DLObject
+ *
+ * Class that most directly handles operations on a plugin file
+ * (opening it for reading, loading/unloading it in memory, finding a specific symbol in the file, etc.)
+ * Subclasses have the same functionality, but implementations specific to different processors/platforms.
+ */
 class DLObject {
 protected:
     void *_segment, *_symtab;

Modified: scummvm/branches/gsoc2010-plugins/backends/plugins/elf-provider.h
===================================================================
--- scummvm/branches/gsoc2010-plugins/backends/plugins/elf-provider.h	2010-08-16 16:01:31 UTC (rev 52123)
+++ scummvm/branches/gsoc2010-plugins/backends/plugins/elf-provider.h	2010-08-16 16:32:06 UTC (rev 52124)
@@ -34,6 +34,15 @@
 
 #include "backends/plugins/elf-loader.h"
 
+/**
+ * ELFPlugin
+ *
+ * Objects of this class are returned when the PluginManager calls
+ * getPlugins() on an ELFPluginProvider. An intermediary class for
+ * dealing with plugin files, ELFPlugin is responsible for creating/destroying
+ * a DLObject that handles the opening/loading/unloading of the plugin file whose
+ * path in the target backend's file system is "_filename".
+ */
 class ELFPlugin : public DynamicPlugin {
 protected:
 	DLObject *_dlHandle;

Modified: scummvm/branches/gsoc2010-plugins/backends/plugins/shorts-segment-manager.h
===================================================================
--- scummvm/branches/gsoc2010-plugins/backends/plugins/shorts-segment-manager.h	2010-08-16 16:01:31 UTC (rev 52123)
+++ scummvm/branches/gsoc2010-plugins/backends/plugins/shorts-segment-manager.h	2010-08-16 16:32:06 UTC (rev 52124)
@@ -35,10 +35,19 @@
 #define ShortsMan ShortSegmentManager::instance()
 
 /**
- * Manages the segments of small data put in the gp-relative area for MIPS processors,
- * and lets these segments be handled differently in the ELF loader.
+ * ShortSegmentManager
+ *
+ * Since MIPS is limited to 32 bits per instruction, loading data that's further away than 16 bits
+ * takes several instructions. Thus, small global data (which is likely to be accessed a lot from
+ * multiple locations) is often put into a GP-relative area (GP standing for the global pointer register)
+ * in MIPS processors. This class manages these segments of small global data, and is used by the
+ * member functions of MIPSDLObject, which query in information from this manager in order to deal with
+ * this segment during the loading/unloading of plugins.
+ *
  * Since there's no true dynamic linker to change the GP register between plugins and the main engine,
- * custom linker scripts ensure the GP-area is in the same place for both.
+ * custom ld linker scripts for both the main executable and the plugins ensure the GP-area is in the
+ * same place for both. The ShortSegmentManager accesses this place via the symbols __plugin_hole_start
+ * and __plugin_hole_end, which are defined in those custom ld linker scripts.
  */
 class ShortSegmentManager : public Common::Singleton<ShortSegmentManager> {
 private:


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.