Parameters

x

function to be run at kernel boot time or module insertion

Description

module_init() will either be called duringdo_initcalls() (ifbuiltin) or at module insertion time (if a module). There can onlybe one per module.

Parameters

x

function to be run when driver is removed

Description

module_exit() will wrap the driver clean-up codewithcleanup_module() when used with rmmod whenthe driver is a module. If the driver is staticallycompiled into the kernel,module_exit() has no effect.There can only be one per module.

Definition:

struct klp_modinfo {    Elf_Ehdr hdr;    Elf_Shdr *sechdrs;    char *secstrings;    unsigned int symndx;};

Members

hdr

ELF header

sechdrs

Section header table

secstrings

String table for the section headers

symndx

The symbol table section index

Parameters

structmodule*module

the module we should check for

Description

Only try to get a module reference count if the module is not being removed.This call will fail if the module is in the process of being removed.

Care must also be taken to ensure the module exists and is alive prior tousage of this call. This can be gauranteed through two means:

1. Direct protection: you know an earlier caller must have increased themodule reference through__module_get(). This can typically be achievedby having another entity other than the module itself increment themodule reference count.

2. Implied protection: there is an implied protection against moduleremoval. An example of this is the implied protection used by kernfs /sysfs. The sysfs store / read file operations are guaranteed to existthrough the use of kernfs’s active reference (seekernfs_active()) and asysfs / kernfs file removal cannot happen unless the same file is notactive. Therefore, if a sysfs file is being read or written to the modulewhich created it must still exist. It is therefore safe to usetry_module_get() on module sysfs store / read ops.

One of the real values totry_module_get() is themodule_is_live() checkwhich ensures that the caller oftry_module_get() can yield to userspacemodule removal requests and gracefully fail if the module is on its way out.

Returns true if the reference count was successfully incremented.

Parameters

structmodule*module

the module we should release a reference count for

Description

If you successfully bump a reference count to a module withtry_module_get(),when you are finished you must callmodule_put() to release that referencecount.

Definition:

struct usb_device_id {    __u16 match_flags;    __u16 idVendor;    __u16 idProduct;    __u16 bcdDevice_lo;    __u16 bcdDevice_hi;    __u8 bDeviceClass;    __u8 bDeviceSubClass;    __u8 bDeviceProtocol;    __u8 bInterfaceClass;    __u8 bInterfaceSubClass;    __u8 bInterfaceProtocol;    __u8 bInterfaceNumber;    kernel_ulong_t driver_info  ;};

Members

match_flags

Bit mask controlling which of the other fields are used tomatch against new devices. Any field except for driver_info may beused, although some only make sense in conjunction with other fields.This is usually set by a USB_DEVICE_*() macro, which sets allother fields in this structure except for driver_info.

idVendor

USB vendor ID for a device; numbers are assignedby the USB forum to its members.

idProduct

Vendor-assigned product ID.

bcdDevice_lo

Low end of range of vendor-assigned product version numbers.This is also used to identify individual product versions, fora range consisting of a single device.

bcdDevice_hi

High end of version number range. The range of productversions is inclusive.

bDeviceClass

Class of device; numbers are assignedby the USB forum. Products may choose to implement classes,or be vendor-specific. Device classes specify behavior of allthe interfaces on a device.

bDeviceSubClass

Subclass of device; associated with bDeviceClass.

bDeviceProtocol

Protocol of device; associated with bDeviceClass.

bInterfaceClass

Class of interface; numbers are assignedby the USB forum. Products may choose to implement classes,or be vendor-specific. Interface classes specify behavior onlyof a given interface; other interfaces may support other classes.

bInterfaceSubClass

Subclass of interface; associated with bInterfaceClass.

bInterfaceProtocol

Protocol of interface; associated with bInterfaceClass.

bInterfaceNumber

Number of interface; composite devices may usefixed interface numbers to differentiate between vendor-specificinterfaces.

driver_info

Holds information used by the driver. Usually it holdsa pointer to a descriptor understood by the driver, or perhapsdevice flags.

Parameters

_cls

the class, subclass, prog-if triple for this device

_msk

the class mask for this device

Description

This macro is used to create astructacpi_device_id that matches aspecific PCI class. The .id and .driver_data fields will be leftinitialized with the default value.

Definition:

struct mdio_device_id {    __u32 phy_id;    __u32 phy_id_mask;};

Members

phy_id

The result of(mdio_read(MII_PHYSID1) << 16 | mdio_read(MII_PHYSID2)) &phy_id_maskfor this PHY type

phy_id_mask

Defines the significant bits ofphy_id. A value of 0is used to terminate an array ofstructmdio_device_id.

Definition:

struct amba_id {    unsigned int            id;    unsigned int            mask;    void *data;};

Members

id

The significant bits if the hardware device ID

mask

Bitmask specifying which bits of the id field are significant whenmatching. A driver binds to a device when ((hardware device ID) & mask)== id.

data

Private data used by the driver.

Definition:

struct mips_cdmm_device_id {    __u8 type;};

Members

type

Device type identifier.

Definition:

struct mei_cl_device_id {    char name[MEI_CL_NAME_SIZE];    uuid_le uuid;    __u8 version;    kernel_ulong_t driver_info;};

Members

name

helper name

uuid

client uuid

version

client protocol version

driver_info

information used by the driver.

Definition:

struct rio_device_id {    __u16 did, vid;    __u16 asm_did, asm_vid;};

Members

did

RapidIO device ID

vid

RapidIO vendor ID

asm_did

RapidIO assembly device ID

asm_vid

RapidIO assembly vendor ID

Definition:

struct fsl_mc_device_id {    __u16 vendor;    const char obj_type[16];};

Members

vendor

vendor ID

obj_type

MC object type

Definition:

struct tb_service_id {    __u32 match_flags;    char protocol_key[8 + 1];    __u32 protocol_id;    __u32 protocol_version;    __u32 protocol_revision;    kernel_ulong_t driver_data;};

Members

match_flags

Flags used to match the structure

protocol_key

Protocol key the service supports

protocol_id

