gokm/chardev

import "gokm/chardev"

Package chardev creates character devices (/dev/<name>) backed by Go code. They’re “misc” devices: the kernel picks the minor number and devtmpfs creates the /dev node.

type dev struct{}
func (dev) Open() (chardev.File, error) { return &session{}, nil }

type session struct{ ... }  // implements chardev.Reader / Writer / Releaser

err := chardev.Register(&chardev.Device{Name: "mydev", Mode: 0o666, Opener: dev{}})

Each open() gets its own File. Read and Write receive kernel buffers (at most 64 KiB per call) and the file offset; the returned count advances it. Devices are deregistered automatically at module exit.

Waiting for data (a device that produces data over time):

func (s *session) ReadFlags(p []byte, off int64, fl chardev.Flags) (int, error) {
	err := dev.Wait(fl, func() bool { return len(queue) > 0 }) // EAGAIN, EINTR
	...
}
func (s *session) Poll() chardev.PollEvents { ... chardev.PollIn ... }

// producer, e.g. a goroutine:
queue = append(queue, data); dev.Wake()

Poll makes the device work with poll, select and epoll; Wake tells pollers and Wait-ers to look again.

Index#

Functions#

func CopyFromUser#

func CopyFromUser(dst []byte, uaddr uintptr) error

CopyFromUser copies len(dst) bytes from the user-space address uaddr (e.g. an ioctl argument). It returns EFAULT if the memory isn’t readable. Process context only (it may fault pages in).

func CopyToUser#

func CopyToUser(uaddr uintptr, src []byte) error

CopyToUser copies src to the user-space address uaddr.

func IO#

func IO(typ byte, nr uint8) uint32

Linux ioctl command encoding (_IO, _IOR, _IOW, _IOWR from <asm-generic/ioctl.h>): typ is the “magic” byte, nr the command number, size the size of the argument struct.

func IOR#

func IOR(typ byte, nr uint8, size uintptr) uint32

IOR is a command that reads from the device into a user buffer.

func IOW#

func IOW(typ byte, nr uint8, size uintptr) uint32

IOW is a command that writes a user buffer to the device.

func IOWR#

func IOWR(typ byte, nr uint8, size uintptr) uint32

IOWR is a command that does both.

func Register#

func Register(d *Device) error

Register creates /dev/<Name>.

Types#

type Device#

type Device struct {
	Name   string
	Mode   uint32 // /dev node permissions; 0 means 0600
	Opener Opener

}

Device is a character device.

func (*Device) Deregister#

func (d *Device) Deregister()

Deregister removes the device. Files still open keep working until closed (they also keep the module loaded).

func (*Device) Wait#

func (d *Device) Wait(fl Flags, ready func() bool) error

Wait blocks until ready() returns true, re-checking it after each Wake. With fl.Nonblock() it returns EAGAIN instead of blocking. A signal interrupts it with EINTR, and a deregistered device returns ENODEV. Call it from file operations (Read, Write, Ioctl), with no locks held that Wake’s caller needs; ready runs without any lock of its own.

func (*Device) Wake#

func (d *Device) Wake()

Wake makes pollers re-check Poll and wakes Wait calls. It can be called from any context, atomic ones included.

type File#

type File any

File is one open instance of a device; it implements any of the interfaces below. Operations it doesn’t implement fail with EINVAL.

type Flags#

type Flags uint32

Flags are the open file’s flags (O_* values of the file’s f_flags).

func (Flags) Nonblock#

func (f Flags) Nonblock() bool

Nonblock reports O_NONBLOCK: don’t wait, fail with EAGAIN instead.

type FlagsReader#

type FlagsReader interface {
	ReadFlags(p []byte, off int64, fl Flags) (int, error)
}

FlagsReader and FlagsWriter are Reader and Writer that also get the file’s flags (e.g. O_NONBLOCK); used instead of Read/Write when implemented.

type FlagsWriter#

type FlagsWriter interface {
	WriteFlags(p []byte, off int64, fl Flags) (int, error)
}

type Ioctler#

type Ioctler interface {
	Ioctl(cmd uint32, arg uintptr) (int, error)
}

Ioctler handles ioctl(2). arg is the raw argument: when it’s a user pointer, read/write through it with CopyFromUser/CopyToUser. The int result is what ioctl returns (non-negative).

type OpenFunc#

type OpenFunc func() (File, error)

OpenFunc adapts a function to an Opener.

func (OpenFunc) Open#

func (f OpenFunc) Open() (File, error)

type Opener#

type Opener interface {
	Open() (File, error)
}

Opener creates the per-open state of a device.

type PollEvents#

type PollEvents uint32

PollEvents are poll(2) events.

const (
	PollIn  PollEvents = 0x1  // readable
	PollPri PollEvents = 0x2  // urgent data
	PollOut PollEvents = 0x4  // writable
	PollErr PollEvents = 0x8  // error
	PollHup PollEvents = 0x10 // hang up (e.g. end of stream)
)

type Poller#

type Poller interface {
	Poll() PollEvents
}

Poller reports which operations would not block, for poll, select and epoll. Call Device.Wake when that may have changed. Files without Poll are always readable and writable.

type Reader#

type Reader interface {
	Read(p []byte, off int64) (int, error)
}

Reader reads into p from offset off. Return 0 (nil or io.EOF) at end.

type Releaser#

type Releaser interface {
	Release()
}

Releaser is called when the last reference to the open file closes.

type Writer#

type Writer interface {
	Write(p []byte, off int64) (int, error)
}

Writer writes p at offset off.