SPI transfer helpers: libfprint Reference Manual

## SPI transfer helpers SPI transfer helpers — Helpers to ease SPI transfers |

## Functions

void | (*FpiSpiTransferCallback) ()
FpiSpiTransfer * | fpi_spi_transfer_new ()
FpiSpiTransfer * | fpi_spi_transfer_ref ()
void | fpi_spi_transfer_unref ()
void | fpi_spi_transfer_write ()
void | fpi_spi_transfer_write_full ()
void | fpi_spi_transfer_read ()
void | fpi_spi_transfer_read_full ()
void | fpi_spi_transfer_submit ()
gboolean | fpi_spi_transfer_submit_sync ()

## Types and Values

| FpiSpiTransfer

## Description

FpiSpiTransfer is a structure to simplify the SPI transfer handling for the linux spidev device. The main goal are to ease memory management and provide a usable asynchronous API to libfprint drivers.

Currently only transfers with a write and subsequent read are supported.

Drivers should always use this API rather than calling read/write/ioctl on the spidev device.

Setting `G_MESSAGES_DEBUG` and `FP_DEBUG_TRANSFER` will result in the message content to be dumped.

## Functions

### FpiSpiTransferCallback ()

    void
    (*FpiSpiTransferCallback) (FpiSpiTransfer *transfer,
                               FpDevice *dev,
                               gpointer user_data,
                               GError *error);

### fpi_spi_transfer_new ()

    FpiSpiTransfer *
    fpi_spi_transfer_new (FpDevice *device,
                          int spidev_fd);

Creates a new FpiSpiTransfer.

#### Parameters

device | The FpDevice the transfer is for |
spidev_fd | The file descriptor for the spidev device |

#### Returns

A newly created FpiSpiTransfer.

[transfer full]

### fpi_spi_transfer_ref ()

    FpiSpiTransfer *
    fpi_spi_transfer_ref (FpiSpiTransfer *self);

Increments the reference count of `self` by one.

#### Parameters

self | A FpiSpiTransfer |

#### Returns

`self` .

[transfer full]

### fpi_spi_transfer_unref ()

    void
    fpi_spi_transfer_unref (FpiSpiTransfer *self);

Decrements the reference count of `self` by one, freeing the structure when the reference count reaches zero.

#### Parameters

self | A FpiSpiTransfer |

### fpi_spi_transfer_write ()

    void
    fpi_spi_transfer_write (FpiSpiTransfer *transfer,
                            gsize length);

Prepare the write part of an SPI transfer allocating a new buffer internally that will be free'ed automatically.

#### Parameters

transfer | The FpiSpiTransfer |
length | The buffer size to allocate |

### fpi_spi_transfer_write_full ()

    void
    fpi_spi_transfer_write_full (FpiSpiTransfer *transfer,
                                 guint8 *buffer,
                                 gsize length,
                                 GDestroyNotify free_func);

Prepare the write part of an SPI transfer.

#### Parameters

transfer | The FpiSpiTransfer |
buffer | The data to write. |
length | The size of `buffer` |
free_func | Destroy notify for `buffer` . | [destroy buffer]

### fpi_spi_transfer_read ()

    void
    fpi_spi_transfer_read (FpiSpiTransfer *transfer,
                           gsize length);

Prepare the read part of an SPI transfer allocating a new buffer internally that will be free'ed automatically.

#### Parameters

transfer | The FpiSpiTransfer |
length | The buffer size to allocate |

### fpi_spi_transfer_read_full ()

    void
    fpi_spi_transfer_read_full (FpiSpiTransfer *transfer,
                                guint8 *buffer,
                                gsize length,
                                GDestroyNotify free_func);

Prepare the read part of an SPI transfer.

#### Parameters

transfer | The FpiSpiTransfer |
buffer | Buffer to read data into. |
length | The size of `buffer` |
free_func | Destroy notify for `buffer` . | [destroy buffer]

### fpi_spi_transfer_submit ()

    void
    fpi_spi_transfer_submit (FpiSpiTransfer *transfer,
                             GCancellable *cancellable,
                             FpiSpiTransferCallback callback,
                             gpointer user_data);

Submit an SPI transfer with a specific timeout and callback functions.

The underlying transfer cannot be cancelled. The current implementation will only call `callback` after the transfer has been completed.

Note that FpiSpiTransfer will be stolen when this function is called. So that all associated data will be free'ed automatically, after the callback ran unless `fpi_usb_transfer_ref()` is explicitly called.

#### Parameters

transfer | The transfer to submit, must have been filled. | [transfer full]
cancellable | Cancellable to use, e.g. `fpi_device_get_cancellable()` |
callback | Callback on completion or error |
user_data | Data to pass to callback |

### fpi_spi_transfer_submit_sync ()

    gboolean
    fpi_spi_transfer_submit_sync (FpiSpiTransfer *transfer,
                                  GError **error);

Synchronously submit an SPI transfer. Use of this function is discouraged as it will block all other operations in the application.

Note that you still need to `fpi_spi_transfer_unref()` the FpiSpiTransfer afterwards.

#### Parameters

transfer | The transfer to submit, must have been filled. |
error | Location to store GError to |

#### Returns

TRUE on success, otherwise FALSE and `error` will be set

## Types and Values

### FpiSpiTransfer

    typedef struct {
      FpDevice *device;

      FpiSsm   *ssm;

      gssize    length_wr;
      gssize    length_rd;

      guchar   *buffer_wr;
      guchar   *buffer_rd;
    } FpiSpiTransfer;

Helper for handling SPI transfers. Currently transfers can either be pure write/read transfers or a write followed by a read (full duplex support can easily be added if desired).

#### Members

FpDevice *`device`; | The FpDevice that the transfer belongs to. |
FpiSsm *`ssm`; | Storage slot to associate the transfer with a state machine. Used by `fpi_ssm_spi_transfer_cb()` to modify the given state machine. |
gssize `length_wr`; | The length of the write buffer |
gssize `length_rd`; | The length of the read buffer |
guchar *`buffer_wr`; | The write buffer. |
guchar *`buffer_rd`; | The read buffer. |