WM_StartMPEx 

Syntax

#include <nitro/wm.h>

WMErrCode WM_StartMPEx(
        WMCallbackFunc  callback ,
        u16*            recvBuf ,
        u16             recvBufSize ,
        u16*            sendBuf ,
        u16             sendBufSize ,
        u16             mpFreq ,
        u16             defaultRetryCount ,
        BOOL            minPollBmpMode ,
        BOOL            singlePacketMode ,
        BOOL            fixFreqMode ,
        BOOL            ignoreFatalError
);

Arguments

callback Callback function to be called when the notification of the status for the asynchronous process is sent or when the asynchronous process completes. This callback is called from within the interrupt handler.
recvBuf Receive data storage buffer that the SDK uses internally. This value must be aligned to the 32-byte boundary. Because the ARM7 processor writes directly to the buffer, be careful of coherency with the cache.
recvBufSize Size of the buffer that stores received data. This value must be larger than the return value of WM_GetMPReceiveBufferSize. This value must also be in multiples of 64 bytes.
sendBuf Send data storage buffer that the SDK uses internally. This value must be aligned to the 32-byte boundary. Because the ARM7 processor writes directly to the buffer, be careful of coherency with the cache.
sendBufSize Send data storage buffer size that the SDK uses internally. This value must be larger than the return value of WM_GetMPReceiveBufferSize. This value must also be in multiples of 32 bytes.
mpFreq How many times to perform MP communications in one frame. If 0, the mode becomes the continuous communication mode. The continuous communication mode is provided for high capacity data communications. This argument affects only the parent.
defaultRetryCount For communication on ports 0-7, default value of the number of resend attempts when the send attempt fails. This value has no relation to the communication that occurs on ports 8-15 and the resends can be repeated without limit. This argument affects only the parent.
minPollBmpMode When TRUE, the value of the MP communications poll bitmap becomes the logical OR of the destination of the packet that the parent sends on that communication.
When FALSE, it sets up the poll bitmaps of all child devices. The default value of WM_StartMP is FALSE.
This argument affects only the parent.
singlePacketMode When TRUE, this function always sends only one packet for each MP communication. When FALSE, the packets are packed as much as the send size allows. The default value in WM_StartMP is FALSE.
fixFreqMode If a resend occurs, this normally performs continuous MP communications. However, if TRUE, the number of communications does not increase even if a resend occurs. In one frame, the number of MP communications that are performed is less than the number in the mpFreq argument. (There is always a possibility that the rate may fall below mpFreq due to the relationship of the communication path status and data length).
Internally, the upper limit on the count, including MP communication resends, is implemented by setting the same value as mpFreq. If mpFreq is 0, this specification is ignored.
This argument affects only the parent.
ignoreFatalError If a fatal error occurs during MP communication due to the radio wave status, the parent is disconnected from a child and a child from the parent. However, when TRUE, the disconnection process is not executed even if a fatal error occurred, and the connection is maintained. This flag should not be set to TRUE for modes other than limited modes such as MB.

Return Values

Returns the results of the WMErrCode enumerated type process.

Description

Begins the MP mode. This function can be executed only if the WM is in either the PARENT state or the CHILD state. If the return value is WM_ERRCODE_OPERATING, a callback is generated after the MP mode change process is complete. The WM state changes to the appropriate MP_PARENT or MP_CHILD state. A callback is also generated when data is received through MP communication or when MP communication is complete. After entering the MP communication mode, the V-Blank synchronization process is executed automatically between connected devices. MP communication is attempted in each frame for the number of times that is specified by mpFreq. The number of attempts is not guaranteed and is dependent on the communication status. The maximum number of MP communication attempts that occur during a each frame varies with each communication parameter. The setting values set using this function (defaultRetryCount, minPollBmpMode, singlePacketMode, fixFreqMode, and ignoreFatalError) are only valid during the MP_PARENT or MP_CHILD state started by calling this function. After you configure these settings using WM_SetMPParameter, you can achieve the same effect by calling WM_StartMP, but in that case, these settings are valid until WM returns to the READY state.

Using minPollBmpMode requires a detailed understanding of MP communications. Because of this, it should normally not be set to "valid." When set to "valid," if ports 8 through 15 are used, communication must occur once every 60 seconds for all ports on all children.

For a child performing MP communications, call WM_StartMPEx shortly after the child connects to a parent with WM_StartConnect. From the time the connection is established until WM_StartMPEx is called, the child does not respond to messages sent by the parent. When this status exceeds the parent CAM lifetime set by WM_SetLifeTime, the child is disconnected from the parent.

Also, avoid trying to change the MP communications parameters by calling the WM_EndMP function and the WM_StartMPEx function continuously while connected. MP communications internal information, such as Sequential communications information, will be initialized, so the consistency of communications before and afterwards will be lost.
In order to change specific MP communications parameters such as MP communication frequency during MP communications, it is possible to use functions such as WM_SetMPFrequency and WM_SetMPParameter.

See Also

WM_StartMP
WM_EndMP
WM_SetMPDataToPort
WM_SetPortCallback
WM_SetMPFrequency
WM_SetMPParameter

Revision History

2007/05/02 Added a description of fixFreqMode.
2007/05/02 Changed code to match changes to the active range of setting values.
2006/01/13 Added warnings related to changes in MP communications parameters during communications.
2005/11/24 Changed text to reflect changes in the WM_StartMP function's features.
2005/06/08 Added text indicating the callback is called from the interrupt handler.
2005/02/14 Added note about minPollBmpMode.
2004/10/22 Changed return value types.
2004/10/03 Added note about ignoreFatalError.
2004/09/25 Added and revised Description.
2004/08/27 Added Arguments.
2004/08/25 Initial version.


CONFIDENTIAL