cheetah.h

00001 /*=========================================================================
00002 | Cheetah Interface Library
00003 |--------------------------------------------------------------------------
00004 | Copyright (c) 2004-2008 Total Phase, Inc.
00005 | All rights reserved.
00006 | www.totalphase.com
00007 |
00008 | Redistribution and use in source and binary forms, with or without
00009 | modification, are permitted provided that the following conditions
00010 | are met:
00011 |
00012 | - Redistributions of source code must retain the above copyright
00013 |   notice, this list of conditions and the following disclaimer.
00014 |
00015 | - Redistributions in binary form must reproduce the above copyright
00016 |   notice, this list of conditions and the following disclaimer in the
00017 |   documentation and/or other materials provided with the distribution.
00018 |
00019 | - Neither the name of Total Phase, Inc. nor the names of its
00020 |   contributors may be used to endorse or promote products derived from
00021 |   this software without specific prior written permission.
00022 |
00023 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00024 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00025 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00026 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
00027 | COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00028 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00029 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00032 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034 | POSSIBILITY OF SUCH DAMAGE.
00035 |--------------------------------------------------------------------------
00036 | To access Total Phase Cheetah devices through the API:
00037 |
00038 | 1) Use one of the following shared objects:
00039 |      cheetah.so       --  Linux shared object
00040 |          or
00041 |      cheetah.dll      --  Windows dynamic link library
00042 |
00043 | 2) Along with one of the following language modules:
00044 |      cheetah.c/h      --  C/C++ API header file and interface module
00045 |      cheetah_py.py    --  Python API
00046 |      cheetah.bas      --  Visual Basic 6 API
00047 |      cheetah.cs       --  C# .NET source
00048 |      cheetah_net.dll  --  Compiled .NET binding
00049  ========================================================================*/
00050 
00051 
00052 #ifndef __cheetah_h__
00053 #define __cheetah_h__
00054 
00055 #ifdef __cplusplus
00056 extern "C" {
00057 #endif
00058 
00059 
00060 /*=========================================================================
00061 | TYPEDEFS
00062  ========================================================================*/
00063 #ifndef TOTALPHASE_DATA_TYPES
00064 #define TOTALPHASE_DATA_TYPES
00065 
00066 #ifndef _MSC_VER
00067 /* C99-compliant compilers (GCC) */
00068 #include <stdint.h>
00069 typedef uint8_t   u08;
00070 typedef uint16_t  u16;
00071 typedef uint32_t  u32;
00072 typedef uint64_t  u64;
00073 typedef int8_t    s08;
00074 typedef int16_t   s16;
00075 typedef int32_t   s32;
00076 typedef int64_t   s64;
00077 
00078 #else
00079 /* Microsoft compilers (Visual C++) */
00080 typedef unsigned __int8   u08;
00081 typedef unsigned __int16  u16;
00082 typedef unsigned __int32  u32;
00083 typedef unsigned __int64  u64;
00084 typedef signed   __int8   s08;
00085 typedef signed   __int16  s16;
00086 typedef signed   __int32  s32;
00087 typedef signed   __int64  s64;
00088 
00089 #endif /* __MSC_VER */
00090 
00091 #endif /* TOTALPHASE_DATA_TYPES */
00092 
00093 
00094 /*=========================================================================
00095 | DEBUG
00096  ========================================================================*/
00097 /* Set the following macro to '1' for debugging */
00098 #define CH_DEBUG 0
00099 
00100 
00101 /*=========================================================================
00102 | VERSION
00103  ========================================================================*/
00104 #define CH_HEADER_VERSION  0x0300   /* v3.00 */
00105 
00106 
00107 /*=========================================================================
00108 | STATUS CODES
00109  ========================================================================*/
00110 /*
00111  * All API functions return an integer which is the result of the
00112  * transaction, or a status code if negative.  The status codes are
00113  * defined as follows:
00114  */
00115 enum CheetahStatus {
00116     /* General codes (0 to -99) */
00117     CH_OK                      =    0,
00118     CH_UNABLE_TO_LOAD_LIBRARY  =   -1,
00119     CH_UNABLE_TO_LOAD_DRIVER   =   -2,
00120     CH_UNABLE_TO_LOAD_FUNCTION =   -3,
00121     CH_INCOMPATIBLE_LIBRARY    =   -4,
00122     CH_INCOMPATIBLE_DEVICE     =   -5,
00123     CH_INCOMPATIBLE_DRIVER     =   -6,
00124     CH_COMMUNICATION_ERROR     =   -7,
00125     CH_UNABLE_TO_OPEN          =   -8,
00126     CH_UNABLE_TO_CLOSE         =   -9,
00127     CH_INVALID_HANDLE          =  -10,
00128     CH_CONFIG_ERROR            =  -11,
00129     CH_UNKNOWN_PROTOCOL        =  -12,
00130     CH_STILL_ACTIVE            =  -13,
00131     CH_FUNCTION_NOT_AVAILABLE  =  -14,
00132     CH_OS_ERROR                =  -15,
00133 
00134     /* SPI codes (-100 to -199) */
00135     CH_SPI_WRITE_ERROR         = -100,
00136     CH_SPI_BATCH_EMPTY_QUEUE   = -101,
00137     CH_SPI_BATCH_SHORT_BUFFER  = -102,
00138     CH_SPI_ASYNC_EMPTY         = -103,
00139     CH_SPI_ASYNC_PENDING       = -104,
00140     CH_SPI_ASYNC_MAX_REACHED   = -105,
00141     CH_SPI_ASYNC_EXCESS_DELAY  = -106
00142 };
00143 #ifndef __cplusplus
00144 typedef enum CheetahStatus CheetahStatus;
00145 #endif
00146 
00147 
00148 /*=========================================================================
00149 | GENERAL TYPE DEFINITIONS
00150  ========================================================================*/
00151 /* Cheetah handle type definition */
00152 typedef int Cheetah;
00153 
00154 /*
00155  * Cheetah version matrix.
00156  * 
00157  * This matrix describes the various version dependencies
00158  * of Cheetah components.  It can be used to determine
00159  * which component caused an incompatibility error.
00160  * 
00161  * All version numbers are of the format:
00162  *   (major << 8) | minor
00163  * 
00164  * ex. v1.20 would be encoded as:  0x0114
00165  */
00166 struct CheetahVersion {
00167     /* Software, firmware, and hardware versions. */
00168     u16 software;
00169     u16 firmware;
00170     u16 hardware;
00171 
00172     /*
00173      * Hardware revisions that are compatible with this software version.
00174      * The top 16 bits gives the maximum accepted hardware revision.
00175      * The lower 16 bits gives the minimum accepted hardware revision.
00176      */
00177     u32 hw_revs_for_sw;
00178 
00179     /*
00180      * Firmware revisions that are compatible with this software version.
00181      * The top 16 bits gives the maximum accepted fw revision.
00182      * The lower 16 bits gives the minimum accepted fw revision.
00183      */
00184     u32 fw_revs_for_sw;
00185 
00186     /*
00187      * Driver revisions that are compatible with this software version.
00188      * The top 16 bits gives the maximum accepted driver revision.
00189      * The lower 16 bits gives the minimum accepted driver revision.
00190      * This version checking is currently only pertinent for WIN32
00191      * platforms.
00192      */
00193     u32 drv_revs_for_sw;
00194 
00195     /* Software requires that the API interface must be >= this version. */
00196     u16 api_req_by_sw;
00197 };
00198 #ifndef __cplusplus
00199 typedef struct CheetahVersion CheetahVersion;
00200 #endif
00201 
00202 
00203 /*=========================================================================
00204 | GENERAL API
00205  ========================================================================*/
00206 /*
00207  * Get a list of ports to which Cheetah devices are attached.
00208  * 
00209  * num_devices = maximum number of elements to return
00210  * devices     = array into which the port numbers are returned
00211  * 
00212  * Each element of the array is written with the port number.
00213  * Devices that are in-use are ORed with CH_PORT_NOT_FREE
00214  * (0x8000).
00215  *
00216  * ex.  devices are attached to ports 0, 1, 2
00217  *      ports 0 and 2 are available, and port 1 is in-use.
00218  *      array => 0x0000, 0x8001, 0x0002
00219  * 
00220  * If the array is NULL, it is not filled with any values.
00221  * If there are more devices than the array size, only the
00222  * first nmemb port numbers will be written into the array.
00223  * 
00224  * Returns the number of devices found, regardless of the
00225  * array size.
00226  */
00227 #define CH_PORT_NOT_FREE 0x8000
00228 int ch_find_devices (
00229     int   num_devices,
00230     u16 * devices
00231 );
00232 
00233 
00234 /*
00235  * Get a list of ports to which Cheetah devices are attached
00236  *
00237  * This function is the same as ch_find_devices() except that
00238  * it returns the unique IDs of each Cheetah device.  The IDs
00239  * are guaranteed to be non-zero if valid.
00240  *
00241  * The IDs are the unsigned integer representation of the 10-digit
00242  * serial numbers.
00243  */
00244 int ch_find_devices_ext (
00245     int   num_devices,
00246     u16 * devices,
00247     int   num_ids,
00248     u32 * unique_ids
00249 );
00250 
00251 
00252 /*
00253  * Open the Cheetah port.
00254  * 
00255  * The port number is a zero-indexed integer.
00256  *
00257  * The port number is the same as that obtained from the
00258  * ch_find_devices() function above.
00259  * 
00260  * Returns an Cheetah handle, which is guaranteed to be
00261  * greater than zero if it is valid.
00262  * 
00263  * This function is recommended for use in simple applications
00264  * where extended information is not required.  For more complex
00265  * applications, the use of ch_open_ext() is recommended.
00266  */
00267 Cheetah ch_open (
00268     int port_number
00269 );
00270 
00271 
00272 /*
00273  * Open the Cheetah port, returning extended information
00274  * in the supplied structure.  Behavior is otherwise identical
00275  * to ch_open() above.  If 0 is passed as the pointer to the
00276  * structure, this function is exactly equivalent to ch_open().
00277  * 
00278  * The structure is zeroed before the open is attempted.
00279  * It is filled with whatever information is available.
00280  * 
00281  * For example, if the hardware version is not filled, then
00282  * the device could not be queried for its version number.
00283  * 
00284  * This function is recommended for use in complex applications
00285  * where extended information is required.  For more simple
00286  * applications, the use of ch_open() is recommended.
00287  */
00288 struct CheetahExt {
00289     /* Version matrix */
00290     CheetahVersion   version;
00291 
00292     /* Features of this device. */
00293     int              features;
00294 };
00295 #ifndef __cplusplus
00296 typedef struct CheetahExt CheetahExt;
00297 #endif
00298 
00299 Cheetah ch_open_ext (
00300     int          port_number,
00301     CheetahExt * ch_ext
00302 );
00303 
00304 
00305 /* Close the Cheetah port. */
00306 int ch_close (
00307     Cheetah cheetah
00308 );
00309 
00310 
00311 /*
00312  * Return the port for this Cheetah handle.
00313  * 
00314  * The port number is a zero-indexed integer.
00315  */
00316 int ch_port (
00317     Cheetah cheetah
00318 );
00319 
00320 
00321 /*
00322  * Return the unique ID for this Cheetah adapter.
00323  * IDs are guaranteed to be non-zero if valid.
00324  * The ID is the unsigned integer representation of the
00325  * 10-digit serial number.
00326  */
00327 u32 ch_unique_id (
00328     Cheetah cheetah
00329 );
00330 
00331 
00332 /*
00333  * Return the status string for the given status code.
00334  * If the code is not valid or the library function cannot
00335  * be loaded, return a NULL string.
00336  */
00337 const char * ch_status_string (
00338     int status
00339 );
00340 
00341 
00342 /*
00343  * Return the version matrix for the device attached to the
00344  * given handle.  If the handle is 0 or invalid, only the
00345  * software and required api versions are set.
00346  */
00347 int ch_version (
00348     Cheetah          cheetah,
00349     CheetahVersion * version
00350 );
00351 
00352 
00353 /*
00354  * Sleep for the specified number of milliseconds
00355  * Accuracy depends on the operating system scheduler
00356  * Returns the number of milliseconds slept
00357  */
00358 u32 ch_sleep_ms (
00359     u32 milliseconds
00360 );
00361 
00362 
00363 /* Configure the target power pin. */
00364 #define CH_TARGET_POWER_OFF 0x00
00365 #define CH_TARGET_POWER_ON 0x01
00366 #define CH_TARGET_POWER_QUERY 0x80
00367 int ch_target_power (
00368     Cheetah cheetah,
00369     u08     power_flag
00370 );
00371 
00372 
00373 #define CH_HOST_IFCE_FULL_SPEED 0x00
00374 #define CH_HOST_IFCE_HIGH_SPEED 0x01
00375 int ch_host_ifce_speed (
00376     Cheetah cheetah
00377 );
00378 
00379 
00380 /* Returns the device address that the beagle is attached to. */
00381 int ch_dev_addr (
00382     Cheetah cheetah
00383 );
00384 
00385 
00386 
00387 /*=========================================================================
00388 | SPI API
00389  ========================================================================*/
00390 /* Set the SPI bit rate in kilohertz. */
00391 int ch_spi_bitrate (
00392     Cheetah cheetah,
00393     int     bitrate_khz
00394 );
00395 
00396 
00397 /*
00398  * These configuration parameters specify how to clock the
00399  * bits that are sent and received on the Cheetah SPI
00400  * interface.
00401  * 
00402  * The polarity option specifies which transition
00403  * constitutes the leading edge and which transition is the
00404  * falling edge.  For example, CH_SPI_POL_RISING_FALLING
00405  * would configure the SPI to idle the SCK clock line low.
00406  * The clock would then transition low-to-high on the
00407  * leading edge and high-to-low on the trailing edge.
00408  * 
00409  * The phase option determines whether to sample or setup on
00410  * the leading edge.  For example, CH_SPI_PHASE_SAMPLE_SETUP
00411  * would configure the SPI to sample on the leading edge and
00412  * setup on the trailing edge.
00413  * 
00414  * The bitorder option is used to indicate whether LSB or
00415  * MSB is shifted first.
00416  *
00417  * The SS polarity option is to indicate the polarity of the
00418  * slave select pin (active high or active low).  Each of
00419  * the lower three bits of ss_polarity corresponds to each
00420  * of the SS lines.  Set the bit value for a given SS line
00421  * to 0 for active low or 1 for active high.
00422  */
00423 enum CheetahSpiPolarity {
00424     CH_SPI_POL_RISING_FALLING = 0,
00425     CH_SPI_POL_FALLING_RISING = 1
00426 };
00427 #ifndef __cplusplus
00428 typedef enum CheetahSpiPolarity CheetahSpiPolarity;
00429 #endif
00430 
00431 enum CheetahSpiPhase {
00432     CH_SPI_PHASE_SAMPLE_SETUP = 0,
00433     CH_SPI_PHASE_SETUP_SAMPLE = 1
00434 };
00435 #ifndef __cplusplus
00436 typedef enum CheetahSpiPhase CheetahSpiPhase;
00437 #endif
00438 
00439 enum CheetahSpiBitorder {
00440     CH_SPI_BITORDER_MSB = 0,
00441     CH_SPI_BITORDER_LSB = 1
00442 };
00443 #ifndef __cplusplus
00444 typedef enum CheetahSpiBitorder CheetahSpiBitorder;
00445 #endif
00446 
00447 /* Configure the SPI master interface */
00448 int ch_spi_configure (
00449     Cheetah            cheetah,
00450     CheetahSpiPolarity polarity,
00451     CheetahSpiPhase    phase,
00452     CheetahSpiBitorder bitorder,
00453     u08                ss_polarity
00454 );
00455 
00456 
00457 /* Clear the batch queue */
00458 int ch_spi_queue_clear (
00459     Cheetah cheetah
00460 );
00461 
00462 
00463 /* Enable / disable the master outputs */
00464 int ch_spi_queue_oe (
00465     Cheetah cheetah,
00466     u08     oe
00467 );
00468 
00469 
00470 /*
00471  * Queue a delay in clock cycles
00472  * The return value is the actual number of cycles queued.
00473  */
00474 int ch_spi_queue_delay_cycles (
00475     Cheetah cheetah,
00476     int     cycles
00477 );
00478 
00479 
00480 /*
00481  * Queue a delay in nanoseconds
00482  * The return value is the approximate number of nanoseconds queued.
00483  */
00484 int ch_spi_queue_delay_ns (
00485     Cheetah cheetah,
00486     int     nanoseconds
00487 );
00488 
00489 
00490 /*
00491  * Assert the slave select lines.  Each of the lower three
00492  * bits of ss_polarity corresponds to each of the SS lines.
00493  * Set the bit value for a given SS line to 1 to assert the
00494  * line or 0 to deassert the line.  The polarity is determined
00495  * by ch_spi_configure() above.
00496  */
00497 int ch_spi_queue_ss (
00498     Cheetah cheetah,
00499     u08     active
00500 );
00501 
00502 
00503 /* Repeatedly send a single byte */
00504 int ch_spi_queue_byte (
00505     Cheetah cheetah,
00506     int     count,
00507     u08     data
00508 );
00509 
00510 
00511 /*
00512  * Send a byte array.  Repeated bytes are automatically
00513  * optimized into a repeated byte sequence.
00514  */
00515 int ch_spi_queue_array (
00516     Cheetah     cheetah,
00517     int         num_bytes,
00518     const u08 * data_out
00519 );
00520 
00521 
00522 /* Calculate the expected length of the returned data */
00523 int ch_spi_batch_length (
00524     Cheetah cheetah
00525 );
00526 
00527 
00528 /*
00529  * Perform the SPI shift operation.
00530  *
00531  * After the operation completes, the batch queue is untouched.
00532  * Therefore, this function may be called repeatedly in rapid
00533  * succession.
00534  */
00535 int ch_spi_batch_shift (
00536     Cheetah cheetah,
00537     int     num_bytes,
00538     u08 *   data_in
00539 );
00540 
00541 
00542 /*
00543  * Queue the current batch queue for asynchronous shifting.
00544  *
00545  * After the operation completes, the batch queue is untouched.
00546  * Therefore, this function may be called repeatedly in rapid
00547  * succession.
00548  */
00549 int ch_spi_async_submit (
00550     Cheetah cheetah
00551 );
00552 
00553 
00554 /* Collect an asynchronous batch that was previously submitted. */
00555 int ch_spi_async_collect (
00556     Cheetah cheetah,
00557     int     num_bytes,
00558     u08 *   data_in
00559 );
00560 
00561 
00562 
00563 
00564 #ifdef __cplusplus
00565 }
00566 #endif
00567 
00568 #endif  /* __cheetah_h__ */
Generated on Sun May 8 08:41:38 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3