Parallel Port Devices¶

intparport_yield(struct pardevice * dev)¶

relinquish a parallel port temporarily

Parameters

structpardevice*dev

a device on the parallel port

Description

This function relinquishes the port if it would be helpful to otherdrivers to do so. Afterwards it tries to reclaim the port usingparport_claim(), and the return value is the same as forparport_claim(). If it fails, the port is left unclaimed and it isthe driver’s responsibility to reclaim the port.

Theparport_yield() andparport_yield_blocking() functions are formarking points in the driver at which other drivers may claim theport and use their devices. Yielding the port is similar toreleasing it and reclaiming it, but is more efficient because noaction is taken if there are no other devices needing the port. Infact, nothing is done even if there are other devices waiting butthe current device is still within its “timeslice”. The defaulttimeslice is half a second, but it can be adjusted via the /procinterface.

intparport_yield_blocking(struct pardevice * dev)¶

relinquish a parallel port temporarily

Parameters

structpardevice*dev

a device on the parallel port

Description

This function relinquishes the port if it would be helpful to otherdrivers to do so. Afterwards it tries to reclaim the port usingparport_claim_or_block(), and the return value is the same as forparport_claim_or_block().

intparport_wait_event(struct parport * port, signed long timeout)¶

wait for an event on a parallel port

Parameters

structparport*port

port to wait on

signedlongtimeout

time to wait (in jiffies)

This function waits for up totimeout jiffies for aninterrupt to occur on a parallel port. If the port timeout isset to zero, it returns immediately.

If an interrupt occurs before the timeout period elapses, thisfunction returns zero immediately. If it times out, it returnsone. An error code less than zero indicates an error (mostlikely a pending signal), and the calling code should finishwhat it’s doing as soon as it can.

intparport_wait_peripheral(struct parport * port, unsigned char mask, unsigned char result)¶

wait for status lines to change in 35ms

Parameters

structparport*port

port to watch

unsignedcharmask

status lines to watch

unsignedcharresult

desired values of chosen status lines

This function waits until the masked status lines have thedesired values, or until 35ms have elapsed (see IEEE 1284-1994page 24 to 25 for why this value in particular is hardcoded).Themask andresult parameters are bitmasks, with the bitsdefined by the constants in parport.h:PARPORT_STATUS_BUSY,and so on.

The port is polled quickly to start off with, in anticipationof a fast response from the peripheral. This fast pollingtime is configurable (using /proc), and defaults to 500usec.If the timeout for this port (seeparport_set_timeout()) iszero, the fast polling time is 35ms, and this function doesnot call schedule().

If the timeout for this port is non-zero, after the fastpolling fails it usesparport_wait_event() to wait for up to10ms, waking up if an interrupt occurs.

intparport_negotiate(struct parport * port, int mode)¶

negotiate an IEEE 1284 mode

Parameters

structparport*port

port to use

intmode

mode to negotiate to

Use this to negotiate to a particular IEEE 1284 transfer mode.Themode parameter should be one of the constants inparport.h startingIEEE1284_MODE_xxx.

The return value is 0 if the peripheral has accepted thenegotiation to the mode specified, -1 if the peripheral is notIEEE 1284 compliant (or not present), or 1 if the peripheralhas rejected the negotiation.

ssize_tparport_write(struct parport * port, const void * buffer, size_t len)¶

write a block of data to a parallel port

Parameters

structparport*port

port to write to

constvoid*buffer

data buffer (in kernel space)

size_tlen

number of bytes of data to transfer

This will write up tolen bytes ofbuffer to the portspecified, using the IEEE 1284 transfer mode most recentlynegotiated to (usingparport_negotiate()), as long as thatmode supports forward transfers (host to peripheral).

It is the caller’s responsibility to ensure that the firstlen bytes ofbuffer are valid.

This function returns the number of bytes transferred (if zeroor positive), or else an error code.

ssize_tparport_read(struct parport * port, void * buffer, size_t len)¶

read a block of data from a parallel port

Parameters

structparport*port

port to read from

void*buffer

data buffer (in kernel space)

size_tlen

number of bytes of data to transfer

This will read up tolen bytes ofbuffer to the portspecified, using the IEEE 1284 transfer mode most recentlynegotiated to (usingparport_negotiate()), as long as thatmode supports reverse transfers (peripheral to host).

It is the caller’s responsibility to ensure that the firstlen bytes ofbuffer are available to write to.

This function returns the number of bytes transferred (if zeroor positive), or else an error code.

longparport_set_timeout(struct pardevice * dev, long inactivity)¶

