msg.c

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

 *
 * rt_rpcx makes an extended Remote Procedure Call (RPC). rt_rpcx is used for
 * synchronous inter task messaging. It sends an arbitrary @e smsg of size
 * @e ssize bytes to the task @e task then it always blocks waiting until a 
 * message, of size @e rsize bytes at most, is returned in @e rmsg from the 
 * called task. If the returned message is greater tha rsize it will be 
 * truncated. So the caller task is always blocked on the receiver priority 
 * queue while the receiver inheredits the blocked sender priority if it is 
 * higher (lower in value) than its. The receiver task may get the message 
 * with any rt_receivex function. It can send an answer with @ref rt_returnx().
 *
 * @param task pointer to the RT_TASK structure of the receiver.
 *
 * @param smsg points to the message to be sent.
 *
 * @param rmsg points to the message to be returned by the receiver.
 *
 * @param ssize size of the message to be sent.
 *
 * @param rsize maximum allowed size for the message to be received.
 *
 * @return On success, task (the pointer to the task that received the
 * message) is returned. If the message has not been sent (e.g. the
 * task @e task was killed before receiving the message) 0 is returned.
 *
 * See also: rt_receivex_*, @ref rt_returnx(), @ref rt_isrpc().
 *
 * @note The trio @ref rt_rpcx(), @ref rt_receivex(), @ref rt_returnx()
 * 	 implements functions similar to its peers send-receive-reply
 * 	 found in QNX. For a even greater compatibility see
 *       rt_Send-rt_Receive-rt_Reply.
 */
RT_TASK *rt_rpcx(RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize)
{
	if (task) {
		struct mcb_t mcb;
		SET_RPC_MCB();
		return rt_rpc(task, (unsigned int)&mcb, &mcb.rbytes);
	}
	return 0;
}


/**
 * @ingroup rpcx
 * @anchor rt_rpcx_if
 * @brief Make an extended remote procedure call, only if the calling task 
 * will not be blocked.
 *
 * rt_rpcx_if tries to make an extended Remote Procedure Call (RPC). If the
 * receiver task is ready to accept a message rt_rpcx_if sends the
 * message as it will be done by rt_rpcx.
 * If the receiver is not ready rt_rpcx_if returns immediately. The receiver 
 * task may get the message with any rt_receivex function. It can send the 
 * answer with * @ref rt_returnx().
 *
 * @param task pointer to the RT_TASK structure of the receiver.
 *
 * @param smsg points to the message to be sent.
 *
 * @param rmsg points to the message to be returned by the receiver.
 *
 * @param ssize size of the message to be sent.
 *
 * @param rsize maximum allowed size for the message to be received.
 *
 * @return On success, task (the pointer to the task that received the
 * message) is returned. If message has not been sent, 0 is
 * returned. On other failure, a special value is returned as
 * described below:
 * - @b 0: The task @e task was not ready to receive the message or
 *   	   it was killed before sending the reply.
 * - @b 0xFFFF: @e task does not refer to a valid task.
 *
 * See also: notes under @ref rt_rpc().
 *
 * @note Since all the messaging functions return a task address,
 * 	 0xFFFF could seem an inappropriate return value. However on
 * 	 all the CPUs RTAI runs on, 0xFFFF is not an address that can
 *  	 be used by any RTAI task, so it is should be always safe.
 */
RT_TASK *rt_rpcx_if(RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize)
{
	if (task) {
		struct mcb_t mcb;
		SET_RPC_MCB();
		return rt_rpc_if(task, (unsigned int)&mcb, &mcb.rbytes);
	}
	return 0;
}


