# SPDX-License-Identifier: CC-BY-SA-4.0
# SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <bartekgola@gmail.com>

TODO list for libgpiod

==========

This document contains the list of things I'd like to have in libgpiod before
declaring it "mostly feature-complete". If anyone wants to help, this can
serve as the starting point.

==========

* implement dbus API for controlling GPIOs

A common complaint from users about gpioset is that the state of a line is not
retained once the program exits. While this is precisely the way linux
character devices work, it's understandable that most users will want some
centralized way of controlling GPIOs - similar to how sysfs worked.

One of the possible solutions is a DBus API. We need a daemon exposing chips
and lines as dbus objects and allowing to control and inspect lines using
dbus methods and monitor them using signals.

As of writing of this document some of the work has already been done and the
skeleton of the dbus daemon written in C using GLib has already been developed
and is partially functional.

----------

* implement rust bindings

With Rust gaining popularity as a low-level system's language and the
possibility of it making its way into the linux kernel, it's probably time to
provide Rust bindings to libgpiod as part of the project.

----------

* implement a simple daemon for controlling GPIOs in C together with a client
  program

This is by far the lowest priority task. Similarly as with the dbus daemon:
the goal is to provide a centralized agent controlling GPIOs with a simple
interface consisting of a command line client communicating with the server
over unix sockets.

In this case however the goal is to have as few dependencies as possible. This
is because for some small systems dbus is overkill. Since we won't be using any
standardized protocol, it will take much more effort to implement it correctly.

==========

API changes for v2.0

Once the v2 kernel uAPI is released, the plan for libgpiod is to start the
development cycle for a new major release with backward incompatible API in
order to support new features exposed by the GPIO character device as well as
rework certain badly designed interfaces. This would mean bumping the major
version number to 2 and breaking API and ABI.

At the same time I'd like to keep the changes much less invasive for a regular
user than the previous major API change from v0.x to v1.x. Most of the changes
would impact C++ and Python bindings, so it would be tempting to detach their
API versions and keep the core library stable but I'd prefer to keep a common
API version for all parts of the repository and also use this opportunity to
remove deprecated symbols from the main header.

Planned v2.x features will be listed below:
----------

Core library:

* rethink the gpiod_line_bulk structure

This structure is widely used by the library itself and always allocated on
the stack. It contains an array of 64 pointers the size of which is 256 & 512
bytes on 32- and 64-bit architectures respectively. This is a significant part
of the stack limit on linux, so it's worth rethinking it. Maybe a doubly linked
list of lines would be better (although slower to access).

* rework looking up lines by names

GPIO line names in the kernel aren't unique - neither globally nor within
a single chip. The current API doesn't take this into consideration and simply
returns the first matching line in gpiod_line_find() and co. This needs
addressing in future API.

Bindings:

* line objects should only hold weak references to their owning chip objects
  in C++ and python bindings

The way line objects in C++ and Python bindings are holding full references to
the associated chip objects is wrong and results from me not knowing any better
at the time I wrote it. This has the effect of forcing us to create a new
object whenever we "get" a line from a chip - we cannot store them within the
chip object as it would lead to circular dependencies. We should instead use
weak references (PyWeakref in python and std::weak_ptr in C++).

* re-write the python bindings to make them more 'pythonic'

There are several problems with the current python API. For instance: instead
of methods, properties should be used wherever possible (chip's name and label,
line's direction, active-state etc.), we should probably store the line objects
within the chip instead of creating them everytime get_line() is called and
several more.

* use ::std::chrono::time_point instead of ::std::chrono:duration in C++
  bindings

Duration is a time interval so it's not the best candidate for storing
timestamps. Switch to using time_point where applicable.