Struct DeviceRegistry 

pub struct DeviceRegistry {
    pub objects: KObjectStore,
    /* private fields */
}

The registry for devices.

Devices are specified in file systems with major and minor device numbers, together referred to as a DeviceType. When userspace opens one of those files, we look up the DeviceType in the device registry to instantiate a file for that device.

The DeviceRegistry also manages the KObjectStore, which provides metadata for devices via the sysfs file system, typically mounted at /sys.

Fields

objects: KObjectStore

The KObjects for registered devices.

Implementations

impl DeviceRegistry

pub fn register_device<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, metadata: DeviceMetadata, class: Class, dev_ops: impl DeviceOps, ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a device with the DeviceRegistry.

If you are registering a device that exists in other systems, please check the metadata for that device in /sys and make sure you use the same properties when calling this function because these value are visible to userspace.

For example, a typical device will appear in sysfs at a path like:

/sys/devices/{bus}/{class}/{name}

Many common classes have convenient accessors on DeviceRegistry::objects.

To fill out the DeviceMetadata, look at the uevent file:

/sys/devices/{bus}/{class}/{name}/uevent

which as the following format:

  MAJOR={major-number}
  MINOR={minor-number}
  DEVNAME={devname}
  DEVMODE={devmode}

Often, the {name} and the {devname} are the same, but if they are not the same, please take care to use the correct string in the correct field.

If the {major-number} is 10 and the {minor-number} is in the range 52..128, please use register_misc_device instead because these device numbers are dynamically allocated.

If the {major-number} is in the range 234..255, please use register_dyn_device instead because these device are also dynamically allocated.

If you are unsure which device numbers to use, consult devices.txt:

https://www.kernel.org/doc/Documentation/admin-guide/devices.txt

If you are still unsure, please ask an experienced Starnix contributor rather than make up a device number.

For most devices, the create_device_sysfs_ops parameter should be DeviceDirectory::new, but some devices have custom directories in sysfs.

Finally, the dev_ops parameter is where you provide the callback for instantiating your device.

pub fn register_device_with_dir<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, metadata: DeviceMetadata, class: Class, build_directory: impl FnOnce(&Device, &SimpleDirectoryMutator), dev_ops: impl DeviceOps, ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a device with a custom directory.

See register_device for an explanation of the parameters.

pub fn register_misc_device<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, dev_ops: impl DeviceOps, ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a dynamic device in the MISC_MAJOR major device number.

MISC devices (major number 10) with minor numbers in the range 52..128 are dynamically assigned. Rather than hardcoding registrations with these device numbers, use this function instead to register the device.

See register_device for an explanation of the parameters.

pub fn register_dyn_device<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, class: Class, dev_ops: impl DeviceOps, ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a dynamic device with major numbers 234..255.

Majors device numbers 234..255 are dynamically assigned. Rather than hardcoding registrations with these device numbers, use this function instead to register the device.

Note: We do not currently allocate from this entire range because we have mistakenly hardcoded some device registrations from the dynamic range. Once we fix these registrations to be dynamic, we should expand to using the full dynamic range.

See register_device for an explanation of the parameters.

pub fn register_dyn_device_with_dir<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, class: Class, build_directory: impl FnOnce(&Device, &SimpleDirectoryMutator), dev_ops: impl DeviceOps, ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a dynamic device with a custom directory.

See register_device for an explanation of the parameters.

pub fn register_dyn_device_with_devname<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, devname: &FsStr, class: Class, build_directory: impl FnOnce(&Device, &SimpleDirectoryMutator), dev_ops: impl DeviceOps, ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a dynamic device with major numbers 234..255.

Majors device numbers 234..255 are dynamically assigned. Rather than hardcoding registrations with these device numbers, use this function instead to register the device.

Note: We do not currently allocate from this entire range because we have mistakenly hardcoded some device registrations from the dynamic range. Once we fix these registrations to be dynamic, we should expand to using the full dynamic range.

See register_device for an explanation of the parameters.

pub fn register_silent_dyn_device<'a, L>( &self, locked: &mut Locked<L>, name: &FsStr, dev_ops: impl DeviceOps, ) -> Result<DeviceMetadata, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register a “silent” dynamic device with major numbers 234..255.

Only use for devices that should not be registered with the KObjectStore/appear in sysfs. This is a rare occurrence.