/** 
 * @ingroup rpc
 * @anchor rt_rpcx_until
 * @brief Make an extended remote procedure call with absolute timeout.
 *
 * rt_rpcx_until makes an extended Remote Procedure Call (RPC). 
 * It sends an arbitrary @e smsg of size @e ssize bytes to the task @e task 
 * then it always blocks waiting until a message, of size @e rsize bytes at 
 * most, is returned in @e rmsg from the called task or a timeout occurs. 
 * If the returned message is greater tha rsize it will be truncated. 
 * So the caller task is always blocked on the receiver priority queue while
 * the receiver inheredits the blocked sender priority if it is higher 
 * (lower in value) than its. The receiver task may get the message with any 
 * rt_receivex function. It can send an answer with @ref rt_returnx().
 *
 * @param task pointer to the RT_TASK structure of the receiver.
 *
 * @param smsg points to the message to be sent.
 *
 * @param rmsg points to the message to be returned by the receiver.
 *
 * @param ssize size of the message to be sent.
 *
 * @param rsize maximum allowed size for the message to be received.
 *
 * @param time is an absolute timeout value.
 *
 * @return On success, task (the pointer to the task that received the
 * message) is returned. If message has not been sent or no answer
 * arrived, 0 is returned.
 * On other failure, a special value is returned as described below:
 * - @b 0: The message could not be sent or the answer did not arrived
 *    	   in time.  
 * - @b 0xFFFF: @e task does not refer to a valid task.
 *
 * See also: @ref rt_receive(), @ref rt_return(), @ref rt_isrpc().
 *
 * @note Since all the messaging functions return a task address, 0xFFFF
 * could seem an inappropriate return value. However on all the CPUs
 * RTAI runs on, 0xFFFF is not an address that can be used by any RTAI
 * task, so it is should be always safe.<br>
 * See also the notes under @ref rt_rpc().
 */
RT_TASK *rt_rpcx_until(RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize, RTIME time)
{
	if (task) {
		struct mcb_t mcb;
		SET_RPC_MCB();
		return rt_rpc_until(task, (unsigned int)&mcb, &mcb.rbytes, time);
	}
	return 0;
}


/** 
 * @ingroup rpc
 * @anchor rt_rpcx_timed
 * @brief Make an extended remote procedure call with a relative timeout.
 *
 * rt_rpcx_timed makes an extended Remote Procedure Call (RPC). 
 * It sends an arbitrary @e smsg of size @e ssize bytes to the task @e task 
 * then it always blocks waiting until a message, of size @e rsize bytes at 
 * most, is returned in @e rmsg from the called task or a timeout occurs. 
 * If the returned message is greater tha rsize it will be truncated. 
 * So the caller task is always blocked on the receiver priority queue while
 * the receiver inheredits the blocked sender priority if it is higher 
 * (lower in value) than its. The receiver task may get the message with any 
 * rt_receivex function. It can send an answer with @ref rt_returnx().
 *
 * @param task pointer to the RT_TASK structure of the receiver.
 *
 * @param smsg points to the message to be sent.
 *
 * @param rmsg points to the message to be returned by the receiver.
 *
 * @param ssize size of the message to be sent.
 *
 * @param rsize maximum allowed size for the message to be received.
 *
 * @param delay is the relative timeout.
 *
 * @return On success, task (the pointer to the task that received the
 * message) is returned. If message has not been sent or no answer
 * arrived, 0 is returned.
 * On other failure, a special value is returned as described below:
 * - @b 0: The message could not be sent or the answer did not arrived
 *    	   in time.  
 * - @b 0xFFFF: @e task does not refer to a valid task.
 *
 * See also: @ref rt_receive(), @ref rt_return(), @ref rt_isrpc().
 *
 * @note Since all the messaging functions return a task address, 0xFFFF
 * could seem an inappropriate return value. However on all the CPUs
 * RTAI runs on, 0xFFFF is not an address that can be used by any RTAI
 * task, so it is should be always safe.<br>
 * See also the notes under @ref rt_rpc().
 */
RT_TASK *rt_rpcx_timed(RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize, RTIME delay)
{
	if (task) {
		struct mcb_t mcb;
		SET_RPC_MCB();
		return rt_rpc_timed(task, (unsigned int)&mcb, &mcb.rbytes, delay);
	}
	return 0;
}

#define task_mcb (task->mcb)
#define SET_SEND_MCB() \
	do { \
		task_mcb.sbuf   = msg; \
		task_mcb.sbytes = size; \
		task_mcb.rbuf   = 0; \
		task_mcb.rbytes = 0; \
	} while (0)

/**
 * @ingroup msg
 * @anchor rt_sendx
 * @brief Send an extended message.
 *
 * rt_sendx sends an arbitrary message @e msg of size @e size bytes to the task 
 * @e task. If the
 * receiver task is ready to get the message rt_sendx does not block
 * the sending task, but its execution can be preempted if the
 * receiving task has a higher priority. Otherwise the caller task is
 * blocked and queued up in priority order on the receive list of the sent
 * task.
 *
 * @param task is a pointer to a task structure.
 *
 * @param msg points to the message to be sent.
 *
 * @param size size of the message to be sent.
 *
 * @return On success, the pointer to the task that received the message is
 * returned.<br>
 * 0 is returned if the caller is unblocked but the message has not
 * been sent, e.g. the task @e task was killed before receiving the
 * message.<br>
 * A special value is returned as described below in case of
 * a failure:
 * - @b 0xFFFF: @e task does not refer to a valid task.
 * 
 * @note Since all the messaging functions return a task address
 * 0xFFFF could seem an inappropriate return value. However on all the
 * CPUs RTAI runs on 0xFFFF is not an address that can be used by any
 * RTAI task, so it is should be safe always.
 */