set the inactivity timeout for a device

Parameters

structpardevice*dev

device on a port

longinactivity

inactivity timeout (in jiffies)

This sets the inactivity timeout for a particular device on aport. This affects functions likeparport_wait_peripheral().The special value 0 means not to call schedule() while dealingwith this device.

The return value is the previous inactivity timeout.

Any callers ofparport_wait_event() for this device are wokenup.

int__parport_register_driver(struct parport_driver * drv, struct module * owner, const char * mod_name)¶

register a parallel port device driver

Parameters

structparport_driver*drv

structure describing the driver

structmodule*owner

owner module of drv

constchar*mod_name

module name string

This can be called by a parallel port device driver in orderto receive notifications about ports being found in thesystem, as well as ports no longer available.

If devmodel is true then the new device model is usedfor registration.

Thedrv structure is allocated by the caller and must not bedeallocated until after callingparport_unregister_driver().

If using the non device model:The driver’s attach() function may block. The port thatattach() is given will be valid for the duration of thecallback, but if the driver wants to take a copy of thepointer it must callparport_get_port() to do so. Callingparport_register_device() on that port will do this for you.

The driver’s detach() function may block. The port thatdetach() is given will be valid for the duration of thecallback, but if the driver wants to take a copy of thepointer it must callparport_get_port() to do so.

Returns 0 on success. The non device model will always succeeds.but the new device model can fail and will return the error code.

voidparport_unregister_driver(struct parport_driver * drv)¶

deregister a parallel port device driver

Parameters

structparport_driver*drv

structure describing the driver that was given toparport_register_driver()

This should be called by a parallel port device driver thathas registered itself using parport_register_driver() when itis about to be unloaded.

When it returns, the driver’s attach() routine will no longerbe called, and for each port that attach() was called for, thedetach() routine will have been called.

All the driver’s attach() and detach() calls are guaranteed to havefinished by the time this function returns.

struct parport *parport_get_port(struct parport * port)¶

increment a port’s reference count

Parameters

structparport*port

the port

This ensures that a struct parport pointer remains validuntil the matchingparport_put_port() call.

voidparport_put_port(struct parport * port)¶

decrement a port’s reference count

Parameters

structparport*port

the port

This should be called once for each call toparport_get_port(),once the port is no longer needed. When the reference count reacheszero (port is no longer used), free_port is called.

struct parport *parport_register_port(unsigned long base, int irq, int dma, struct parport_operations * ops)¶

register a parallel port

Parameters

unsignedlongbase

base I/O address

intirq

IRQ line

intdma

DMA channel

structparport_operations*ops

pointer to the port driver’s port operations structure

When a parallel port (lowlevel) driver finds a port thatshould be made available to parallel port device drivers, itshould callparport_register_port(). Thebase,irq, anddma parameters are for the convenience of port drivers, andfor ports where they aren’t meaningful needn’t be set toanything special. They can be altered afterwards by adjustingthe relevant members of the parport structure that is returnedand represents the port. They should not be tampered withafter calling parport_announce_port, however.

If there are parallel port device drivers in the system thathave registered themselves using parport_register_driver(),they are not told about the port at this time; that is done byparport_announce_port().

Theops structure is allocated by the caller, and must not bedeallocated before callingparport_remove_port().

If there is no memory to allocate a new parport structure,this function will returnNULL.

voidparport_announce_port(struct parport * port)¶

tell device drivers about a parallel port

Parameters

structparport*port

parallel port to announce

After a port driver has registered a parallel port withparport_register_port, and performed any necessaryinitialisation or adjustments, it should callparport_announce_port() in order to notify all device driversthat have called parport_register_driver(). Their attach()functions will be called, withport as the parameter.

voidparport_remove_port(struct parport * port)¶

deregister a parallel port

Parameters

structparport*port

parallel port to deregister

When a parallel port driver is forcibly unloaded, or aparallel port becomes inaccessible, the port driver must callthis function in order to deal with device drivers that stillwant to use it.

The parport structure associated with the port has itsoperations structure replaced with one containing ‘null’operations that return errors or just don’t do anything.

Any drivers that have registered themselves usingparport_register_driver() are notified that the port is nolonger accessible by having their detach() routines calledwithport as the parameter.

struct pardevice *parport_register_dev_model(struct parport * port, const char * name, const struct pardev_cb * par_dev_cb, int id)¶

register a device on a parallel port

Parameters

structparport*port

port to which the device is attached

constchar*name

a name to refer to the device

