WM_StartMP

# 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