usbgadget

package
v0.0.0-...-703625d Latest Latest
Warning

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

 Go to latest Published: Sep 25, 2025 License: GPL-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package usbgadget provides a high-level interface to manage USB gadgets THIS PACKAGE IS FOR INTERNAL USE ONLY AND ITS API MAY CHANGE WITHOUT NOTICE

Index

Constants

View Source 
const (

	// https://www.usb.org/sites/default/files/documents/hid1_11.pdf
	// https://www.usb.org/sites/default/files/hut1_2.pdf
	KeyboardLedMaskNumLock    = 1 << 0
	KeyboardLedMaskCapsLock   = 1 << 1
	KeyboardLedMaskScrollLock = 1 << 2
	KeyboardLedMaskCompose    = 1 << 3
	KeyboardLedMaskKana       = 1 << 4
	// power on/off LED is 5
	KeyboardLedMaskShift  = 1 << 6
	ValidKeyboardLedMasks = KeyboardLedMaskNumLock | KeyboardLedMaskCapsLock | KeyboardLedMaskScrollLock | KeyboardLedMaskCompose | KeyboardLedMaskKana | KeyboardLedMaskShift
)
View Source 
const (
	// https://www.usb.org/sites/default/files/documents/hut1_2.pdf
	// Dynamic Flags (DV)
	LeftControl  = 0xE0
	LeftShift    = 0xE1
	LeftAlt      = 0xE2
	LeftSuper    = 0xE3 // Left GUI (e.g. Windows key, Apple Command key)
	RightControl = 0xE4
	RightShift   = 0xE5
	RightAlt     = 0xE6
	RightSuper   = 0xE7 // Right GUI (e.g. Windows key, Apple Command key)
)
View Source 
const (
	// https://www.usb.org/sites/default/files/documents/hid1_11.pdf Appendix C
	ModifierMaskLeftControl  = 0x01
	ModifierMaskRightControl = 0x10
	ModifierMaskLeftShift    = 0x02
	ModifierMaskRightShift   = 0x20
	ModifierMaskLeftAlt      = 0x04
	ModifierMaskRightAlt     = 0x40
	ModifierMaskLeftSuper    = 0x08
	ModifierMaskRightSuper   = 0x80
)
View Source 
const DefaultAutoReleaseDuration = 100 * time.Millisecond

DefaultAutoReleaseDuration is the default duration for auto-release of a key.

Variables

View Source 
var FileChangeResolvedActionString = map[FileChangeResolvedAction]string{
	FileChangeResolvedActionUnknown:                    "UNKNOWN",
	FileChangeResolvedActionDoNothing:                  "DO_NOTHING",
	FileChangeResolvedActionRemove:                     "REMOVE",
	FileChangeResolvedActionCreateFile:                 "FILE_CREATE",
	FileChangeResolvedActionWriteFile:                  "FILE_WRITE",
	FileChangeResolvedActionUpdateFile:                 "FILE_UPDATE",
	FileChangeResolvedActionAppendFile:                 "FILE_APPEND",
	FileChangeResolvedActionCreateSymlink:              "SYMLINK_CREATE",
	FileChangeResolvedActionRecreateSymlink:            "SYMLINK_RECREATE",
	FileChangeResolvedActionCreateDirectoryAndSymlinks: "DIR_CREATE_AND_SYMLINKS",
	FileChangeResolvedActionReorderSymlinks:            "SYMLINK_REORDER",
	FileChangeResolvedActionCreateDirectory:            "DIR_CREATE",
	FileChangeResolvedActionRemoveDirectory:            "DIR_REMOVE",
	FileChangeResolvedActionTouch:                      "TOUCH",
	FileChangeResolvedActionMountConfigFS:              "CONFIGFS_MOUNT",
}
View Source 
var FileStateString = map[FileState]string{
	FileStateUnknown:                "UNKNOWN",
	FileStateAbsent:                 "ABSENT",
	FileStateDirectory:              "DIRECTORY",
	FileStateFile:                   "FILE",
	FileStateFileContentMatch:       "FILE_CONTENT_MATCH",
	FileStateFileWrite:              "FILE_WRITE",
	FileStateMounted:                "MOUNTED",
	FileStateMountedConfigFS:        "CONFIGFS_MOUNTED",
	FileStateSymlink:                "SYMLINK",
	FileStateSymlinkInOrderConfigFS: "SYMLINK_IN_ORDER_CONFIGFS",
	FileStateTouch:                  "TOUCH",
}
View Source 
var KeyCodeToMaskMap = map[byte]byte{
	LeftControl:  ModifierMaskLeftControl,
	LeftShift:    ModifierMaskLeftShift,
	LeftAlt:      ModifierMaskLeftAlt,
	LeftSuper:    ModifierMaskLeftSuper,
	RightControl: ModifierMaskRightControl,
	RightShift:   ModifierMaskRightShift,
	RightAlt:     ModifierMaskRightAlt,
	RightSuper:   ModifierMaskRightSuper,
}