conststructpardev_cb*par_dev_cb

struct containing callbacks

intid

device number to be given to the device

This function, called by parallel port device drivers,declares that a device is connected to a port, and tells thesystem all it needs to know.

The struct pardev_cb contains pointer to callbacks. preemptioncallback function,preempt, is called when this device driverhas claimed access to the port but another device driver wantsto use it. It is given,private, as its parameter, and shouldreturn zero if it is willing for the system to release the portto another driver on its behalf. If it wants to keep control ofthe port it should return non-zero, and no action will be taken.It is good manners for the driver to try to release the port atthe earliest opportunity after its preemption callback rejects apreemption attempt. Note that if a preemption callback is happyfor preemption to go ahead, there is no need to release theport; it is done automatically. This function may not block, asit may be called from interrupt context. If the device driverdoes not support preemption,preempt can beNULL.

The wake-up (“kick”) callback function,wakeup, is called whenthe port is available to be claimed for exclusive access; thatis,parport_claim() is guaranteed to succeed when called frominside the wake-up callback function. If the driver wants toclaim the port it should do so; otherwise, it need not takeany action. This function may not block, as it may be calledfrom interrupt context. If the device driver does not want tobe explicitly invited to claim the port in this way,wakeup canbeNULL.

The interrupt handler,irq_func, is called when an interruptarrives from the parallel port. Note that if a device driverwants to use interrupts it should use parport_enable_irq(),and can also check the irq member of the parport structurerepresenting the port.

The parallel port (lowlevel) driver is the one that has calledrequest_irq() and whose interrupt handler is called first.This handler does whatever needs to be done to the hardware toacknowledge the interrupt (for PC-style ports there is nothingspecial to be done). It then tells the IEEE 1284 code aboutthe interrupt, which may involve reacting to an IEEE 1284event depending on the current IEEE 1284 phase. After this,it callsirq_func. Needless to say,irq_func will be calledfrom interrupt context, and may not block.

ThePARPORT_DEV_EXCL flag is for preventing port sharing, andso should only be used when sharing the port with other devicedrivers is impossible and would lead to incorrect behaviour.Use it sparingly! Normally,flags will be zero.

This function returns a pointer to a structure that representsthe device on the port, orNULL if there is not enough memoryto allocate space for that structure.

voidparport_unregister_device(struct pardevice * dev)¶

deregister a device on a parallel port

Parameters

structpardevice*dev

pointer to structure representing device

This undoes the effect of parport_register_device().

struct parport *parport_find_number(int number)¶

find a parallel port by number

Parameters

intnumber

parallel port number

This returns the parallel port with the specified number, orNULL if there is none.

There is an implicitparport_get_port() done already; to throwaway the reference to the port thatparport_find_number()gives you, useparport_put_port().

struct parport *parport_find_base(unsigned long base)¶

find a parallel port by base address

Parameters

unsignedlongbase

base I/O address

This returns the parallel port with the specified baseaddress, orNULL if there is none.

There is an implicitparport_get_port() done already; to throwaway the reference to the port thatparport_find_base()gives you, useparport_put_port().

intparport_claim(struct pardevice * dev)¶

claim access to a parallel port device

Parameters

structpardevice*dev

pointer to structure representing a device on the port

This function will not block and so can be used from interruptcontext. Ifparport_claim() succeeds in claiming access tothe port it returns zero and the port is available to use. Itmay fail (returning non-zero) if the port is in use by anotherdriver and that driver is not willing to relinquish control ofthe port.

intparport_claim_or_block(struct pardevice * dev)¶

claim access to a parallel port device

Parameters

structpardevice*dev

pointer to structure representing a device on the port

This behaves likeparport_claim(), but will block if necessaryto wait for the port to be free. A return value of 1indicates that it slept; 0 means that it succeeded withoutneeding to sleep. A negative error code indicates failure.

voidparport_release(struct pardevice * dev)¶

give up access to a parallel port device

Parameters

structpardevice*dev

pointer to structure representing parallel port device

This function cannot fail, but it should not be called withoutthe port claimed. Similarly, if the port is already claimedyou should not try claiming it again.

struct pardevice *parport_open(int devnum, const char * name)¶

find a device by canonical device number

Parameters

intdevnum

canonical device number

constchar*name

name to associate with the device

This function is similar to parport_register_device(), exceptthat it locates a device by its number rather than by the portit is attached to.

All parameters except fordevnum are the same as forparport_register_device(). The return value is the same asfor parport_register_device().

voidparport_close(struct pardevice * dev)¶

