Add SPI method: bulkread

[mcprat]

Designed for communication with SPI Flash memory chips.

Single-use or combinations of the existing methods are not efficient or functional for the use case of NOR/NAND flash chip reading and writing. It is essential that between reading and writing that the Chip Select pin remains asserted (High) for the entire period. Usage of the write and read methods is therefore not possible in combination because each of them de-asserts CS at the end of the method. There is no need for that behavior to change though.

The transfer method is inefficient because it sends a command to the FT232H that not only allows Full-Duplex but actually REQUIRES it for a command to complete. This is due to the design of the MPSSE. If I use the same FT232H command and attempt to read more than I am writing, a timeout occurs. In other words, the FT232H only allows communication at all during a Full-duplex command when there is data to be handled in Full-duplex, the amount you read MUST BE equal to the amount you write.

For example, an SPI read of a NOR flash chip: After instructing the FT232H to open the connection to the flash chip, you write the command to the slave as 1 byte, then the address as 3 bytes and the chip responds AFTER the write, not DURING, for as long as CS is asserted. In order to read only 1 of the 64 blocks of a 4 MB flash chip using the transfer method, I would have to append 65,532 zeros to the array that I am writing to the chip to keep the connection alive for each iteration of the loop, which is mandated both by the slave (NOR Flash) with CS, and by the master (FT232H) with the full-duplex command. Again, half-duplex read then write is a very simple matter, as with any SPI slave, that would be treated as two separate commands, read and then write. But on many SPI slaves, half-duplex write then read is almost always in the same instruction, where CS assertion must not be interrupted between commands of the master (FT232H), and this is a very popular implementation.

I have also designed this method to solve the issue #94 that I posted

For a while, I thought it should work with a single write command and two poll reads
...not true...

in parallel order, double read still doesnt fix it:

spi._ft232h._write(str(bytearray((commandR, len_lowR, len_highR))))
spi._ft232h._write(str(bytearray((commandR, len_lowR, len_highR))))
payload1 = spi._ft232h._poll_read(lengthR)
payload2 = spi._ft232h._poll_read(lengthR)

but in series order, double read does give clean output:

spi._ft232h._write(str(bytearray((commandR, len_lowR, len_highR))))
payload1 = spi._ft232h._poll_read(lengthR)
spi._ft232h._write(str(bytearray((commandR, len_lowR, len_highR))))
payload2 = spi._ft232h._poll_read(lengthR)

This is tested both in situations where the expected output is all ff, the expected output is all 00, or the expected output is real life data, confirmed with CRC32.

My take on this is basically sacrificing a little more python environment memory, to save the chips buffer from suffering. I am convinced that the problem is NOT with the poll_read function.
I am not sure if it is just my chip with this problem or many more, but this surely prevents it from appearing during heavy use, at practically any frequency. I have tried setting my clock as low as 1 MHz.

Therefore I propose this method, bulkread (I can't think of a better name, maybe readblock) with the following features...

• both the array to write and the length to read back are optional (one or the other), configurable, and with defaults
• allows a read up to the limit of the FT232H capabilities, both hard limit in the datasheet (64 KB) by ensuring input is within the range...
• and soft limit handling from data corruption issue observed in my real life testing by simply performing two separate poll reads (see Single-byte data corruption from FT232H Hardware Limits #94)
• Warning the user about the data length limits
• Deasserting CS is the VERY LAST action sent to the FT232H
• the buffer flush command (0x87) is not used, in my testing, it makes no difference, less talking to the master means more talking to the slave.
• a very simple mode setting, to allow writing only with the same method, not having to change methods by setting readmode to 0
• all math is moved to the top, before anything is pushed to the device

Similar logic should be applied to every other method in the library, to inform the user before errors occur, and prevent errors due to (most likely) hardware defects.

@ladyada @tdicola Please help me out with the logger.debug line...I'm not sure about the syntax or purpose or usage of it