readme

rtai-3.1-test3的源代码(Real-Time Application Interface )

an owner that is identified by combining the requesting task handle, or "id",
and the node identifier, so they should be called just from within an RTAI 
task. Thus you have to care setting up an initializiation task if you want 
to use them in a "make it all at once" unified initialisation. Better never 
call them directly in init_module functions, in case of kernel space 
applications, even if you use a reqiest port with "id".

"Port"s request/release need to be timedout, and possibly repeated, in case of 
collisions on the unique server "port", preset and used by "netrpc" to accept 
the related requests on the remote node. A Linux timer is used for this scope,
since it is possible that no RTAI timer is running at the time a request is 
made. So "port"s request/release are not real time operations, they must be 
carried out before beginning any true real time work. Because of this assumption
they are not time critical and are timed out softly, without too much a hurry.

A further remark must be made in relation to intertask receive functions.
If you want to receive from any task there is no need to use RT_receive(x),
rt_receive(x) will receive also from remote tasks. If you want a specific
receive instead you must use RT_receive(x), recalling that you will receive 
from a local stub acting as the agent of the remote task. RT_receive(x) takes 
care of it, with a little added overhead since it has to find the stub 
associated to the node-port-task appearing in the RT_receive(x) argument list. 
You can improve the efficiency of specific receives from remote tasks by 
finding their local stubs yourself, using:
	RT_TASK *rt_find_asgn_stub(unsigned long long owner, int asgn);
where "owner" combines the remote "node" and "task". It can be built by using 
the macro: OWNER(node, task); "asgn" will assign a port-stub combination to 
the owner pair if it is different from zero and none exists yet. Any following
request for a "port" from the remote "task" will be given the one you have
created. With such a technique you can then effectively use a specific
rt_receive(x) on the task returned by rt_find_asgn_stub. The gain will be
more significant for user space applications, even if it is likely that you
will not notice any difference. 
See the 3 mode of executing found in "usoundmesg" for an example of what just
explained.

The same reasoning applies to RT_return(x). Take care of using RT_return(x)
with RT_receive(x) and rt_return with rt_receive(x), never mix them.  

Notice that "node" must be the networkwise integer corresponding to the
dotted decimal notation of the remote IP address. In kernel space the function 
"ddn2nl" is provided to transform the standard dotted decimal notation, 
xxx.xxx.xxx.xxx, into such an integer. In user space standard libc functions 
can be used directly, see the examples. 

The "ddn2l" prototype is:
	unsigned long ddn2nl(const char *ddn);
a null value being returned for a bad "ddn" string. A "ddn" string is assumed
to be bad if any of its dotted field contains a value greater than 0xFF.

The netrpc driver module can be made to know its local node by being insmoded 
either with the parameter <ThisNode="xxx.xxx.xxx.xxx"> or by a call to: 
	rt_set_this_node(const char *ddn, unsigned long node);
made by the application module before using any netrpc service. In the above 
call "ddn" is the dotted decimal notation string and node the corresponding 
"node". A call with a NULL "ddn" means that "node" contains a valid value while
a non NULL "ddn" implies that the local node is obtained from converting the 
related string, "node" being discarded.