close a device opened withparport_open()

Parameters

structpardevice*dev

device to close

This is toparport_open() asparport_unregister_device() is toparport_register_device().

16x50 UART Driver¶

voiduart_update_timeout(struct uart_port * port, unsigned int cflag, unsigned int baud)¶

update per-port FIFO timeout.

Parameters

structuart_port*port

uart_port structure describing the port

unsignedintcflag

termios cflag value

unsignedintbaud

speed of the port

Set the port FIFO timeout value. Thecflag value shouldreflect the actual hardware settings.

unsigned intuart_get_baud_rate(struct uart_port * port, struct ktermios * termios, struct ktermios * old, unsigned int min, unsigned int max)¶

return baud rate for a particular port

Parameters

structuart_port*port

uart_port structure describing the port in question.

structktermios*termios

desired termios settings.

structktermios*old

old termios (or NULL)

unsignedintmin

minimum acceptable baud rate

unsignedintmax

maximum acceptable baud rate

Decode the termios structure into a numeric baud rate,taking account of the magic 38400 baud rate (with spd_*flags), and mapping theB0 rate to 9600 baud.

If the new baud rate is invalid, try the old termios setting.If it’s still invalid, we try 9600 baud.

Update thetermios structure to reflect the baud ratewe’re actually going to be using. Don’t do this for the casewhere B0 is requested (“hang up”).

unsigned intuart_get_divisor(struct uart_port * port, unsigned int baud)¶

return uart clock divisor

Parameters

structuart_port*port

uart_port structure describing the port.

unsignedintbaud

desired baud rate

Calculate the uart clock divisor for the port.

voiduart_console_write(struct uart_port * port, const char * s, unsigned int count, void (*putchar)(struct uart_port *, int))¶

write a console message to a serial port

Parameters

structuart_port*port

the port to write the message

constchar*s

array of characters

unsignedintcount

number of characters in string to write

void(*)(structuart_port*,int)putchar

function to write character to port

intuart_parse_earlycon(char * p, unsigned char * iotype, resource_size_t * addr, char ** options)¶

Parse earlycon options

Parameters

char*p

ptr to 2nd field (ie., just beyond ‘<name>,’)

unsignedchar*iotype

ptr for decoded iotype (out)

resource_size_t*addr

ptr for decoded mapbase/iobase (out)

char**options

ptr for <options> field; NULL if not present (out)

Decodes earlycon kernel command line parameters of the form

earlycon=<name>,io|mmio|mmio16|mmio32|mmio32be|mmio32native,<addr>,<options>console=<name>,io|mmio|mmio16|mmio32|mmio32be|mmio32native,<addr>,<options>

The optional form

earlycon=<name>,0x<addr>,<options>console=<name>,0x<addr>,<options>

is also accepted; the returnediotype will be UPIO_MEM.

Returns 0 on success or -EINVAL on failure

voiduart_parse_options(const char * options, int * baud, int * parity, int * bits, int * flow)¶

Parse serial port baud/parity/bits/flow control.

Parameters

constchar*options

pointer to option string

int*baud

pointer to an ‘int’ variable for the baud rate.

int*parity

pointer to an ‘int’ variable for the parity.

int*bits

pointer to an ‘int’ variable for the number of data bits.

int*flow

pointer to an ‘int’ variable for the flow control character.

uart_parse_options decodes a string containing the serial consoleoptions. The format of the string is <baud><parity><bits><flow>,eg: 115200n8r

intuart_set_options(struct uart_port * port, struct console * co, int baud, int parity, int bits, int flow)¶

setup the serial console parameters

Parameters

structuart_port*port

pointer to the serial ports uart_port structure

structconsole*co

console pointer

intbaud

baud rate

intparity

parity character - ‘n’ (none), ‘o’ (odd), ‘e’ (even)

intbits

number of data bits

intflow

flow control character - ‘r’ (rts)

intuart_register_driver(struct uart_driver * drv)¶

register a driver with the uart core layer

Parameters

structuart_driver*drv

low level driver structure

Register a uart driver with the core driver. We in turn registerwith the tty layer, and initialise the core driver per-port state.

We have a proc file in /proc/tty/driver which is named after thenormal driver.

drv->port should be NULL, and the per-port structures should beregistered using uart_add_one_port after this call has succeeded.

voiduart_unregister_driver(struct uart_driver * drv)¶

remove a driver from the uart core layer

Parameters

structuart_driver*drv

low level driver structure

Remove all references to a driver from the core driver. The lowlevel driver must have removed all its ports via theuart_remove_one_port() if it registered them withuart_add_one_port().(ie, drv->port == NULL)

