uapi

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2019 License: MIT Imports: 3 Imported by: 0

README

uapi

GoDoc

GPIOD UAPI is a thin layer over the system ioctl calls that comprise the Linux GPIO UAPI.

This library is used by gpiod to interact with the Linux kernel.

The library is exposed to allow for testing of the UAPI with the minimal amount of Go in the way.

gpiod provides a higher level of abstraction, so for general use you probably want to be using that.

API

The GPIO UAPI comprises six ioctls:

IOCTL Scope Description
GetChipInfo chip Returns information about the chip itself.
GetLineInfo chip Returns information about a particular line on the chip.
GetLineHandle chip Requests a set of lines, and returns a file handle for ioctl commands. The set may be any subset of the lines supported by the chip, including a single line. This may be used for both input and output lines. The lines remain reserved by the caller until the returned fd is closed.
GetLineEvent chip Requests an individual input line with edge detection enabled, and returns a file handle for ioctl commands and to return edge events. Events can only be requested on input lines. The line remains reserved by the caller until the returned fd is closed.
GetLineValues line Returns the current value of a set of lines.
SetLineValues line Sets the current value of a set of lines.

Usage

The following is a brief example of the usage of each of the major functions:

    f, _ := os.OpenFile("/dev/gpiochip0", unix.O_CLOEXEC, unix.O_RDONLY)

    // get chip info
    ci, _ := uapi.GetChipInfo(f.Fd())

    // get line info
    li, _ := uapi.GetLineInfo(f.Fd(), offset)

    // request a line
    hr := uapi.HandleRequest{
        Lines: uint32(len(offsets)),
        Flags: handleFlags,
        // initialise Offsets, DefaultValues and Consumer...
    }
    err := uapi.GetLineHandle(f.Fd(), &hr)

    // request a line with events
    er := uapi.EventRequest{
        Offset:      offset,
        HandleFlags: handleFlags,
        EventFlags:  eventFlags,
        // initialise Consumer...
    }
    err := uapi.GetLineEvent(f.Fd(), &er)
    if err != nil {
        // wait on er.fd for events...

        // read event
        evt, _ := uapi.ReadEvent(er.fd)
    }

    // get values
    var values uapi.HandleData
    _ := uapi.GetLineValues(er.fd, &values)

    // set values
    values[0] = uint8(value)
    _ := uapi.SetLineValues(hr.fd, values)

Error handling and other tedious bits, such as initialising the arrays in the requests, omitted for brevity.

Refer to gpiod for a concrete example of uapi usage.

Documentation

Overview

Package uapi provides the Linux GPIO UAPI definitions for gpiod.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BytesToString 

func BytesToString(a []byte) string

BytesToString is a helper function that converts strings stored in byte arrays, as returned by GetChipInfo and GetLineInfo, into strings.

func GetLineEvent 

func GetLineEvent(fd uintptr, request *EventRequest) error

GetLineEvent requests a line from the GPIO character device with event reporting enabled.

The fd is an open GPIO character device. The line must be an input and must not already be requested. If successful, the fd for the line is returned in the request.fd.

func GetLineHandle 

func GetLineHandle(fd uintptr, request *HandleRequest) error

GetLineHandle requests a line from the GPIO character device.

This request is without event reporting. The fd is an open GPIO character device. The lines must not already be requested. The flags in the request will be applied to all lines in the request. If successful, the fd for the line is returned in the request.fd.

func GetLineValues 

func GetLineValues(fd uintptr, values *HandleData) error

GetLineValues returns the values of a set of requested lines.

The fd is a requested line, as returned by GetLineHandle or GetLineEvent.

func SetLineConfig added in v0.3.0 

func SetLineConfig(fd uintptr, config *HandleConfig) error

SetLineConfig sets the config of an existing handle request.

The config flags in the request will be applied to all lines in the handle request.

func SetLineValues 

func SetLineValues(fd uintptr, values HandleData) error

SetLineValues sets the values of a set of requested lines.

The fd is a requested line, as returned by GetLineHandle or GetLineEvent.

Types

type ChipInfo 

type ChipInfo struct {
	// The system name of the device.
	Name [nameSize]byte

	// An identifying label added by the device driver.
	Label [nameSize]byte

	// The number of lines supported by this chip.
	Lines uint32
}

ChipInfo contains the details of a GPIO chip.

func GetChipInfo 

func GetChipInfo(fd uintptr) (ChipInfo, error)

GetChipInfo returns the ChipInfo for the GPIO character device.

The fd is an open GPIO character device.