Protocol id the service supports

protocol_version

Version of the protocol

protocol_revision

Revision of the protocol software

driver_data

Driver specific data

Definition:

struct typec_device_id {    __u16 svid;    __u8 mode;    kernel_ulong_t driver_data;};

Members

svid

Standard or Vendor ID

mode

Mode index

driver_data

Driver specific data

Definition:

struct tee_client_device_id {    uuid_t uuid;};

Members

uuid

For TEE based client devices we use the device uuid asthe identifier.

Definition:

struct wmi_device_id {    const char guid_string[UUID_STRING_LEN+1];    const void *context;};

Members

guid_string

36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba

context

pointer to driver specific data

Definition:

struct mhi_device_id {    const char chan[MHI_NAME_SIZE];    kernel_ulong_t driver_data;};

Members

chan

MHI channel name

driver_data

driver data;

Definition:

struct dfl_device_id {    __u16 type;    __u16 feature_id;    kernel_ulong_t driver_data;};

Members

type

DFL FIU type of the device. Seeenumdfl_id_type.

feature_id

feature identifier local to its DFL FIU type.

driver_data

driver specific data.

Definition:

struct ishtp_device_id {    guid_t guid;    kernel_ulong_t driver_data;};

Members

guid

GUID of the device.

driver_data

pointer to driver specific data

Definition:

struct cdx_device_id {    __u16 vendor;    __u16 device;    __u16 subvendor;    __u16 subdevice;    __u32 class;    __u32 class_mask;    __u32 override_only;};

Members

vendor

Vendor ID

device

Device ID

subvendor

Subsystem vendor ID (or CDX_ANY_ID)

subdevice

Subsystem device ID (or CDX_ANY_ID)

class

Device classMost drivers do not need to specify class/class_maskas vendor/device is normally sufficient.

class_mask

Limit which sub-fields of the class field are compared.

override_only

Match only when dev->driver_override is this driver.

Definition:

struct coreboot_device_id {    __u32 tag;    kernel_ulong_t driver_data;};

Members

tag

tag ID

driver_data

driver specific data

Definition:

