TODO - pub/scm/libs/libgpiod/libgpiod - Git at Google

 # 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.
	# 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.