KeyCodeToMaskMap is a slice of KeyCodeMask for quick lookup

Functions

This section is empty.

Types

type ApplyFunc 

type ApplyFunc func(c *ChangeSet, changes []*FileChange) error

type ByteSlice 

type ByteSlice []byte

func (ByteSlice) MarshalJSON 

func (s ByteSlice) MarshalJSON() ([]byte, error)

func (*ByteSlice) UnmarshalJSON 

func (s *ByteSlice) UnmarshalJSON(data []byte) error

type ChangeSet 

type ChangeSet struct {
	Changes []FileChange
}

func (*ChangeSet) AddFileChange 

func (c *ChangeSet) AddFileChange(component string, path string, expectedState FileState, expectedContent []byte, dependsOn []string, description string)

func (*ChangeSet) AddFileChangeStruct 

func (c *ChangeSet) AddFileChangeStruct(r RequestedFileChange)

func (*ChangeSet) Apply 

func (c *ChangeSet) Apply() error

func (*ChangeSet) ApplyChanges 

func (c *ChangeSet) ApplyChanges() error

type ChangeSetResolver 

type ChangeSetResolver struct {
	// contains filtered or unexported fields
}

func (*ChangeSetResolver) Apply 

func (c *ChangeSetResolver) Apply() error

func (*ChangeSetResolver) GetChanges 

func (c *ChangeSetResolver) GetChanges() ([]*FileChange, error)

type ChangeState 

type ChangeState uint8
const (
	ChangeStateUnknown ChangeState = iota
	ChangeStateRequired
	ChangeStateNotChanged
	ChangeStateChanged
	ChangeStateError
)

type Config 

type Config struct {
	VendorId     string `json:"vendor_id"`
	ProductId    string `json:"product_id"`
	SerialNumber string `json:"serial_number"`
	Manufacturer string `json:"manufacturer"`
	Product      string `json:"product"`
	// contains filtered or unexported fields
}

Config is a struct that represents the customizations for a USB gadget. TODO: rename to something else that won't confuse with the USB gadget configuration

type Devices 

type Devices struct {
	AbsoluteMouse bool `json:"absolute_mouse"`
	RelativeMouse bool `json:"relative_mouse"`
	Keyboard      bool `json:"keyboard"`
	MassStorage   bool `json:"mass_storage"`
}

Devices is a struct that represents the USB devices that can be enabled on a USB gadget.

type FileChange 

type FileChange struct {
	RequestedFileChange
	ActualState   FileState
	ActualContent []byte
	// contains filtered or unexported fields
}

func (*FileChange) Action 

func (fc *FileChange) Action() FileChangeResolvedAction

func (*FileChange) ResetActionResolution 

func (fc *FileChange) ResetActionResolution()

type FileChangeResolvedAction 