intuart_add_one_port(struct uart_driver * drv, struct uart_port * uport)¶

attach a driver-defined port structure

Parameters

structuart_driver*drv

pointer to the uart low level driver structure for this port

structuart_port*uport

uart port structure to use for this port.

This allows the driver to register its own uart_port structurewith the core driver. The main purpose is to allow the lowlevel uart drivers to expand uart_port, rather than having yetmore levels of structures.

intuart_remove_one_port(struct uart_driver * drv, struct uart_port * uport)¶

detach a driver defined port structure

Parameters

structuart_driver*drv

pointer to the uart low level driver structure for this port

structuart_port*uport

uart port structure for this port

This unhooks (and hangs up) the specified port structure from thecore driver. No further calls will be made to the low-level codefor this port.

voiduart_handle_dcd_change(struct uart_port * uport, unsigned int status)¶

handle a change of carrier detect state

Parameters

structuart_port*uport

uart_port structure for the open port

unsignedintstatus

new carrier detect status, nonzero if active

Caller must hold uport->lock

voiduart_handle_cts_change(struct uart_port * uport, unsigned int status)¶

handle a change of clear-to-send state

Parameters

structuart_port*uport

uart_port structure for the open port

unsignedintstatus

new clear to send status, nonzero if active

Caller must hold uport->lock

voiduart_insert_char(struct uart_port * port, unsigned int status, unsigned int overrun, unsigned int ch, unsigned int flag)¶

push a char to the uart layer

Parameters

structuart_port*port

corresponding port

unsignedintstatus

state of the serial port RX buffer (LSR for 8250)

unsignedintoverrun

mask of overrun bits instatus

unsignedintch

character to push

unsignedintflag

flag for the character (see TTY_NORMAL and friends)

Description

User is responsible to call tty_flip_buffer_push when they are done withinsertion.

booluart_try_toggle_sysrq(struct uart_port * port, unsigned int ch)¶

Enables SysRq from serial line

Parameters

structuart_port*port

uart_port structure where char(s) after BREAK met

unsignedintch

new character in the sequence after received BREAK

Enables magic SysRq when the required sequence is met on port(see CONFIG_MAGIC_SYSRQ_SERIAL_SEQUENCE).

Returns false ifch is out of enabling sequence and should behandled some other way, true ifch was consumed.

intuart_get_rs485_mode(struct uart_port * port)¶

retrieve rs485 properties for given uart

Parameters

structuart_port*port

uart device’s target port

Description

This function implements the device tree binding described inDocumentation/devicetree/bindings/serial/rs485.txt.

struct uart_8250_port *serial8250_get_port(int line)¶

retrieve struct uart_8250_port

Parameters

intline

serial line number

Description

This function retrieves struct uart_8250_port for the specific line.This structmustnot be used to perform a 8250 or serial core operationwhich is not accessible otherwise. Its only purpose is to make the structaccessible to the runtime-pm callbacks for context suspend/restore.The lock assumption made here is none because runtime-pm suspend/resumecallbacks should not be invoked if there is any operation performed on theport.

voidserial8250_suspend_port(int line)¶

suspend one serial port

Parameters

intline

serial line number

Suspend one serial port.

voidserial8250_resume_port(int line)¶

resume one serial port

Parameters

intline

serial line number

Resume one serial port.

intserial8250_register_8250_port(struct uart_8250_port * up)¶

register a serial port

Parameters

structuart_8250_port*up

serial port template

Configure the serial port specified by the request. If theport exists and is in use, it is hung up and unregisteredfirst.

The port is then probed and if necessary the IRQ is autodetectedIf this fails an error is returned.

On success the port is ready to use and the line number is returned.

voidserial8250_unregister_port(int line)¶

remove a 16x50 serial port at runtime

Parameters

intline

serial line number

Remove one serial port. This may not be called from interruptcontext. We hand the port back to the our control.

Pulse-Width Modulation (PWM)¶

Pulse-width modulation is a modulation technique primarily used tocontrol power supplied to electrical devices.

The PWM framework provides an abstraction for providers and consumers ofPWM signals. A controller that provides one or more PWM signals isregistered asstructpwm_chip. Providersare expected to embed this structure in a driver-specific structure.This structure contains fields that describe a particular chip.

A chip exposes one or more PWM signal sources, each of which exposed asastructpwm_device. Operations can beperformed on PWM devices to control the period, duty cycle, polarity andactive state of the signal.

