WM_StartMPEx

C Specification

#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 Specifies the 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 Specifies how many times to perform MP communications in one frame. If 0 is designated, the mode becomes the continuous communication mode. The continuous communication mode is provided for high capacity data communications. This argument affects only the parent device.
defaultRetryCount For communication on ports 0-7, this argument designates the 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 device.
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.
If 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 device.
singlePacketMode When this value is TRUE, this function always sends only one packet for each MP communication. When this value is 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 the value for this argument is 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. (Based on the state of the channel and the length of the data, there is always the possibility that this number could fall below the value in the mpFreq argument.)
This argument affects only the parent device.
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 this flag is specified as 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. Not only does this function use WM_SetMPParameter to set defaultRetryCount, minPollBmpMode, singlePacketMode, and ignoreFatalError ahead of time, but it is equivalent to calling WM_StartMP.

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.

See Also

WM_StartMP, WM_EndMP, WM_SetMPDataToPort, WM_SetPortCallback

Revision History

11/24/2005 Changed description in line with changes to specifications of the WM_StartMP function.
06/08/2005 Added statement about callback being called from the interrupt handler.
02/14/2005 Added description about minPollBmpMode.
10/22/2004 Changed type of return value.
10/03/2004 Added description about ignoreFatalError.
09/25/2004 Added to and revised Description.
08/27/2004 Added arguments.
08/25/2004 Initial version.