type FileChangeResolvedAction uint8
const (
	FileChangeResolvedActionUnknown FileChangeResolvedAction = iota
	FileChangeResolvedActionDoNothing
	FileChangeResolvedActionRemove
	FileChangeResolvedActionCreateFile
	FileChangeResolvedActionWriteFile
	FileChangeResolvedActionUpdateFile
	FileChangeResolvedActionAppendFile
	FileChangeResolvedActionCreateSymlink
	FileChangeResolvedActionRecreateSymlink
	FileChangeResolvedActionCreateDirectoryAndSymlinks
	FileChangeResolvedActionReorderSymlinks
	FileChangeResolvedActionCreateDirectory
	FileChangeResolvedActionRemoveDirectory
	FileChangeResolvedActionTouch
	FileChangeResolvedActionMountConfigFS
)

type FileState 

type FileState uint8
const (
	FileStateUnknown FileState = iota
	FileStateAbsent
	FileStateDirectory
	FileStateFile
	FileStateFileContentMatch
	FileStateFileWrite // update file content without checking
	FileStateMounted
	FileStateMountedConfigFS
	FileStateSymlink
	FileStateSymlinkInOrderConfigFS // configfs is a shithole, so we need to check if the symlinks are created in the correct order
	FileStateSymlinkNotInOrderConfigFS
	FileStateTouch
)

type KeyboardState 

type KeyboardState struct {
	NumLock    bool `json:"num_lock"`
	CapsLock   bool `json:"caps_lock"`
	ScrollLock bool `json:"scroll_lock"`
	Compose    bool `json:"compose"`
	Kana       bool `json:"kana"`
	Shift      bool `json:"shift"` // This is not part of the main USB HID spec
	// contains filtered or unexported fields
}

Synchronization between LED states and CAPS LOCK, NUM LOCK, SCROLL LOCK, COMPOSE, and KANA events is maintained by the host and NOT the keyboard. If using the keyboard descriptor in Appendix B, LED states are set by sending a 5-bit absolute report to the keyboard via a Set_Report(Output) request.

func (*KeyboardState) Byte 

func (k *KeyboardState) Byte() byte

Byte returns the raw byte representation of the keyboard state.

type KeysDownState 

type KeysDownState struct {
	Modifier byte      `json:"modifier"`
	Keys     ByteSlice `json:"keys"`
}

type RequestedFileChange 

type RequestedFileChange struct {
	Component       string
	Key             string
	Path            string // will be used as Key if Key is empty
	ParamSymlinks   []symlink
	ExpectedState   FileState
	ExpectedContent []byte
	DependsOn       []string
	BeforeChange    []string // if the file is going to be changed, apply the change first
	Description     string
	IgnoreErrors    bool
	When            string // only apply the change if when meets the condition
}

func (*RequestedFileChange) IsSame 

func (f *RequestedFileChange) IsSame(other *RequestedFileChange) bool

func (*RequestedFileChange) String 

func (f *RequestedFileChange) String() string

type UsbGadget 

type UsbGadget struct {
	// contains filtered or unexported fields
}

UsbGadget is a struct that represents a USB gadget.

func NewUsbGadget 

func NewUsbGadget(name string, enabledDevices *Devices, config *Config, logger *zerolog.Logger) *UsbGadget

NewUsbGadget creates a new UsbGadget.

func (*UsbGadget) AbsMouseReport 

func (u *UsbGadget) AbsMouseReport(x int, y int, buttons uint8) error

func (*UsbGadget) AbsMouseWheelReport 

func (u *UsbGadget) AbsMouseWheelReport(wheelY int8) error

func (*UsbGadget) BindUDC 

func (u *UsbGadget) BindUDC() error

BindUDC binds the gadget to the UDC.

func (*UsbGadget) Close 

func (u *UsbGadget) Close() error

Close cleans up resources used by the USB gadget

func (*UsbGadget) DelayAutoReleaseWithDuration 

func (u *UsbGadget) DelayAutoReleaseWithDuration(resetDuration time.Duration)

func (*UsbGadget) GetConfigPath 

func (u *UsbGadget) GetConfigPath(itemKey string) (string, error)

GetConfigPath returns the path to the config item.

func (*UsbGadget) GetKeyboardState 

func (u *UsbGadget) GetKeyboardState() KeyboardState

func (*UsbGadget) GetKeysDownState 