Note that PWM devices are exclusive resources: they can always only beused by one consumer at a time.

enumpwm_polarity¶

polarity of a PWM signal

Constants

PWM_POLARITY_NORMAL

a high signal for the duration of the duty-cycle, followed by a low signal for the remainder of the pulseperiod

PWM_POLARITY_INVERSED

a low signal for the duration of the duty-cycle, followed by a high signal for the remainder of the pulseperiod

structpwm_args¶

board-dependent PWM arguments

Definition

struct pwm_args {  unsigned int period;  enum pwm_polarity polarity;};

Members

period

reference period

polarity

reference polarity

Description

This structure describes board-dependent arguments attached to a PWMdevice. These arguments are usually retrieved from the PWM lookup table ordevice tree.

Do not confuse this with the PWM state: PWM arguments represent the initialconfiguration that users want to use on this PWM device rather than thecurrent PWM hardware state.

structpwm_device¶

PWM channel object

Definition

struct pwm_device {  const char *label;  unsigned long flags;  unsigned int hwpwm;  unsigned int pwm;  struct pwm_chip *chip;  void *chip_data;  struct pwm_args args;  struct pwm_state state;  struct pwm_state last;};

Members

label

name of the PWM device

flags

flags associated with the PWM device

hwpwm

per-chip relative index of the PWM device

pwm

global index of the PWM device

chip

PWM chip providing this PWM device

chip_data

chip-private data associated with the PWM device

args

PWM arguments

state

last applied state

last

last implemented state (for PWM_DEBUG)

voidpwm_get_state(const structpwm_device * pwm, struct pwm_state * state)¶

retrieve the current PWM state

Parameters

conststructpwm_device*pwm

PWM device

structpwm_state*state

state to fill with the current PWM state

voidpwm_init_state(const structpwm_device * pwm, struct pwm_state * state)¶

prepare a new state to be applied withpwm_apply_state()

Parameters

conststructpwm_device*pwm

PWM device

structpwm_state*state

state to fill with the prepared PWM state

Description

This functions prepares a state that can later be tweaked and appliedto the PWM device withpwm_apply_state(). This is a convenient functionthat first retrieves the current PWM state and the replaces the periodand polarity fields with the reference values defined in pwm->args.Once the function returns, you can adjust the ->enabled and ->duty_cyclefields according to your needs before callingpwm_apply_state().

->duty_cycle is initially set to zero to avoid cases where the current->duty_cycle value exceed the pwm_args->period one, which would triggeran error if the user callspwm_apply_state() without adjusting ->duty_cyclefirst.

unsigned intpwm_get_relative_duty_cycle(const struct pwm_state * state, unsigned int scale)¶

Get a relative duty cycle value

Parameters

conststructpwm_state*state

PWM state to extract the duty cycle from

unsignedintscale

target scale of the relative duty cycle

Description

This functions converts the absolute duty cycle stored instate (expressedin nanosecond) into a value relative to the period.

For example if you want to get the duty_cycle expressed in percent, call:

pwm_get_state(pwm,state);duty = pwm_get_relative_duty_cycle(state, 100);

intpwm_set_relative_duty_cycle(struct pwm_state * state, unsigned int duty_cycle, unsigned int scale)¶

Set a relative duty cycle value

Parameters

structpwm_state*state

PWM state to fill

unsignedintduty_cycle

relative duty cycle value

unsignedintscale

scale in whichduty_cycle is expressed

Description

This functions converts a relative into an absolute duty cycle (expressedin nanoseconds), and puts the result in state->duty_cycle.

For example if you want to configure a 50% duty cycle, call:

pwm_init_state(pwm,state);pwm_set_relative_duty_cycle(state, 50, 100);pwm_apply_state(pwm,state);

This functions returns -EINVAL ifduty_cycle and/orscale areinconsistent (scale == 0 orduty_cycle >scale).

structpwm_ops¶

PWM controller operations

Definition

struct pwm_ops {  int (*request)(struct pwm_chip *chip, struct pwm_device *pwm);  void (*free)(struct pwm_chip *chip, struct pwm_device *pwm);  int (*capture)(struct pwm_chip *chip, struct pwm_device *pwm, struct pwm_capture *result, unsigned long timeout);  int (*apply)(struct pwm_chip *chip, struct pwm_device *pwm, const struct pwm_state *state);  void (*get_state)(struct pwm_chip *chip, struct pwm_device *pwm, struct pwm_state *state);  struct module *owner;  int (*config)(struct pwm_chip *chip, struct pwm_device *pwm, int duty_ns, int period_ns);  int (*set_polarity)(struct pwm_chip *chip, struct pwm_device *pwm, enum pwm_polarity polarity);  int (*enable)(struct pwm_chip *chip, struct pwm_device *pwm);  void (*disable)(struct pwm_chip *chip, struct pwm_device *pwm);};

