Rtnl2SetClockRate
Rtnl2SetClockRate sets the rate of a clock.
Syntax
BOOL Rtnl2SetClockRate(
[in] RTNL2_HCLOCK Clock,
[in] LONG RequestedScaledOffsetPpm,
[out] LONG *pActualScaledOffsetPpm
);Parameters
[in] Clock
A handle to the clock object (see RTNL2_HCLOCK).
[in] RequestedScaledOffsetPpm
The new rate to apply, in ppm relative to the nominal rate (positive or negative).
[out] pActualScaledOffsetPpm
The rate applied, in ppm relative to the nominal rate (positive or negative).
Return Value
If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to obtain an error code.
Possible error codes:
| Error code | Meaning |
|---|---|
|
ERROR_NOT_READY |
The calling process has not called Rtnl2Init. |
|
ERROR_INVALID_PARAMETER |
The supplied clock handle is invalid. |
|
ERROR_ACCESS_DENIED |
The clock object was not opened with the RTNL2_CLOCK_FLAG_MODIFY flag. |
|
ERROR_DEVICE_FEATURE_NOT_SUPPORTED |
The hardware doesn’t support setting the NIC clock rate. |
|
RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT |
The NL2 process didn’t reply within an acceptable delay. |
|
RTNL2_ERROR_NO_MORE_COMMUNICATION |
Unable to communicate with the NL2 process. This might be because the NL2 process is not running anymore, or because an application process thread was terminated during a previous call to an NL2 API function. |
Remarks
The RequestedScaledOffsetPpm parameter is in Q16.16 fixed-point representation. For example, +1.5ppm is represented as 0x00018000 (because 1.5 * 2^16 = 98304 = 0x00018000) while -1.5ppm is represented as 0xFFFE8000 (because -1.5 * 2^16 = -98304 = 0xFFFE8000).
Although the maximum theoretial value for the rate offset is approximately +/-32767ppm, some hardware only supports a smaller range. If the supplied value of RequestedScaledOffsetPpm is too large for a given hardware (see RTNL2_INTERFACE_FEATURES.ClockRateScaledOffsetPpmMax and RTNL2_INTERFACE_FEATURES.ClockRateScaledOffsetPpmMin), the NL2 silently clamps it to the maximum supported value.
The RequestedScaledOffsetPpm value can be slightly modified by the NL2 to match the granularity supported by the hardware.
The function immediately reads back the actual applied rate and returns it in the pActualScaledOffsetPpm parameter, which is also in Q16.16 fixed-point representation. Note that pActualScaledOffsetPpm is optional; if it’s NULL, the function does not return the actual applied rate.
Characteristics
| Real-time | ||
|
Deterministic |
No |
|
|
Shutdown-safe |
No |
|
| Local memory usage | ||
|
Process |
External MSpace usage |
Internal MSpace usage |
|
System |
No |
No |
|
NL2 process |
No |
No |
|
Calling process |
No |
No |
| Windows contiguous memory usage | ||
|
Usage |
No |
|
Requirements
| Minimum supported version | Header | Library |
|---|---|---|
|
wRTOS 1.0 SDK |
Rtnl2Api.h |
Rtnl2Api.lib |
See Also:
