Each element of the array is written with the port number.

Devices that are in use are OR’ed with CH_PORT_NOT_FREE (0x8000). Under Linux, such devices correspond to Cheetah adapters that are currently in use. Under Windows, such devices are currently in use, but it is not known if the device is a Cheetah adapter.

Example:

Devices are attached to port 0, 1, 2.
Ports 0 and 2 are available, and port 1 is in-use.
devices = { 0x0000, 0x8001, 0x0002 }

If the input array is NULL, it is not filled with any values.

If there are more devices than the array size (as specified by nelem), only the first nelem port numbers will be written into the array.

This function is the same as ch_find_devices() except that is also returns the unique IDs of each Cheetah device. The IDs are guaranteed to be non-zero if valid.

The IDs are the unsigned integer representation of the 10-digit serial numbers.

This function is recommended for use in simple applications where extended information is not required. For more complex applications, the use of ch_open_ext() is recommended.

If 0 is passed as the pointer to the structure ch_ext, this function will behave exactly like ch_open().

The CheetahExt structure is described below:

struct CheetahExt {
    CheetahVersion   version;
    /* Features of this device. */
    int              features;
}

The CheetahVersion structure describes the various version dependencies of Cheetah components. It can be used to determine which component caused an incompatibility error.

struct CheetahVersion {
    /* Software and hardware versions. */
    u16 software;
    u16 hardware;

    /* 
     * Hardware revisions that are compatible with this 
     * software version.  The top 16 bits gives the maximum
     * accepted hardware revision.  The lower 16 bits gives 
     * the minimum accepted hardware revision.
     */
    u32 hw_revs_for_sw;

    /*
     * Driver revisions that are compatible with this 
     * software version.  The top 16 bits gives the maximum 
     * accepted driver revision.  The lower 16 bits gives 
     * the minimum accepted driver revision.  This version
     * checking is currently only pertinent for WIN32
     * platforms.
     */
    u32 drv_revs_for_sw;

    /* 
     * Software requires that the API interface must be >= this 
     * version. 
     */
    u16 api_req_by_sw;
};

All version numbers are of the format:

(major << 8) | minor
example: v1.20 would be encoded as 0x0114.

The structure is zeroed before the open is attempted. It is filled with whatever information is available. For example, if the hardware version is not filled, then the device could not be queried for its version number.

This function is recommended for use in complex applications where extended information is required. For simpler applications, the use of ch_open() is recommended.

None.

None.

None.

If the handle is 0 or invalid, only the software version is set.

See the details of ch_open_ext for the definition of CheetahVersion.

This function provides a convenient cross-platform function to sleep the current thread using standard operating system functions.

The accuracy of this function depends on the operating system scheduler. This function will return the number of milliseconds that were actually slept.

Both target power pins are controlled together. Independent control is not supported. This function may be executed in any operation mode.

This function returns enumerated values specifying the USB speed at which the host computer is communicating with the given Cheetah device. See Table 3.

Used to determine the USB communication rate between the Cheetah device and the host. A High Speed USB interface is highly recommended to take full advantage of the high speed SPI interface.

This function returns the actual bitrate set.

The power-on default bitrate is 1 MHz.

Only certain discrete bitrates are supported by the Cheetah adapter. As such, this actual bitrate set will be less than or equal to the requested bitrate unless the requested value is less than 100 kHz, in which case the Cheetah adapter will default to 100 kHz. The maximum supported speed for the Cheetah adapter is 50 MHz.

If bitrate_khz is 0, the function will set the bit rate to the minimum value, 100 kHz.

A Cheetah status code is returned with CH_OK on success.

These configuration parameters specify how to clock the bits that are sent and received on the Cheetah SPI interface.

The polarity option specifies which transition constitutes the leading edge and which transition is the falling edge. For example, CH_SPI_POL_RISING_FALLING would configure the SPI to idle the SCLK clock line low. The clock would then transition low-to-high on the leading edge and high-to-low on the trailing edge.

The phase option determines whether to sample or setup on the leading edge of the clock signal. For example, CH_SPI_PHASE_SAMPLE_SETUP would configure the SPI to sample on the leading edge and setup on the trailing edge of the clock.