type EventData 

type EventData struct {
	// The time the event was detected.
	Timestamp uint64

	// The type of event detected.
	ID uint32
	// contains filtered or unexported fields
}

EventData contains the details of a particular line event.

func ReadEvent 

func ReadEvent(fd uintptr) (EventData, error)

ReadEvent reads a single event from a requested line.

The fd is a requested line, as returned by GetLineEvent.

This function is blocking and should only be called when the fd is known to be ready to read.

type EventFlag 

type EventFlag uint32

EventFlag indicates the types of events that will be reported. 

const (
	// EventRequestRisingEdge requests rising edge events.
	// This means a transition from a low logical state to a high logical state.
	// For active high lines (the default) this means a transition from a
	// physical low to a physical high.
	// Note that for active low lines this means a transition from a physical
	// high to a physical low.
	EventRequestRisingEdge EventFlag = 1 << iota

	// EventRequestFallingEdge requests falling edge events.
	// This means a transition from a high logical state to a low logical state.
	// For active high lines (the default) this means a transition from a
	// physical high to a physical low.
	// Note that for active low lines this means a transition from a physical
	// low to a physical high.
	EventRequestFallingEdge

	// EventRequestBothEdges requests both rising and falling edge events.
	// This is equivalent to requesting both EventRequestRisingEdge and
	// EventRequestRisingEdge.
	EventRequestBothEdges = EventRequestRisingEdge | EventRequestFallingEdge
)

func (EventFlag) IsBothEdges 

func (f EventFlag) IsBothEdges() bool

IsBothEdges returns true if both rising and falling edge events have been requested.

func (EventFlag) IsFallingEdge 

func (f EventFlag) IsFallingEdge() bool

IsFallingEdge returns true if falling edge events have been requested.

func (EventFlag) IsRisingEdge 

func (f EventFlag) IsRisingEdge() bool

IsRisingEdge returns true if rising edge events have been requested.

type EventRequest 

type EventRequest struct {
	// The line to be requested.
	Offset uint32

	// The line flags applied to this line.
	HandleFlags HandleFlag

	// The type of events to report.
	EventFlags EventFlag

	// The string identifying the requester to be applied to the line.
	Consumer [nameSize]byte

	// The file handle for the requested line.
	// Set if the request is successful.
	Fd int32
}

EventRequest is a request for control of a line with event reporting enabled.

type HandleConfig added in v0.3.0 

type HandleConfig struct {
	// The flags to be applied to the lines.
	Flags HandleFlag

	// The default values to be applied to output lines (when
	// HandleRequestOutput is set in the Flags).
	DefaultValues [HandlesMax]uint8
	// contains filtered or unexported fields
}

HandleConfig is a request to change the config of an existing request.

Can be applied to both handle and event requests. Event requests cannot be reconfigured to outputs.

type HandleData 

type HandleData [HandlesMax]uint8

HandleData contains the logical value for each line. Zero is a logical low and any other value is a logical high.

type HandleFlag 

type HandleFlag uint32

HandleFlag contains the 

const (
	// HandleRequestInput requests the line as an input.
	//
	// This is ignored if Output is also set.
	HandleRequestInput HandleFlag = 1 << iota

	// HandleRequestOutput requests the line as an output.
	//
	// This takes precedence over Input, if both are set.
	HandleRequestOutput

	// HandleRequestActiveLow requests the line be made active low.
	HandleRequestActiveLow

	// HandleRequestOpenDrain requests the line be made open drain.
	//
	// This option requires the line to be requested as an Output.
	// This cannot be set at the same time as OpenSource.
	HandleRequestOpenDrain

	// HandleRequestOpenSource requests the line be made open source.
	//
	// This option requires the line to be requested as an Output.
	// This cannot be set at the same time as OpenDrain.
	HandleRequestOpenSource

	// HandleRequestPullUp requests the line have pull-up enabled.
	HandleRequestPullUp

	// HandleRequestPullDown requests the line have pull-down enabled.
	HandleRequestPullDown

	// HandleRequestBiasDisable requests the line have bias disabled.
	HandleRequestBiasDisable

	// HandlesMax is the maximum number of lines that can be requested in a
	// single request.
	HandlesMax = 64
)

func (HandleFlag) IsActiveLow 

func (f HandleFlag) IsActiveLow() bool

IsActiveLow returns true if the line is requested as a active low.

func (HandleFlag) IsBiasDisable added in v0.3.0 

func (f HandleFlag) IsBiasDisable() bool