struct prev_cputime {#ifndef CONFIG_VIRT_CPU_ACCOUNTING_NATIVE;    u64 utime;    u64 stime;    raw_spinlock_t lock;#endif;};

Members

utime

time spent in user mode

stime

time spent in system mode

lock

protects the above two fields

Parameters

structtask_struct*p

the task

conststructcpumask*new_mask

CPU affinity mask

Return

zero if successful, or a negative error code

Parameters

conststructtask_struct*p

the task in question.

Return

The nice value [ -20 ... 0 ... 19 ].

Parameters

conststructtask_struct*p

the task in question.

Return

1 ifp is an idle task. 0 otherwise.

Parameters

structtask_struct*p

The process to be woken up.

Description

Attempt to wake up the nominated process and move it to the set of runnableprocesses.

This function executes a full memory barrier before accessing the task state.

Return

1 if the process was woken up, 0 if it was already running.

Parameters

structpreempt_notifier*notifier

notifierstructto register

Parameters

structpreempt_notifier*notifier

notifierstructto unregister

Description

This isnot safe to call from within a preemption notifier.

Parameters

void

no arguments

Description

The tracing infrastructure uses preempt_enable_notrace to preventrecursion and tracing preempt enabling caused by the tracinginfrastructure itself. But as tracing can happen in areas comingfrom userspace or just about to enter userspace, a preempt enablecan occur beforeuser_exit() is called. This will cause the schedulerto be called when the system is still in usermode.

To prevent this, the preempt_enable_notrace will use this functioninstead ofpreempt_schedule() to exit user context if needed beforecalling the scheduler.

Parameters

structcpupri*cp

The cpupri context

structtask_struct*p

The task

structcpumask*lowest_mask

A mask to fill in with selected CPUs (or NULL)

bool(*fitness_fn)(structtask_struct*p,intcpu)

A pointer to a function to do custom checks whether the CPUfits a specific criteria so that we only return those CPUs.

Note

This function returns the recommended CPUs as calculated during thecurrent invocation. By the time the call returns, the CPUs may have infact changed priorities any number of times. While not ideal, it is notan issue of correctness since the normal rebalancer logic will correctany discrepancies created by racing against the uncertainty of the currentpriority configuration.

Return

(int)bool - CPUs were found

Parameters

structcpupri*cp

The cpupri context

intcpu

The target CPU

intnewpri

The priority (INVALID,NORMAL,RT1-RT99,HIGHER) to assign to this CPU

Note

Assumes cpu_rq(cpu)->lock is locked

Return

(void)

Parameters

structcpupri*cp

The cpupri context

Return

-ENOMEM on memory allocation failure.

Parameters

structcpupri*cp

The cpupri context

Parameters

structcfs_rq*cfs_rq

the cfs_rq whose avg changed

Description

This function ‘ensures’: tg->load_avg := Sum tg->cfs_rq[]->avg.load.However, because tg->load_avg is a global value there are performanceconsiderations.

In order to avoid having to look at the other cfs_rq’s, we use adifferential update where we store the last value we propagated. This inturn allows skipping updates if the differential is ‘small’.

Updating tg’s load_avg is necessary beforeupdate_cfs_share().

Parameters

u64now

current time, as percfs_rq_clock_pelt()

structcfs_rq*cfs_rq

cfs_rq to update

Description

The cfs_rq avg is the direct sum of all its entities (blocked and runnable)avg. The immediate corollary is that all (fair) tasks must be attached.

cfs_rq->avg is used fortask_h_load() andupdate_cfs_share() for example.

Since both these conditions indicate a changed cfs_rq->avg.load we shouldcallupdate_tg_load_avg() when this function returns true.

Return

true if the load decayed or we removed load.

Parameters

structcfs_rq*cfs_rq

cfs_rq to attach to

structsched_entity*se

sched_entity to attach

Description

Must callupdate_cfs_rq_load_avg() before this, since we rely oncfs_rq->avg.last_update_time being current.

Parameters

structcfs_rq*cfs_rq

cfs_rq to detach from

structsched_entity*se

sched_entity to detach

Description

Must callupdate_cfs_rq_load_avg() before this, since we rely oncfs_rq->avg.last_update_time being current.

Parameters

intcpu

the CPU to get the utilization for

structtask_struct*p

task for which the CPU utilization should be predicted or NULL

intdst_cpu

CPUp migrates to, -1 ifp moves fromcpu orp == NULL

intboost

1 to enable boosting, otherwise 0

Description

The unit of the return value must be the same as the one of CPU capacityso that CPU utilization can be compared with CPU capacity.

CPU utilization is the sum of running time of runnable tasks plus therecent utilization of currently non-runnable tasks on that CPU.It represents the amount of CPU capacity currently used by CFS tasks inthe range [0..max CPU capacity] with max CPU capacity being the CPUcapacity at f_max.

The estimated CPU utilization is defined as the maximum between CPUutilization and sum of the estimated utilization of the currentlyrunnable tasks on that CPU. It preserves a utilization “snapshot” ofpreviously-executed tasks, which helps better deduce how busy a CPU willbe when a long-sleeping task wakes up. The contribution to CPU utilizationof such a task would be significantly decayed at this point of time.

Boosted CPU utilization is defined as max(CPU runnable, CPU utilization).CPU contention for CFS tasks can be detected by CPU runnable > CPUutilization. Boosting is implemented incpu_util() so that internalusers (e.g. EAS) can use it next to external users (e.g. schedutil),latter viacpu_util_cfs_boost().

CPU utilization can be higher than the current CPU capacity(f_curr/f_max * max CPU capacity) or even the max CPU capacity becauseof rounding errors as well as task migrations or wakeups of new tasks.CPU utilization has to be capped to fit into the [0..max CPU capacity]range. Otherwise a group of CPUs (CPU0 util = 121% + CPU1 util = 80%)could be seen as over-utilized even though CPU1 has 20% of spare CPUcapacity. CPU utilization is allowed to overshoot current CPU capacitythough since this is useful for predicting the CPU capacity requiredafter task migrations (scheduler-driven DVFS).

Return

(Boosted) (estimated) utilization for the specified CPU.

Parameters

structsched_domain*sd

The scheduling domain of the load balancing

intcpu

A CPU

Description

Always use CPU priority when balancing load between SMT siblings. Whenbalancing load between cores, it is not sufficient thatcpu is idle. Onlyuse CPU priority if the whole core is idle.

Return

True if the priority ofcpu must be followed. False otherwise.

Parameters

structlb_env*env

The load balancing environment

structsg_lb_stats*sgs

Load-balancing statistics of the candidate busiest group

structsched_group*group

The candidate busiest group

Description

env::dst_cpu can do asym_packing if it has higher priority than thepreferred CPU ofgroup.

Return

true ifenv::dst_cpu can do with asym_packing load balance. Falseotherwise.

Parameters

structlb_env*env

The load balancing environment.

structsd_lb_stats*sds

Load-balancing data with statistics of the local group.

structsched_group*group

sched_group whose statistics are to be updated.

structsg_lb_stats*sgs

variable to hold the statistics for this group.

bool*sg_overloaded

sched_group is overloaded

bool*sg_overutilized

sched_group is overutilized

Parameters

structlb_env*env

The load balancing environment.

structsd_lb_stats*sds

sched_domain statistics

structsched_group*sg

sched_group candidate to be checked for being the busiest

structsg_lb_stats*sgs

sched_group statistics

Description

Determine ifsg is a busier group than the previously selectedbusiest group.

Return

true ifsg is a busier group than the previously selectedbusiest group.false otherwise.

Parameters

intcpu

the processor on which idleness is tested.

structtask_struct*p

task which should be ignored.

Return

1 if the CPU would be idle. 0 otherwise.

Parameters

structlb_env*env

The load balancing environment.

structsd_lb_stats*sds

variable to hold the statistics for this sched_domain.

Parameters

structlb_env*env

load balance environment

structsd_lb_stats*sds

statistics of the sched_domain whose imbalance is to be calculated.

Parameters

structlb_env*env

The load balancing environment.

Description

Also calculates the amount of runnable load which should be movedto restore balance.

Return

• The busiest group if imbalance exists.

Parameters

work

identifier for the completion structure

Description

This macro declares and initializes a completion structure. Generally usedfor static declarations. You should use the _ONSTACK variant for automaticvariables.

Parameters

work

identifier for the completion structure

Description

This macro declares and initializes a completion structure on the kernelstack.

Parameters

structcompletion*x

pointer to completion structure that is to be initialized

Description

This inline function will initialize a dynamically created completionstructure.

Parameters

structcompletion*x

pointer to completion structure that is to be reinitialized

Description

This inline function should be used to reinitialize a completion structure so it canbe reused. This is especially important aftercomplete_all() is used.

Parameters

void

no arguments

Description

When BITS_PER_LONG < 64, this uses sequence number sampling usingjiffies_lock to protect the 64-bit read.

Return

current 64-bit jiffies value

Parameters

a

first comparable as unsigned long

b

second comparable as unsigned long

Description

Do this with “<0” and “>=0” to only test the sign of the result. Agood compiler would generate better code (and a really good compilerwouldn’t care). Gcc is currently neither.

Return

true is time a is after time b, otherwisefalse.

Parameters

a

first comparable as unsigned long

b

second comparable as unsigned long

Return

true is time a is before time b, otherwisefalse.

Parameters

a

first comparable as unsigned long

b

second comparable as unsigned long

Return

true is time a is after or the same as time b, otherwisefalse.

Parameters

a

first comparable as unsigned long

b

second comparable as unsigned long

Return

true is time a is before or the same as time b, otherwisefalse.

Parameters

a

time to test

b

beginning of the range

c

end of the range

Return

true is time a is in the range [b, c], otherwisefalse.

Parameters

a

time to test

b

beginning of the range

c

end of the range

Return

true is time a is in the range [b, c), otherwisefalse.

Parameters

a

first comparable as __u64

b

second comparable as __u64

Description

This must be used when utilizing jiffies_64 (i.e. return value ofget_jiffies_64()).

Return

true is time a is after time b, otherwisefalse.

Parameters

a

first comparable as __u64

b

second comparable as __u64

Description

This must be used when utilizing jiffies_64 (i.e. return value ofget_jiffies_64()).

Return

true is time a is before time b, otherwisefalse.

Parameters

a

first comparable as __u64

b

second comparable as __u64

Description

This must be used when utilizing jiffies_64 (i.e. return value ofget_jiffies_64()).

Return

true is time a is after or the same as time b, otherwisefalse.

Parameters

a

first comparable as __u64

b

second comparable as __u64

Description

This must be used when utilizing jiffies_64 (i.e. return value ofget_jiffies_64()).

Return

true is time a is before or the same as time b, otherwisefalse.

Parameters

a

time to test

b

beginning of the range

c

end of the range

Return

true is time a is in the range [b, c], otherwisefalse.

Parameters

a

time (unsigned long) to compare to jiffies

Return

true is time a is before jiffies, otherwisefalse.

Parameters

a

time (__u64) to compare to jiffies_64

Return

true is time a is before jiffies_64, otherwisefalse.

Parameters

a

time (unsigned long) to compare to jiffies

Return

true is time a is after jiffies, otherwisefalse.

Parameters

a

time (__u64) to compare to jiffies_64

Return

true is time a is after jiffies_64, otherwisefalse.

Parameters

a

time (unsigned long) to compare to jiffies

Return

true is time a is before or the same as jiffies, otherwisefalse.

Parameters

a

time (__u64) to compare to jiffies_64

Return

true is time a is before or the same jiffies_64, otherwisefalse.

Parameters

a

time (unsigned long) to compare to jiffies

Return

true is time a is after or the same as jiffies, otherwisefalse.

Parameters

a

time (__u64) to compare to jiffies_64

Return

true is time a is after or the same as jiffies_64, otherwisefalse.

Parameters

constunsignedlongj

jiffies value

Return

nanoseconds value

Parameters

constunsignedintm

time in milliseconds

Description

conversion is done as follows:

• negative values mean ‘infinite timeout’ (MAX_JIFFY_OFFSET)

• ‘too large’ values [that would result in larger thanMAX_JIFFY_OFFSET values] mean ‘infinite timeout’ too.

• all other values are converted to jiffies by either multiplyingthe input value by a factor or dividing it with a factor andhandling any 32-bit overflows.for the details see_msecs_to_jiffies()

msecs_to_jiffies() checks for the passed in value being a constantvia__builtin_constant_p() allowing gcc to eliminate most of thecode.__msecs_to_jiffies() is called if the value passed does notallow constant folding and the actual conversion must be done atruntime.The HZ range specific helpers_msecs_to_jiffies() are called bothdirectly here and from__msecs_to_jiffies() in the case whereconstant folding is not possible.

Return

jiffies value

Parameters

_secs

time in seconds

Description

Conversion is done by simple multiplication with HZ

secs_to_jiffies() is defined as a macro rather than a static inlinefunction so it can be used in static initializers.

Return

jiffies value

Parameters

constunsignedintu

time in microseconds

Description

conversion is done as follows:

• ‘too large’ values [that would result in larger thanMAX_JIFFY_OFFSET values] mean ‘infinite timeout’ too.

• all other values are converted to jiffies by either multiplyingthe input value by a factor or dividing it with a factor andhandling any 32-bit overflows as for msecs_to_jiffies.

usecs_to_jiffies() checks for the passed in value being a constantvia__builtin_constant_p() allowing gcc to eliminate most of thecode.__usecs_to_jiffies() is called if the value passed does notallow constant folding and the actual conversion must be done atruntime.The HZ range specific helpers_usecs_to_jiffies() are called bothdirectly here and from__msecs_to_jiffies() in the case whereconstant folding is not possible.

Return

jiffies value

Parameters

constunsignedlongj

jiffies value

Description

Avoid unnecessary multiplications/divisions in thetwo most common HZ cases.

Return

milliseconds value

Parameters

constunsignedlongj

jiffies value

Return

microseconds value

Parameters

constunsignedintyear0

year to convert

constunsignedintmon0

month to convert

constunsignedintday

day to convert

constunsignedinthour

hour to convert

constunsignedintmin

minute to convert

constunsignedintsec

second to convert

Description

Converts Gregorian date to seconds since 1970-01-01 00:00:00.Assumes input in normal date format, i.e. 1980-12-31 23:59:59=> year=1980, mon=12, day=31, hour=23, min=59, sec=59.

[For the Julian calendar (which was used in Russia before 1917,Britain & colonies before 1752, anywhere else before 1582,and is still in use by some communities) leave out the-year/100+year/400 terms, and add 10.]

This algorithm was first published by Gauss (I think).

A leap second can be indicated by calling this function with sec as60 (allowable under ISO 8601). The leap second is treated the sameas the following second since they don’t exist in UNIX time.

An encoding of midnight at the end of the day as 24:00:00 - ie. midnighttomorrow - (allowable under ISO 8601) is supported.

Return

seconds since the epoch time for the given input date

Parameters

structtimespec64*ts

pointer to timespec variable to be set

time64_tsec

seconds to set

s64nsec

nanoseconds to set

Description

Set seconds and nanoseconds field of a timespec variable andnormalize to the timespec storage format

Note

The tv_nsec part is always in the range of 0 <= tv_nsec < NSEC_PER_SEC.For negative values only the tv_sec field is negative !

Parameters

s64nsec

the nanoseconds value to be converted

Return

the timespec64 representation of the nsec parameter.

Parameters

constunsignedintm

time in milliseconds

Description

conversion is done as follows:

• negative values mean ‘infinite timeout’ (MAX_JIFFY_OFFSET)

• ‘too large’ values [that would result in larger thanMAX_JIFFY_OFFSET values] mean ‘infinite timeout’ too.

• all other values are converted to jiffies by either multiplyingthe input value by a factor or dividing it with a factor andhandling any 32-bit overflows.for the details see_msecs_to_jiffies()

msecs_to_jiffies() checks for the passed in value being a constantvia__builtin_constant_p() allowing gcc to eliminate most of thecode,__msecs_to_jiffies() is called if the value passed does notallow constant folding and the actual conversion must be done atruntime.The _msecs_to_jiffies helpers are the HZ dependent conversionroutines found in include/linux/jiffies.h

Return

jiffies value

Parameters

constunsignedintu

time in milliseconds

Return

jiffies value

Parameters

conststructtimespec64*value

pointer tostructtimespec64

Description

The TICK_NSEC - 1 rounds up the value to the next resolution. Notethat a remainder subtract here would not do the right thing as theresolution values don’t fall on second boundaries. I.e. the line:nsec -= nsec % TICK_NSEC; is NOT a correct resolution rounding.Note that due to the small error in the multiplier here, thisrounding is incorrect for sufficiently large values of tv_nsec, butwell formed timespecs should have tv_nsec < NSEC_PER_SEC, so we’reOK.

Rather, we just shift the bits off the right.

The >> (NSEC_JIFFIE_SC - SEC_JIFFIE_SC) converts the scaled nsecvalue to a scaled second value.

Return

jiffies value

Parameters

constunsignedlongjiffies

jiffies value

structtimespec64*value

pointer tostructtimespec64

Parameters

unsignedlongx

jiffies value

Return

jiffies converted to clock_t (CLOCKS_PER_SEC)

Parameters

unsignedlongx

clock_t value

Return

clock_t value converted to jiffies

Parameters

u64x

jiffies_64 value

Return

jiffies_64 value converted to 64-bit “clock_t” (CLOCKS_PER_SEC)

Parameters

u64j

jiffies64 value

Return

nanoseconds value

Parameters

constu64j

jiffies64 value

Return

milliseconds value

Parameters

u64n

nsecs in u64

Description

Unlike {m,u}secs_to_jiffies, type of input is not unsigned int but u64.And this doesn’t return MAX_JIFFY_OFFSET since this function is designedfor scheduler, not for use in device drivers to calculate timeout value.

note

NSEC_PER_SEC = 10^9 = (5^9 * 2^9) = (1953125 * 512)ULLONG_MAX ns = 18446744073.709551615 secs = about 584 years

Return

nsecs converted to jiffies64 value

Parameters

u64n

nsecs in u64

Description

Unlike {m,u}secs_to_jiffies, type of input is not unsigned int but u64.And this doesn’t return MAX_JIFFY_OFFSET since this function is designedfor scheduler, not for use in device drivers to calculate timeout value.

note

NSEC_PER_SEC = 10^9 = (5^9 * 2^9) = (1953125 * 512)ULLONG_MAX ns = 18446744073.709551615 secs = about 584 years

Return

nsecs converted to jiffies value

Parameters

conststructtimespec64lhs

first (left) timespec64 to add

conststructtimespec64rhs

second (right) timespec64 to add

Description

It’s assumed that both values are valid (>= 0).And, each timespec64 is in normalized form.

Return

sum oflhs +rhs

Parameters

structtimespec64*ts

destinationstructtimespec64

conststruct__kernel_timespec__user*uts

user’s time value asstruct__kernel_timespec

Description

Handles compat or 32-bit modes.

Return

0 on success or negative errno on error

Parameters

conststructtimespec64*ts

inputstructtimespec64

struct__kernel_timespec__user*uts

user’sstruct__kernel_timespec

Return

0 on success or negative errno on error

Parameters

structtimespec64*ts

destinationstructtimespec64

constvoid__user*uts

user’s old-format time value (structold_timespec32)

Description

Handles X86_X32_ABI compatibility conversion.

Return

0 on success or negative errno on error

Parameters

conststructtimespec64*ts

inputstructtimespec64

void__user*uts

user’sstructold_timespec32

Description

Handles X86_X32_ABI compatibility conversion.

Return

0 on success or negative errno on error

Parameters

structitimerspec64*it

destinationstructitimerspec64

conststruct__kernel_itimerspec__user*uit

user’sstruct__kernel_itimerspec

Return

0 on success or negative errno on error

Parameters

conststructitimerspec64*it

inputstructitimerspec64

struct__kernel_itimerspec__user*uit

user’sstruct__kernel_itimerspec

Return

0 on success or negative errno on error

Parameters

structitimerspec64*its

destinationstructitimerspec64

conststructold_itimerspec32__user*uits

user’sstructold_itimerspec32

Return

0 on success or negative errno on error

Parameters

conststructitimerspec64*its

inputstructitimerspec64

structold_itimerspec32__user*uits

user’sstructold_itimerspec32

Return

0 on success or negative errno on error

Parameters

unsignedlongj

the time in (relative) jiffies that should be rounded

intcpu

the processor number on which the timeout will happen

Description

__round_jiffies_relative() rounds a time delta in the future (in jiffies)up or down to (approximately) full seconds. This is useful for timersfor which the exact time they fire does not matter too much, as long asthey fire approximately every X seconds.

By rounding these timers to whole seconds, all such timers will fireat the same time, rather than at various times spread out. The goalof this is to have the CPU wake up less, which saves power.

The exact rounding is skewed for each processor to avoid allprocessors firing at the exact same time, which could leadto lock contention or spurious cache line bouncing.

The return value is the rounded version of thej parameter.

Parameters

unsignedlongj

the time in (absolute) jiffies that should be rounded

Description

round_jiffies() rounds an absolute time in the future (in jiffies)up or down to (approximately) full seconds. This is useful for timersfor which the exact time they fire does not matter too much, as long asthey fire approximately every X seconds.

By rounding these timers to whole seconds, all such timers will fireat the same time, rather than at various times spread out. The goalof this is to have the CPU wake up less, which saves power.

The return value is the rounded version of thej parameter.

Parameters

unsignedlongj

the time in (relative) jiffies that should be rounded

Description

round_jiffies_relative() rounds a time delta in the future (in jiffies)up or down to (approximately) full seconds. This is useful for timersfor which the exact time they fire does not matter too much, as long asthey fire approximately every X seconds.

By rounding these timers to whole seconds, all such timers will fireat the same time, rather than at various times spread out. The goalof this is to have the CPU wake up less, which saves power.

The return value is the rounded version of thej parameter.

Parameters

unsignedlongj

the time in (relative) jiffies that should be rounded

intcpu

the processor number on which the timeout will happen

Description

This is the same as__round_jiffies_relative() except that it will neverround down. This is useful for timeouts for which the exact timeof firing does not matter too much, as long as they don’t fire tooearly.

Parameters

unsignedlongj

the time in (absolute) jiffies that should be rounded

Description

This is the same asround_jiffies() except that it will neverround down. This is useful for timeouts for which the exact timeof firing does not matter too much, as long as they don’t fire tooearly.

Parameters

unsignedlongj

the time in (relative) jiffies that should be rounded

Description

This is the same asround_jiffies_relative() except that it will neverround down. This is useful for timeouts for which the exact timeof firing does not matter too much, as long as they don’t fire tooearly.

Parameters

structtimer_list*timer

the timer to be initialized

void(*func)(structtimer_list*)

timer callback function

unsignedintflags

timer flags

constchar*name

name of the timer

structlock_class_key*key

lockdep class key of the fake lock used for tracking timersync lock dependencies

Description

timer_init_key() must be done to a timer prior to callingany of theother timer functions.

Parameters

structtimer_list*timer

The pending timer to be modified

unsignedlongexpires

New absolute timeout in jiffies

Description

mod_timer_pending() is the same for pending timers asmod_timer(), butwill not activate inactive timers.

Iftimer->function == NULL then the start operation is silentlydiscarded.

Return

• 0 - The timer was inactive and not modified or was in

