Total Phase API
Total Phase API
8. In the event that there was a malfunction in the firmware update, the Aardvark
adapter may not be recognizable by an Aardvark-enabled application. Try the update
again, since the Aardvark adapter has most likely become locked due to a corruption in
the upgrade process. If the update still does not take effect, it is best to revert back to
the previous firmware. This can be done by running a previous version of aaflash that
contains an earlier firmware version. Check the Total Phase website or the
distribution CD that was included with your Aardvark adapter for previous versions of
the firmware.
5 API Documentation
Top
5.1 Introduction
The API documentation that follows is oriented toward the Aardvark Rosetta C bindings.
The set of API functions and their functionality is identical regardless of which Rosetta
language binding is utilized. The only differences will be found in the calling convention of
the functions. For further information on such differences please refer to the
documentation that accompanies each language bindings in the Aardvark software
distribution.
The Aardvark OEM I2C Host Adapter and the Aardvark OEM SPI Host Adapter have a
subset of these features. Attempting to use a feature that is not supported will result in an
error.
Top
5.2 General Data Types
The following definitions are provided for convenience. All Aardvark data types are
unsigned.
Top
5.3 Notes on Status Codes
Most of the Aardvark API functions can return a status or error code back to the caller.
The complete list of status codes is provided at the end of this chapter. All of the error
codes are assigned values less than 0, separating these responses from any numerical
values returned by certain API functions.
Each API function can return one of two error codes with regard to the loading of the
underlying Aardvark DLL, AA_UNABLE_TO_LOAD_LIBRARY and
AA_INCOMPATIBLE_LIBRARY. If these status codes are received, refer to the previous
sections in this manual that discuss the DLL and API integration of the Aardvark software.
Furthermore, all API calls can potentially return the error
AA_UNABLE_TO_LOAD_FUNCTION. If this error is encountered, there is likely a serious
version incompatibility that was not caught by the automatic version checking system.
Where appropriate, compare the language binding versions (e.g., AA_HEADER_VERSION
found in aardvark.h and AA_CFILE_VERSION found in aardvark.c ) to verify that there
are no mismatches. Next, ensure that the Rosetta language binding (e.g., aardvark.c and
aardvark.h ) are from the same release as the Aardvark DLL. If all of these versions are
synchronized and there are still problems, please contact Total Phase support for
assistance.
Any API function that accepts an Aardvark handle can return the error
AA_INVALID_HANDLE if the handle does not correspond to a valid Aardvark device that
has already been opened. If this error is received, check the application code to ensure
that the aa_open command returned a valid handle and that this handle is not corrupted
before being passed to the offending API function.
Finally, any I2C or SPI API call that communicates with an Aardvark device can return the
error AA_COMMUNICATION_ERROR. This means that while the Aardvark handle is valid and
the communication channel is open, there was an error receiving the acknowledgment
response from the Aardvark adapter. This can occur in situations where the incoming data
stream has been saturated by asynchronously received messages an outgoing message is
sent to the Aardvark adapter, but the incoming acknowledgment is dropped by the
operating system as a result of the incoming USB receive buffer being full. The error
signifies that it was not possible to guarantee that the connected Aardvark device has
processed the host PC request, though it is likely that the requested action has been
communicated to the Aardvark adapter and the response was simply lost. For example, if
the slave functions are enabled and the incoming communication buffer is saturated, an
API call to disable the slave may return AA_COMMUNICATION_ERROR even though the slave
has actually been disabled.
If either the I2C or SPI subsystems have been disabled by aa_configure, all other API
functions that interact with I2C or SPI will return AA_I2C_NOT_ENABLED or
AA_SPI_NOT_ENABLED, respectively.
These common status responses are not reiterated for each function. Only the error codes
that are specific to each API function are described below.
All of the possible error codes, along with their values and status strings, are listed
following the API documentation.
Top
5.4 General
5.4.1 Interface
Arguments
None.
Details
Each element of the array is written with the port number. Devices that are in use are
ORed with AA_PORT_NOT_FREE ( 0x8000 ).
Example:
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.
Arguments
Return Value
This function returns the number of devices found, regardless of the array sizes.
None.
Details
This function is the same as aa_find_devices() except that is also returns the
unique IDs of each Aardvark device. The IDs are guaranteed to be non-zero if valid.
The IDs are the unsigned integer representation of the 10-digit serial numbers.
The number of devices and IDs returned in each of their respective arrays is
determined by the minimum of num_devices and num_ids. However, if either array is
NULL, the length passed in for the other array is used as-is, and the NULL array is not
populated. If both arrays are NULL, neither array is populated, but the number of
devices found is still returned.
Open an Aardvark device (aa_open) Top
Aardvark aa_open (int port_number);
Open the Aardvark port.
Arguments
port_number The port is the same as the one obtained from function
aa_find_devices. It is a zero-based number.
Return Value
This function returns an Aardvark handle, which is guaranteed to be greater than zero
if valid.
Details
This function is recommended for use in simple applications where extended
information is not required. For more complex applications, the use of
aa_open_ext() is recommended.
The open function also deactivates all slave functionality. An Aardvark device could
have potentially been opened, enabled as a slave, and configured to send
asynchronous responses to a third-party master. If the controlling application quits
without calling aa_close(), the port is freed but the slave functions can still be active.
The open function deactivates slave functionality to ensure that the new application
has access to an Aardvark device that is in a known-state. Also the I2C bus is freed, in
the event that it was held indefinitely from a previous AA_I2C_NO_STOP transaction.
Arguments
Details
If 0 is passed as the pointer to the structure, this function will behave exactly like
aa_open().
The features field denotes the capabilities of the Aardvark device. See the API
function aa_features for more information.
The structure is zeroed before the open is attempted. It is filled with whatever
information is available. For example, if the firmware version is not filled, then the
device could not be queried for its version number.
This open function also terminates all slave functionality as described for the
aa_open() call.
Arguments
None.
Details
An Aardvark adapter could have potentially been opened, enabled as a slave, and
configured to send and receive asynchronous responses to and from a third-party
master. A call to aa_close() will deactivate all slave functionality. Also the I2C bus is
freed, in the event that it was held indefinitely from a previous AA_I2C_NO_STOP
transaction.
If the handle argument is zero, the function will attempt to close all possible handles,
thereby closing all open Aardvark adapters. The total number of Aardvark adapters
closed is returned by the function.
Arguments
Return Value
None.
Details
None.
Arguments
Return Value
The features of the Aardvark device are returned. These are a bit-mask of the
following values.
None.
Details
None.
Arguments
Return Value
This function returns the unique ID for this Aardvark adapter. The IDs are guaranteed
to be non-zero if valid. The ID is the unsigned integer representation of the 10-digit
serial number.
None.
Details
None.
Arguments
Return Value
This function returns a human readable string that corresponds to status. If the code is
not valid, it returns a NULL string.
None.
Details
None.
Arguments
Details
The handle must be standard file descriptor. In C, a file descriptor can be obtained by
using the ANSI C function "open" or by using the function "fileno" on a FILE* stream.
A FILE* stream obtained using fopen or can correspond to the common stdout or
stderr available when including stdlib.h.
0 none
1 – error
2 – warning
3 – info
4 – debug
Note that if the handle is invalid, the application can crash during a logging operation.
Due to inconsistencies arising from how Microsoft handles linkage to the C runtime
library, logging to a file may not work in Windows. However, logging to stdout and
stderr is still supported. As a convenience, the following two constants are defined
and can be passed as the handle argument.
AA_LOG_STDOUT
AA_LOG_STDERR
Arguments
Return Value
An Aardvark status code is returned with AA_OK on success.
None.
Details
If the handle is 0 or invalid, only the software version is set.
Arguments
aardvark handle of an Aardvark adapter
config enumerated type specifying configuration. See Table 2
AA_CONFIG_GPIO_ONLY Configure all pins as GPIO. Disable both I2C and SPI.
AA_CONFIG_SPI_GPIO Configure I2C pins as GPIO. Enable SPI.
AA_CONFIG_GPIO_I2C Configure SPI pins as GPIO. Enable I2C.
AA_CONFIG_SPI_I2C Disable GPIO. Enable both I2C and SPI.
AA_CONFIG_QUERY Queries existing configuration (does not modify).
Return Value
The current configuration on the Aardvark adapter will be returned. The configuration
will be described by the same values in AardvarkConfig.
AA_CONFIG_ERROR The I2C or SPI subsystem is currently active and the new
configuration requires the subsystem to be deactivated.
Details
If either the I2C or SPI subsystems have been disabled by this API call, all other API
functions that interact with I2C or SPI will return AA_CONFIG_ERROR.
Note: Whenever the configure command is executed and GPIO lines are enabled, the
GPIO lines will be momentarily switched to high-Z before their direction and pullup
configurations are executed.
Arguments
Details
Both target power pins are controlled together. Independent control is not supported.
This function may be executed in any operation mode.
Check if there is any asynchronous data pending from the Aardvark adapter.
Arguments
Return Value
A status code indicating which types of asynchronous messages are available for
processing. See Table 4.
These codes can be bitwise ORed together if there are multiple types of data available.
None.
Details
Recall that, like all other Aardvark functions, this function is not thread-safe.
If the timeout value is negative, the function will block indefinitely until data arrives. If
the timeout value is 0, the function will perform a non-blocking check for pending
asynchronous data.
As described before, the Aardvark software contains asynchronous queues that can
be filled during synchronous operations on the Aardvark adapter. If data is already in
one or more asynchronous queues, it will immediately return with all of the types of
asynchronous data that are currently available. Further data may be pending in the
operating systems incoming receive buffer, but the function will not examine that
data. Hence any pending data in the operating systems incoming buffer will not be
reported to the user until the Aardvarks software queues have been fully serviced.
If there is no data already available, this function will check the operating systems
receive buffer for the presence of asynchronous data. The function will block for the
specified timeout. It will then only report the type of the very first data that has been
received. The function will not examine the remainder of the operating systems
receive buffer to see what other asynchronous messages are pending.
One can employ the following technique to guarantee that all pending asynchronous
data have been captured during each service cycle:
2. If the polling function indicates that there is data available, call the appropriate
service function once for each type of data that is available.
4. Call the appropriate service function once for each type of data that is available.
5. Repeat steps 3 and 4 until the polling function reports that there is no data
available.
Sleep (aa_sleep_ms) Top
u32 aa_sleep_ms (u32 milliseconds);
Sleep for given amount of time.
Arguments
None.
Details
The accuracy of this function depends on the operating system scheduler. This
function will return the number of milliseconds that were actually slept.
Top
5.5 I2C Interface
1. It is not necessary to set the bitrate for the Aardvark I2C slave.
2. An I2C master operation read or write operation can be transacted while leaving the
I2C slave functionality enabled. In a multi-master situation it is possible for the
Aardvark adapter to lose the bus during the slave addressing portion of the
transaction. If the other master that wins the bus subsequently addresses this
Aardvark adapters slave address, the Aardvark adapter will respond appropriately to
the request using its slave mode capabilities.
3. It is always advisable to set the slave response before first enabling the slave. This
ensures that valid data is sent to any requesting master.
4. It is not possible to receive messages larger than approximately 4 KiB as a slave due to
operating system limitations on the asynchronous incoming buffer. As such, one
should not queue up more than 4 KiB of total slave data between calls to the Aardvark
API.
5. Since firmware revision 2.00 it is possible for the Aardvark I2C master to employ some
of the advanced features of I2C. This is accomplished by the AardvarkI2cFlags
argument type that is included in the aa_i2c_read and aa_i2c_write argument lists.
The options in Table 5 are available can be logically ORed together to combine them
for one operation.
6. Since firmware revision 3.00 it is possible for the Aardvark I2C master to return an
extended status code for master read and master write transactions. These codes are
described in Table 6 and are returned by the aa_i2c_read_ext and
aa_i2c_write_ext functions, as well as the analogous slave API functions.
5.5.2 General I2C
Arguments
Return Value
The current state of the I2C pull-up resistors on the Aardvark adapter will be
returned. The configuration will be described by the same values as in the table above.
Details
Both pull-up resistors are controlled together. Independent control is not supported.
This function may be performed in any operation mode.
Arguments
Return Value
An Aardvark status code is returned that is AA_OK on success.
AA_I2C_ALREADY_FREE_BUS The bus was already free and no action was taken.
Details
If the Aardvark I2C subsystem had executed a master transaction and is holding the
bus due to a previous AA_I2C_NO_STOP flag, this function will issue the stop command
and free the bus. If the bus is already free, it will return the status code
AA_I2C_BUS_ALREADY_FREE.
Similarly, if the Aardvark I2C subsystem was placed into slave mode and in the middle
of a slave transaction, this command will disconnect the slave from the bus, flush the
last transfer, and re-enable the slave. Such a feature is useful if the Aardvark adapter
was receiving bytes but then was forced to wait indefinitely on the bus because of the
absence of the terminating stop command. After disabling the slave, any pending slave
reception will be available to the host through the usual aa_i2c_slave_write_stats
and aa_i2c_slave_read API calls.
The bus is always freed (i.e., a stop command is executed if necessary) and the slave
functions are disabled at software opening and closing of the device.
Arguments
Return Value
This function returns the actual timeout set.
None.
Details
The power-on default timeout is 200ms. The minimum timeout value is 10ms and the
maximum is 450ms. If a timeout value outside this range is passed to the API function,
the timeout will be restricted. The exact timeout that is set can vary based on the
resolution of the timer within the Aardvark adapter. The nominal timeout that was set
is returned back by the API function.
If timeout_ms is 0, the function will return the bus lock timeout presently set on the
Aardvark adapter and the bus lock timeout will be left unmodified.
If the bus is locked during the middle of any I2C transaction (master transmit, master
receive, slave transmit, slave receive) the appropriate extended API function will
return the status code AA_I2C_STATUS_BUS_LOCKED as described in the preceding
Notes section. The bus lock timeout is measured between events on the I2C bus,
where an event is a start condition, the completion of 9bits of data transfer, a repeated
start condition, or a stop condition. For example, if a full 9 bits are not completed
within the bus lock timeout (due to clock stretching or some other error), the bus lock
error will be triggered.
Please note that once the Aardvark adapter detects a bus lock timeout, it will abort its
I2C interface, even if the timeout condition is seen in the middle of a byte. When the
Aardvark is acting as an I2C mater device, this may result in only a partial byte being
executed on the bus.
Arguments
aardvark handle of an Aardvark adapter
bitrate_khz the requested bitrate in khz.
Return Value
This function returns the actual bitrate set.
None.
Details
The power-on default bitrate is 100 kHz.
Only certain discrete bitrates are supported by the Aardvark I2C master interface. As
such, this actual bitrate set will be less than or equal to the requested bitrate.
If bitrate_khz is 0, the function will return the bitrate presently set on the Aardvark
adapter and the bitrate will be left unmodified.
Arguments
Return Value
Number of bytes read.
Details
For ordinary 7-bit addressing, the lower 7 bits of slave_addr should correspond to
the slave address. The topmost bits are ignored. The Aardvark I2C subsystem will
assemble the address along with the R/W bit after grabbing the bus. For 10-bit
addressing, the lower 10 bits of addr should correspond to the slave address. The
Aardvark adapter will then assemble the address into the proper format as described
in the Philips specification, namely by first issuing an write transaction on the bus to
specify the 10-bit slave and then a read transaction to read the requested number of
bytes. The initial write transaction can be skipped if the "Combined Format" feature is
requested in conjunction with the 10-bit addressing functionality.
If the number of bytes read is zero, the following conditions are possible.
The requested slave is on the bus but refuses to acknowledge its address.
The Aardvark adapter was unable to seize the bus due to the presence of
another I2C master. Here, the arbitration was lost during the slave addressing
phase – results can be unpredictable.
Zero bytes were requested from a slave. The slave acknowledged its address
and returned 1 byte. That byte was dropped.
Ordinarily the number of bytes read, if not 0, will equal the requested number of bytes.
One special scenario in which this will not happen is if the Aardvark adapter loses the
bus during the data transmission due to the presence of another I2C master.
If the slave has fewer bytes to transmit than the number requested by the master, the
slave will simply stop transmitting and the master will receive 0xff for each remaining
byte in the transmission. This behavior is in accordance with the I2C protocol.
Additionally, the flags argument can be used to specify a sized read operation. If the
flag includes the value AA_I2C_SIZED_READ, the Aardvark adapter will treat the first
byte received from the slave as a packet length field. This length denotes the number
of bytes that the slave has available for reading (not including the length byte itself).
The Aardvark adapter will continue to read the minimum of num_bytes-1 and the
length field. The length value must be greater than 0. If it is equal to 0, it will be treated
as though it is 1. In order to support protocols that include an optional checksum byte
(e.g., SMBus) the flag can alternatively be set to AA_I2C_SIZED_READ_EXTRA1. In this
case the Aardvark will read one more data byte beyond the number specified by the
length field.
Arguments
None.
Details
This function operates exactly like aa_i2c_read, except that the return value now
specifies a status code. The number of bytes read is returned through an additional
pointer argument at the tail of the parameter list.
The status code allows the user to discover specific events on the I2C bus that would
otherwise be transparent given only the number of bytes transacted. The "Notes"
section describes the status codes.
For a master read operation, the AA_I2C_STATUS_DATA_NACK flag is not used since
the acknowledgment of data bytes is predetermined by the master and the I2C
specification.
Arguments
Return Value
Number of bytes written.
Details
For ordinary 7-bit addressing, the lower 7 bits of slave_addr should correspond to
the slave address. The topmost bits are ignored. The Aardvark I2C subsystem will
assemble the address along with the R/W bit after grabbing the bus. For 10-bit
addressing, the lower 10 bits of addr should correspond to the slave address. The
Aardvark adapter will then assemble the address into the proper format as described
in the Philips specification. There is a limitation that a maximum of only 65534 bytes
can be written in a single transaction if the 10-bit addressing mode is used.
The slave_addr 0x00 has been reserved in the I2C protocol specification for general
call addressing. I2C slaves that are enabled to respond to a general call will
acknowledge this address. The general call is not treated specially in the Aardvark I2C
master. The user of this API can manually assemble the first data byte if the hardware
address programming feature with general call is required.
It is actually possible to write 0 bytes to the slave. The slave will be addressed and then
the stop condition will be immediately transmitted by the Aardvark adapter. No bytes
are sent to the slave, so the data argument is ignored (i.e., it can be 0 or point to invalid
memory).
If the number of bytes written is zero, the following conditions are possible.
The requested slave is on the bus but refuses to acknowledge its address.
The Aardvark adapter was unable to seize the bus due to the presence of
another I2C master. Here, the arbitration was lost during the slave addressing
phase results can be unpredictable.
The slave was addressed and no bytes were written to it because num_bytes
was set to 0.
The number of bytes written can be less than the requested number of bytes in the
transaction due to the following possibilities.
The Aardvark adapter loses the bus during the data transmission due to the
presence of another I2C master.
Arguments
Return Value
Status code (see "Notes" section).
None.
Details
This function operates exactly like aa_i2c_write, except that the return value now
specifies a status code. The number of bytes written is returned through an additional
pointer argument at the tail of the parameter list.
The status code allows the user to discover specific events on the I2C bus that would
otherwise be transparent given only the number of bytes transacted. The "Notes"
section describes the status codes.
Normally the I2C master will write to the slave until the slave issues a NACK or
the requested number of bytes have been written.
If the master has wishes to write 10 bytes, the I2C slave issues either an ACK or
NACK on the tenth byte without affecting the total number of bytes transferred.
Hence, the aa_i2c_write function cannot provide the caller with the information
that the 10th byte was ACK'ed or NACK'ed.
On the other hand, if the aa_i2c_write_ext is used, the status code will
distinguish the two scenarios. This status information could be useful for further
communications with that particular slave device.
Arguments
Return Value
Combined I2C status code from the write and read operations.
None.
Details
This function performs the functions of aa_i2c_write_ext and aa_i2c_read_ext in
one atomic operation, thereby minimizing the latency between consecutive write and
read operations due to the USB communication layer.
A combined status code from the write and the read operations is provided as the
return value of the function. The return value is constructed as (read_status
<< 8) | (write_status). See the "Notes" section, along with the details of
aa_i2c_write_ext and aa_i2c_read_ext, for more discussion about the specific
status codes. Note that if the write phase of the operation completes with a non-zero
status code, the Aardvark adapter will not physically execute the read phase of the
operation.
If either the write or read fails with an error (as opposed to simply a non-zero status
code), the return value of the function reflects the appropriate error code, with
preference given to write errors.
Arguments
Return Value
An Aardvark status code is returned that is AA_OK on success.
None.
Details
The lower 7 bits of addr should correspond to the slave address of this Aardvark
adapter. If the topmost bit of addr is set, the slave will respond to a general call
transmission by an I2C master. After having been addressed by a general call, the
Aardvark I2C slave treats the transaction no differently than a single slave
communication. There is no support for the hardware address programming feature of
the general call that is described in the I2C protocol specification since that capability
is not needed for Aardvark devices.
If maxTxBytes is 0, there is no limit on the number of bytes that this slave will transmit
per transaction. If it is non-zero, then the slave will stop transmitting bytes at the
specified limit and subsequent bytes received by the master will be 0xff due to the
bus pull-up resistors. The response that is transmitted by the slave is set through the
aa_i2c_slave_set_response function described below. If the maximum is greater
than the response (as set through aa_i2c_slave_set_response ) the Aardvark slave
will wrap the response string as many times as necessary to send the requested
number of bytes.
If maxRxBytes is 0, the slave can receive an unlimited number of bytes from the
master. However, if it is non-zero, the slave will send a not-acknowledge bit after the
last byte that it accepts. The master should then release the bus. Even if the master
does not stop transmitting, the slave will return the received data back to the host PC
and then transition to a idle state, waiting to be addressed in a subsequent transaction.
If a master transaction is executed after the slave features have been enabled, the
slave features will remain enabled after the master transaction completes.
Arguments
Return Value
An Aardvark status code is returned that is AA_OK on success.
None.
Details
None.
Arguments
Return Value
The number of bytes accepted by the Aardvark slave for the response.
None.
Details
The value of num_bytes must be greater than zero. If it is zero, the response string is
undefined until this function is called with the correct parameters.
Due to limited buffer space on the Aardvark slave, the device may only accept a
portion of the intended response. If the value returned by this function is less than
num_bytes the Aardvark slave has dropped the remainder of the bytes.
If more bytes are requested in a transaction, the response string will be wrapped as
many times as necessary to complete the transaction.
Arguments
Return Value
The number of bytes written asynchronously.
This function will wait 500 milliseconds before timing out. See the aa_async_poll
function if a variable timeout is required.
(aa_i2c_slave_write_stats_ext)
int aa_i2c_slave_write_stats_ext (Aardvark aardvark, aa_u16 *
num_written);
Return number of bytes written from a previous Aardvark I2C slave to I2C master
transmission with extended status information.
Arguments
Return Value
None.
Details
This function operates exactly like aa_i2c_slave_write_stats, except that the
return value now specifies a status code. The number of bytes written is returned
through an additional pointer argument at the tail of the parameter list.
The only possible status code is AA_I2C_STATUS_BUS_ERROR which can occur when an
illegal START, STOP, or RESTART condition appears on the bus during a transaction. In
this case the num_written may not exactly reflect the number of bytes written by the
slave. It can be off by 1.
Arguments
Return Value
This function returns the number of bytes read asynchronously.
Details
If the message was directed to this specific slave, *addr will be set to the value of this
slaves address. However, this slave may have received this message through a general
call addressing. In this case, *addr will be 0x80 instead of its own address.
The num_bytes parameter specifies the size of the memory pointed to by data. It is
possible, however, that the received slave message exceeds this length. In such a
situation, AA_I2C_DROPPED_EXCESS_BYTES is returned, meaning that num_bytes was
placed into data but the remaining bytes were discarded.
There is no cause for alarm if the number of bytes read is less than num_bytes. This
simply indicates that the incoming message was short.
The reception of bytes by the Aardvark slave, when it is configured as an I2C slave, is
asynchronous with respect to the PC host software. Hence, there could be multiple
responses queued up from previous transactions.
This function will wait 500 milliseconds before timing out. See the aa_async_poll
function if a variable timeout is required.
Arguments
None.
Details
This function operates exactly like aa_i2c_slave_read, except that the return value
now specifies a status code. The number of bytes read is returned through an
additional pointer argument at the tail of the parameter list.
The only possible status code is AA_I2C_STATUS_BUS_ERROR which can occur when an
illegal START, STOP, or RESTART condition appears on the bus during a transaction.
Top
5.6 SPI Interface
1. The SPI master and slave must both be configured to use the same bit protocol (mode).
2. It is not necessary to set the bitrate for the Aardvark SPI slave.
3. An SPI master operation read or write operation can be transacted while leaving the
SPI slave functionality enabled. During the master transaction, the slave will be
temporarily deactivated. Once the master transaction is complete, the slave will be
automatically reactivated.
4. It is always advisable to set the slave response before first enabling the slave. This
ensures that valid data is sent to any requesting master.
5. It is not possible to receive messages larger than approximately 4 KiB as a slave due to
operating system limitations on the asynchronous incoming buffer. As such, one
should not queue up more than 4 KiB of total slave data between calls to the Aardvark
API.
6. It is not possible to send messages larger than approximately 4 KiB as a master due to
operating system limitations on the asynchronous incoming buffer. The SPI is full-
duplex so there must be enough buffer space to accommodate the slave response
when sending as a master.
7. Sending zero bytes as an SPI master will simply toggle the slave select line for 5-10 µs.
Arguments
Return Value
An Aardvark status code is returned that is AA_OK on success.
None.
Details
These configuration parameters specify how to clock the bits that are sent and
received on the Aardvark SPI interface.
The polarity option specifies which transition constitutes the leading edge and which
transition is the falling edge. For example, AA_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. For
example, AA_SPI_PHASE_SAMPLE_SETUP would configure the SPI to sample on the
leading edge and setup on the trailing edge.
The bitorder option is used to indicate whether LSB or MSB is shifted first.
Arguments
Return Value
This function returns the actual bitrate set.
Specific Error Codes
None.
Details
Only certain discrete bitrates are supported by the Aardvark adapter. As such, this
actual bitrate set will be less than or equal to the requested bitrate unless the
requested value is less than 125 kHz, in which case the Aardvark adapter will default
to 125 kHz.
If bitrate_khz is 0, the function will return the bitrate presently set on the Aardvark
adapter and the bitrate will be left unmodified.
(aa_spi_master_ss_polarity)
int aa_spi_master_ss_polarity (Aardvark aardvark,
AardvarkSpiSSPolarity polarity);
Change the output polarity on the SS line.
Arguments
Return Value
None.
Details
This function only affects the SPI master functions on the Aardvark adapter. When
configured as an SPI slave, the Aardvark adapter will always be setup with SS as active
low.
Arguments
Return Value
This function returns the total number of bytes read from the slave which normally
will be the same as the number of bytes written to the slave. See below for how this
value relates to in_num_bytes.
Details
Due to the full-duplex nature of the SPI protocol, for every byte written to the slave,
one byte is also received. The Aardvark will always receive the same number of bytes
that it sends out (barring any error). This is the return value mentioned above. The
user has the option of saving all, some, or none of those received bytes by varying the
size of in_num_bytes.
This function will always write out the number of bytes defined by out_num_bytes
from the memory pointed to by data_out. When out_num_bytes is larger than
in_num_bytes, data_in is completely filled and any extra bytes are dropped. When
out_num_bytes is less than in_num_bytes, all the received bytes are saved and
data_in is only partially filled.
The data_in pointer should reference memory that is at least allocated to the size
specified by in_num_bytes. Otherwise there will be a memory access violation in the
program.
If out_num_bytes is 0, no bytes will be written to the slave. However, the slave select
line will be dropped for 5-10 µs. This can be useful in sending a signal to a downstream
SPI slave without actually sending any bytes. For example, if an SPI slave has tied the
slave select to an interrupt line and it sees the line is toggled without any bytes sent, it
can interpret the action as a command to prepare its firmware for an subsequent
reception of bytes. If out_num_bytes is 0, data_out, data_in, and in_num_bytes
can be set to 0.
If the return value of this function is less than out_num_bytes, there was an error. SPI
is a bit-blasting scheme where the master does not even know if there is a slave on the
other end of the transmission. Therefore, it is always expected that the master will
send the entire length of the transaction.
An error will likely occur if the number of bytes sent is significantly greater than 4 KiB.
This function cannot reliably execute larger transfers due to the buffering issues
explained in the "Software | Application Notes" section. Only a partial number of bytes
will be sent to the slave and only a partial number will be received from the slave; it is
quite possible that these numbers will not be equal. The size of the partial response is
returned by this function and any received data up to in_num_bytes will be in the
memory pointed to by data_in. Note that the last few bytes of the response may be
corrupted as well.
Arguments
Return Value
None.
Details
None.
Arguments
Return Value
An Aardvark status code is returned that is AA_OK on success.
None.
Details
None.
Arguments
Return Value
The number of bytes accepted by the Aardvark for the response.
None.
Details
The value of num_bytes must be greater than zero. If it is zero, the response string is
undefined until this function is called with the correct parameters.
Due to limited buffer space on the Aardvark slave, the device may only accept a
portion of the intended response. If the value returned by this function is less than
num_bytes the Aardvark slave has dropped the remainder of the bytes.
If more bytes are requested in a transaction, the response string will be wrapped as
many times as necessary to complete the transaction.
The buffer space will nominally be 64 bytes but may change depending on firmware
revision.
Arguments
Details
The num_bytes parameter specifies the size of the memory pointed to by data. It is
possible, however, that the received slave message exceeds this length. In such a
situation, AA_SPI_DROPPED_EXCESS_BYTES is returned, meaning that num_bytes was
placed into data but the remaining bytes were discarded.
There is no cause for alarm if the number of bytes read is less than num_bytes. This
simply indicates that the incoming message was short.
The reception of bytes by the Aardvark adapter, when it is configured as an SPI slave,
is asynchronous with respect to the PC host software. Hence, there could be multiple
responses queued up from previous write transactions.
This function will wait 500 milliseconds before timing out. See the aa_async_poll
function if a variable timeout is required.
The SPI API does not include a function that is analogous to the I2C function
Top
5.7 GPIO Interface
1. The following enumerated type maps the named lines on the Aardvark I2C/SPI output
cable to bit positions in the GPIO API. All GPIO API functions will index these lines
through a single 8-bit masked value. Thus, each bit position in the mask can be
referred back its corresponding line through the mapping described below.
Table 8 : AardvarkGpioBits : enumerated type of line locations in bit mask
2. There is no check in the GPIO API calls to see if a particular GPIO line is enabled in the
current configuration. If a line is not enabled for GPIO, the get function will simply
return 0 for those bits. Another example is if one changes the GPIO directions for I2C
lines while the I2C subsystem is still active. These new direction values will be cached
and will automatically be activate if a later call to aa_configure disables the I2C
subsystem and enables GPIO for the I2C lines. The same type of behavior holds for
aa_gpio_pullup and aa_gpio_set.
3. Additionally, for lines that are not configured as inputs, a change in the pullup
configuration using aa_gpio_pullup will be cached and will take effect the next time
the line is active and configured as an input. The same behavior holds for aa_gpio_set
when a line is configured as an input instead of an output.
5. Note: For hardware version 1.02, it is not possible to have high-Z inputs on the I2C
lines since that hardware has 2.2K pullups on the I2C bus.
Arguments
None.
Details
None.
Arguments
Return Value
An Aardvark status code is returned that is AA_OK on success.
None.
Details
None.
Arguments
Return Value
None.
Details
A line's bit position in the mask will be 0 if it is configured as an output or if it
corresponds to a subsystem that is still active.
Return Value
None.
Details
If a line is configured as an input or not activated for GPIO, the output value will be
cached. The next time the line is an output and activated for GPIO, the output value
previously set will automatically take effect.
Arguments
None.
Details
The function will return either when a change has occurred or the timeout expires.
Pins configured for I2C or SPI will be ignored. Pins configured as outputs will be
ignored. The timeout, specified in milliseconds, has a precision of approximately 2 ms.
The maximum allowable timeout is approximately 60 seconds. If the timeout expires,
this function will return the current state of the GPIO lines. It is the applications
responsibility to save the old value of the lines and determine if there is a change
based on the return value of this function.
The function aa_gpio_change will return immediately with the current value of the
GPIO lines for the first invocation after any of the following functions are called:
aa_configure, aa_gpio_direction, or aa_gpio_pullup. If the function
aa_gpio_get is called before calling aa_gpio_change, aa_gpio_change will only
register any changes from the value last returned by aa_gpio_get.
Top
5.8 Error Codes
6 Legal / Contact
Top
6.1 Disclaimer
All of the software and documentation provided in this manual, is copyright Total Phase,
Inc. ("Total Phase"). License is granted to the user to freely use and distribute the software
and documentation in complete and unaltered form, provided that the purpose is to use or
evaluate Total Phase products. Distribution rights do not include public posting or
mirroring on Internet websites. Only a link to the Total Phase download area can be
provided on such public websites.