For example, mode 3 in the figure found in the "SPI Background" chapter would correspond to the pair (CH_SPI_POL_FALLING_RISING, CH_SPI_PHASE_SETUP_SAMPLE).

The bitorder option is used to indicate whether LSB or MSB is shifted first.

The ss_polarity option is a bit mask that indicates whether each SS line is active high or active low. For example, setting ss_polarity to 0x05 would mean that SS3 and SS1 are active high and SS2 is active low.

A Cheetah status code is returned with CH_OK on success.

All queued data and commands are removed from the queue.

A Cheetah status code is returned with CH_OK on success.

This function enables and disables the outputs on the Cheetah device. When enabled, the Cheetah device connects to the SPI bus and is ready to drive the signal lines. When the Cheetah output enable is disabled, the device disconnects from the bus and each signal line is held at their current values with very weak internal pull-up or pull-down on the Cheetah device.

Call this function to enable the Cheetah outputs before calling any of the other queue functions.

A Cheetah status code is returned with CH_OK on success.

This function adds a command to the batch queue to assert/deassert the SPI slave select lines. The active parameter is a bit mask. For example, setting active to 0x05 would mean that SS3 and SS1 are asserted and SS2 is deasserted. The polarity of the slave select is determined from a previous call to ch_spi_configure.

Returns the actual number of times the byte in data_out was added to the queue. This should equal count.

Queues count number of bytes to send and sets each byte to the value of data_out.

For this command, and the ch_spi_queue_array command, the polarity, phase, and bit ordering will be determined by the configuration set with the ch_spi_configure function.

Returns the number of bytes queued. This should equal num_bytes.

The array will be processed with a minimal run length encoding algorithm, so repeated sequences of single bytes will be sent more efficiently. This helps reduce outgoing (host to Cheetah) bandwidth on the USB bus.

For this command, and the ch_spi_queue_byte command, the polarity, phase, and bit ordering will be determined by the configuration set with the ch_spi_configure function.

Returns the actual number of cycles of delay that were queued.

Queues cycles amount of delay on the bus. These are in units of clock cycles as set with ch_spi_bitrate. The delays can only be queued in multiples of 8. The function will return the actual number of cycles queued. The requested number of cycles will be rounded up to the next multiple of 8.

The requested number of cycles must be greater than zero and less than or equal to 2 ³² −9. If the requested number of cycles is out of bounds, no delay is queued and the function will return 0.

Returns the actual number of nanoseconds of delay that were queued.

Queues nanoseconds amount of delay on the bus. The fundamental unit of delay that can be queued on the Cheetah SPI bus is 8 times the clock period. Therefore, requested delay will be rounded up to the next even multiple of this time span. The function will return the actual number of nanoseconds queued.

The requested number of nanoseconds must be greater than zero and less than or equal to 2 seconds. If the requested number of nanoseconds is out of bounds, no delay is queued and the function will return 0.

Returns the number of data bytes in the queue. This does not include the commands (SS assertion, OE, etc). It only corresponds to the number of bytes that will be shifted out on the SPI bus. The value returned is also the number of bytes to expect from the slave device when the currently queued commands are executed.

None.

The number of bytes sent by the Cheetah device across the SPI bus.

This function performs all of the accumulated commands in the queue and shifts them in order onto the SPI bus. After the operation completes, the batch queue is not cleared. Therefore, this function may be called repeatedly if the same sequence of commands is to be shifted across the bus multiple times.

As data is shifted by the Cheetah device onto the MOSI line, the slave device will shift the same amount of data back across the MISO line. This function will put the first num_bytes number of bytes received from the slave device into the data_in array. To ensure that all of the data from the slave device is captured, call ch_spi_batch_length to determine how much data to expect from the slave device. Setting num_bytes to 0 is permissible for cases where the data from slave device is not required and can simply be discarded.

If the number of bytes received from the slave device is less than num_bytes, only the number of bytes received will be put into data_in. However, all of the outgoing bytes in the queue will still be shifted. When setting num_bytes to a value less than the total outgoing length, a special optimization will automatically take effect. This optimization will help reduce the traffic on the USB bus in the inbound direction (Cheetah to host). This optimization introduces an 8 clock cycle delay in the operation of the Cheetah device at the point that the Cheetah device stops sending the slave response back to the host.