  shutdown state and the operation was discarded

• 1 - The timer was active and requeued to expire atexpires

Parameters

structtimer_list*timer

The timer to be modified

unsignedlongexpires

New absolute timeout in jiffies

Description

mod_timer(timer, expires) is equivalent to:

timer_delete(timer); timer->expires = expires; add_timer(timer);

mod_timer() is more efficient than the above open coded sequence. Incase that the timer is inactive, thetimer_delete() part is a NOP. Thetimer is in any case activated with the new expiry timeexpires.

Note that if there are multiple unserialized concurrent users of thesame timer, thenmod_timer() is the only safe way to modify the timeout,sinceadd_timer() cannot modify an already running timer.

Iftimer->function == NULL then the start operation is silentlydiscarded. In this case the return value is 0 and meaningless.

Return

• 0 - The timer was inactive and started or was in shutdown

  state and the operation was discarded

• 1 - The timer was active and requeued to expire atexpires or

  the timer was active and not modified becauseexpires didnot change the effective expiry time

Parameters

structtimer_list*timer

The timer to be modified

unsignedlongexpires

New absolute timeout in jiffies

Description

timer_reduce() is very similar tomod_timer(), except that it will onlymodify an enqueued timer if that would reduce the expiration time. Iftimer is not enqueued it starts the timer.

Iftimer->function == NULL then the start operation is silentlydiscarded.

Return

• 0 - The timer was inactive and started or was in shutdown

