Part of Slepp's ProjectsPastebinTURLImagebinFilebin
Feedback -- English French German Japanese
Create Upload Newest Tools Donate
Sign In | Create Account


Friday, April 13th, 2007 at 8:45:08am UTC 

  1. <html>
  2. <head>
  3. <title>Rockbox plugin memory layout</title>
  4. <style type="text/css">
  5. table { border-width: thin; border-style: solid; border-color:grey; }
  6. td { border-width: thin; border-style: solid; border-color:grey; vertical-align: top; }
  7. </style>
  9. </head>
  11. <body>
  13. <h1>Rockbox plugin memory layout</h1>
  15. <p>A plugin contains following segments:</p>
  17. <table>
  18.         <tr>
  19.                 <td>.header</td>
  20.                 <td>The plugin header structure (see apps/plugin.h)</td>
  21.         </tr>
  22.         <tr>
  23.                 <td>.text</td>
  24.                 <td>Executable code</td>
  25.         </tr>
  26.         <tr>
  27.                 <td>.rodata</td>
  28.                 <td>Initialised read only data (e.g. string constants or const structs)</td>
  29.         </tr>
  30.         <tr>
  31.                 <td>.data</td>
  32.                 <td>Initialised data (e.g. global variables with assignment)</td>
  33.         </tr>
  34.         <tr>
  35.                 <td>.bss</td>
  36.                 <td>Not initialised data (e.g. global variables without assignment)</td>
  37.         </tr>
  38. </table>
  40. <p>There are also some special segments that contain data that are eventually loaded to IRAM:</p>
  42. <table>
  43.         <tr>
  44.                 <td>.iram</td>
  45.                 <td>Consists of .icode (executable code in IRAM), .irodata (initialised read only data in IRAM), .idata (initialised data in IRAM)</td>
  46.         </tr>
  47.         <tr>
  48.                 <td>.ibss</td>
  49.                 <td>Not initialised data in IRAM</td>
  50.         </tr>
  51. </table>
  53. <p>IRAM is a special memory area (fixed addresses) that can be accessed by the CPU very quickly. If a variable must be read or modified very often it should be placed to IRAM. This can be made by adding the following attributes to the declaration:</p>
  55. <ul>
  56.         <li>For a variable: IDATA_ATTR</li>
  57.         <li>For a function: ICODE_ATTR</li>
  58. </ul>
  60. <p>Examples:</p>
  62. <ul>
  63.         <li>static struct dsp_config *dsp IDATA_ATTR = audio_dsp;</li>
  64.         <li>static void pcmbuf_callback(unsigned char** start, size_t* size) ICODE_ATTR;</li>
  65. </ul>
  67. <p>Following symbols are declared during the linkage (see plugins/</p>
  69. <table>
  70.         <tr>
  71.                 <td>plugin_start_addr</td>
  72.                 <td>Start address of the .header section. Since .header is the first section (see below) this is also the address where the plugin is loaded</td>
  73.         </tr>
  74.         <tr>
  75.                 <td>iramcopy</td>
  76.                 <td>Address where the .iram section of the plugin is loaded into memory. This is iimediately after the end of the .data section</td>
  77.         </tr>
  78.         <tr>
  79.                 <td>iramstart</td>
  80.                 <td>Start address of the plugin's .iram section (relocation address).</td>
  81.         </tr>
  82.         <tr>
  83.                 <td>iramend</td>
  84.                 <td>End address of the plugin's .iram section (relocation address). iramend-iramstart will give the size of the plugin's read only data (including code and vars).</td>
  85.         </tr>
  86.         <tr>
  87.                 <td>iedata</td>
  88.                 <td>Start address of the plugin's .ibss section (relocation address)</td>
  89.         </tr>
  90.         <tr>
  91.                 <td>iend</td>
  92.                 <td>End address of the plugin's .ibss section (relocation address). iend-iedata will give the size of the plugin's .ibss section</td>
  93.         </tr>
  94.         <tr>
  95.                 <td>plugin_bss_start</td>
  96.                 <td>Start address of the plugin's .bss section</td>
  97.         </tr>
  98.         <tr>
  99.                 <td>plugin_end_addr</td>
  100.                 <td>End address of the plugin's .bss section. plugin_end_addr- plugin_bss_start will give the size of the plugin's .bss section. Since .bss is the last section (see below) this is also the address where plugin ends when it's loaded into the RAM </td>
  101.         </tr>
  102. </table>
  104. <p>The relocation address of the .iram section is the start of the IRAM area in the RAM. But when the plugin is loaded, its .iram section is loaded to another address (iramcopy).</p>
  106. <p>The sections described above are laid out in memory as follows (this is how the RAM area into which the plugin is loaded looks like after the plugin has been loaded to RAM; this RAM area is actually the buffer pluginbuf, see apps/plugin.c):</p>
  108. <table>
  109.         <tr>
  110.                 <td>.header</td>
  111.                 <td>&larr; plugin_start_addr</td>
  112.         </tr>
  113.         <tr>
  114.                 <td>.text</td>
  115.                 <td></td>
  116.         </tr>
  117.         <tr>
  118.                 <td>.rodata</td>
  119.                 <td></td>
  120.         </tr>
  121.         <tr>
  122.                 <td>.data</td>
  123.                 <td></td>
  124.         </tr>
  125.         <tr>
  126.                 <td>.iram<br></td>
  127.                 <td>&larr; iramcopy</td>
  128.         </tr>
  129.         <tr>
  130.                 <td>.ibss</td>
  131.                 <td></td>
  132.         </tr>
  133.         <tr>
  134.                 <td>.bss<br></td>
  135.                 <td>&larr; plugin_bss_start<br>&larr; plugin_bss_end</td>
  136.         </tr>
  137. </table>
  139. <p>If the plugin makes use of IRAM (code or data), one of the first actions in the plugin code should be a call to PLUGIN_IRAM_INIT(api). This copies the contents of the plugin's .iram section (which is pointed to by iramcopy) to the IRAM area and then zeroes out the area of RAM that contained the plugin's .iram and .ibss sections. After the call, the arrays iramcopy (its size is iramend-iramstart) and iedata (its size is iend-iedata) can be used by the plugin at will. If the plugin doesn’t make use of IRAM, iramend will be equal to iramstart and iend will be equal to iedata.</p>
  141. <p>After the call to PLUGIN_IRAM_INIT(api), the RAM looks as follows:</p>
  143. <table>
  144.         <tr><td bgcolor="lightgrey">Lower addresses</td></tr>
  145.         <tr><td bgcolor="lightgrey">IRAM</td></tr>
  146.         <tr><td>Contents of the plugin's .iram section</td></tr>
  147.         <tr><td>Not initialised area, size=size of plugin's .ibss</td></tr>
  148.         <tr><td>... (Rest of IRAM)</td></tr>
  149.         <tr><td bgcolor="lightgrey">"Normal" memory</td></tr>
  150.         <tr><td>... (Rockbox code, etc.)</td></tr>
  151.         <tr><td>.header (here the pluginbuf starts)</td></tr>
  152.         <tr><td>.text</td></tr>
  153.         <tr><td>.rodata</td></tr>
  154.         <tr><td>.data</td></tr>
  155.         <tr><td>Zeroed out area, size=size of .iram (contained .iram before the call, can now be used at will)</td></tr>
  156.         <tr><td>Zeroed out area, size=size of .ibss (contained .ibss before the call, can now be used at will)</td></tr>
  157.         <tr><td>.bss</td></tr>
  158.         <tr><td>... (Rest of RAM)</td></tr>
  159. </table>
  161. <p>The call to PLUGIN_IRAM_INIT(api) is not made by the plugin loader but must be made by the plugin itself because if the plugin uses IRAM the music playback must be stopped (music playback also uses IRAM). So the plugin has a chance e.g. to ask the user whether it would be OK to stop the playback and start the plugin. If the call would be made by the plugin loader, music playback would unconditionally stopped. It's assumed that a programmer who's advanced enough to use IRAM in the plugin will be also careful enough and will not forget to call PLUGIN_IRAM_INIT(api).</p>
  163. </body>
  164. </html>


Update the Post

Either update this post and resubmit it with changes, or make a new post.

You may also comment on this post.

update paste below
details of the post (optional)

Note: Only the paste content is required, though the following information can be useful to others.

Save name / title?

(space separated, optional)

Please note that information posted here will expire by default in one month. If you do not want it to expire, please set the expiry time above. If it is set to expire, web search engines will not be allowed to index it prior to it expiring. Items that are not marked to expire will be indexable by search engines. Be careful with your passwords. All illegal activities will be reported and any information will be handed over to the authorities, so be good.

comments powered by Disqus