The number of bytes to be sent by the Cheetah device across the SPI bus.

This function will submit the current batch queue asynchronously to the Cheetah. A temporary outgoing buffer will be created to store the batch queue. An internal incoming buffer will be also created to asynchronously capture the slave response data. The application programmer does not have to explicitly manage these two buffers. The function will immediately return after queuing this batch onto the USB, rather than waiting for the shift to complete on the SPI bus.

At this point, the application can submit another batch to the queue. This can be done immediately by submitting the same queue a second time without altering it — the application simply needs to call ch_spi_async_submit again. Or, the application may clear the queue and assemble a different batch all together (see the ch_spi_queue family of functions). Any subsequent calls to ch_spi_async_submit will again create a temporary outgoing buffer and copy the current batch into it. Likewise, a temporary incoming buffer will also be created.

Note that the submitted batch should be sufficiently long (in real time) so that it does not complete before the application can submit more batches (and also collect the first batch). This will allow the adjacent batches to shift with very little delay between them. How long to be safe? First, there is always the possibility that the application’s process could be scheduled out by the operating system before it has an opportunity to submit the subsequent batch. The operating system scheduler timeslice may be as much as 10 ms. Therefore, submitted batches should be long enough to bridge one, if not two, time slices. Second, if the application is performing its own functions between the submission of two batches, the length of the batches should be long enough to accommodate the CPU time of those functions.

Keep in mind that there can significant memory overhead for each asynchronous batch:

1. Up to 4 times the size of the outgoing number of bytes. In the worst case, if there are no sequential repeats of data, the outgoing buffer is approximately twice the size of the number of bytes shifted out on the SPI bus (this doesn’t count SS# assert/deassert commands or intermediate delays) and there is potentially another factor of two due to kernel/user mode memory allocation. So if the application shifts 10 KB out in one batch, the outgoing buffer overhead is approximately 40 KB.

2. 2 times the size of the incoming buffer for each batch.

3. Size of the data_in buffer supplied to the ch_spi_async_collect function.

Hence, it is important to not queue many megabytes of batches with the asynchronous interface. Additionally, only a fixed number of batches can be submitted and be left pending prior to collection. This number is fixed to 16.

Considering the time delay between the last queued command of one asynchronous batch and the first queued command of an immediately subsequent asynchronous batch, there potentially can be delays inserted due to a padding algorithm that takes effect at the end of any given batch. In general, there can be a maximum delay of (2040 / spi_bitrate_hz) present on the SPI bus between two asynchronous batches.

Finally, the asynchronous interface is only useful if the outgoing data of any asynchronous batch does not rely on the return MISO data of a previous asynchronous batch.

The number of bytes sent by the Cheetah device across the SPI bus.

This function can be called at anytime after submitting a batch for asynchronous processing. It will block until the first pending batch completes. For example, if there are 5 batches outstanding, this function will return after 1 batch has fully completed, leaving the other 4 batches still outstanding.

The function will fill the user-supplied buffer with the incoming MISO data for the completed batch. The incoming data will be copied from the internal incoming buffer originally created by ch_spi_async_submit into the user supplied data_in buffer. The internal buffers (both outgoing and incoming) for the completed batch will be deleted before this function returns to the application.

If ch_close is called without collecting pending asynchronous batches, those batches will be canceled, even if they are in progress. All temporary buffers will be freed as well.

A suggested mode of operation would be as follows:

1. Submit 2–4 asynchronous batches, each with about 40 ms worth of SPI shifting. A single batch can contain many SPI commands / packets, of course.

2. Call ch_spi_async_collect to collect one batch. Signal another thread to process this data.

3. Submit another asynchronous batch to replace the one that was just collected.

4. Repeat steps 2 & 3 while your other thread simply processes the data.

Note that this merely is a recommendation for use and developers can modify this procedure as it suits their own application requirements.

The application must keep full accounting of how many batches have been submitted and how many are collected during each step of the process. It is even possible that the application will not need multiple threads if it can process the data between steps 2 and 3 and guarantee the algorithm will not take too long to process the incoming data.