1/*
2 * Copyright 2019, Data61
3 * Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 * ABN 41 687 119 230.
5 *
6 * This software may be distributed and modified according to the terms of
7 * the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 * See "LICENSE_BSD2.txt" for details.
9 *
10 * @TAG(DATA61_BSD)
11 */
12
13#pragma once
14
15#include <platsupport/io.h>
16#include <platsupport/gpio.h>
17
18typedef struct gpio_chain gpio_chain_t;
19
20/**
21 * Initialise a GPIO chain structure.
22 *
23 * @param malloc_ops    Initialised malloc_ops structure.
24 * @param ret_chain     Pointer to a (gpio_chain_t *) that will be filled in.
25 * @return              0 on success, otherwise an error code
26 */
27int gpio_chain_init(ps_malloc_ops_t *malloc_ops, gpio_chain_t **ret_chain);
28
29/**
30 * Destroy a initialised GPIO chain.
31 *
32 * @param malloc_ops    Initialised malloc_ops structure.
33 * @param chain         Initialised GPIO chain that will be destroyed.
34 * @return              0 on success, otherwise an error code
35 */
36int gpio_chain_destroy(ps_malloc_ops_t *malloc_ops, gpio_chain_t *chain);
37
38/**
39 * Add a GPIO pin to a GPIO chain. Note that the lifetime of the gpio_t
40 * pointer passed in must be the same as the lifetime of the gpio chain that
41 * holds the pointer.
42 *
43 * @param chain     Initialised GPIO chain to have a GPIO pin added to it.
44 * @param gpio      Initialised gpio_t structure which represents a chain.
45 * @return          0 on success, otherwise an error code
46 */
47int gpio_chain_add(gpio_chain_t *chain, gpio_t *gpio);
48
49/**
50 * Remove a GPIO pin from a GPIO chain.
51 *
52 * @param chain     Initialised GPIO chain to have a GPIO removed from it.
53 * @param gpio      The target GPIO pin to remove from the chain.
54 * @return          0 on success, otherwise an error code
55 */
56int gpio_chain_remove(gpio_chain_t *chain, gpio_t *gpio);
57
58/**
59 * Read from a daisy chain of GPIO pins.
60 *
61 * All pins in the chain must be configured for input.  The buffer supplied for
62 * output will only be touched as far as "len" bits.
63 *
64 * @param chain     An initialised GPIO chain.
65 * @param data      A buffer in which the driver should place the data it reads.
66 * @param len       The number of chained GPIO pins to read from.
67 * @return          The number of bits of data read. Or an error code
68 *                  on error.
69 */
70int gpio_chain_read(gpio_chain_t *chain, char *data, int len);
71
72/**
73 * Write to a daisy chain of GPIO pins.
74 *
75 * All pins in the chian must be configured for output. The "len" argument will
76 * determine how many chained pins the driver will attempt to write to.
77 *
78 * @param chain     An initialized GPIO chain.
79 * @param data      A buffer from which the driver will draw the data to be
80 *                  written out.
81 * @param len       The number of bits to write out from the buffer to chained
82 *                  GPIO pins.
83 * @return          The number of bits of data written out. Or an error code
84 */
85int gpio_chain_write(gpio_chain_t *chain, char *data, int len);
86