Fundamentals of #use spi versus setup_spi()

[SkeeterHawk]

It is understood that CCS is moving us programmers toward using the #use spi preprocessor over the "legacy" setup_spi() function, but the documentation is not clear on which function goes with which methodology of using the SPI port and you don't dare use the wrong one because disaster will almost certainly occur. The documentation within "Help" needs help. To make matters more confusing, the "SPI Overview" doesn't even mention the #use spi preprocessor that they actually want you to use.

Just going through the documentation, here are the functions and their assiciations

#use spi

spi_xfer() - Listed as the primary suggested function for R/W in the #use spi documentation. In the most recent compiler version 5.114, this function has issues in Slave mode and should not be used
spi_prewrite() - Not listed anywhere in the documentation, but is used within multiple Example programs within the compiler
spi_init() - This function says that it uses #use spi, but is not used in any of the Example files for SPI. This function appears to do the same thing as the preprocessor by setting the baud rate, so is this already obsolete?
spi_speed() - This function also says that it uses #use spi, but is not used in any of the Example files for SPI. This function appears to do the same thing as the preprocessor by setting the baud rate and clock, so is this already obsolete too?
spi_xfer_in() - Also not listed anywhere in the documentation, but is used within the Example program within the compiler

When #use spi is used and the chip has an SPI Peripheral and not a MSSP:

spi_transfer() - Listed as another suggested function at the bottom of the #use spi documentation
spi_transfer_write() - Listed as another suggested function at the bottom of the #use spi documentation
spi_transfer_read() - Listed as another suggested function at the bottom of the #use spi documentation
spi_transfer_done() - Listed as another suggested function at the bottom of the #use spi documentation
spi_transfer_clear() - Listed as another suggested function at the bottom of the #use spi documentation

setup_spi()

spi_write() - Listed as another suggested function at the bottom of the setup_spi() documentation
spi_read() - Listed as another suggested function at the bottom of the setup_spi() documentation
spi_data_is_in() - Listed as another suggested function at the bottom of the setup_spi() documentation
spi_set_txcnt() - Listed as another suggested function at the bottom of the setup_spi() documentation

_________________
Life is too short to only write code in assembly...

[temtronic]

just a comment , while waiting for SPRING to arrive.....

Since CCS wants everyone to use the 'new' way, perhaps they should remove the 'old' functions ?

This seems 'good' in my head and anyone with 'legacy' programs should be able to 'upgrade' to the newer functions ?

Then again, I still have a Window98SE PC up and running here......

[SkeeterHawk]

[Ttelmah]

There are a couple of other things here.
CCS always retain old functions, so you can still compile 'historical'
programs with the newer compilers.
The spi_transfer functions were added when chips arrived with the
SPI peripheral rather than the MSSP. This peripheral supports block
transfers of a number of bytes. Initially these only worked with these
peripherals. These were also hard to make emulate the older xfer
functions. After a few releases, CCS wrote versions that worked on
both peripherals, and managed to get the reverse emulation working.

[SkeeterHawk]

[Ttelmah]

Not quite.
They now offer spi_transfer on chips using the MSSP. They updated
the function so the emulation is now 'two way'. The older peripheral
can not use the spa_transfer function as well as the newer peripheral,
and they managed to produce an emulation of the standard spi_xfer
on the newer peripheral as well (this is quite hard to do if you look at the
data sheet for this).
There are some interesting 'hidden extras' on the newer function
(this is where a better demo and documentation would help massivly).
If you setup 'enable' in the #use spi, and use spi_transfer, it'll now
operate the enable at the start of the whole transaction, instead of
byte by byte. Undocumented....