1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
6<META http-equiv="Content-Style-Type" content="text/css">
7<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
8<title>RSOLinkFar</title>
9</head>
10
11<body>
12
13<h1>RSOLinkFar</h1>
14
15<h2>Syntax</h2>
16<dl><dd><pre class="construction">
17#include &lt;revolution/rso.h&gt;
18
19int RSOLinkFar(RSOObjectHeader* rsoImp, const RSOObjectHeader* rsoExp, void *buff);
20</pre></dd></dl>
21
22<h2>Arguments</h2>
23<TABLE class="arguments" border="1" >
24  <tr>
25<TH>rsoImp</TH>
26<TD>Pointer to the module information to link.</TD>
27  </tr>
28  <tr>
29<TH>rsoExp</TH>
30<TD>Pointer to the module information to reference.</TD>
31  </tr>
32  <tr>
33<TH>buff</TH>
34<TD>Area in which to write the added code.</TD>
35  </tr>
36</TABLE>
37
38<h2>Return Values</h2>
39<p>
40If linking succeeded, returns the number of codes that were processed.<BR>Returns -1 if linking failed.
41</p>
42
43<H2>Description</H2>
44<p>
45Typically, branch instructions (<CODE>bx</CODE>) have only a 28-bit offset (&plusmn;32 MB). Therefore, when a dynamic module is placed in external main memory (<CODE>MEM2</CODE>), functions in internal main memory (<CODE>MEM1</CODE>) cannot be accessed.<br> Use <code>RSOLinkFar</code> to avoid that.<br>The <code>LinkFar</code> function in the demo outputs a relay jump code to <SPAN class="argument">buff</SPAN> and enables access from the external module by linking to those functions from <SPAN class="argument">rsoImp</SPAN>. <br>Request the necessary buffer size with <code><a href="./RSOGetFarCodeSize.html">RSOGetFarCodeSize</a></code>.<br><br> <B>Note:</B> Allocate the buffer from the same main memory (MEM2 or MEM1) as the referencing module (<SPAN class="argument">rsoImp</SPAN>).<br>In addition, normally after linking, the code in the module is overwritten. Thus, when using <code><a href="./RSOLinkList.html">RSOLinkListFixed</a></code>, proceed up to <code><a href="./RSOFixedLevel.html">RSO_FL_INTERNAL</a></code> at the release level.<br><br>
46
47If this function returns -1, indicating that linking failed, it means that <SPAN class="argument">rsoImp</SPAN> and <SPAN class="argument">buff</SPAN> are separated by &plusmn;32MB or more and cannot reach each other with a relative jump. When you allocate memory for <SPAN class="argument">rsoImp</SPAN> and <SPAN class="argument">buff</SPAN>, make sure to locate them within &plusmn;32MB of each other.
48</p>
49
50
51<h2>Differences from RSOLinkJump</h2>
52<p>
53Whereas in <code><a href="./RSOLinkJump.html">RSOLinkJump</a></code>, the relay jump code is dependent on the module that is referred to, <code>RSOLinkFar</code> is dependent on the referring module.<br>This is an effective method when the module referring across memory areas is known.
54</p>
55
56<h2>See Also</h2>
57<p class="reference">
58<a href="./RSOGetFarCodeSize.html">RSOGetFarCodeSize</a>
59</p>
60
61<H2>Revision History</H2>
62<p>
632008/07/10 Removed <CODE>RSOLink.h</CODE> from <B>Syntax</B>. Added a note indicating when a jump cannot be reached.<BR>2006/12/19 Added <B>Differences from RSOLinkJump</B>.<br> 2006/09/25 Initial version.<BR>
64</p>
65
66<hr><p>CONFIDENTIAL</p></body>
67</html>
68