"Netrpc" needs a network support and such a support can come either from Linux
or from RTNet (http://www.rts.uni-hannover.de/rtnet/). Clearly only RTNet can
provide true real time communications.
As already hinted "Netrpc" can serve soft and hard ports alike, the difference 
being related to the use of a soft real time stub task, for a soft port, while 
a hard real time stub is used for hard ports. In the soft case "netrpc" 
emulates RTNet (http://www.rts.uni-hannover.de/rtnet/) internally using Linux 
Ethernet support, so it does not supply a real time networking. To use NETRPC 
communications in true hard real time you must install the real RTNet services 
and inform "netrpc.c" that it is available, by setting the related compilation 
macro found in "netrpc.c", i.e. HARD_RTNET, to 1.
In the case RTNet is available it is possible to either substitute "netrpc.c" 
soft support or use both, by setting SOFT_RTNET to either 1 or 0.
When there is just one support in place netrpc.c automatically sets network 
calls appropriately. When both are used it is under user responsability to
specifically ask for the preferred service. The choice comes through using 
the port_request functions, already described above.
It is important to notice that a soft port requests implies a remote soft stub 
support, while a hard port request defaults to a hard stub. While it can make
sense using real time networking in soft real time tasks the opposite is 
likely mostly inappropriate. So "netrpc" forces the stubs to be soft when just
Linux networking is available, coherently forcing them to hard when just RTNet 
is being used. However there is no constraint imposed by NETRPC in the case 
both supports are in place and the user can choose whatever s/he wants.

It must be noted also that the specific implementation adopted for our RPC
scheme acts along the ideas already used for LXRT. In fact, networking
apart, the remote execution is carried out by a stub task, you can call it
buddy, proxy, agent, already hinted at. The possibility of expanding its use 
to any user specific application is already in place, once more following the 
ideas used in extending LXRT.

Netrpc has no security and error correction in its code but let its user
implement its own by hooking into it encode/decode functions and APIs table 
extensions. The encode/decode functions can be used to provide data 
compression and error checking also, even in a selective way by assigning 
ids at port requests.
Since such a service can be costly for real time applications it has been
preferred to avoid any internally coded scheme. In fact real time networking
will likely be mostly used on trusted "internal" connections requiring none, 
or a very simple data encoding at most. Thus it is better to let a user do 
what s/he wants. A simple demonstration of encode/decode is provided in 
"showroom", see "share/scrambler". It contains also an example of a user
specific NETRPC calls expansion.

To verify almost all the possibility offered by "netrpc" there are:
- an example in kernel space (basetest),
- five examples in user space (basetest, sound, soundmsg, resumefromintr, 
  async). 
Anything that works in user land will work in the kernel land also. That's why 
there is only one example in kernel space. 
"Netrpc" is now a production tool. In fact RTAI has a production application, 
i.e. RTAI-Lab, that is fully based on "netrpc". At the moment this text is the 
only documentation available. You should look also at netrpc.h, the above 
cited examples and RTAI-Lab to better understand what can be done with it. 
So the tool for integrated symmetricall local/distributed-kernel/user-space 
application is available and its usage is up to you.

For your convenience a list of the functions and macros explained in this README
follows. There is clearly no need to explain "RT_..." services since they 
follow the general rules explained at the very beginning.

- int rt_send_req_rel_port(unsigned long node, int port, unsigned long id, MBX *mbx);

- #define rt_request_soft_port(node)           rt_send_req_rel_port(node, 0, 0, 0, 0)
- #define rt_request_soft_port_id(node, id)    rt_send_req_rel_port(node, 0, id, 0, 0)
- #define rt_request_soft_port_mbx(node, mbx)  rt_send_req_rel_port(node, 0, 0, mbx, 0)
- #define rt_request_soft_port_id_mbx(node, id, mbx)  rt_send_req_rel_port(node, 0, id, mbx, 0)

- All of the above in the hard form, e.g:
- #define rt_request_hard_port(node)      rt_send_req_rel_port(node, 0, 0, 0, 1)
and combinations thereof.
For backward compatibility reasons there is a version also without hard_soft, 
e.g. simply rt_request_port. It defaults to a soft request.

- #define rt_release_port(node, port)  rt_send_req_rel_port(node, port, 0, 0)

- unsigned long ddn2nl(const char *ddn);

- unsigned long rt_set_this_node(const char *ddn, unsigned long node);

#define OWNER(node, task) \
        ((((unsigned long long)(node)) << 32) | (unsigned long)(task))

- RT_TASK *rt_find_asgn_stub(unsigned long long owner, int asgn);

- int rt_rel_stub(unsigned long long owner);

- int rt_waiting_return(unsigned long node, int port);

- int rt_sync_net_rpc(unsigned long node, int port);

- rt_get_net_rpc_ret(
	MBX *mbx, 
	unsigned long long *retval, 
	void *msg1, 
	int *msglen1, 
	void *msg2, 
	int *msglen2, 
	RTIME timeout, 
	int type
  );

As usual ... comments and bugs fixes are welcomed.

Paolo.