Members

request

optional hook for requesting a PWM

free

optional hook for freeing a PWM

capture

capture and report PWM signal

apply

atomically apply a new PWM config

get_state

get the current PWM state. This function is onlycalled once per PWM device when the PWM chip isregistered.

owner

helps prevent removal of modules exporting active PWMs

config

configure duty cycles and period length for this PWM

set_polarity

configure the polarity of this PWM

enable

enable PWM output toggling

disable

disable PWM output toggling

structpwm_chip¶

abstract a PWM controller

Definition

struct pwm_chip {  struct device *dev;  const struct pwm_ops *ops;  int base;  unsigned int npwm;  struct pwm_device * (*of_xlate)(struct pwm_chip *pc, const struct of_phandle_args *args);  unsigned int of_pwm_n_cells;  struct list_head list;  struct pwm_device *pwms;};

Members

dev

device providing the PWMs

ops

callbacks for this PWM controller

base

number of first PWM controlled by this chip

npwm

number of PWMs controlled by this chip

of_xlate

request a PWM device given a device tree PWM specifier

of_pwm_n_cells

number of cells expected in the device tree PWM specifier

list

list node for internal use

pwms

array of PWM devices allocated by the framework

structpwm_capture¶

PWM capture data

Definition

struct pwm_capture {  unsigned int period;  unsigned int duty_cycle;};

Members

period

period of the PWM signal (in nanoseconds)

duty_cycle

duty cycle of the PWM signal (in nanoseconds)

intpwm_config(structpwm_device * pwm, int duty_ns, int period_ns)¶

change a PWM device configuration

Parameters

structpwm_device*pwm

PWM device

intduty_ns

“on” time (in nanoseconds)

intperiod_ns

duration (in nanoseconds) of one cycle

Return

0 on success or a negative error code on failure.

intpwm_enable(structpwm_device * pwm)¶

start a PWM output toggling

Parameters

structpwm_device*pwm

PWM device

Return

0 on success or a negative error code on failure.

voidpwm_disable(structpwm_device * pwm)¶

stop a PWM output toggling

Parameters

structpwm_device*pwm

PWM device

intpwm_set_chip_data(structpwm_device * pwm, void * data)¶

set private chip data for a PWM

Parameters

structpwm_device*pwm

PWM device

void*data

pointer to chip-specific data

Return

0 on success or a negative error code on failure.

void *pwm_get_chip_data(structpwm_device * pwm)¶

get private chip data for a PWM

Parameters

structpwm_device*pwm

PWM device

Return

A pointer to the chip-private data for the PWM device.

intpwmchip_add_with_polarity(structpwm_chip * chip, enumpwm_polarity polarity)¶

register a new PWM chip

Parameters

structpwm_chip*chip

the PWM chip to add

enumpwm_polaritypolarity

initial polarity of PWM channels

Description

Register a new PWM chip. If chip->base < 0 then a dynamically assigned basewill be used. The initial polarity for all channels is specified by thepolarity parameter.

Return

0 on success or a negative error code on failure.

intpwmchip_add(structpwm_chip * chip)¶

register a new PWM chip

Parameters

structpwm_chip*chip

the PWM chip to add

Description

Register a new PWM chip. If chip->base < 0 then a dynamically assigned basewill be used. The initial polarity for all channels is normal.

Return

0 on success or a negative error code on failure.

intpwmchip_remove(structpwm_chip * chip)¶

remove a PWM chip

Parameters

structpwm_chip*chip

the PWM chip to remove

Description

Removes a PWM chip. This function may return busy if the PWM chip providesa PWM device that is still requested.

Return

0 on success or a negative error code on failure.

structpwm_device *pwm_request(int pwm, const char * label)¶

request a PWM device

Parameters

intpwm

global PWM device index

constchar*label

PWM device label

Description

This function is deprecated, usepwm_get() instead.

Return

A pointer to a PWM device or an ERR_PTR()-encoded error code onfailure.

structpwm_device *pwm_request_from_chip(structpwm_chip * chip, unsigned int index, const char * label)¶

request a PWM device relative to a PWM chip

Parameters

structpwm_chip*chip

PWM chip

unsignedintindex

per-chip index of the PWM to request

constchar*label

