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#
func CopyFromUser(dst []byte, uaddr uintptr) errorfunc CopyToUser(uaddr uintptr, src []byte) errorfunc IO(typ byte, nr uint8) uint32func IOR(typ byte, nr uint8, size uintptr) uint32func IOW(typ byte, nr uint8, size uintptr) uint32func IOWR(typ byte, nr uint8, size uintptr) uint32func Register(d *Device) error- type Device
- type File
- type Flags
- type FlagsReader
- type FlagsWriter
- type Ioctler
- type OpenFunc
- type Opener
- type PollEvents
- type Poller
- type Reader
- type Releaser
- type Writer
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.