Documentation/watchdog/convert_drivers_to_kernel_api.rst

Source file repositories/reference/linux-study-clean/Documentation/watchdog/convert_drivers_to_kernel_api.rst

File Facts

System
Linux kernel
Corpus path
Documentation/watchdog/convert_drivers_to_kernel_api.rst
Extension
.rst
Size
7763 bytes
Lines
219
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: operation-table or driver-model contract
Status
pattern implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

Remove the struct file_operations
---------------------------------

Old drivers define their own file_operations for actions like open(), write(),
etc... These are now handled by the framework and just call the driver when
needed. So, in general, the struct file_operations and assorted functions can
go. Only very few driver-specific details have to be moved to other functions.
Here is a overview of the functions and probably needed actions:

- open: Everything dealing with resource management (file-open checks, magic
  close preparations) can simply go. Device specific stuff needs to go to the
  driver specific start-function. Note that for some drivers, the start-function
  also serves as the ping-function. If that is the case and you need start/stop
  to be balanced (clocks!), you are better off refactoring a separate start-function.

- close: Same hints as for open apply.

- write: Can simply go, all defined behaviour is taken care of by the framework,
  i.e. ping on write and magic char ('V') handling.

- ioctl: While the driver is allowed to have extensions to the IOCTL interface,
  the most common ones are handled by the framework, supported by some assistance
  from the driver:

	WDIOC_GETSUPPORT:
		Returns the mandatory struct watchdog_info from the driver

	WDIOC_GETSTATUS:
		Needs the status-callback defined, otherwise returns 0

	WDIOC_GETBOOTSTATUS:
		Needs the bootstatus member properly set. Make sure it is 0 if you
		don't have further support!

	WDIOC_SETOPTIONS:
		No preparations needed

	WDIOC_KEEPALIVE:
		If wanted, options in watchdog_info need to have WDIOF_KEEPALIVEPING
		set

	WDIOC_SETTIMEOUT:
		Options in watchdog_info need to have WDIOF_SETTIMEOUT set
		and a set_timeout-callback has to be defined. The core will also
		do limit-checking, if min_timeout and max_timeout in the watchdog
		device are set. All is optional.

	WDIOC_GETTIMEOUT:
		No preparations needed

	WDIOC_GETTIMELEFT:
		It needs get_timeleft() callback to be defined. Otherwise it
		will return EOPNOTSUPP

  Other IOCTLs can be served using the ioctl-callback. Note that this is mainly
  intended for porting old drivers; new drivers should not invent private IOCTLs.
  Private IOCTLs are processed first. When the callback returns with
  -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
  is directly given to the user.

Example conversion::

  -static const struct file_operations s3c2410wdt_fops = {
  -       .owner          = THIS_MODULE,
  -       .write          = s3c2410wdt_write,
  -       .unlocked_ioctl = s3c2410wdt_ioctl,
  -       .open           = s3c2410wdt_open,
  -       .release        = s3c2410wdt_release,
  -};

Annotation

Implementation Notes