tanriol/ftdi-rs

A Rust wrapper over libftdi1 library for FTDI devices

ftdi-rs's Issues

FTDI JTAG ECLIPSE

Unify `ftdi-rs` and `safe-ftdi`

Opening this Issue so we can hash out the details... I documented my findings in a Markdown file, reproduced here for convenience :)

Differences between ftdi-rs and safe-ftdi

Short version: We both seem to have the same ideas, but slightly different
ways of going about implementing a safe wrapper.

Context struct

ftdi-rs keeps a copy of the ftdi_context; safe-ftdi stores
a pointer.

ftdi-rs:

pub struct Context {
    native: ffi::ftdi_context,
}

safe-ftdi:

pub struct Context {
    context : *mut ftdic::ftdi_context,
}

Similarly, for Drop:

ftdi-rs:

impl Drop for Context {
    fn drop(&mut self) {
        unsafe { ffi::ftdi_deinit(&mut self.native) }
    }
}

safe-ftdi:

impl Drop for Context {
    fn drop(&mut self) {
        unsafe { ftdic::ftdi_free(self.context) }
    }
}

I'm not sure which one is better...

Error Handling

ftdi-rs maps everything back to an io::Result type, and each function has
function-specific matching code
to map back to an io::Error in the Err variant of io::Result.

safe-ftdi has a single private check_ftdi_error
that's at the end of each function that maps back to its own safe_ftdi::Error
in the Err variant of safe-ftdi::Result. With some error, we could probably
implement From<T> for safe_ftdi::Error for various errors to use ? and
avoid typing out check_ftdi_error in each function.

Present in ftdi-rs but not safe-ftdi

• Read and Write implementations! This is good, and something I should've
  implemented, but didn't :D!
• You follow C-GETTER in the API guidelines. I didn't get this far, but I
  wouldn't have before learning about this tonight.
• Better bounds-checking.

Present in safe-ftdi but not ftdi-rs

• A crate-specific error type.
  I think this is preferable to reusing io::Result<>, and it seems to be
  standard for crates to define their own error type. A friend has been helping
  me out with redefining what such an error type looks like.
• mercpcl re-implementation :).

Other Questions I Have

• Can ftdi_rs::Interface
  be a C-style enum, removing the Into conversion?

Function name mapping

libftd1-sys	ftdi-rs	safe-ftdi	Comment
ftdi_init	new
ftdi_new		new
ftdi_set_interface	set_interface
ftdi_usb_reset	usb_reset
ftdi_usb_purge_buffers	usb_purge_buffers
ftdi_set_latency_timer	set_latency_timer
ftdi_get_latency_timer	latency_timer		C-GETTER
ftdi_write_data_set_chunksize	set_write_chunksize
ftdi_write_data_get_chunksize	write_chunksize		C-GETTER
ftdi_read_data_set_chunksize	set_read_chunksize
ftdi_read_data_get_chunksize	read_chunksize		C-GETTER
ftdi_usb_open	usb_open	open
ftdi_set_baudrate		set_baudrate
ftdi_set_bitmode		set_bitmode
ftdi_read_pins		read_pins
ftdi_read_data	io::Read::read	read_data	Should be exposed along w/ trait?
ftdi_write_data	io::Write::write	write_data	Should be exposed along w/ trait?

Create an async API of some kind

The main options are:

• Reuse the libftdi APIs.
  Upside: close to the upstream APIs.
  Downside: weird integration because these APIs want to drive the libusb event loop themselves.

• Reuse the libftdi APIs, but also provide integration with tokio / async-std.
  Upside: close to upstream and more or less native.
  Downside: a significant amount of nontrivial code.

• Reimplement basic read/write and provide integration with tokio / async-std.
  Upside: more or less native.
  Downside: a significant amount of nontrivial code, including some minimal REing of libftdi.

• Use a separate ftdi thread, provide integration based on futures channels.
  Upside: should be pretty easy.
  Downside: extra latency.

• Something else?

Consider implementing a FTDI D2XX backend

According to @xobs,

The big thing ftd2xx gets us on Windows is driver-less plug-and-play operation, which is much easier on support.

However, the big downside IMHO is the licensing situation. The driver license terms contain a few points that look potentially problematic. Warning: I am not a lawyer, this is not a legal advice, if you have any doubts, consult a lawyer.. Specifically, the part granting the license

1.3 If you are a manufacturer of a device that includes a Genuine FTDI Component (each a "Device") then you may install the Software onto that device. If you are a seller or distributor of a Device then You may distribute the Software with the Device. If you are a user of a Device then you may install the Software on the Device, or onto a computer system in order to use the Device.

seems to make no provisions for software developers, which, taken together with the undertaking

3.1.7 not to provide, or otherwise make available, the Software in any form, in whole or in part (including, but not limited to, program listings, object and source program listings, object code and source code) to any person.

likely means that at least the drivers themselves cannot be included on crates.io and will have to be downloaded by any developer / user separately. One could try to argue that in some cases, like iCEBreaker designs, software components together with hardware form a new Device, so the developer is a device manufacturer / distributor for the purposes of this license, but this looks like something that only a court can decide for sure, so it may be reasonable to err on the side of caution.