  state and the operation was discarded

• 1 - The timer was active and requeued to expire atexpires or

  the timer was active and not modified becauseexpiresdid not change the effective expiry time such that thetimer would expire earlier than already scheduled

Parameters

structtimer_list*timer

The timer to be started

Description

Starttimer to expire attimer->expires in the future.timer->expiresis the absolute expiry time measured in ‘jiffies’. When the timer expirestimer->function(timer) will be invoked from soft interrupt context.

Thetimer->expires andtimer->function fields must be set priorto calling this function.

Iftimer->function == NULL then the start operation is silentlydiscarded.

Iftimer->expires is already in the pasttimer will be queued toexpire at the next timer tick.

This can only operate on an inactive timer. Attempts to invoke this onan active timer are rejected with a warning.

Parameters

structtimer_list*timer

The timer to be started

Description

Same asadd_timer() except that the timer flag TIMER_PINNED is set.

Seeadd_timer() for further details.

Parameters

structtimer_list*timer

The timer to be started

Description

Same asadd_timer() except that the timer flag TIMER_PINNED is unset.

Seeadd_timer() for further details.

Parameters

structtimer_list*timer

The timer to be started

intcpu

The CPU to start it on

Description

Same asadd_timer() except that it starts the timer on the given CPU andthe TIMER_PINNED flag is set. When timer shouldn’t be a pinned timer inthe next round,add_timer_global() should be used instead as it unsetsthe TIMER_PINNED flag.

Seeadd_timer() for further details.

Parameters

structtimer_list*timer

The timer to be deactivated

Description

The function only deactivates a pending timer, but contrary totimer_delete_sync() it does not take into account whether the timer’scallback function is concurrently executed on a different CPU or not.It neither prevents rearming of the timer. Iftimer can be rearmedconcurrently then the return value of this function is meaningless.

Return

• 0 - The timer was not pending

• 1 - The timer was pending and deactivated

Parameters

structtimer_list*timer

The timer to be deactivated

Description

The function does not wait for an eventually running timer callback on adifferent CPU but it prevents rearming of the timer. Any attempt to armtimer after this function returns will be silently ignored.

This function is useful for teardown code and should only be used whentimer_shutdown_sync() cannot be invoked due to locking or context constraints.

Return

• 0 - The timer was not pending

• 1 - The timer was pending

Parameters

structtimer_list*timer

Timer to deactivate

Description

This function tries to deactivate a timer. On success the timer is notqueued and the timer callback function is not running on any CPU.

This function does not guarantee that the timer cannot be rearmed rightafter dropping the base lock. That needs to be prevented by the callingcode if necessary.

Return

• 0 - The timer was not pending

• 1 - The timer was pending and deactivated

• -1 - The timer callback function is running on a different CPU

Parameters

structtimer_list*timer

The timer to be deactivated

Description

Synchronization rules: Callers must prevent restarting of the timer,otherwise this function is meaningless. It must not be called frominterrupt contexts unless the timer is an irqsafe one. The caller mustnot hold locks which would prevent completion of the timer’s callbackfunction. The timer’s handler must not calladd_timer_on(). Upon exitthe timer is not queued and the handler is not running on any CPU.

For !irqsafe timers, the caller must not hold locks that are held ininterrupt context. Even if the lock has nothing to do with the timer inquestion. Here’s why:

CPU0                             CPU1----                             ----                                 <SOFTIRQ>                                   call_timer_fn();                                   base->running_timer = mytimer;spin_lock_irq(somelock);                                 <IRQ>                                    spin_lock(somelock);timer_delete_sync(mytimer);while (base->running_timer == mytimer);

Nowtimer_delete_sync() will never return and never release somelock.The interrupt on the other CPU is waiting to grab somelock but it hasinterrupted the softirq that CPU0 is waiting to finish.

This function cannot guarantee that the timer is not rearmed again bysome concurrent or preempting code, right after it dropped the baselock. If there is the possibility of a concurrent rearm then the returnvalue of the function is meaningless.

If such a guarantee is needed, e.g. for teardown situations then usetimer_shutdown_sync() instead.

Return

• 0 - The timer was not pending

• 1 - The timer was pending and deactivated

Parameters

structtimer_list*timer

The timer to be shutdown

Description

When the function returns it is guaranteed that:

• timer is not queued

• The callback function oftimer is not running

• timer cannot be enqueued again. Any attempt to rearmtimer is silently ignored.

Seetimer_delete_sync() for synchronization rules.

This function is useful for final teardown of an infrastructure wherethe timer is subject to a circular dependency problem.

A common pattern for this is a timer and a workqueue where the timer canschedule work and work can arm the timer. On shutdown the workqueue mustbe destroyed and the timer must be prevented from rearming. Unless thecode has conditionals like ‘if (mything->in_shutdown)’ to prevent thatthere is no way to get this correct withtimer_delete_sync().

timer_shutdown_sync() is solving the problem. The correct ordering ofcalls in this case is:

timer_shutdown_sync(mything->timer);workqueue_destroy(mything->workqueue);

After this ‘mything’ can be safely freed.

This obviously implies that the timer is not required to be functionalfor the rest of the shutdown operation.

Return

• 0 - The timer was not pending

• 1 - The timer was pending

Parameters

consts64secs

seconds to set

constunsignedlongnsecs

nanoseconds to set

Return

The ktime_t representation of the value.

Parameters

constktime_tcmp1

comparable1

constktime_tcmp2

comparable2

Return

...cmp1 < cmp2: return <0cmp1 == cmp2: return 0cmp1 > cmp2: return >0

Parameters

constktime_tcmp1

comparable1

constktime_tcmp2

comparable2

Return

true if cmp1 happened after cmp2.

Parameters

constktime_tcmp1

comparable1

constktime_tcmp2

comparable2

Return

true if cmp1 happened before cmp2.

Parameters

constktime_tkt

the ktime_t variable to convert

structtimespec64*ts

the timespec variable to store the result in

Return

true if there was a successful conversion,false if kt was 0.

Definition:

struct hrtimer_sleeper {    struct hrtimer timer;    struct task_struct *task;};

Members

timer

embedded timer structure

task

task to wake up

Parameters

structhrtimer*timer

the timer to be added

ktime_ttim

expiry time

constenumhrtimer_modemode

timer mode: absolute (HRTIMER_MODE_ABS) orrelative (HRTIMER_MODE_REL), and pinned (HRTIMER_MODE_PINNED);softirq based mode is considered for debug purpose only!

Parameters

conststructhrtimer*timer

the timer to read

Parameters

structhrtimer*timer

Timer to check

Return

True if the timer is queued, false otherwise

Description

The function can be used lockless, but it gives only a current snapshot.

Parameters

structhrtimer*timer

Timer to update

enumhrtimer_restart(*function)(structhrtimer*)

New callback function

Description

Only safe to call if the timer is not enqueued. Can be called in the callback function if thetimer is not enqueued at the same time (see the comments above HRTIMER_STATE_ENQUEUED).

Parameters

structhrtimer*timer

hrtimer to forward

ktime_tinterval

the interval to forward

Description

It is a variant ofhrtimer_forward(). The timer will expire after the currenttime of the hrtimer clock base. Seehrtimer_forward() for details.

Parameters

structhrtimer*timer

hrtimer to forward

ktime_tnow

forward past this time

ktime_tinterval

the interval to forward

Description

Forward the timer expiry so it will expire in the future.

There is also a variant of the functionhrtimer_forward_now().

Context

Can be safely called from the callback function oftimer. If calledfrom other contextstimer must neither be enqueued nor running thecallback and the caller needs to take care of serialization.

Return

The number of overruns are returned.

Parameters

structhrtimer*timer

the timer to be added

ktime_ttim

expiry time

u64delta_ns

“slack” range for the timer

constenumhrtimer_modemode

timer mode: absolute (HRTIMER_MODE_ABS) orrelative (HRTIMER_MODE_REL), and pinned (HRTIMER_MODE_PINNED);softirq based mode is considered for debug purpose only!

Parameters

structhrtimer*timer

hrtimer to stop

Description

• 0 when the timer was not active

• 1 when the timer was active

• -1 when the timer is currently executing the callback function andcannot be stopped

Parameters

structhrtimer*timer

the timer to be cancelled

Return

0 when the timer was not active1 when the timer was active

Parameters

conststructhrtimer*timer

the timer to read

booladjust

adjust relative timers when CONFIG_TIME_LOW_RES=y

Parameters

structhrtimer*timer

the timer to be initialized

enumhrtimer_restart(*function)(structhrtimer*)

the callback function

clockid_tclock_id

the clock to be used

enumhrtimer_modemode

The modes which are relevant for initialization:HRTIMER_MODE_ABS, HRTIMER_MODE_REL, HRTIMER_MODE_ABS_SOFT,HRTIMER_MODE_REL_SOFT

Description

The PINNED variants of the above can be handed in,but the PINNED bit is ignored as pinning happenswhen the hrtimer is started

Parameters

structhrtimer*timer

The timer to be initialized

enumhrtimer_restart(*function)(structhrtimer*)

the callback function

clockid_tclock_id

The clock to be used

enumhrtimer_modemode

The timer mode

Description

Similar tohrtimer_setup(), except that this one must be used ifstructhrtimer is in stackmemory.

Parameters

structhrtimer_sleeper*sl

sleeper to be started

enumhrtimer_modemode

timer mode abs/rel

Description

Wrapper aroundhrtimer_start_expires() for hrtimer_sleeper based timersto allow PREEMPT_RT to tweak the delivery mode (soft/hardirq context)

Parameters

structhrtimer_sleeper*sl

sleeper to be initialized

clockid_tclock_id

the clock to be used

enumhrtimer_modemode

timer mode abs/rel

Parameters

structwait_queue_head*wq_head

the waitqueue to test for waiters

Description

returns true if the wait list is not empty

NOTE

this function is lockless and requires care, incorrect usage _will_lead to sporadic and non-obvious failure.

Use either while holding wait_queue_head::lock or when used for wakeupswith an extrasmp_mb() like:

CPU0 - waker                    CPU1 - waiter                                for (;;) {@cond = true;                     prepare_to_wait(&wq_head, &wait, state);smp_mb();                         // smp_mb() from set_current_state()if (waitqueue_active(wq_head))         if (@cond)  wake_up(wq_head);                      break;                                  schedule();                                }                                finish_wait(&wq_head, &wait);

Because without the explicitsmp_mb() it’s possible for thewaitqueue_active() load to get hoisted over thecond store such that we’llobserve an empty wait list while the waiter might not observecond.

Also note that this ‘optimization’ trades aspin_lock() for ansmp_mb(),which (when the lock is uncontended) are of roughly equal cost.

Parameters

structwait_queue_head*wq_head

wait queue head

Description

Returns true of wq_head has only one sleeper on the list.

Please refer to the comment for waitqueue_active.

Parameters

structwait_queue_head*wq_head

wait queue head

Description

Returns true if wq_head has waiting processes

Please refer to the comment for waitqueue_active.

Parameters

structwait_queue_head*wq_head

the wait queue head

Description

In the very rare cases where a ->poll() implementation uses a waitqueue whoselifetime is tied to a task rather than to the ‘structfile’ being polled,this function must be called before the waitqueue is freed so thatnon-blocking polls (e.g. epoll) are notified that the queue is going away.

The caller must also RCU-delay the freeing of the wait_queue_head, e.g. viaan explicitsynchronize_rcu() orcall_rcu(), or via SLAB_TYPESAFE_BY_RCU.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

Description

The process is put to sleep (TASK_UNINTERRUPTIBLE) until thecondition evaluates to true. Thecondition is checked each timethe waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

Description

The process is put to sleep (TASK_INTERRUPTIBLE -- so as not to contributeto system load) until thecondition evaluates to true. Thecondition is checked each time the waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

timeout

timeout, in jiffies

Description

The process is put to sleep (TASK_UNINTERRUPTIBLE) until thecondition evaluates to true. Thecondition is checked each timethe waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Return

0 if thecondition evaluated tofalse after thetimeout elapsed,1 if thecondition evaluated totrue after thetimeout elapsed,or the remaining jiffies (at least 1) if thecondition evaluatedtotrue before thetimeout elapsed.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

cmd1

the command will be executed before sleep

cmd2

the command will be executed after sleep

Description

The process is put to sleep (TASK_UNINTERRUPTIBLE) until thecondition evaluates to true. Thecondition is checked each timethe waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

Description

The process is put to sleep (TASK_INTERRUPTIBLE) until thecondition evaluates to true or a signal is received.Thecondition is checked each time the waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

The function will return -ERESTARTSYS if it was interrupted by asignal and 0 ifcondition evaluated to true.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

timeout

timeout, in jiffies

Description

The process is put to sleep (TASK_INTERRUPTIBLE) until thecondition evaluates to true or a signal is received.Thecondition is checked each time the waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Return

0 if thecondition evaluated tofalse after thetimeout elapsed,1 if thecondition evaluated totrue after thetimeout elapsed,the remaining jiffies (at least 1) if thecondition evaluatedtotrue before thetimeout elapsed, or -ERESTARTSYS if it wasinterrupted by a signal.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

timeout

timeout, as a ktime_t

Description

The process is put to sleep (TASK_UNINTERRUPTIBLE) until thecondition evaluates to true or a signal is received.Thecondition is checked each time the waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

The function returns 0 ifcondition became true, or -ETIME if the timeoutelapsed.

Parameters

wq

the waitqueue to wait on

condition

a C expression for the event to wait for

timeout

timeout, as a ktime_t

Description

The process is put to sleep (TASK_INTERRUPTIBLE) until thecondition evaluates to true or a signal is received.Thecondition is checked each time the waitqueuewq is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

The function returns 0 ifcondition became true, -ERESTARTSYS if it wasinterrupted by a signal, or -ETIME if the timeout elapsed.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

Description

The process is put to sleep (TASK_IDLE) until thecondition evaluates to true.Thecondition is checked each time the waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

Description

The process is put to sleep (TASK_IDLE) until thecondition evaluates to true.Thecondition is checked each time the waitqueuewq_head is woken up.

The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flagset thus if other processes wait on the same list, when thisprocess is woken further processes are not considered.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Parameters

wq_head

the waitqueue to wait on

condition

a C expression for the event to wait for

timeout

timeout, in jiffies

Description

The process is put to sleep (TASK_IDLE) until thecondition evaluates to true. Thecondition is checked each timethe waitqueuewq_head is woken up.

wake_up() has to be called after changing any variable that couldchange the result of the wait condition.

Return

0 if thecondition evaluated tofalse after thetimeout elapsed,1 if thecondition evaluated totrue after thetimeout elapsed,or the remaining jiffies (at least 1) if thecondition evaluatedtotrue before thetimeout elapsed.