WM_StartMP

# 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.

CONFIDENTIAL