See register_dyn_device for an explanation of dyn devices and of the parameters.

pub fn add_device<'a, L>( &self, locked: &mut Locked<L>, kernel_or_task: impl KernelOrTask<'a>, name: &FsStr, metadata: DeviceMetadata, class: Class, build_directory: impl FnOnce(&Device, &SimpleDirectoryMutator), ) -> Result<Device, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Directly add a device to the KObjectStore.

This function should be used only by device that have registered an entire major device number. If you want to add a single minor device, use the register_device function instead.

See register_device for an explanation of the parameters.

pub fn add_net_device(&self, name: &FsStr) -> Device

Add a net device to the device registry.

Net devices are different from other devices because they do not have a device number. Instead, their uevent files have the following format:

INTERFACE={name}
IFINDEX={index}

Currently, we only register the net devices by name and use an empty uevent file.

pub fn remove_net_device(&self, device: Device)

Remove a net device from the device registry.

See add_net_device for more details.

pub fn add_numberless_device<L>( &self, _locked: &mut Locked<L>, name: &FsStr, class: Class, build_directory: impl FnOnce(&Device, &SimpleDirectoryMutator), ) -> Device

where L: LockEqualOrBefore<FileOpsCore>,

Directly add a device to the KObjectStore that lacks a device number.

This function should be used only by device do not have a major or a minor number. You can identify these devices because they appear in sysfs and have an empty uevent file.

See register_device for an explanation of the parameters.

pub fn remove_device<L>( &self, locked: &mut Locked<L>, current_task: &CurrentTask, device: Device, )

where L: LockEqualOrBefore<FileOpsCore>,

Remove a device directly added with add_device.

This function should be used only by device that have registered an entire major device number. Individually registered minor device cannot be removed at this time.

pub fn list_major_devices<L>( &self, locked: &mut Locked<L>, mode: DeviceMode, ) -> Vec<(u32, FsString)>

where L: LockEqualOrBefore<FileOpsCore>,

Returns a list of the registered major device numbers for the given DeviceMode and their names.

pub fn list_minor_devices<L>( &self, locked: &mut Locked<L>, mode: DeviceMode, range: Range<DeviceType>, ) -> Vec<(DeviceType, FsString)>

where L: LockEqualOrBefore<FileOpsCore>,

Returns a list of the registered minor devices for the given DeviceMode and their names.

pub fn register_major<'a, L>( &self, locked: &mut Locked<L>, name: FsString, mode: DeviceMode, major: u32, dev_ops: impl DeviceOps, ) -> Result<(), Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Register an entire major device number.

If you register an entire major device, use add_device and remove_device to manage the sysfs entiries for your device rather than trying to register and unregister individual minor devices.

pub fn next_anonymous_dev_id<'a, L>(&self, locked: &mut Locked<L>) -> DeviceType

where L: LockEqualOrBefore<FileOpsCore>,

Allocate an anonymous device identifier.

pub fn register_listener<'a, L>( &self, locked: &mut Locked<L>, listener: impl DeviceListener + 'static, ) -> DeviceListenerKey

where L: LockEqualOrBefore<FileOpsCore>,

Register a new listener for uevents on devices.

Returns a key used to unregister the listener.

pub fn unregister_listener<'a, L>( &self, locked: &mut Locked<L>, key: &DeviceListenerKey, )

where L: LockEqualOrBefore<FileOpsCore>,

Unregister a listener previously registered through register_listener.

pub fn dispatch_uevent<'a, L>( &self, locked: &mut Locked<L>, action: UEventAction, device: Device, )

where L: LockEqualOrBefore<FileOpsCore>,

Dispatch an uevent for the given device.

pub fn open_device<L>( &self, locked: &mut Locked<L>, current_task: &CurrentTask, node: &NamespaceNode, flags: OpenFlags, device_type: DeviceType, mode: DeviceMode, ) -> Result<Box<dyn FileOps>, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Instantiate a file for the specified device.

The device will be looked up in the device registry by DeviceMode and DeviceType.

pub fn get_device<L>( &self, locked: &mut Locked<L>, device_type: DeviceType, mode: DeviceMode, ) -> Result<DeviceHandle, Errno>

where L: LockEqualOrBefore<FileOpsCore>,

Trait Implementations

impl Default for DeviceRegistry

fn default() -> Self

Returns the “default value” for a type.