IsBiasDisable returns true if the line is requested with bias disabled.

func (HandleFlag) IsInput 

func (f HandleFlag) IsInput() bool

IsInput returns true if the line is requested as an input.

func (HandleFlag) IsOpenDrain 

func (f HandleFlag) IsOpenDrain() bool

IsOpenDrain returns true if the line is requested as an open drain.

func (HandleFlag) IsOpenSource 

func (f HandleFlag) IsOpenSource() bool

IsOpenSource returns true if the line is requested as an open source.

func (HandleFlag) IsOutput 

func (f HandleFlag) IsOutput() bool

IsOutput returns true if the line is requested as an output.

func (HandleFlag) IsPullDown added in v0.3.0 

func (f HandleFlag) IsPullDown() bool

IsPullDown returns true if the line is requested with pull-down enabled.

func (HandleFlag) IsPullUp added in v0.3.0 

func (f HandleFlag) IsPullUp() bool

IsPullUp returns true if the line is requested with pull-up enabled.

type HandleRequest 

type HandleRequest struct {
	// The lines to be requested.
	Offsets [HandlesMax]uint32

	// The flags to be applied to the lines.
	Flags HandleFlag

	// The default values to be applied to output lines.
	DefaultValues [HandlesMax]uint8

	// The string identifying the requester to be applied to the lines.
	Consumer [nameSize]byte

	// The number of lines being requested.
	Lines uint32

	// The file handle for the requested lines.
	// Set if the request is successful.
	Fd int32
}

HandleRequest is a request for control of a set of lines. The lines must all be on the same GPIO chip.

type LineFlag 

type LineFlag uint32

LineFlag are the flags for a line. 

const (
	// LineFlagRequested indicates that the line has been requested.
	// It may have been requested by this process or another process.
	// The line cannot be requested again until this flag is clear.
	LineFlagRequested LineFlag = 1 << iota

	// LineFlagIsOut indicates that the line is an output.
	LineFlagIsOut

	// LineFlagActiveLow indicates that the line is active low.
	LineFlagActiveLow

	// LineFlagOpenDrain indicates that the line will pull low when set low but
	// float when set high. This flag only applies to output lines.
	// An output cannot be both open drain and open source.
	LineFlagOpenDrain

	// LineFlagOpenSource indicates that the line will pull high when set high
	// but float when set low. This flag only applies to output lines.
	// An output cannot be both open drain and open source.
	LineFlagOpenSource

	// LineFlagPullUp indicates that the internal line pull up is enabled.
	LineFlagPullUp

	// LineFlagPullDown indicates that the internal line pull down is enabled.
	LineFlagPullDown

	// LineFlagBiasDisable indicates that the internal line bias is disabled.
	LineFlagBiasDisable
)

func (LineFlag) IsActiveLow 

func (f LineFlag) IsActiveLow() bool

IsActiveLow returns true if the line is active low.

func (LineFlag) IsBiasDisable added in v0.3.0 

func (f LineFlag) IsBiasDisable() bool

IsBiasDisable returns true if the line has bias disabled.

func (LineFlag) IsOpenDrain 

func (f LineFlag) IsOpenDrain() bool

IsOpenDrain returns true if the line is open-drain.

func (LineFlag) IsOpenSource 

func (f LineFlag) IsOpenSource() bool

IsOpenSource returns true if the line is open-source.

func (LineFlag) IsOut 

func (f LineFlag) IsOut() bool

IsOut returns true if the line is an output.

func (LineFlag) IsPullDown added in v0.3.0 

func (f LineFlag) IsPullDown() bool

IsPullDown returns true if the line has pull-down enabled.

func (LineFlag) IsPullUp added in v0.3.0 

func (f LineFlag) IsPullUp() bool

IsPullUp returns true if the line has pull-up enabled.

func (LineFlag) IsRequested 

func (f LineFlag) IsRequested() bool

IsRequested returns true if the line is requested.

type LineInfo 

type LineInfo struct {
	// The offset of the line within the chip.
	Offset uint32

	// The line flags applied to this line.
	Flags LineFlag

	// The system name for this line.
	Name [nameSize]byte

	// If requested, a string added by the requester to identify the
	// owner of the request.
	Consumer [nameSize]byte
}

LineInfo contains the details of a single line of a GPIO chip.

func GetLineInfo 

func GetLineInfo(fd uintptr, offset int) (LineInfo, error)

GetLineInfo returns the LineInfo for one line from the GPIO character device.

The fd is an open GPIO character device. The offset is zero based.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.