gpio: rename gpiod to gpiocdev (hybridgroup#1116)

Author: gen2thomas

drivers/MIGRATION.md MIGRATION.md

@@ -1,11 +1,52 @@
-# Migration of drivers
+# Migration guide
 
 From time to time a breaking change of API can happen. Following to [SemVer](https://semver.org/), the gobot main version
 should be increased. In such case all users needs to adjust there projects for the next update, although they not using
-a driver with changed API.
+a driver or platform with changed API.
 
-To prevent this scenario for most users, the main version will not always increased, but affected drivers are listed
-here and a migration strategy is provided.
+To prevent this scenario for most users, the main version will not always increased, but affected drivers and platforms
+are listed here and a migration strategy is provided.
+
+## Switch from version 2.4.0 (applications using the gpiod options affected)
+
+### The term gpiod was renamed to cdev
+
+Using the term "cdev" (short for character device Kernel ABI for GPIO access) is more suitable than using "gpiod" (the
+name of the user space driver in Linux). Also it relates better to the term "sysfs" (the legacy sysfs Kernel ABI for
+GPIO access). The former name was chosen so there would be no difference to the used go module "gpiod". Since also this
+module is now renamed to "go-gpiocdev", we choose the better name "cdev" from now on.
+
+This change affects all applications, which using the With... options of "gpiod" or "sysfs". A search and replace is
+suitable:
+
+```go
+// old
+...
+  a := NewAdaptor(adaptors.WithGpiodAccess())
+...
+
+// new
+...
+  a := NewAdaptor(adaptors.WithGpioCdevAccess())
+...
+```
+
+```go
+// old
+...
+  a := NewAdaptor(adaptors.WithSysfsAccess())
+...
+
+// new
+...
+  a := NewAdaptor(adaptors.WithGpioSysfsAccess())
+...
+```
+
+Also those findings needs to be replaced, which usually affects developers, but not users:
+
+* `system.WithDigitalPinGpiodAccess()` --> `system.WithDigitalPinCdevAccess()`
+* `IsGpiodDigitalPinAccess()` --> `IsCdevDigitalPinAccess()`
 
 ## Switch from version 2.3.0 (ble and sphero adaptors affected)
 

adaptor.go

@@ -29,7 +29,7 @@ type DigitalPinOptioner interface {
 		lseqno uint32), edge int) (changed bool)
 	// SetPollForEdgeDetection use a discrete input polling method to detect edges. A poll interval of zero or smaller
 	// will deactivate this function. Please note: Using this feature is CPU consuming and less accurate than using cdev
-	// event handler (gpiod implementation) and should be done only if the former is not implemented or not working for
+	// event handler (go-gpiocdev package) and should be done only if the former is not implemented or not working for
 	// the adaptor. E.g. sysfs driver in gobot has not implemented edge detection yet. The function is only useful
 	// together with SetEventHandlerForEdge() and its corresponding With*() functions.
 	SetPollForEdgeDetection(pollInterval time.Duration, pollQuitChan chan struct{}) (changed bool)

drivers/gpio/hcsr04_driver.go

@@ -36,7 +36,7 @@ type hcsr04Configuration struct {
 }
 
 // hcsr04UseEdgePollingOption is the type for applying to use discrete edge polling instead pin edge detection
-// by "cdev" from gpiod.
+// by "cdev" from the go-gpiocdev package.
 type hcsr04UseEdgePollingOption bool
 
 // HCSR04Driver is a driver for ultrasonic range measurement.
@@ -132,7 +132,7 @@ func NewHCSR04Driver(a gobot.Adaptor, triggerPinID, echoPinID string, opts ...in
 	return &d
 }
 
-// WithHCSR04UseEdgePolling use discrete edge polling instead pin edge detection by "cdev" from gpiod.
+// WithHCSR04UseEdgePolling use discrete edge polling instead pin edge detection by "cdev" from the go-gpiocdev package.
 func WithHCSR04UseEdgePolling() hcsr04OptionApplier {
 	return hcsr04UseEdgePollingOption(true)
 }

platforms/adaptors/digitalpinsadaptor.go

@@ -66,7 +66,7 @@ type DigitalPinsAdaptor struct {
 	mutex          sync.Mutex
 }
 
-// NewDigitalPinsAdaptor provides the access to digital pins of the board. It supports sysfs and gpiod system drivers.
+// NewDigitalPinsAdaptor provides the access to digital pins of the board. It supports sysfs and cdev system drivers.
 // This is decided by the given accesser. The translator is used to adapt the pin header naming, which is given by user,
 // to the internal file name or chip/line nomenclature. This varies by each platform. If for some reasons the default
 // initializer is not suitable, it can be given by the option "WithDigitalPinInitializer()". This is especially needed,
@@ -92,15 +92,15 @@ func WithDigitalPinInitializer(pc digitalPinInitializer) digitalPinsInitializeOp
 	return digitalPinsInitializeOption(pc)
 }
 