func (u *UsbGadget) GetKeysDownState() KeysDownState

func (*UsbGadget) GetLastUserInputTime 

func (u *UsbGadget) GetLastUserInputTime() time.Time

func (*UsbGadget) GetPath 

func (u *UsbGadget) GetPath(itemKey string) (string, error)

GetPath returns the path to the item.

func (*UsbGadget) GetUsbState 

func (u *UsbGadget) GetUsbState() (state string)

GetUsbState returns the current state of the USB gadget

func (*UsbGadget) Init 

func (u *UsbGadget) Init() error

func (*UsbGadget) IsUDCBound 

func (u *UsbGadget) IsUDCBound() (bool, error)

IsUDCBound checks if the UDC state is bound.

func (*UsbGadget) KeyboardReport 

func (u *UsbGadget) KeyboardReport(modifier byte, keys []byte) error

func (*UsbGadget) KeypressReport 

func (u *UsbGadget) KeypressReport(key byte, press bool) error

func (*UsbGadget) OpenKeyboardHidFile 

func (u *UsbGadget) OpenKeyboardHidFile() error

func (*UsbGadget) OverrideGadgetConfig 

func (u *UsbGadget) OverrideGadgetConfig(itemKey string, itemAttr string, value string) (error, bool)

OverrideGadgetConfig overrides the gadget config for the given item and attribute. It returns an error if the item is not found or the attribute is not found. It returns true if the attribute is overridden, false otherwise.

func (*UsbGadget) RebindUsb 

func (u *UsbGadget) RebindUsb(ignoreUnbindError bool) error

RebindUsb rebinds the USB gadget to the UDC.

func (*UsbGadget) RelMouseReport 

func (u *UsbGadget) RelMouseReport(mx int8, my int8, buttons uint8) error

func (*UsbGadget) SetGadgetConfig 

func (u *UsbGadget) SetGadgetConfig(config *Config)

func (*UsbGadget) SetGadgetDevices 

func (u *UsbGadget) SetGadgetDevices(devices *Devices)

func (*UsbGadget) SetOnKeepAliveReset 

func (u *UsbGadget) SetOnKeepAliveReset(f func())

func (*UsbGadget) SetOnKeyboardStateChange 

func (u *UsbGadget) SetOnKeyboardStateChange(f func(state KeyboardState))

func (*UsbGadget) SetOnKeysDownChange 

func (u *UsbGadget) SetOnKeysDownChange(f func(state KeysDownState))

func (*UsbGadget) UnbindUDC 

func (u *UsbGadget) UnbindUDC() error

UnbindUDC unbinds the gadget from the UDC.

func (*UsbGadget) UpdateGadgetConfig 

func (u *UsbGadget) UpdateGadgetConfig() error

func (*UsbGadget) UpdateKeysDown 

func (u *UsbGadget) UpdateKeysDown(modifier byte, keys []byte) KeysDownState

func (*UsbGadget) WithTransaction 

func (u *UsbGadget) WithTransaction(fn func() error) error

type UsbGadgetTransaction 

type UsbGadgetTransaction struct {
	// contains filtered or unexported fields
}

func (*UsbGadgetTransaction) Commit 

func (tx *UsbGadgetTransaction) Commit() error

func (*UsbGadgetTransaction) CreateConfigPath 

func (tx *UsbGadgetTransaction) CreateConfigPath()

func (*UsbGadgetTransaction) DisableGadgetItemConfig 

func (tx *UsbGadgetTransaction) DisableGadgetItemConfig(item gadgetConfigItem)

func (*UsbGadgetTransaction) MountConfigFS 

func (tx *UsbGadgetTransaction) MountConfigFS()

func (*UsbGadgetTransaction) RebindUsb 

func (tx *UsbGadgetTransaction) RebindUsb(ignoreUnbindError bool)

func (*UsbGadgetTransaction) WriteGadgetConfig 

func (tx *UsbGadgetTransaction) WriteGadgetConfig()

func (*UsbGadgetTransaction) WriteUDC 

func (tx *UsbGadgetTransaction) WriteUDC()

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.