a literal description string of this PWM

Return

A pointer to the PWM device at the given index of the given PWMchip. A negative error code is returned if the index is not valid for thespecified PWM chip or if the PWM device cannot be requested.

voidpwm_free(structpwm_device * pwm)¶

free a PWM device

Parameters

structpwm_device*pwm

PWM device

Description

This function is deprecated, usepwm_put() instead.

intpwm_apply_state(structpwm_device * pwm, const struct pwm_state * state)¶

atomically apply a new state to a PWM device

Parameters

structpwm_device*pwm

PWM device

conststructpwm_state*state

new state to apply

intpwm_capture(structpwm_device * pwm, structpwm_capture * result, unsigned long timeout)

capture and report a PWM signal

Parameters

structpwm_device*pwm

PWM device

structpwm_capture*result

structure to fill with capture result

unsignedlongtimeout

time to wait, in milliseconds, before giving up on capture

Return

0 on success or a negative error code on failure.

intpwm_adjust_config(structpwm_device * pwm)¶

adjust the current PWM config to the PWM arguments

Parameters

structpwm_device*pwm

PWM device

Description

This function will adjust the PWM config to the PWM arguments providedby the DT or PWM lookup table. This is particularly useful to adaptthe bootloader config to the Linux one.

structpwm_device *of_pwm_get(structdevice * dev, struct device_node * np, const char * con_id)¶

request a PWM via the PWM framework

Parameters

structdevice*dev

device for PWM consumer

structdevice_node*np

device node to get the PWM from

constchar*con_id

consumer name

Description

Returns the PWM device parsed from the phandle and index specified in the“pwms” property of a device tree node or a negative error-code on failure.Values parsed from the device tree are stored in the returned PWM deviceobject.

If con_id is NULL, the first PWM device listed in the “pwms” property willbe requested. Otherwise the “pwm-names” property is used to do a reverselookup of the PWM index. This also means that the “pwm-names” propertybecomes mandatory for devices that look up the PWM device via the con_idparameter.

Return

A pointer to the requested PWM device or an ERR_PTR()-encodederror code on failure.

structpwm_device *pwm_get(structdevice * dev, const char * con_id)¶

look up and request a PWM device

Parameters

structdevice*dev

device for PWM consumer

constchar*con_id

consumer name

Description

Lookup is first attempted using DT. If the device was not instantiated froma device tree, a PWM chip and a relative index is looked up via a tablesupplied by board setup code (see pwm_add_table()).

Once a PWM chip has been found the specified PWM device will be requestedand is ready to be used.

Return

A pointer to the requested PWM device or an ERR_PTR()-encodederror code on failure.

voidpwm_put(structpwm_device * pwm)¶

release a PWM device

Parameters

structpwm_device*pwm

PWM device

structpwm_device *devm_pwm_get(structdevice * dev, const char * con_id)¶

resource managedpwm_get()

Parameters

structdevice*dev

device for PWM consumer

constchar*con_id

consumer name

Description

This function performs likepwm_get() but the acquired PWM device willautomatically be released on driver detach.

Return

A pointer to the requested PWM device or an ERR_PTR()-encodederror code on failure.

structpwm_device *devm_of_pwm_get(structdevice * dev, struct device_node * np, const char * con_id)¶

resource managedof_pwm_get()

Parameters

structdevice*dev

device for PWM consumer

structdevice_node*np

device node to get the PWM from

constchar*con_id

consumer name

Description

This function performs likeof_pwm_get() but the acquired PWM device willautomatically be released on driver detach.

Return

A pointer to the requested PWM device or an ERR_PTR()-encodederror code on failure.

structpwm_device *devm_fwnode_pwm_get(structdevice * dev, struct fwnode_handle * fwnode, const char * con_id)¶

request a resource managed PWM from firmware node

Parameters

structdevice*dev

device for PWM consumer

structfwnode_handle*fwnode

firmware node to get the PWM from

constchar*con_id

consumer name

Description

Returns the PWM device parsed from the firmware node. Seeof_pwm_get() andacpi_pwm_get() for a detailed description.

Return

A pointer to the requested PWM device or an ERR_PTR()-encodederror code on failure.

voiddevm_pwm_put(structdevice * dev, structpwm_device * pwm)¶

resource managedpwm_put()

Parameters

structdevice*dev

device for PWM consumer

structpwm_device*pwm

PWM device

Description

Release a PWM previously allocated usingdevm_pwm_get(). Calling thisfunction is usually not needed because devm-allocated resources areautomatically released on driver detach.