-// WithGpiodAccess can be used to change the default legacy sysfs implementation to the character device Kernel ABI,
-// provided by the gpiod package.
-func WithGpiodAccess() digitalPinsSystemSysfsOption {
+// WithGpioCdevAccess can be used to change the default legacy sysfs implementation to the character device Kernel ABI,
+// provided by the go-gpiocdev package.
+func WithGpioCdevAccess() digitalPinsSystemSysfsOption {
 	return digitalPinsSystemSysfsOption(false)
 }
 
-// WithSysfsAccess can be used to change the default character device implementation, provided by the gpiod package, to
-// the legacy sysfs Kernel ABI.
-func WithSysfsAccess() digitalPinsSystemSysfsOption {
+// WithGpioSysfsAccess can be used to change the default character device implementation, provided by the go-gpiocdev
+// package, to the legacy sysfs Kernel ABI.
+func WithGpioSysfsAccess() digitalPinsSystemSysfsOption {
 	return digitalPinsSystemSysfsOption(true)
 }
 
@@ -206,7 +206,7 @@ func (a *DigitalPinsAdaptor) Connect() error {
 		if *cfg.useSysfs {
 			system.WithDigitalPinSysfsAccess()(a.sys)
 		} else {
-			system.WithDigitalPinGpiodAccess()(a.sys)
+			system.WithDigitalPinCdevAccess()(a.sys)
 		}
 	}
 

platforms/adaptors/digitalpinsadaptor_test.go

@@ -63,7 +63,7 @@ func TestNewDigitalPinsAdaptor(t *testing.T) {
 	assert.NotNil(t, a.translate)
 	assert.Nil(t, a.pins)       // will be created on connect
 	assert.Nil(t, a.pinOptions) // will be created on connect
-	assert.True(t, a.sys.IsGpiodDigitalPinAccess())
+	assert.True(t, a.sys.IsCdevDigitalPinAccess())
 }
 
 func TestDigitalPinsConnect(t *testing.T) {

platforms/adaptors/digitalpinsadaptoroptions.go

@@ -80,7 +80,7 @@ func (o digitalPinsInitializeOption) String() string {
 }
 
 func (o digitalPinsSystemSysfsOption) String() string {
-	return "use gpiod system access option for digital pins"
+	return "use sysfs vs. cdev system access option for digital pins"
 }
 
 func (o digitalPinsForSystemSpiOption) String() string {

platforms/adaptors/digitalpinsadaptoroptions_test.go

@@ -53,16 +53,16 @@ func TestDigitalPinsWithSysfsAccess(t *testing.T) {
 	// arrange
 	a := NewDigitalPinsAdaptor(system.NewAccesser(), nil)
 	require.NoError(t, a.Connect())
-	require.True(t, a.sys.IsGpiodDigitalPinAccess())
+	require.True(t, a.sys.IsCdevDigitalPinAccess())
 	require.NoError(t, a.Finalize())
 	// act, connect is mandatory to set options to the system
-	WithSysfsAccess().apply(a.digitalPinsCfg)
+	WithGpioSysfsAccess().apply(a.digitalPinsCfg)
 	require.NoError(t, a.Connect())
 	// assert
 	assert.True(t, a.sys.IsSysfsDigitalPinAccess())
 }
 
-func TestDigitalPinsWithGpiodAccess(t *testing.T) {
+func TestDigitalPinsWithCdevAccess(t *testing.T) {
 	// arrange
 	a := NewDigitalPinsAdaptor(system.NewAccesser(system.WithDigitalPinSysfsAccess()), nil)
 	require.NoError(t, a.Connect())
@@ -71,10 +71,10 @@ func TestDigitalPinsWithGpiodAccess(t *testing.T) {
 	// we have to mock the fs at this point to ensure the option can be applied on each test environment
 	a.sys.UseMockFilesystem([]string{"/dev/gpiochip0"})
 	// act, connect is mandatory to set options to the system
-	WithGpiodAccess().apply(a.digitalPinsCfg)
+	WithGpioCdevAccess().apply(a.digitalPinsCfg)
 	require.NoError(t, a.Connect())
 	// assert
-	assert.True(t, a.sys.IsGpiodDigitalPinAccess())
+	assert.True(t, a.sys.IsCdevDigitalPinAccess())
 }
 
 func TestDigitalReadWithGpiosActiveLow(t *testing.T) {

platforms/beaglebone/beaglebone_adaptor.go

@@ -45,7 +45,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of sysfs
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of sysfs
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //
 //	Optional parameters for PWM, see [adaptors.NewPWMPinsAdaptor]

platforms/beaglebone/pocketbeagle_adaptor.go

@@ -16,7 +16,7 @@ type PocketBeagleAdaptor struct {
 // NewPocketBeagleAdaptor creates a new Adaptor for the PocketBeagle
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of sysfs
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of sysfs
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //
 //	Optional parameters for PWM, see [adaptors.NewPWMPinsAdaptor]

platforms/beaglebone/pocketbeagle_adaptor_test.go

@@ -26,10 +26,10 @@ func TestNewPocketBeagleAdaptor(t *testing.T) {
 
 func TestNewPocketBeagleAdaptorWithOption(t *testing.T) {
 	// arrange & act
-	a := NewPocketBeagleAdaptor(adaptors.WithGpiodAccess())
+	a := NewPocketBeagleAdaptor(adaptors.WithGpioCdevAccess())
 	// we have to mock the fs at this point to ensure the option can be applied on each test environment
 	a.sys.UseMockFilesystem([]string{"/dev/gpiochip0"})
 	// assert
 	require.NoError(t, a.Connect())
-	assert.True(t, a.sys.IsGpiodDigitalPinAccess())
+	assert.True(t, a.sys.IsCdevDigitalPinAccess())
 }

platforms/chip/chip_adaptor.go

@@ -40,7 +40,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of sysfs
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of sysfs
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //
 //	Optional parameters for PWM, see [adaptors.NewPWMPinsAdaptor]

platforms/dragonboard/dragonboard_adaptor.go

@@ -48,7 +48,7 @@ var fixedPins = map[string]int{
 //
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of sysfs
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of sysfs
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 func NewAdaptor(opts ...adaptors.DigitalPinsOptionApplier) *Adaptor {
 	sys := system.NewAccesser(system.WithDigitalPinSysfsAccess())

platforms/intel-iot/joule/joule_adaptor.go

@@ -32,7 +32,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of sysfs
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of sysfs
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //
 //	Optional parameters for PWM, see [adaptors.NewPWMPinsAdaptor]

platforms/jetson/jetson_adaptor.go

@@ -40,7 +40,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of sysfs
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of sysfs
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //
 //	Optional parameters for PWM, see [adaptors.NewPWMPinsAdaptor]

platforms/nanopi/nanopi_adaptor.go

@@ -37,7 +37,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithSysfsAccess():	use legacy sysfs driver instead of default character device gpiod
+//	adaptors.WithGpioSysfsAccess():	use legacy sysfs driver instead of default character device driver
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //	adaptors.WithGpiosActiveLow(pin's): invert the pin behavior
 //	adaptors.WithGpiosPullUp/Down(pin's): sets the internal pull resistor

platforms/nanopi/nanopi_adaptor_test.go

@@ -85,15 +85,15 @@ func TestNewAdaptor(t *testing.T) {
 	assert.NotNil(t, a.PWMPinsAdaptor)
 	assert.NotNil(t, a.I2cBusAdaptor)
 	assert.NotNil(t, a.SpiBusAdaptor)
-	assert.True(t, a.sys.IsGpiodDigitalPinAccess())
+	assert.True(t, a.sys.IsCdevDigitalPinAccess())
 	// act & assert
 	a.SetName("NewName")
 	assert.Equal(t, "NewName", a.Name())
 }
 
 func TestNewAdaptorWithOption(t *testing.T) {
 	// arrange & act
-	a := NewNeoAdaptor(adaptors.WithGpiosActiveLow("1"), adaptors.WithSysfsAccess())
+	a := NewNeoAdaptor(adaptors.WithGpiosActiveLow("1"), adaptors.WithGpioSysfsAccess())
 	// assert
 	require.NoError(t, a.Connect())
 	assert.True(t, a.sys.IsSysfsDigitalPinAccess())
@@ -104,7 +104,7 @@ func TestDigitalIO(t *testing.T) {
 	// arrange
 	a := initConnectedTestAdaptor()
 	dpa := a.sys.UseMockDigitalPinAccess()
-	require.True(t, a.sys.IsGpiodDigitalPinAccess())
+	require.True(t, a.sys.IsCdevDigitalPinAccess())
 	// act & assert write
 	err := a.DigitalWrite("7", 1)
 	require.NoError(t, err)
@@ -125,7 +125,7 @@ func TestDigitalIO(t *testing.T) {
 func TestDigitalIOSysfs(t *testing.T) {
 	// some basic tests, further tests are done in "digitalpinsadaptor.go"
 	// arrange
-	a := NewNeoAdaptor(adaptors.WithSysfsAccess())
+	a := NewNeoAdaptor(adaptors.WithGpioSysfsAccess())
 	require.NoError(t, a.Connect())
 	dpa := a.sys.UseMockDigitalPinAccess()
 	require.True(t, a.sys.IsSysfsDigitalPinAccess())
@@ -274,7 +274,7 @@ func TestFinalizeErrorAfterGPIO(t *testing.T) {
 	// arrange
 	a := initConnectedTestAdaptor()
 	dpa := a.sys.UseMockDigitalPinAccess()
-	require.True(t, a.sys.IsGpiodDigitalPinAccess())
+	require.True(t, a.sys.IsCdevDigitalPinAccess())
 	require.NoError(t, a.DigitalWrite("7", 1))
 	dpa.UseUnexportError("gpiochip0", "203")
 	// act

platforms/raspi/raspi_adaptor.go

@@ -40,7 +40,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithSysfsAccess():	use legacy sysfs driver instead of default character device gpiod
+//	adaptors.WithGpioSysfsAccess():	use legacy sysfs driver instead of default character device driver
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //	adaptors.WithGpiosActiveLow(pin's): invert the pin behavior
 //	adaptors.WithGpiosPullUp/Down(pin's): sets the internal pull resistor

platforms/raspi/raspi_adaptor_test.go

@@ -84,15 +84,15 @@ func TestNewAdaptor(t *testing.T) {
 	assert.NotNil(t, a.PWMPinsAdaptor)
 	assert.NotNil(t, a.I2cBusAdaptor)
 	assert.NotNil(t, a.SpiBusAdaptor)
-	assert.True(t, a.sys.IsGpiodDigitalPinAccess())
+	assert.True(t, a.sys.IsCdevDigitalPinAccess())
 	// act & assert
 	a.SetName("NewName")
 	assert.Equal(t, "NewName", a.Name())
 }
 
 func TestNewAdaptorWithOption(t *testing.T) {
 	// arrange & act
-	a := NewAdaptor(adaptors.WithGpiosActiveLow("1"), adaptors.WithSysfsAccess())
+	a := NewAdaptor(adaptors.WithGpiosActiveLow("1"), adaptors.WithGpioSysfsAccess())
 	// assert
 	require.NoError(t, a.Connect())
 	assert.True(t, a.sys.IsSysfsDigitalPinAccess())
@@ -283,7 +283,7 @@ func TestDigitalIO(t *testing.T) {
 		panic(err)
 	}
 	dpa := a.sys.UseMockDigitalPinAccess()
-	require.True(t, a.sys.IsGpiodDigitalPinAccess())
+	require.True(t, a.sys.IsCdevDigitalPinAccess())
 	// act & assert write
 	_ = a.DigitalWrite("7", 1)
 	assert.Equal(t, []int{1}, dpa.Written("gpiochip0", "4"))

platforms/rockpi/rockpi_adaptor.go

@@ -40,7 +40,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithGpiodAccess():	use character device gpiod driver instead of the default sysfs (NOT work on RockPi4C+!)
+//	adaptors.WithGpioCdevAccess():	use character device driver instead of the default sysfs (NOT work on RockPi4C+!)
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //	adaptors.WithGpiosActiveLow(pin's): invert the pin behavior
 func NewAdaptor(opts ...adaptors.DigitalPinsOptionApplier) *Adaptor {

platforms/tinkerboard/adaptor.go

@@ -38,7 +38,7 @@ type Adaptor struct {
 //
 // Optional parameters:
 //
-//	adaptors.WithSysfsAccess():	use legacy sysfs driver instead of default character device gpiod
+//	adaptors.WithGpioSysfsAccess():	use legacy sysfs driver instead of default character device driver
 //	adaptors.WithSpiGpioAccess(sclk, ncs, sdo, sdi):	use GPIO's instead of /dev/spidev#.#
 //	adaptors.WithGpiosActiveLow(pin's): invert the pin behavior
 //	adaptors.WithGpiosPullUp/Down(pin's): sets the internal pull resistor

platforms/tinkerboard/adaptor_test.go

@@ -87,15 +87,15 @@ func TestNewAdaptor(t *testing.T) {
 	assert.NotNil(t, a.I2cBusAdaptor)
 	assert.NotNil(t, a.SpiBusAdaptor)
 	assert.NotNil(t, a.OneWireBusAdaptor)
-	assert.True(t, a.sys.IsGpiodDigitalPinAccess())
+	assert.True(t, a.sys.IsCdevDigitalPinAccess())
 	// act & assert
 	a.SetName("NewName")
 	assert.Equal(t, "NewName", a.Name())
 }
 
 func TestNewAdaptorWithOption(t *testing.T) {
 	// arrange & act
-	a := NewAdaptor(adaptors.WithGpiosActiveLow("1"), adaptors.WithSysfsAccess())
+	a := NewAdaptor(adaptors.WithGpiosActiveLow("1"), adaptors.WithGpioSysfsAccess())
 	// assert
 	require.NoError(t, a.Connect())
 	assert.True(t, a.sys.IsSysfsDigitalPinAccess())
@@ -106,7 +106,7 @@ func TestDigitalIO(t *testing.T) {
 	// arrange
 	a := initConnectedTestAdaptor()
 	dpa := a.sys.UseMockDigitalPinAccess()
-	require.True(t, a.sys.IsGpiodDigitalPinAccess())
+	require.True(t, a.sys.IsCdevDigitalPinAccess())
 	// act & assert write
 	err := a.DigitalWrite("7", 1)
 	require.NoError(t, err)
@@ -127,7 +127,7 @@ func TestDigitalIO(t *testing.T) {
 func TestDigitalIOSysfs(t *testing.T) {
 	// some basic tests, further tests are done in "digitalpinsadaptor.go"
 	// arrange
-	a := NewAdaptor(adaptors.WithSysfsAccess())
+	a := NewAdaptor(adaptors.WithGpioSysfsAccess())
 	require.NoError(t, a.Connect())
 	dpa := a.sys.UseMockDigitalPinAccess()
 	require.True(t, a.sys.IsSysfsDigitalPinAccess())
@@ -262,7 +262,7 @@ func TestFinalizeErrorAfterGPIO(t *testing.T) {
 	// arrange
 	a := initConnectedTestAdaptor()
 	dpa := a.sys.UseMockDigitalPinAccess()
-	require.True(t, a.sys.IsGpiodDigitalPinAccess())
+	require.True(t, a.sys.IsCdevDigitalPinAccess())
 	require.NoError(t, a.DigitalWrite("7", 1))
 	dpa.UseUnexportError("gpiochip0", "17")
 	// act