RT_TASK *rt_sendx(RT_TASK *task, void *msg, int size) 
{
	if (task) {
		SET_SEND_MCB();
		return rt_send(task, (unsigned int)&task_mcb);
	}
	return 0;
}


/**
 * @ingroup msg
 * @anchor rt_sendx_if
 * @brief Send an extended message, only if the calling task will not be 
 * blocked.
 *
 * rt_sendx_if sends an arbitrary message @e msg of size @e size bytes to the 
 * task @e task if the latter is ready to receive. So the caller task in never
 * blocked but its execution can be preempted if the
 * receiving task has a higher priority.
 *
 * @param task is a pointer to a task structure.
 *
 * @param msg points to the message to be sent.
 *
 * @param size size of the message to be sent.
 *
 * @return On success, the pointer to the task that received the message is
 * returned.<br>
 * 0 is returned if the caller is unblocked but the message has not
 * been sent, e.g. the task @e task was killed before receiving the
 * message.<br>
 * A special value is returned as described below in case of
 * a failure:
 * - @b 0xFFFF: @e task does not refer to a valid task.
 * 
 * @note Since all the messaging functions return a task address
 * 0xFFFF could seem an inappropriate return value. However on all the
 * CPUs RTAI runs on 0xFFFF is not an address that can be used by any
 * RTAI task, so it is should be safe always.
 */
RT_TASK *rt_sendx_if(RT_TASK *task, void *msg, int size)
{
	if (task) {
		SET_SEND_MCB();
		return rt_send_if(task, (unsigned int)&task_mcb);
	}
	return 0;
}


/**
 * @ingroup msg
 * @anchor rt_sendx_until
 * @brief Send an extended message with absolute timeout.
 *
 * rt_sendx_until sends an arbitrary message @e msg of size @e size bytes to 
 * the task @e task. If the
 * receiver task is ready to get the message rt_sendx_until does not block
 * the sending task, but its execution can be preempted if the
 * receiving task has a higher priority. Otherwise the caller task is
 * blocked and queued up in priority order on the receive list of the sent
 * task.
 * In this case the function returns if:
 * - the caller task is in the first place of the waiting queue and
 *   the receiver gets the message and has a lower priority;
 * - a timeout occurs;
 * - an error occurs (e.g. the receiver task is killed).
 *
 * @param task is a pointer to a task structure.
 *
 * @param msg points to the message to be sent.
 *
 * @param size size of the message to be sent.
 *
 * @param time is an absolute timeout value.
 *
 * @return On success, the pointer to the task that received the message is
 * returned.<br>
 * 0 is returned if the caller is unblocked but the message has not
 * been sent, e.g. the task @e task was killed before receiving the
 * message.<br>
 * A special value is returned as described below in case of
 * a failure:
 * - @b 0: operation timed out, message was not delivered;
 * - @b 0xFFFF: @e task does not refer to a valid task.
 * 
 * @note Since all the messaging functions return a task address
 * 0xFFFF could seem an inappropriate return value. However on all the
 * CPUs RTAI runs on 0xFFFF is not an address that can be used by any
 * RTAI task, so it is should be safe always.
 */
RT_TASK *rt_sendx_until(RT_TASK *task, void *msg, int size, RTIME time)
{
	if (task) {
		SET_SEND_MCB();
		return rt_send_until(task, (unsigned int)&task_mcb, time);
	}
	return 0;
}


/**
 * @ingroup msg
 * @anchor rt_sendx_timed
 * @brief Send an extended message with relative timeout.
 *
 * rt_sendx_until sends an arbitrary message @e msg of size @e size bytes to 
 * the task @e task. If the
 * receiver task is ready to get the message rt_sendx_until does not block
 * the sending task, but its execution can be preempted if the
 * receiving task has a higher priority. Otherwise the caller task is
 * blocked and queued up in priority order on the receive list of the sent
 * task.
 * In this case the function returns if:
 * - the caller task is in the first place of the waiting queue and
 *   the receiver gets the message and has a lower priority;
 * - a timeout occurs;
 * - an error occurs (e.g. the receiver task is killed).
 *
 * @param task is a pointer to a task structure.
 *