nanospin_calibrate()

Calibrate before calling nanospin*()

Synopsis:

#include <time.h>

int nanospin_calibrate( int disable );

Arguments:

disable: 1 to disable interrupts during the call to nanospin_calibrate(), or 0 to enable them; see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The nanospin_calibrate() function performs the calibration for the nanospin()* family of delay functions. The first time that you call nanospin(), nanospin_ns(), or nanospin_ns_to_count(), the C library invokes nanospin_calibrate() with an argument of 0 (interrupts enabled), unless you call it directly first.

Note: If you don't directly invoke nanospin_calibrate(), the first nanospin*() call in a process will have an overly long delay.

The nanospin*() functions are designed for use with hardware that requires short time delays between accesses. You should use them to delay only for times less than a few milliseconds. For longer delays, use the POSIX timer_*() functions.

Interrupts occurring during nanospin_calibrate() can throw off its timings. If disable is 0 (zero), you can prevent this situation by:

obtaining I/O privileges
disabling the interrupts around the nanospin_calibrate() call

If disable is 1 (one), the code disables interrupts around the calibration loop(s). The calling thread is still responsible for obtaining I/O privileges before calling nanospin_calibrate():

In order to obtain I/O privileges:

The process must have the PROCMGR_AID_IO ability enabled. For more information, see procmgr_ability().
The calling thread must successfully call:
```
ThreadCtl( _NTO_TCTL_IO, 0 );
```

In order to make startup faster and reduce jitter, nanospin_calibrate() tries to read the calibration data from values stored in the system page. The startup for some boards includes an -o option that you can use to specify the calibration data (100 loop time and overhead) to store in the system page.

Returns:

EOK: Success.
EINTR: A too-high rate of interrupts occurred during the calibration routine.
EPERM: The calling process doesn't have the required permission; see procmgr_ability().

Examples:

Busy-wait for 100 nanoseconds:

#include <time.h>
#include <sys/syspage.h>

int disable = 0;
unsigned long time = 100;

…
/* Wake up the hardware, then wait for it to be ready. */

if ( (nanospin_calibrate( disable )) == EOK )
   nanospin_count( nanospin_ns_to_count( time ) );
else
   printf ("Didn't calibrate successfully.\n");

/* Use the hardware. */
…

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes