world leader in high performance signal processing
Trace: » device-drivers

Linux Device Drivers

Driver Basics

Driver Entry and Exit points

Atomic and pointer manipulation

Delaying, scheduling, and timer routines

High-resolution timers

Workqueues and Kevents

Internal Functions

Kernel objects manipulation

Kernel utility functions

Device Resource Management

Device drivers infrastructure

Device Drivers Base

Device Drivers Power Management

Device Drivers ACPI Support

Device drivers PnP support

Userspace IO devices

Parallel Port Devices

  • parport_yield - relinquish a parallel port temporarily

Synopsis:

int parport_yield ( struct pardevice * dev )

Arguments:

  • dev - a device on the parallel port

Description:

This function relinquishes the port if it would be helpful to other drivers to do so. Afterwards it tries to reclaim the port using parport_claim, and the return value is the same as for parport_claim. If it fails, the port is left unclaimed and it is the driver's responsibility to reclaim the port.

The parport_yield and parport_yield_blocking functions are for marking points in the driver at which other drivers may claim the port and use their devices. Yielding the port is similar to releasing it and reclaiming it, but is more efficient because no action is taken if there are no other devices needing the port. In fact, nothing is done even if there are other devices waiting but the current device is still within its timeslice. The default timeslice is half a second, but it can be adjusted via the /proc interface.

  • parport_yield_blocking - relinquish a parallel port temporarily

Synopsis:

int parport_yield_blocking ( struct pardevice * dev )

Arguments:

  • dev - a device on the parallel port

Description:

This function relinquishes the port if it would be helpful to other drivers to do so. Afterwards it tries to reclaim the port using parport_claim_or_block, and the return value is the same as for parport_claim_or_block.

  • parport_wait_event - wait for an event on a parallel port

Synopsis:

int parport_wait_event ( struct parport * port )

Arguments:

  • port - port to wait on
  • timeout - time to wait (in jiffies)

Description:

This function waits for up to timeout jiffies for an interrupt to occur on a parallel port. If the port timeout is set to zero, it returns immediately.

If an interrupt occurs before the timeout period elapses, this function returns zero immediately. If it times out, it returns one. An error code less than zero indicates an error (most likely a pending signal), and the calling code should finish what it's doing as soon as it can.

  • parport_wait_peripheral - wait for status lines to change in 35ms

Synopsis:

int parport_wait_peripheral ( struct parport * port )

Arguments:

  • port - port to watch
  • mask - status lines to watch
  • result - desired values of chosen status lines

Description:

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

The port is polled quickly to start off with, in anticipation of a fast response from the peripheral. This fast polling time is configurable (using /proc), and defaults to 500usec. If the timeout for this port (see parport_set_timeout) is zero, the fast polling time is 35ms, and this function does not call schedule.

If the timeout for this port is non-zero, after the fast polling fails it uses parport_wait_event to wait for up to 10ms, waking up if an interrupt occurs.

  • parport_negotiate - negotiate an IEEE 1284 mode

Synopsis:

int parport_negotiate ( struct parport * port )

Arguments:

  • port - port to use
  • mode - mode to negotiate to

Description:

Use this to negotiate to a particular IEEE 1284 transfer mode. The mode parameter should be one of the constants in parport.h starting IEEE1284_MODE_xxx.

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

  • parport_write - write a block of data to a parallel port

Synopsis:

ssize_t parport_write ( struct parport * port )

Arguments:

  • port - port to write to
  • buffer - data buffer (in kernel space)
  • len - number of bytes of data to transfer

Description:

This will write up to len bytes of buffer to the port specified, using the IEEE 1284 transfer mode most recently negotiated to (using parport_negotiate), as long as that mode supports forward transfers (host to peripheral).

It is the caller's responsibility to ensure that the first len bytes of buffer are valid.

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

  • parport_read - read a block of data from a parallel port

Synopsis:

ssize_t parport_read ( struct parport * port )

Arguments:

  • port - port to read from
  • buffer - data buffer (in kernel space)
  • len - number of bytes of data to transfer

Description:

This will read up to len bytes of buffer to the port specified, using the IEEE 1284 transfer mode most recently negotiated to (using parport_negotiate), as long as that mode supports reverse transfers (peripheral to host).

It is the caller's responsibility to ensure that the first len bytes of buffer are available to write to.

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

  • parport_set_timeout - set the inactivity timeout for a device

Synopsis:

long parport_set_timeout ( struct pardevice * dev )

Arguments:

  • dev - device on a port
  • inactivity - inactivity timeout (in jiffies)

Description:

This sets the inactivity timeout for a particular device on a port. This affects functions like parport_wait_peripheral. The special value 0 means not to call schedule while dealing with this device.

The return value is the previous inactivity timeout.

Any callers of parport_wait_event for this device are woken up.

  • parport_register_driver - register a parallel port device driver

Synopsis:

int parport_register_driver ( struct parport_driver * drv )

Arguments:

  • drv - structure describing the driver

Description:

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

The drv structure is allocated by the caller and must not be deallocated until after calling parport_unregister_driver.

The driver's attach function may block. The port that attach is given will be valid for the duration of the callback, but if the driver wants to take a copy of the pointer it must call parport_get_port to do so. Calling parport_register_device on that port will do this for you.

The driver's detach function may block. The port that detach is given will be valid for the duration of the callback, but if the driver wants to take a copy of the pointer it must call parport_get_port to do so.

Returns 0 on success. Currently it always succeeds.

  • parport_unregister_driver - deregister a parallel port device driver

Synopsis:

void parport_unregister_driver ( struct parport_driver * drv )

Arguments:

  • drv - structure describing the driver that was given to parport_register_driver

Description:

This should be called by a parallel port device driver that has registered itself using parport_register_driver when it is about to be unloaded.

When it returns, the driver's attach routine will no longer be called, and for each port that attach was called for, the detach routine will have been called.

All the driver's attach and detach calls are guaranteed to have finished by the time this function returns.

  • parport_get_port - increment a port's reference count

Synopsis:

struct parport * parport_get_port ( struct parport * port )

Arguments:

  • port - the port

Description:

This ensures that a struct parport pointer remains valid until the matching parport_put_port call.

  • parport_put_port - decrement a port's reference count

Synopsis:

void parport_put_port ( struct parport * port )

Arguments:

  • port - the port

Description:

This should be called once for each call to parport_get_port, once the port is no longer needed.

  • parport_register_port - register a parallel port

Synopsis:

struct parport * parport_register_port ( unsigned long base )

Arguments:

  • base - base I/O address
  • irq - IRQ line
  • dma - DMA channel
  • ops - pointer to the port driver's port operations structure

Description:

When a parallel port (lowlevel) driver finds a port that should be made available to parallel port device drivers, it should call parport_register_port. The base, irq, and dma parameters are for the convenience of port drivers, and for ports where they aren't meaningful needn't be set to anything special. They can be altered afterwards by adjusting the relevant members of the parport structure that is returned and represents the port. They should not be tampered with after calling parport_announce_port, however.

If there are parallel port device drivers in the system that have registered themselves using parport_register_driver, they are not told about the port at this time; that is done by parport_announce_port.

The ops structure is allocated by the caller, and must not be deallocated before calling parport_remove_port.

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

  • parport_announce_port - tell device drivers about a parallel port

Synopsis:

void parport_announce_port ( struct parport * port )

Arguments:

  • port - parallel port to announce

Description:

After a port driver has registered a parallel port with parport_register_port, and performed any necessary initialisation or adjustments, it should call parport_announce_port in order to notify all device drivers that have called parport_register_driver. Their attach functions will be called, with port as the parameter.

  • parport_remove_port - deregister a parallel port

Synopsis:

void parport_remove_port ( struct parport * port )

Arguments:

  • port - parallel port to deregister

Description:

When a parallel port driver is forcibly unloaded, or a parallel port becomes inaccessible, the port driver must call this function in order to deal with device drivers that still want to use it.

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

Any drivers that have registered themselves using parport_register_driver are notified that the port is no longer accessible by having their detach routines called with port as the parameter.

  • parport_register_device - register a device on a parallel port

Synopsis:

struct pardevice * parport_register_device ( struct parport * port )

Arguments:

  • port - port to which the device is attached
  • name - a name to refer to the device
  • pf - preemption callback
  • kf - kick callback (wake-up)
  • irq_func - interrupt handler
  • flags - registration flags
  • handle - data for callback functions

Description:

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

The name is allocated by the caller and must not be deallocated until the caller calls parport_unregister_device for that device.

The preemption callback function, pf, is called when this device driver has claimed access to the port but another device driver wants to use it. It is given handle as its parameter, and should return zero if it is willing for the system to release the port to another driver on its behalf. If it wants to keep control of the 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 at the earliest opportunity after its preemption callback rejects a preemption attempt. Note that if a preemption callback is happy for preemption to go ahead, there is no need to release the port; it is done automatically. This function may not block, as it may be called from interrupt context. If the device driver does not support preemption, pf can be NULL.

The wake-up (kick) callback function, kf, is called when the port is available to be claimed for exclusive access; that is, parport_claim is guaranteed to succeed when called from inside the wake-up callback function. If the driver wants to claim the port it should do so; otherwise, it need not take any action. This function may not block, as it may be called from interrupt context. If the device driver does not want to be explicitly invited to claim the port in this way, kf can be NULL.

The interrupt handler, irq_func, is called when an interrupt arrives from the parallel port. Note that if a device driver wants to use interrupts it should use parport_enable_irq, and can also check the irq member of the parport structure representing the port.

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

The PARPORT_DEV_EXCL flag is for preventing port sharing, and so should only be used when sharing the port with other device drivers 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 represents the device on the port, or NULL if there is not enough memory to allocate space for that structure.

  • parport_unregister_device - deregister a device on a parallel port

Synopsis:

void parport_unregister_device ( struct pardevice * dev )

Arguments:

  • dev - pointer to structure representing device

Description:

This undoes the effect of parport_register_device.

  • parport_find_number - find a parallel port by number

Synopsis:

struct parport * parport_find_number ( int number )

Arguments:

  • number - parallel port number

Description:

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

There is an implicit parport_get_port done already; to throw away the reference to the port that parport_find_number gives you, use parport_put_port.

  • parport_find_base - find a parallel port by base address

Synopsis:

struct parport * parport_find_base ( unsigned long base )

Arguments:

  • base - base I/O address

Description:

This returns the parallel port with the specified base address, or NULL if there is none.

There is an implicit parport_get_port done already; to throw away the reference to the port that parport_find_base gives you, use parport_put_port.

  • parport_claim - claim access to a parallel port device

Synopsis:

int parport_claim ( struct pardevice * dev )

Arguments:

  • dev - pointer to structure representing a device on the port

Description:

This function will not block and so can be used from interrupt context. If parport_claim succeeds in claiming access to the port it returns zero and the port is available to use. It may fail (returning non-zero) if the port is in use by another driver and that driver is not willing to relinquish control of the port.

  • parport_claim_or_block - claim access to a parallel port device

Synopsis:

int parport_claim_or_block ( struct pardevice * dev )

Arguments:

  • dev - pointer to structure representing a device on the port

Description:

This behaves like parport_claim, but will block if necessary to wait for the port to be free. A return value of 1 indicates that it slept; 0 means that it succeeded without needing to sleep. A negative error code indicates failure.

  • parport_release - give up access to a parallel port device

Synopsis:

void parport_release ( struct pardevice * dev )

Arguments:

  • dev - pointer to structure representing parallel port device

Description:

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

  • parport_open - find a device by canonical device number

Synopsis:

struct pardevice * parport_open ( int devnum )

Arguments:

  • devnum - canonical device number
  • name - name to associate with the device

Description:

This function is similar to parport_register_device, except that it locates a device by its number rather than by the port it is attached to.

All parameters except for devnum are the same as for parport_register_device. The return value is the same as for parport_register_device.

  • parport_close - close a device opened with parport_open

Synopsis:

void parport_close ( struct pardevice * dev )

Arguments:

  • dev - device to close

Description:

This is to parport_open as parport_unregister_device is to parport_register_device.

Message-based devices

Fusion message devices

I2O message devices

Sound Devices

  • snd_register_device - Register the ALSA device file for the card

Synopsis:

int snd_register_device ( int type )

Arguments:

  • type - the device type, SNDRV_DEVICE_TYPE_XXX
  • card - the card instance
  • dev - the device index
  • f_ops - the file operations
  • private_data - user pointer for f_ops→open
  • name - the device file name

Description:

Registers an ALSA device file for the given card. The operators have to be set in reg parameter.

This function uses the card's device pointer to link to the correct struct device.

Returns zero if successful, or a negative error code on failure.

  • snd_printk - printk wrapper

Synopsis:

snd_printk ( fmt )

Arguments:

  • fmt - format string
  • args… - variable arguments

Description:

Works like printk but prints the file and the line of the caller when configured with CONFIG_SND_VERBOSE_PRINTK.

  • snd_printd - debug printk

Synopsis:

snd_printd ( fmt )

Arguments:

  • fmt - format string
  • args… - variable arguments

Description:

Works like snd_printk for debugging purposes. Ignored when CONFIG_SND_DEBUG is not set.

  • snd_BUG - give a BUG warning message and stack trace

Synopsis:

snd_BUG (  )

Arguments:

None

Description:

Calls WARN if CONFIG_SND_DEBUG is set. Ignored when CONFIG_SND_DEBUG is not set.

  • snd_BUG_ON - debugging check macro

Synopsis:

snd_BUG_ON ( cond )

Arguments:

  • cond - condition to evaluate

Description:

When CONFIG_SND_DEBUG is set, this macro evaluates the given condition, and call WARN and returns the value if it's non-zero.

When CONFIG_SND_DEBUG is not set, this just returns zero, and the given condition is ignored.

NOTE:

the argument won't be evaluated at all when CONFIG_SND_DEBUG=n. Thus, don't put any statement that influences on the code behavior, such as pre/post increment, to the argument of this macro. If you want to evaluate and give a warning, use standard WARN_ON.

  • snd_printdd - debug printk

Synopsis:

snd_printdd ( format )

Arguments:

  • format - format string
  • args… - variable arguments

Description:

Works like snd_printk for debugging purposes. Ignored when CONFIG_SND_DEBUG_VERBOSE is not set.

  • register_sound_special_device - register a special sound node

Synopsis:

int register_sound_special_device ( const struct file_operations * fops )

Arguments:

  • fops - File operations for the driver
  • unit - Unit number to allocate
  • dev - device pointer

Description:

Allocate a special sound device by minor number from the sound subsystem. The allocated number is returned on success. On failure a negative error code is returned.

  • register_sound_mixer - register a mixer device

Synopsis:

int register_sound_mixer ( const struct file_operations * fops )

Arguments:

  • fops - File operations for the driver
  • dev - Unit number to allocate

Description:

Allocate a mixer device. Unit is the number of the mixer requested. Pass -1 to request the next free mixer unit. On success the allocated number is returned, on failure a negative error code is returned.

  • register_sound_midi - register a midi device

Synopsis:

int register_sound_midi ( const struct file_operations * fops )

Arguments:

  • fops - File operations for the driver
  • dev - Unit number to allocate

Description:

Allocate a midi device. Unit is the number of the midi device requested. Pass -1 to request the next free midi unit. On success the allocated number is returned, on failure a negative error code is returned.

  • register_sound_dsp - register a DSP device

Synopsis:

int register_sound_dsp ( const struct file_operations * fops )

Arguments:

  • fops - File operations for the driver
  • dev - Unit number to allocate

Description:

Allocate a DSP device. Unit is the number of the DSP requested. Pass -1 to request the next free DSP unit. On success the allocated number is returned, on failure a negative error code is returned.

This function allocates both the audio and dsp device entries together and will always allocate them as a matching pair - eg dsp3/audio3

  • unregister_sound_special - unregister a special sound device

Synopsis:

void unregister_sound_special ( int unit )

Arguments:

  • unit - unit number to allocate

Description:

Release a sound device that was allocated with register_sound_special. The unit passed is the return value from the register function.

  • unregister_sound_mixer - unregister a mixer

Synopsis:

void unregister_sound_mixer ( int unit )

Arguments:

  • unit - unit number to allocate

Description:

Release a sound device that was allocated with register_sound_mixer. The unit passed is the return value from the register function.

  • unregister_sound_midi - unregister a midi device

Synopsis:

void unregister_sound_midi ( int unit )

Arguments:

  • unit - unit number to allocate

Description:

Release a sound device that was allocated with register_sound_midi. The unit passed is the return value from the register function.

  • unregister_sound_dsp - unregister a DSP device

Synopsis:

void unregister_sound_dsp ( int unit )

Arguments:

  • unit - unit number to allocate

Description:

Release a sound device that was allocated with register_sound_dsp. The unit passed is the return value from the register function.

Both of the allocated units are released together automatically.

  • snd_pcm_playback_ready - check whether the playback buffer is available

Synopsis:

int snd_pcm_playback_ready ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance

Description:

Checks whether enough free space is available on the playback buffer.

Returns non-zero if available, or zero if not.

  • snd_pcm_capture_ready - check whether the capture buffer is available

Synopsis:

int snd_pcm_capture_ready ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance

Description:

Checks whether enough capture data is available on the capture buffer.

Returns non-zero if available, or zero if not.

  • snd_pcm_playback_data - check whether any data exists on the playback buffer

Synopsis:

int snd_pcm_playback_data ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance

Description:

Checks whether any data exists on the playback buffer. If stop_threshold is bigger or equal to boundary, then this function returns always non-zero.

Returns non-zero if exists, or zero if not.

  • snd_pcm_playback_empty - check whether the playback buffer is empty

Synopsis:

int snd_pcm_playback_empty ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance

Description:

Checks whether the playback buffer is empty.

Returns non-zero if empty, or zero if not.

  • snd_pcm_capture_empty - check whether the capture buffer is empty

Synopsis:

int snd_pcm_capture_empty ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance

Description:

Checks whether the capture buffer is empty.

Returns non-zero if empty, or zero if not.

  • snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian

Synopsis:

int snd_pcm_format_cpu_endian ( snd_pcm_format_t format )

Arguments:

  • format - the format to check

Description:

Returns 1 if the given PCM format is CPU-endian, 0 if opposite, or a negative error code if endian not specified.

  • snd_pcm_new_stream - create a new PCM stream

Synopsis:

int snd_pcm_new_stream ( struct snd_pcm * pcm )

Arguments:

  • pcm - the pcm instance
  • stream - the stream direction, SNDRV_PCM_STREAM_XXX
  • substream_count - the number of substreams

Description:

Creates a new stream for the pcm. The corresponding stream on the pcm must have been empty before calling this, i.e. zero must be given to the argument of snd_pcm_new.

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_new - create a new PCM instance

Synopsis:

int snd_pcm_new ( struct snd_card * card )

Arguments:

  • card - the card instance
  • id - the id string
  • device - the device index (zero based)
  • playback_count - the number of substreams for playback
  • capture_count - the number of substreams for capture
  • rpcm - the pointer to store the new pcm instance

Description:

Creates a new PCM instance.

The pcm operators have to be set afterwards to the new instance via snd_pcm_set_ops.

Returns zero if successful, or a negative error code on failure.

  • snd_device_new - create an ALSA device component

Synopsis:

int snd_device_new ( struct snd_card * card )

Arguments:

  • card - the card instance
  • type - the device type, SNDRV_DEV_XXX
  • device_data - the data pointer of this device
  • ops - the operator table

Description:

Creates a new device component for the given data pointer. The device will be assigned to the card and managed together by the card.

The data pointer plays a role as the identifier, too, so the pointer address must be unique and unchanged.

Returns zero if successful, or a negative error code on failure.

  • snd_device_free - release the device from the card

Synopsis:

int snd_device_free ( struct snd_card * card )

Arguments:

  • card - the card instance
  • device_data - the data pointer to release

Description:

Removes the device from the list on the card and invokes the callbacks, dev_disconnect and dev_free, corresponding to the state. Then release the device.

Returns zero if successful, or a negative error code on failure or if the device not found.

  • snd_device_register - register the device

Synopsis:

int snd_device_register ( struct snd_card * card )

Arguments:

  • card - the card instance
  • device_data - the data pointer to register

Description:

Registers the device which was already created via snd_device_new. Usually this is called from snd_card_register, but it can be called later if any new devices are created after invocation of snd_card_register.

Returns zero if successful, or a negative error code on failure or if the device not found.

  • snd_iprintf - printf on the procfs buffer

Synopsis:

int snd_iprintf ( struct snd_info_buffer * buffer )

Arguments:

  • buffer - the procfs buffer
  • fmt - the printf format
  • - variable arguments

Description:

Outputs the string on the procfs buffer just like printf.

Returns the size of output string.

  • snd_info_get_line - read one line from the procfs buffer

Synopsis:

int snd_info_get_line ( struct snd_info_buffer * buffer )

Arguments:

  • buffer - the procfs buffer
  • line - the buffer to store
  • len - the max. buffer size - 1

Description:

Reads one line from the buffer and stores the string.

Returns zero if successful, or 1 if error or EOF.

  • snd_info_get_str - parse a string token

Synopsis:

const char * snd_info_get_str ( char * dest )

Arguments:

  • dest - the buffer to store the string token
  • src - the original string
  • len - the max. length of token - 1

Description:

Parses the original string and copy a token to the given string buffer.

Returns the updated pointer of the original string so that it can be used for the next call.

  • snd_info_create_module_entry - create an info entry for the given module

Synopsis:

struct snd_info_entry * snd_info_create_module_entry ( struct module * module )

Arguments:

  • module - the module pointer
  • name - the file name
  • parent - the parent directory

Description:

Creates a new info entry and assigns it to the given module.

Returns the pointer of the new instance, or NULL on failure.

  • snd_info_create_card_entry - create an info entry for the given card

Synopsis:

struct snd_info_entry * snd_info_create_card_entry ( struct snd_card * card )

Arguments:

  • card - the card instance
  • name - the file name
  • parent - the parent directory

Description:

Creates a new info entry and assigns it to the given card.

Returns the pointer of the new instance, or NULL on failure.

  • snd_card_proc_new - create an info entry for the given card

Synopsis:

int snd_card_proc_new ( struct snd_card * card )

Arguments:

  • card - the card instance
  • name - the file name
  • entryp - the pointer to store the new info entry

Description:

Creates a new info entry and assigns it to the given card. Unlike snd_info_create_card_entry, this function registers the info entry as an ALSA device component, so that it can be unregistered/released without explicit call. Also, you don't have to register this entry via snd_info_register, since this will be registered by snd_card_register automatically.

The parent is assumed as card→proc_root.

For releasing this entry, use snd_device_free instead of snd_info_free_entry.

Returns zero if successful, or a negative error code on failure.

  • snd_info_free_entry - release the info entry

Synopsis:

void snd_info_free_entry ( struct snd_info_entry * entry )

Arguments:

  • entry - the info entry

Description:

Releases the info entry. Don't call this after registered.

  • snd_info_register - register the info entry

Synopsis:

int snd_info_register ( struct snd_info_entry * entry )

Arguments:

  • entry - the info entry

Description:

Registers the proc info entry.

Returns zero if successful, or a negative error code on failure.

  • snd_rawmidi_receive - receive the input data from the device

Synopsis:

int snd_rawmidi_receive ( struct snd_rawmidi_substream * substream )

Arguments:

  • substream - the rawmidi substream
  • buffer - the buffer pointer
  • count - the data size to read

Description:

Reads the data from the internal buffer.

Returns the size of read data, or a negative error code on failure.

  • snd_rawmidi_transmit_empty - check whether the output buffer is empty

Synopsis:

int snd_rawmidi_transmit_empty ( struct snd_rawmidi_substream * substream )

Arguments:

  • substream - the rawmidi substream

Description:

Returns 1 if the internal output buffer is empty, 0 if not.

  • snd_rawmidi_transmit_peek - copy data from the internal buffer

Synopsis:

int snd_rawmidi_transmit_peek ( struct snd_rawmidi_substream * substream )

Arguments:

  • substream - the rawmidi substream
  • buffer - the buffer pointer
  • count - data size to transfer

Description:

Copies data from the internal output buffer to the given buffer.

Call this in the interrupt handler when the midi output is ready, and call snd_rawmidi_transmit_ack after the transmission is finished.

Returns the size of copied data, or a negative error code on failure.

  • snd_rawmidi_transmit_ack - acknowledge the transmission

Synopsis:

int snd_rawmidi_transmit_ack ( struct snd_rawmidi_substream * substream )

Arguments:

  • substream - the rawmidi substream
  • count - the tranferred count

Description:

Advances the hardware pointer for the internal output buffer with the given size and updates the condition. Call after the transmission is finished.

Returns the advanced size if successful, or a negative error code on failure.

  • snd_rawmidi_transmit - copy from the buffer to the device

Synopsis:

int snd_rawmidi_transmit ( struct snd_rawmidi_substream * substream )

Arguments:

  • substream - the rawmidi substream
  • buffer - the buffer pointer
  • count - the data size to transfer

Description:

Copies data from the buffer to the device and advances the pointer.

Returns the copied size if successful, or a negative error code on failure.

  • snd_rawmidi_new - create a rawmidi instance

Synopsis:

int snd_rawmidi_new ( struct snd_card * card )

Arguments:

  • card - the card instance
  • id - the id string
  • device - the device index
  • output_count - the number of output streams
  • input_count - the number of input streams
  • rrawmidi - the pointer to store the new rawmidi instance

Description:

Creates a new rawmidi instance. Use snd_rawmidi_set_ops to set the operators to the new instance.

Returns zero if successful, or a negative error code on failure.

  • snd_rawmidi_set_ops - set the rawmidi operators

Synopsis:

void snd_rawmidi_set_ops ( struct snd_rawmidi * rmidi )

Arguments:

  • rmidi - the rawmidi instance
  • stream - the stream direction, SNDRV_RAWMIDI_STREAM_XXX
  • ops - the operator table

Description:

Sets the rawmidi operators for the given stream direction.

  • snd_request_card - try to load the card module

Synopsis:

void snd_request_card ( int card )

Arguments:

  • card - the card number

Description:

Tries to load the module snd-card-X for the given card number via request_module. Returns immediately if already loaded.

  • snd_lookup_minor_data - get user data of a registered device

Synopsis:

void * snd_lookup_minor_data ( unsigned int minor )

Arguments:

  • minor - the minor number
  • type - device type (SNDRV_DEVICE_TYPE_XXX)

Description:

Checks that a minor device with the specified type is registered, and returns its user data pointer.

  • snd_register_device_for_dev - Register the ALSA device file for the card

Synopsis:

int snd_register_device_for_dev ( int type )

Arguments:

  • type - the device type, SNDRV_DEVICE_TYPE_XXX
  • card - the card instance
  • dev - the device index
  • f_ops - the file operations
  • private_data - user pointer for f_ops→open
  • name - the device file name
  • device - the struct device to link this new device to

Description:

Registers an ALSA device file for the given card. The operators have to be set in reg parameter.

Returns zero if successful, or a negative error code on failure.

  • snd_unregister_device - unregister the device on the given card

Synopsis:

int snd_unregister_device ( int type )

Arguments:

  • type - the device type, SNDRV_DEVICE_TYPE_XXX
  • card - the card instance
  • dev - the device index

Description:

Unregisters the device file already registered via snd_register_device.

Returns zero if sucecessful, or a negative error code on failure

  • copy_to_user_fromio - copy data from mmio-space to user-space

Synopsis:

int copy_to_user_fromio ( void __user * dst )

Arguments:

  • dst - the destination pointer on user-space
  • src - the source pointer on mmio
  • count - the data size to copy in bytes

Description:

Copies the data from mmio-space to user-space.

Returns zero if successful, or non-zero on failure.

  • copy_from_user_toio - copy data from user-space to mmio-space

Synopsis:

int copy_from_user_toio ( volatile void __iomem * dst )

Arguments:

  • dst - the destination pointer on mmio-space
  • src - the source pointer on user-space
  • count - the data size to copy in bytes

Description:

Copies the data from user-space to mmio-space.

Returns zero if successful, or non-zero on failure.

  • snd_pcm_lib_preallocate_free_for_all - release all pre-allocated buffers on the pcm

Synopsis:

int snd_pcm_lib_preallocate_free_for_all ( struct snd_pcm * pcm )

Arguments:

  • pcm - the pcm instance

Description:

Releases all the pre-allocated buffers on the given pcm.

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_lib_preallocate_pages - pre-allocation for the given DMA type

Synopsis:

int snd_pcm_lib_preallocate_pages ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance
  • type - DMA type (SNDRV_DMA_TYPE_*)
  • data - DMA type dependant data
  • size - the requested pre-allocation size in bytes
  • max - the max. allowed pre-allocation size

Description:

Do pre-allocation for the given DMA buffer type.

When substream→dma_buf_id is set, the function tries to look for the reserved buffer, and the buffer is not freed but reserved at destruction time. The dma_buf_id must be unique for all systems (in the same DMA buffer type) e.g. using snd_dma_pci_buf_id.

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_lib_preallocate_pages_for_all - pre-allocation for continous memory type (all substreams)

Synopsis:

int snd_pcm_lib_preallocate_pages_for_all ( struct snd_pcm * pcm )

Arguments:

  • pcm - the pcm instance
  • type - DMA type (SNDRV_DMA_TYPE_*)
  • data - DMA type dependant data
  • size - the requested pre-allocation size in bytes
  • max - the max. allowed pre-allocation size

Description:

Do pre-allocation to all substreams of the given pcm for the specified DMA type.

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_sgbuf_ops_page - get the page struct at the given offset

Synopsis:

struct page * snd_pcm_sgbuf_ops_page ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance
  • offset - the buffer offset

Description:

Returns the page struct at the given buffer offset. Used as the page callback of PCM ops.

  • snd_pcm_lib_malloc_pages - allocate the DMA buffer

Synopsis:

int snd_pcm_lib_malloc_pages ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the substream to allocate the DMA buffer to
  • size - the requested buffer size in bytes

Description:

Allocates the DMA buffer on the BUS type given earlier to snd_pcm_lib_preallocate_xxx_pages.

Returns 1 if the buffer is changed, 0 if not changed, or a negative code on failure.

  • snd_pcm_lib_free_pages - release the allocated DMA buffer.

Synopsis:

int snd_pcm_lib_free_pages ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the substream to release the DMA buffer

Description:

Releases the DMA buffer allocated via snd_pcm_lib_malloc_pages.

Returns zero if successful, or a negative error code on failure.

  • snd_card_create - create and initialize a soundcard structure

Synopsis:

int snd_card_create ( int idx )

Arguments:

  • idx - card index (address) [0 … (SNDRV_CARDS-1)]
  • xid - card identification (ASCII string)
  • module - top level module for locking
  • extra_size - allocate this extra size after the main soundcard structure
  • card_ret - the pointer to store the created card instance

Description:

Creates and initializes a soundcard structure.

The function allocates snd_card instance via kzalloc with the given space for the driver to use freely. The allocated struct is stored in the given card_ret pointer.

Returns zero if successful or a negative error code.

  • snd_card_disconnect - disconnect all APIs from the file-operations (user space)

Synopsis:

int snd_card_disconnect ( struct snd_card * card )

Arguments:

  • card - soundcard structure

Description:

Disconnects all APIs from the file-operations (user space).

Returns zero, otherwise a negative error code.

Note:

The current implementation replaces all active file→f_op with special dummy file operations (they do nothing except release).

  • snd_card_set_id - set card identification name

Synopsis:

void snd_card_set_id ( struct snd_card * card )

Arguments:

  • card - soundcard structure
  • nid - new identification string

Description:

This function sets the card identification and checks for name collisions.

  • snd_card_register - register the soundcard

Synopsis:

int snd_card_register ( struct snd_card * card )

Arguments:

  • card - soundcard structure

Description:

This function registers all the devices assigned to the soundcard. Until calling this, the ALSA control interface is blocked from the external accesses. Thus, you should call this function at the end of the initialization of the card.

Returns zero otherwise a negative error code if the registrain failed.

  • snd_component_add - add a component string

Synopsis:

int snd_component_add ( struct snd_card * card )

Arguments:

  • card - soundcard structure
  • component - the component id string

Description:

This function adds the component id string to the supported list. The component can be referred from the alsa-lib.

Returns zero otherwise a negative error code.

  • snd_card_file_add - add the file to the file list of the card

Synopsis:

int snd_card_file_add ( struct snd_card * card )

Arguments:

  • card - soundcard structure
  • file - file pointer

Description:

This function adds the file to the file linked-list of the card. This linked-list is used to keep tracking the connection state, and to avoid the release of busy resources by hotplug.

Returns zero or a negative error code.

  • snd_card_file_remove - remove the file from the file list

Synopsis:

int snd_card_file_remove ( struct snd_card * card )

Arguments:

  • card - soundcard structure
  • file - file pointer

Description:

This function removes the file formerly added to the card via snd_card_file_add function. If all files are removed and snd_card_free_when_closed was called beforehand, it processes the pending release of resources.

Returns zero or a negative error code.

  • snd_power_wait - wait until the power-state is changed.

Synopsis:

int snd_power_wait ( struct snd_card * card )

Arguments:

  • card - soundcard structure
  • power_state - expected power state

Description:

Waits until the power-state is changed.

Note:

the power lock must be active before call.

  • snd_dma_program - program an ISA DMA transfer

Synopsis:

void snd_dma_program ( unsigned long dma )

Arguments:

  • dma - the dma number
  • addr - the physical address of the buffer
  • size - the DMA transfer size
  • mode - the DMA transfer mode, DMA_MODE_XXX

Description:

Programs an ISA DMA transfer for the given buffer.

  • snd_dma_disable - stop the ISA DMA transfer

Synopsis:

void snd_dma_disable ( unsigned long dma )

Arguments:

  • dma - the dma number

Description:

Stops the ISA DMA transfer.

  • snd_dma_pointer - return the current pointer to DMA transfer buffer in bytes

Synopsis:

unsigned int snd_dma_pointer ( unsigned long dma )

Arguments:

  • dma - the dma number
  • size - the dma transfer size

Description:

Returns the current pointer in DMA tranfer buffer in bytes

  • snd_ctl_new1 - create a control instance from the template

Synopsis:

struct snd_kcontrol * snd_ctl_new1 ( const struct snd_kcontrol_new * ncontrol )

Arguments:

  • ncontrol - the initialization record
  • private_data - the private data to set

Description:

Allocates a new struct snd_kcontrol instance and initialize from the given template. When the access field of ncontrol is 0, it's assumed as READWRITE access. When the count field is 0, it's assumes as one.

Returns the pointer of the newly generated instance, or NULL on failure.

  • snd_ctl_free_one - release the control instance

Synopsis:

void snd_ctl_free_one ( struct snd_kcontrol * kcontrol )

Arguments:

  • kcontrol - the control instance

Description:

Releases the control instance created via snd_ctl_new or snd_ctl_new1. Don't call this after the control was added to the card.

  • snd_ctl_add - add the control instance to the card

Synopsis:

int snd_ctl_add ( struct snd_card * card )

Arguments:

  • card - the card instance
  • kcontrol - the control instance to add

Description:

Adds the control instance created via snd_ctl_new or snd_ctl_new1 to the given card. Assigns also an unique numid used for fast search.

Returns zero if successful, or a negative error code on failure.

It frees automatically the control which cannot be added.

  • snd_ctl_remove - remove the control from the card and release it

Synopsis:

int snd_ctl_remove ( struct snd_card * card )

Arguments:

  • card - the card instance
  • kcontrol - the control instance to remove

Description:

Removes the control from the card and then releases the instance. You don't need to call snd_ctl_free_one. You must be in the write lock - down_write(card→controls_rwsem).

Returns 0 if successful, or a negative error code on failure.

  • snd_ctl_remove_id - remove the control of the given id and release it

Synopsis:

int snd_ctl_remove_id ( struct snd_card * card )

Arguments:

  • card - the card instance
  • id - the control id to remove

Description:

Finds the control instance with the given id, removes it from the card list and releases it.

Returns 0 if successful, or a negative error code on failure.

  • snd_ctl_rename_id - replace the id of a control on the card

Synopsis:

int snd_ctl_rename_id ( struct snd_card * card )

Arguments:

  • card - the card instance
  • src_id - the old id
  • dst_id - the new id

Description:

Finds the control with the old id from the card, and replaces the id with the new one.

Returns zero if successful, or a negative error code on failure.

  • snd_ctl_find_numid - find the control instance with the given number-id

Synopsis:

struct snd_kcontrol * snd_ctl_find_numid ( struct snd_card * card )

Arguments:

  • card - the card instance
  • numid - the number-id to search

Description:

Finds the control instance with the given number-id from the card.

Returns the pointer of the instance if found, or NULL if not.

The caller must down card→controls_rwsem before calling this function (if the race condition can happen).

  • snd_ctl_find_id - find the control instance with the given id

Synopsis:

struct snd_kcontrol * snd_ctl_find_id ( struct snd_card * card )

Arguments:

  • card - the card instance
  • id - the id to search

Description:

Finds the control instance with the given id from the card.

Returns the pointer of the instance if found, or NULL if not.

The caller must down card→controls_rwsem before calling this function (if the race condition can happen).

  • snd_pcm_set_ops - set the PCM operators

Synopsis:

void snd_pcm_set_ops ( struct snd_pcm * pcm )

Arguments:

  • pcm - the pcm instance
  • direction - stream direction, SNDRV_PCM_STREAM_XXX
  • ops - the operator table

Description:

Sets the given PCM operators to the pcm instance.

  • snd_pcm_set_sync - set the PCM sync id

Synopsis:

void snd_pcm_set_sync ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream

Description:

Sets the PCM sync identifier for the card.

  • snd_interval_refine - refine the interval value of configurator

Synopsis:

int snd_interval_refine ( struct snd_interval * i )

Arguments:

  • i - the interval value to refine
  • v - the interval value to refer to

Description:

Refines the interval value with the reference value. The interval is changed to the range satisfying both intervals. The interval status (min, max, integer, etc.) are evaluated.

Returns non-zero if the value is changed, zero if not changed.

  • snd_interval_ratnum - refine the interval value

Synopsis:

int snd_interval_ratnum ( struct snd_interval * i )

Arguments:

  • i - interval to refine
  • rats_count - number of ratnum_t
  • rats - ratnum_t array
  • nump - pointer to store the resultant numerator
  • denp - pointer to store the resultant denominator

Description:

Returns non-zero if the value is changed, zero if not changed.

  • snd_interval_list - refine the interval value from the list

Synopsis:

int snd_interval_list ( struct snd_interval * i )

Arguments:

  • i - the interval value to refine
  • count - the number of elements in the list
  • list - the value list
  • mask - the bit-mask to evaluate

Description:

Refines the interval value from the list. When mask is non-zero, only the elements corresponding to bit 1 are evaluated.

Returns non-zero if the value is changed, zero if not changed.

  • snd_pcm_hw_rule_add - add the hw-constraint rule

Synopsis:

int snd_pcm_hw_rule_add ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - the pcm runtime instance
  • cond - condition bits
  • var - the variable to evaluate
  • func - the evaluation function
  • private - the private data pointer passed to function
  • dep - the dependent variables
  • - variable arguments

Description:

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_hw_constraint_integer - apply an integer constraint to an interval

Synopsis:

int snd_pcm_hw_constraint_integer ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • var - hw_params variable to apply the integer constraint

Description:

Apply the constraint of integer to an interval parameter.

  • snd_pcm_hw_constraint_minmax - apply a min/max range constraint to an interval

Synopsis:

int snd_pcm_hw_constraint_minmax ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • var - hw_params variable to apply the range
  • min - the minimal value
  • max - the maximal value

Description:

Apply the min/max range constraint to an interval parameter.

  • snd_pcm_hw_constraint_list - apply a list of constraints to a parameter

Synopsis:

int snd_pcm_hw_constraint_list ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • cond - condition bits
  • var - hw_params variable to apply the list constraint
  • l - list

Description:

Apply the list of constraints to an interval parameter.

  • snd_pcm_hw_constraint_ratnums - apply ratnums constraint to a parameter

Synopsis:

int snd_pcm_hw_constraint_ratnums ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • cond - condition bits
  • var - hw_params variable to apply the ratnums constraint
  • r - struct snd_ratnums constriants
  • snd_pcm_hw_constraint_ratdens - apply ratdens constraint to a parameter

Synopsis:

int snd_pcm_hw_constraint_ratdens ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • cond - condition bits
  • var - hw_params variable to apply the ratdens constraint
  • r - struct snd_ratdens constriants
  • snd_pcm_hw_constraint_msbits - add a hw constraint msbits rule

Synopsis:

int snd_pcm_hw_constraint_msbits ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • cond - condition bits
  • width - sample bits width
  • msbits - msbits width
  • snd_pcm_hw_constraint_step - add a hw constraint step rule

Synopsis:

int snd_pcm_hw_constraint_step ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • cond - condition bits
  • var - hw_params variable to apply the step constraint
  • step - step size
  • snd_pcm_hw_constraint_pow2 - add a hw constraint power-of-2 rule

Synopsis:

int snd_pcm_hw_constraint_pow2 ( struct snd_pcm_runtime * runtime )

Arguments:

  • runtime - PCM runtime instance
  • cond - condition bits
  • var - hw_params variable to apply the power-of-2 constraint
  • snd_pcm_hw_param_value - return params field var value

Synopsis:

int snd_pcm_hw_param_value ( const struct snd_pcm_hw_params * params )

Arguments:

  • params - the hw_params instance
  • var - parameter to retrieve
  • dir - pointer to the direction (-1,0,1) or NULL

Description:

Return the value for field var if it's fixed in configuration space defined by params. Return -EINVAL otherwise.

  • snd_pcm_hw_param_first - refine config space and return minimum value

Synopsis:

int snd_pcm_hw_param_first ( struct snd_pcm_substream * pcm )

Arguments:

  • pcm - PCM instance
  • params - the hw_params instance
  • var - parameter to retrieve
  • dir - pointer to the direction (-1,0,1) or NULL

Description:

Inside configuration space defined by params remove from var all values > minimum. Reduce configuration space accordingly. Return the minimum.

  • snd_pcm_hw_param_last - refine config space and return maximum value

Synopsis:

int snd_pcm_hw_param_last ( struct snd_pcm_substream * pcm )

Arguments:

  • pcm - PCM instance
  • params - the hw_params instance
  • var - parameter to retrieve
  • dir - pointer to the direction (-1,0,1) or NULL

Description:

Inside configuration space defined by params remove from var all values < maximum. Reduce configuration space accordingly. Return the maximum.

  • snd_pcm_lib_ioctl - a generic PCM ioctl callback

Synopsis:

int snd_pcm_lib_ioctl ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance
  • cmd - ioctl command
  • arg - ioctl argument

Description:

Processes the generic ioctl commands for PCM. Can be passed as the ioctl callback for PCM ops.

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_period_elapsed - update the pcm status for the next period

Synopsis:

void snd_pcm_period_elapsed ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the pcm substream instance

Description:

This function is called from the interrupt handler when the PCM has processed the period size. It will update the current pointer, wake up sleepers, etc.

Even if more than one periods have elapsed since the last call, you have to call this only once.

  • snd_hwdep_new - create a new hwdep instance

Synopsis:

int snd_hwdep_new ( struct snd_card * card )

Arguments:

  • card - the card instance
  • id - the id string
  • device - the device index (zero-based)
  • rhwdep - the pointer to store the new hwdep instance

Description:

Creates a new hwdep instance with the given index on the card. The callbacks (hwdep→ops) must be set on the returned instance after this call manually by the caller.

Returns zero if successful, or a negative error code on failure.

  • snd_pcm_stop - try to stop all running streams in the substream group

Synopsis:

int snd_pcm_stop ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the PCM substream instance
  • state - PCM state after stopping the stream

Description:

The state of each stream is then changed to the given state unconditionally.

  • snd_pcm_suspend - trigger SUSPEND to all linked streams

Synopsis:

int snd_pcm_suspend ( struct snd_pcm_substream * substream )

Arguments:

  • substream - the PCM substream

Description:

After this call, all streams are changed to SUSPENDED state.

  • snd_pcm_suspend_all - trigger SUSPEND to all substreams in the given pcm

Synopsis:

int snd_pcm_suspend_all ( struct snd_pcm * pcm )

Arguments:

  • pcm - the PCM instance

Description:

After this call, all streams are changed to SUSPENDED state.

  • snd_malloc_pages - allocate pages with the given size

Synopsis:

void * snd_malloc_pages ( size_t size )

Arguments:

  • size - the size to allocate in bytes
  • gfp_flags - the allocation conditions, GFP_XXX

Description:

Allocates the physically contiguous pages with the given size.

Returns the pointer of the buffer, or NULL if no enoguh memory.

  • snd_free_pages - release the pages

Synopsis:

void snd_free_pages ( void * ptr )

Arguments:

  • ptr - the buffer pointer to release
  • size - the allocated buffer size

Description:

Releases the buffer allocated via snd_malloc_pages.

  • snd_dma_alloc_pages - allocate the buffer area according to the given type

Synopsis:

int snd_dma_alloc_pages ( int type )

Arguments:

  • type - the DMA buffer type
  • device - the device pointer
  • size - the buffer size to allocate
  • dmab - buffer allocation record to store the allocated data

Description:

Calls the memory-allocator function for the corresponding buffer type.

Returns zero if the buffer with the given size is allocated successfuly, other a negative value at error.

  • snd_dma_alloc_pages_fallback - allocate the buffer area according to the given type with fallback

Synopsis:

int snd_dma_alloc_pages_fallback ( int type )

Arguments:

  • type - the DMA buffer type
  • device - the device pointer
  • size - the buffer size to allocate
  • dmab - buffer allocation record to store the allocated data

Description:

Calls the memory-allocator function for the corresponding buffer type. When no space is left, this function reduces the size and tries to allocate again. The size actually allocated is stored in res_size argument.

Returns zero if the buffer with the given size is allocated successfuly, other a negative value at error.

  • snd_dma_free_pages - release the allocated buffer

Synopsis:

void snd_dma_free_pages ( struct snd_dma_buffer * dmab )

Arguments:

  • dmab - the buffer allocation record to release

Description:

Releases the allocated buffer via snd_dma_alloc_pages.

  • snd_dma_get_reserved_buf - get the reserved buffer for the given device

Synopsis:

size_t snd_dma_get_reserved_buf ( struct snd_dma_buffer * dmab )

Arguments:

  • dmab - the buffer allocation record to store
  • id - the buffer id

Description:

Looks for the reserved-buffer list and re-uses if the same buffer is found in the list. When the buffer is found, it's removed from the free list.

Returns the size of buffer if the buffer is found, or zero if not found.

  • snd_dma_reserve_buf - reserve the buffer

Synopsis:

int snd_dma_reserve_buf ( struct snd_dma_buffer * dmab )

Arguments:

  • dmab - the buffer to reserve
  • id - the buffer id

Description:

Reserves the given buffer as a reserved buffer.

Returns zero if successful, or a negative code at error.

16x50 UART Driver

  • uart_handle_dcd_change - handle a change of carrier detect state

Synopsis:

void uart_handle_dcd_change ( struct uart_port * uport )

Arguments:

  • uport - uart_port structure for the open port
  • status - new carrier detect status, nonzero if active
  • uart_handle_cts_change - handle a change of clear-to-send state

Synopsis:

void uart_handle_cts_change ( struct uart_port * uport )

Arguments:

  • uport - uart_port structure for the open port
  • status - new clear to send status, nonzero if active
  • uart_update_timeout - update per-port FIFO timeout.

Synopsis:

void uart_update_timeout ( struct uart_port * port )

Arguments:

  • port - uart_port structure describing the port
  • cflag - termios cflag value
  • baud - speed of the port

Description:

Set the port FIFO timeout value. The cflag value should reflect the actual hardware settings.

  • uart_get_baud_rate - return baud rate for a particular port

Synopsis:

unsigned int uart_get_baud_rate ( struct uart_port * port )

Arguments:

  • port - uart_port structure describing the port in question.
  • termios - desired termios settings.
  • old - old termios (or NULL)
  • min - minimum acceptable baud rate
  • max - maximum acceptable baud rate

Description:

Decode the termios structure into a numeric baud rate, taking account of the magic 38400 baud rate (with spd_* flags), and mapping the B0 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 the termios structure to reflect the baud rate we're actually going to be using. Don't do this for the case where B0 is requested (hang up).

  • uart_get_divisor - return uart clock divisor

Synopsis:

unsigned int uart_get_divisor ( struct uart_port * port )

Arguments:

  • port - uart_port structure describing the port.
  • baud - desired baud rate

Description:

Calculate the uart clock divisor for the port.

  • uart_parse_options - Parse serial port baud/parity/bits/flow contro.

Synopsis:

void uart_parse_options ( char * options )

Arguments:

  • options - pointer to option string
  • baud - pointer to an 'int' variable for the baud rate.
  • parity - pointer to an 'int' variable for the parity.
  • bits - pointer to an 'int' variable for the number of data bits.
  • flow - pointer to an 'int' variable for the flow control character.

Description:

uart_parse_options decodes a string containing the serial console options. The format of the string is <baud><parity><bits><flow>,

eg:

115200n8r

  • uart_set_options - setup the serial console parameters

Synopsis:

int uart_set_options ( struct uart_port * port )

Arguments:

  • port - pointer to the serial ports uart_port structure
  • co - console pointer
  • baud - baud rate
  • parity - parity character - 'n' (none), 'o' (odd), 'e' (even)
  • bits - number of data bits
  • flow - flow control character - 'r' (rts)
  • uart_register_driver - register a driver with the uart core layer

Synopsis:

int uart_register_driver ( struct uart_driver * drv )

Arguments:

  • drv - low level driver structure

Description:

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

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

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

  • uart_unregister_driver - remove a driver from the uart core layer

Synopsis:

void uart_unregister_driver ( struct uart_driver * drv )

Arguments:

  • drv - low level driver structure

Description:

Remove all references to a driver from the core driver. The low level driver must have removed all its ports via the uart_remove_one_port if it registered them with uart_add_one_port. (ie, drv→port == NULL)

  • uart_add_one_port - attach a driver-defined port structure

Synopsis:

int uart_add_one_port ( struct uart_driver * drv )

Arguments:

  • drv - pointer to the uart low level driver structure for this port
  • uport - uart port structure to use for this port.

Description:

This allows the driver to register its own uart_port structure with the core driver. The main purpose is to allow the low level uart drivers to expand uart_port, rather than having yet more levels of structures.

  • uart_remove_one_port - detach a driver defined port structure

Synopsis:

int uart_remove_one_port ( struct uart_driver * drv )

Arguments:

  • drv - pointer to the uart low level driver structure for this port
  • uport - uart port structure for this port

Description:

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

  • serial8250_suspend_port - suspend one serial port

Synopsis:

void serial8250_suspend_port ( int line )

Arguments:

  • line - serial line number

Description:

Suspend one serial port.

  • serial8250_resume_port - resume one serial port

Synopsis:

void serial8250_resume_port ( int line )

Arguments:

  • line - serial line number

Description:

Resume one serial port.

  • serial8250_register_port - register a serial port

Synopsis:

int serial8250_register_port ( struct uart_port * port )

Arguments:

  • port - serial port template

Description:

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

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

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

  • serial8250_unregister_port - remove a 16×50 serial port at runtime

Synopsis:

void serial8250_unregister_port ( int line )

Arguments:

  • line - serial line number

Description:

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

Frame Buffer Library

The frame buffer drivers depend heavily on four data structures. These structures are declared in include/linux/fb.h. They are fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. The last three can be made available to and from userland.

fb_info defines the current state of a particular video card. Inside fb_info, there exists a fb_ops structure which is a collection of needed functions to make fbdev and fbcon work. fb_info is only visible to the kernel.

fb_var_screeninfo is used to describe the features of a video card that are user defined. With fb_var_screeninfo, things such as depth and the resolution may be defined.

The next structure is fb_fix_screeninfo. This defines the properties of a card that are created when a mode is set and can't be changed otherwise. A good example of this is the start of the frame buffer memory. This “locks” the address of the frame buffer memory, so that it cannot be changed or moved.

The last structure is fb_monospecs. In the old API, there was little importance for fb_monospecs. This allowed for forbidden things such as setting a mode of 800×600 on a fix frequency monitor. With the new API, fb_monospecs prevents such things, and if used correctly, can prevent a monitor from being cooked. fb_monospecs will not be useful until kernels 2.5.x.

Frame Buffer Memory

Frame Buffer Colormap

Frame Buffer Video Mode Database

Frame Buffer Macintosh Video Mode Database

Frame Buffer Fonts

Refer to the file drivers/video/console/fonts.c for more information.

Input Subsystem

  • struct ff_replay - defines scheduling of the force-feedback effect

Synopsis:

struct ff_replay {
  __u16 length;
  __u16 delay;
};  

Members:

  • length - duration of the effect
  • delay - delay before effect should start playing
  • struct ff_trigger - defines what triggers the force-feedback effect

Synopsis:

struct ff_trigger {
  __u16 button;
  __u16 interval;
};  

Members:

  • button - number of the button triggering the effect
  • interval - controls how soon the effect can be re-triggered
  • struct ff_envelope - generic force-feedback effect envelope

Synopsis:

struct ff_envelope {
  __u16 attack_length;
  __u16 attack_level;
  __u16 fade_length;
  __u16 fade_level;
};  

Members:

  • attack_length - duration of the attack (ms)
  • attack_level - level at the beginning of the attack
  • fade_length - duration of fade (ms)
  • fade_level - level at the end of fade

Description:

The attack_level and fade_level are absolute values; when applying envelope force-feedback core will convert to positive/negative value based on polarity of the default level of the effect. Valid range for the attack and fade levels is 0x0000 - 0x7fff

  • struct ff_constant_effect - defines parameters of a constant force-feedback effect

Synopsis:

struct ff_constant_effect {
  __s16 level;
  struct ff_envelope envelope;
};  

Members:

  • level - strength of the effect; may be negative
  • envelope - envelope data
  • struct ff_ramp_effect - defines parameters of a ramp force-feedback effect

Synopsis:

struct ff_ramp_effect {
  __s16 start_level;
  __s16 end_level;
  struct ff_envelope envelope;
};  

Members:

  • start_level - beginning strength of the effect; may be negative
  • end_level - final strength of the effect; may be negative
  • envelope - envelope data
  • struct ff_condition_effect - defines a spring or friction force-feedback effect

Synopsis:

struct ff_condition_effect {
  __u16 right_saturation;
  __u16 left_saturation;
  __s16 right_coeff;
  __s16 left_coeff;
  __u16 deadband;
  __s16 center;
};  

Members:

  • right_saturation - maximum level when joystick moved all way to the right
  • left_saturation - same for the left side
  • right_coeff - controls how fast the force grows when the joystick moves to the right
  • left_coeff - same for the left side
  • deadband - size of the dead zone, where no force is produced
  • center - position of the dead zone
  • struct ff_periodic_effect - defines parameters of a periodic force-feedback effect

Synopsis:

struct ff_periodic_effect {
  __u16 waveform;
  __u16 period;
  __s16 magnitude;
  __s16 offset;
  __u16 phase;
  struct ff_envelope envelope;
  __u32 custom_len;
  __s16 * custom_data;
};  

Members:

  • waveform - kind of the effect (wave)
  • period - period of the wave (ms)
  • magnitude - peak value
  • offset - mean value of the wave (roughly)
  • phase - 'horizontal' shift
  • envelope - envelope data
  • custom_len - number of samples (FF_CUSTOM only)
  • custom_data - buffer of samples (FF_CUSTOM only)

Description:

Known waveforms - FF_SQUARE, FF_TRIANGLE, FF_SINE, FF_SAW_UP, FF_SAW_DOWN, FF_CUSTOM. The exact syntax FF_CUSTOM is undefined for the time being as no driver supports it yet.

Note:

the data pointed by custom_data is copied by the driver. You can therefore dispose of the memory after the upload/update.

  • struct ff_rumble_effect - defines parameters of a periodic force-feedback effect

Synopsis:

struct ff_rumble_effect {
  __u16 strong_magnitude;
  __u16 weak_magnitude;
};  

Members:

  • strong_magnitude - magnitude of the heavy motor
  • weak_magnitude - magnitude of the light one

Description:

Some rumble pads have two motors of different weight. Strong_magnitude represents the magnitude of the vibration generated by the heavy one.

  • struct ff_effect - defines force feedback effect

Synopsis:

struct ff_effect {
  __u16 type;
  __s16 id;
  __u16 direction;
  struct ff_trigger trigger;
  struct ff_replay replay;
  union u;
};  

Members:

  • type - type of the effect (FF_CONSTANT, FF_PERIODIC, FF_RAMP, FF_SPRING, FF_FRICTION, FF_DAMPER, FF_RUMBLE, FF_INERTIA, or FF_CUSTOM)
  • id - an unique id assigned to an effect
  • direction - direction of the effect
  • trigger - trigger conditions (struct ff_trigger)
  • replay - scheduling of the effect (struct ff_replay)
  • u - effect-specific structure (one of ff_constant_effect, ff_ramp_effect, ff_periodic_effect, ff_condition_effect, ff_rumble_effect) further defining effect parameters

Description:

This structure is sent through ioctl from the application to the driver. To create a new effect application should set its id to -1; the kernel will return assigned id which can later be used to update or delete this effect.

Direction of the effect is encoded as follows:

0 deg → 0x0000 (down) 90 deg → 0x4000 (left) 180 deg → 0x8000 (up) 270 deg → 0xC000 (right)

  • struct input_dev - represents an input device

Synopsis:

struct input_dev {
  const char * name;
  const char * phys;
  const char * uniq;
  struct input_id id;
  unsigned long evbit[BITS_TO_LONGS(EV_CNT)];
  unsigned long keybit[BITS_TO_LONGS(KEY_CNT)];
  unsigned long relbit[BITS_TO_LONGS(REL_CNT)];
  unsigned long absbit[BITS_TO_LONGS(ABS_CNT)];
  unsigned long mscbit[BITS_TO_LONGS(MSC_CNT)];
  unsigned long ledbit[BITS_TO_LONGS(LED_CNT)];
  unsigned long sndbit[BITS_TO_LONGS(SND_CNT)];
  unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];
  unsigned long swbit[BITS_TO_LONGS(SW_CNT)];
  unsigned int keycodemax;
  unsigned int keycodesize;
  void * keycode;
  int (* setkeycode) (struct input_dev *dev, int scancode, int keycode);
  int (* getkeycode) (struct input_dev *dev, int scancode, int *keycode);
  struct ff_device * ff;
  unsigned int repeat_key;
  struct timer_list timer;
  int sync;
  int abs[ABS_MAX + 1];
  int rep[REP_MAX + 1];
  unsigned long key[BITS_TO_LONGS(KEY_CNT)];
  unsigned long led[BITS_TO_LONGS(LED_CNT)];
  unsigned long snd[BITS_TO_LONGS(SND_CNT)];
  unsigned long sw[BITS_TO_LONGS(SW_CNT)];
  int absmax[ABS_MAX + 1];
  int absmin[ABS_MAX + 1];
  int absfuzz[ABS_MAX + 1];
  int absflat[ABS_MAX + 1];
  int (* open) (struct input_dev *dev);
  void (* close) (struct input_dev *dev);
  int (* flush) (struct input_dev *dev, struct file *file);
  int (* event) (struct input_dev *dev, unsigned int type, unsigned int code, int value);
  struct input_handle * grab;
  spinlock_t event_lock;
  struct mutex mutex;
  unsigned int users;
  bool going_away;
  struct device dev;
  struct list_head h_list;
  struct list_head node;
};  

Members:

  • name - name of the device
  • phys - physical path to the device in the system hierarchy
  • uniq - unique identification code for the device (if device has it)
  • id - id of the device (struct input_id)
  • evbit[BITS_TO_LONGS(EV_CNT)] - bitmap of types of events supported by the device (EV_KEY, EV_REL, etc.)
  • keybit[BITS_TO_LONGS(KEY_CNT)] - bitmap of keys/buttons this device has
  • relbit[BITS_TO_LONGS(REL_CNT)] - bitmap of relative axes for the device
  • absbit[BITS_TO_LONGS(ABS_CNT)] - bitmap of absolute axes for the device
  • mscbit[BITS_TO_LONGS(MSC_CNT)] - bitmap of miscellaneous events supported by the device
  • ledbit[BITS_TO_LONGS(LED_CNT)] - bitmap of leds present on the device
  • sndbit[BITS_TO_LONGS(SND_CNT)] - bitmap of sound effects supported by the device
  • ffbit[BITS_TO_LONGS(FF_CNT)] - bitmap of force feedback effects supported by the device
  • swbit[BITS_TO_LONGS(SW_CNT)] - bitmap of switches present on the device
  • keycodemax - size of keycode table
  • keycodesize - size of elements in keycode table
  • keycode - map of scancodes to keycodes for this device
  • setkeycode - optional method to alter current keymap, used to implement sparse keymaps. If not supplied default mechanism will be used
  • getkeycode - optional method to retrieve current keymap. If not supplied default mechanism will be used
  • ff - force feedback structure associated with the device if device supports force feedback effects
  • repeat_key - stores key code of the last key pressed; used to implement software autorepeat
  • timer - timer for software autorepeat
  • sync - set to 1 when there were no new events since last EV_SYNC
  • abs[ABS_MAX + 1] - current values for reports from absolute axes
  • rep[REP_MAX + 1] - current values for autorepeat parameters (delay, rate)
  • key[BITS_TO_LONGS(KEY_CNT)] - reflects current state of device's keys/buttons
  • led[BITS_TO_LONGS(LED_CNT)] - reflects current state of device's LEDs
  • snd[BITS_TO_LONGS(SND_CNT)] - reflects current state of sound effects
  • sw[BITS_TO_LONGS(SW_CNT)] - reflects current state of device's switches
  • absmax[ABS_MAX + 1] - maximum values for events coming from absolute axes
  • absmin[ABS_MAX + 1] - minimum values for events coming from absolute axes
  • absfuzz[ABS_MAX + 1] - describes noisiness for axes
  • absflat[ABS_MAX + 1] - size of the center flat position (used by joydev)
  • open - this method is called when the very first user calls input_open_device. The driver must prepare the device to start generating events (start polling thread, request an IRQ, submit URB, etc.)
  • close - this method is called when the very last user calls input_close_device.
  • flush - purges the device. Most commonly used to get rid of force feedback effects loaded into the device when disconnecting from it
  • event - event handler for events sent _to_ the device, like EV_LED or EV_SND. The device is expected to carry out the requested action (turn on a LED, play sound, etc.) The call is protected by event_lock and must not sleep
  • grab - input handle that currently has the device grabbed (via EVIOCGRAB ioctl). When a handle grabs a device it becomes sole recipient for all input events coming from the device
  • event_lock - this spinlock is is taken when input core receives and processes a new event for the device (in input_event). Code that accesses and/or modifies parameters of a device (such as keymap or absmin, absmax, absfuzz, etc.) after device has been registered with input core must take this lock.
  • mutex - serializes calls to open, close and flush methods
  • users - stores number of users (input handlers) that opened this device. It is used by input_open_device and input_close_device to make sure that dev→open is only called when the first user opens device and dev→close is called when the very last user closes the device
  • going_away - marks devices that are in a middle of unregistering and causes input_open_device*() fail with -ENODEV.
  • dev - driver model's view of this device
  • h_list - list of input handles associated with the device. When accessing the list dev→mutex must be held
  • node - used to place the device onto input_dev_list
  • struct input_handler - implements one of interfaces for input devices

Synopsis:

struct input_handler {
  void * private;
  void (* event) (struct input_handle *handle, unsigned int type, unsigned int code, int value);
  int (* connect) (struct input_handler *handler, struct input_dev *dev, const struct input_device_id *id);
  void (* disconnect) (struct input_handle *handle);
  void (* start) (struct input_handle *handle);
  const struct file_operations * fops;
  int minor;
  const char * name;
  const struct input_device_id * id_table;
  const struct input_device_id * blacklist;
  struct list_head h_list;
  struct list_head node;
};  

Members:

  • private - driver-specific data
  • event - event handler. This method is being called by input core with interrupts disabled and dev→event_lock spinlock held and so it may not sleep
  • connect - called when attaching a handler to an input device
  • disconnect - disconnects a handler from input device
  • start - starts handler for given handle. This function is called by input core right after connect method and also when a process that grabbed a device releases it
  • fops - file operations this driver implements
  • minor - beginning of range of 32 minors for devices this driver can provide
  • name - name of the handler, to be shown in /proc/bus/input/handlers
  • id_table - pointer to a table of input_device_ids this driver can handle
  • blacklist - pointer to a table of input_device_ids this driver should ignore even if they match id_table
  • h_list - list of input handles associated with the handler
  • node - for placing the driver onto input_handler_list

Description:

Input handlers attach to input devices and create input handles. There are likely several handlers attached to any given input device at the same time. All of them will get their copy of input event generated by the device.

Note that input core serializes calls to connect and disconnect methods.

  • struct input_handle - links input device with an input handler

Synopsis:

struct input_handle {
  void * private;
  int open;
  const char * name;
  struct input_dev * dev;
  struct input_handler * handler;
  struct list_head d_node;
  struct list_head h_node;
};  

Members:

  • private - handler-specific data
  • open - counter showing whether the handle is 'open', i.e. should deliver events from its device
  • name - name given to the handle by handler that created it
  • dev - input device the handle is attached to
  • handler - handler that works with the device through this handle
  • d_node - used to put the handle on device's list of attached handles
  • h_node - used to put the handle on handler's list of handles from which it gets events
  • struct ff_device - force-feedback part of an input device

Synopsis:

struct ff_device {
  int (* upload) (struct input_dev *dev, struct ff_effect *effect,struct ff_effect *old);
  int (* erase) (struct input_dev *dev, int effect_id);
  int (* playback) (struct input_dev *dev, int effect_id, int value);
  void (* set_gain) (struct input_dev *dev, u16 gain);
  void (* set_autocenter) (struct input_dev *dev, u16 magnitude);
  void (* destroy) (struct ff_device *);
  void * private;
  unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];
  struct mutex mutex;
  int max_effects;
  struct ff_effect * effects;
  struct file * effect_owners[];
};  

Members:

  • upload - Called to upload an new effect into device
  • erase - Called to erase an effect from device
  • playback - Called to request device to start playing specified effect
  • set_gain - Called to set specified gain
  • set_autocenter - Called to auto-center device
  • destroy - called by input core when parent input device is being destroyed
  • private - driver-specific data, will be freed automatically
  • ffbit[BITS_TO_LONGS(FF_CNT)] - bitmap of force feedback capabilities truly supported by device (not emulated like ones in input_dev→ffbit)
  • mutex - mutex for serializing access to the device
  • max_effects - maximum number of effects supported by device
  • effects - pointer to an array of effects currently loaded into device
  • effect_owners[] - array of effect owners; when file handle owning an effect gets closed the effect is automatically erased

Description:

Every force-feedback device must implement upload and playback methods; erase is optional. set_gain and set_autocenter need only be implemented if driver sets up FF_GAIN and FF_AUTOCENTER bits.

Note that playback, set_gain and set_autocenter are called with dev→event_lock spinlock held and interrupts off and thus may not sleep.

  • input_event - report new input event

Synopsis:

void input_event ( struct input_dev * dev )

Arguments:

  • dev - device that generated the event
  • type - type of the event
  • code - event code
  • value - value of the event

Description:

This function should be used by drivers implementing various input devices. See also input_inject_event.

  • input_inject_event - send input event from input handler

Synopsis:

void input_inject_event ( struct input_handle * handle )

Arguments:

  • handle - input handle to send event through
  • type - type of the event
  • code - event code
  • value - value of the event

Description:

Similar to input_event but will ignore event if device is grabbed and handle injecting event is not the one that owns the device.

  • input_grab_device - grabs device for exclusive use

Synopsis:

int input_grab_device ( struct input_handle * handle )

Arguments:

  • handle - input handle that wants to own the device

Description:

When a device is grabbed by an input handle all events generated by the device are delivered only to this handle. Also events injected by other input handles are ignored while device is grabbed.

  • input_release_device - release previously grabbed device

Synopsis:

void input_release_device ( struct input_handle * handle )

Arguments:

  • handle - input handle that owns the device

Description:

Releases previously grabbed device so that other input handles can start receiving input events. Upon release all handlers attached to the device have their start method called so they have a change to synchronize device state with the rest of the system.

  • input_open_device - open input device

Synopsis:

int input_open_device ( struct input_handle * handle )

Arguments:

  • handle - handle through which device is being accessed

Description:

This function should be called by input handlers when they want to start receive events from given input device.

  • input_close_device - close input device

Synopsis:

void input_close_device ( struct input_handle * handle )

Arguments:

  • handle - handle through which device is being accessed

Description:

This function should be called by input handlers when they want to stop receive events from given input device.

  • input_get_keycode - retrieve keycode currently mapped to a given scancode

Synopsis:

int input_get_keycode ( struct input_dev * dev )

Arguments:

  • dev - input device which keymap is being queried
  • scancode - scancode (or its equivalent for device in question) for which keycode is needed
  • keycode - result

Description:

This function should be called by anyone interested in retrieving current keymap. Presently keyboard and evdev handlers use it.

  • input_set_keycode - assign new keycode to a given scancode

Synopsis:

int input_set_keycode ( struct input_dev * dev )

Arguments:

  • dev - input device which keymap is being updated
  • scancode - scancode (or its equivalent for device in question)
  • keycode - new keycode to be assigned to the scancode

Description:

This function should be called by anyone needing to update current keymap. Presently keyboard and evdev handlers use it.

  • input_allocate_device - allocate memory for new input device

Synopsis:

struct input_dev * input_allocate_device ( void )

Arguments:

  • void - no arguments

Description:

Returns prepared struct input_dev or NULL.

NOTE:

Use input_free_device to free devices that have not been registered; input_unregister_device should be used for already registered devices.

  • input_free_device - free memory occupied by input_dev structure

Synopsis:

void input_free_device ( struct input_dev * dev )

Arguments:

  • dev - input device to free

Description:

This function should only be used if input_register_device was not called yet or if it failed. Once device was registered use input_unregister_device and memory will be freed once last reference to the device is dropped.

Device should be allocated by input_allocate_device.

NOTE:

If there are references to the input device then memory will not be freed until last reference is dropped.

  • input_set_capability - mark device as capable of a certain event

Synopsis:

void input_set_capability ( struct input_dev * dev )

Arguments:

  • dev - device that is capable of emitting or accepting event
  • type - type of the event (EV_KEY, EV_REL, etc…)
  • code - event code

Description:

In addition to setting up corresponding bit in appropriate capability bitmap the function also adjusts dev→evbit.

  • input_register_device - register device with input core

Synopsis:

int input_register_device ( struct input_dev * dev )

Arguments:

  • dev - device to be registered

Description:

This function registers device with input core. The device must be allocated with input_allocate_device and all it's capabilities set up before registering. If function fails the device must be freed with input_free_device. Once device has been successfully registered it can be unregistered with input_unregister_device; input_free_device should not be called in this case.

  • input_unregister_device - unregister previously registered device

Synopsis:

void input_unregister_device ( struct input_dev * dev )

Arguments:

  • dev - device to be unregistered

Description:

This function unregisters an input device. Once device is unregistered the caller should not try to access it as it may get freed at any moment.

  • input_register_handler - register a new input handler

Synopsis:

int input_register_handler ( struct input_handler * handler )

Arguments:

  • handler - handler to be registered

Description:

This function registers a new input handler (interface) for input devices in the system and attaches it to all input devices that are compatible with the handler.

  • input_unregister_handler - unregisters an input handler

Synopsis:

void input_unregister_handler ( struct input_handler * handler )

Arguments:

  • handler - handler to be unregistered

Description:

This function disconnects a handler from its input devices and removes it from lists of known handlers.

  • input_register_handle - register a new input handle

Synopsis:

int input_register_handle ( struct input_handle * handle )

Arguments:

  • handle - handle to register

Description:

This function puts a new input handle onto device's and handler's lists so that events can flow through it once it is opened using input_open_device.

This function is supposed to be called from handler's connect method.

  • input_unregister_handle - unregister an input handle

Synopsis:

void input_unregister_handle ( struct input_handle * handle )

Arguments:

  • handle - handle to unregister

Description:

This function removes input handle from device's and handler's lists.

This function is supposed to be called from handler's disconnect method.

  • input_ff_upload - upload effect into force-feedback device

Synopsis:

int input_ff_upload ( struct input_dev * dev )

Arguments:

  • dev - input device
  • effect - effect to be uploaded
  • file - owner of the effect
  • input_ff_erase - erase a force-feedback effect from device

Synopsis:

int input_ff_erase ( struct input_dev * dev )

Arguments:

  • dev - input device to erase effect from
  • effect_id - id of the ffect to be erased
  • file - purported owner of the request

Description:

This function erases a force-feedback effect from specified device. The effect will only be erased if it was uploaded through the same file handle that is requesting erase.

  • input_ff_event - generic handler for force-feedback events

Synopsis:

int input_ff_event ( struct input_dev * dev )

Arguments:

  • dev - input device to send the effect to
  • type - event type (anything but EV_FF is ignored)
  • code - event code
  • value - event value
  • input_ff_create - create force-feedback device

Synopsis:

int input_ff_create ( struct input_dev * dev )

Arguments:

  • dev - input device supporting force-feedback
  • max_effects - maximum number of effects supported by the device

Description:

This function allocates all necessary memory for a force feedback portion of an input device and installs all default handlers. dev→ffbit should be already set up before calling this function. Once ff device is created you need to setup its upload, erase, playback and other handlers before registering input device

  • input_ff_destroy - frees force feedback portion of input device

Synopsis:

void input_ff_destroy ( struct input_dev * dev )

Arguments:

  • dev - input device supporting force feedback

Description:

This function is only needed in error path as input core will automatically free force feedback structures when device is destroyed.

  • input_ff_create_memless - create memoryless force-feedback device

Synopsis:

int input_ff_create_memless ( struct input_dev * dev )

Arguments:

  • dev - input device supporting force-feedback
  • data - driver-specific data to be passed into play_effect
  • play_effect - driver-specific method for playing FF effect

Serial Peripheral Interface (SPI)

SPI is the “Serial Peripheral Interface”, widely used with embedded systems because it is a simple and efficient interface: basically a multiplexed shift register. Its three signal wires hold a clock (SCK, often in the range of 1-20 MHz), a “Master Out, Slave In” (MOSI) data line, and a “Master In, Slave Out” (MISO) data line. SPI is a full duplex protocol; for each bit shifted out the MOSI line (one per clock) another is shifted in on the MISO line. Those bits are assembled into words of various sizes on the way to and from system memory. An additional chipselect line is usually active-low (nCS); four signals are normally used for each peripheral, plus sometimes an interrupt.

The SPI bus facilities listed here provide a generalized interface to declare SPI busses and devices, manage them according to the standard Linux driver model, and perform input/output operations. At this time, only “master” side interfaces are supported, where Linux talks to SPI peripherals and does not implement such a peripheral itself. (Interfaces to support implementing SPI slaves would necessarily look different.)

The programming interface is structured around two kinds of driver, and two kinds of device. A “Controller Driver” abstracts the controller hardware, which may be as simple as a set of GPIO pins or as complex as a pair of FIFOs connected to dual DMA engines on the other side of the SPI shift register (maximizing throughput). Such drivers bridge between whatever bus they sit on (often the platform bus) and SPI, and expose the SPI side of their device as a struct spi_master. SPI devices are children of that master, represented as a struct spi_device and manufactured from struct spi_board_info descriptors which are usually provided by board-specific initialization code. A struct spi_driver is called a “Protocol Driver”, and is bound to a spi_device using normal driver model calls.

The I/O model is a set of queued messages. Protocol drivers submit one or more struct spi_message objects, which are processed and completed asynchronously. (There are synchronous wrappers, however.) Messages are built from one or more struct spi_transfer objects, each of which wraps a full duplex SPI transfer. A variety of protocol tweaking options are needed, because different chips adopt very different policies for how they use the bits transferred with SPI.

  • struct spi_device - Master side proxy for an SPI slave device

Synopsis:

struct spi_device {
  struct device dev;
  struct spi_master * master;
  u32 max_speed_hz;
  u8 chip_select;
  u8 mode;
#define SPI_CPHA	0x01
#define SPI_CPOL	0x02
#define SPI_MODE_0	(0|0)
#define SPI_MODE_1	(0|SPI_CPHA)
#define SPI_MODE_2	(SPI_CPOL|0)
#define SPI_MODE_3	(SPI_CPOL|SPI_CPHA)
#define SPI_CS_HIGH	0x04
#define SPI_LSB_FIRST	0x08
#define SPI_3WIRE	0x10
#define SPI_LOOP	0x20
#define SPI_NO_CS	0x40
#define SPI_READY	0x80
  u8 bits_per_word;
  int irq;
  unsigned long irq_flags;
  void * controller_state;
  void * controller_data;
  char modalias[SPI_NAME_SIZE];
};  

Members:

  • dev - Driver model representation of the device.
  • master - SPI controller used with the device.
  • max_speed_hz - Maximum clock rate to be used with this chip (on this board); may be changed by the device's driver. The spi_transfer.speed_hz can override this for each transfer.
  • chip_select - Chipselect, distinguishing chips handled by master.
  • mode - The spi mode defines how data is clocked out and in. This may be changed by the device's driver. The active low default for chipselect mode can be overridden (by specifying SPI_CS_HIGH) as can the MSB first default for each word in a transfer (by specifying SPI_LSB_FIRST).
  • bits_per_word - Data transfers involve one or more words; word sizes like eight or 12 bits are common. In-memory wordsizes are powers of two bytes (e.g. 20 bit samples use 32 bits). This may be changed by the device's driver, or left at the default (0) indicating protocol words are eight bit bytes. The spi_transfer.bits_per_word can override this for each transfer.
  • irq - Negative, or the number passed to request_irq to receive interrupts from this device.
  • irq_flags - The flags passed to request_irq
  • controller_state - Controller's runtime state
  • controller_data - Board-specific definitions for controller, such as FIFO initialization parameters; from board_info.controller_data
  • modalias[SPI_NAME_SIZE] - Name of the driver to use with this device, or an alias for that name. This appears in the sysfs modalias attribute for driver coldplugging, and in uevents used for hotplugging

Description:

A spi_device is used to interchange data between an SPI slave (usually a discrete chip) and CPU memory.

In dev, the platform_data is used to hold information about this device that's meaningful to the device's protocol driver, but not to its controller. One example might be an identifier for a chip variant with slightly different functionality; another might be information about how this particular board wires the chip's pins.

  • struct spi_driver - Host side protocol driver

Synopsis:

struct spi_driver {
  const struct spi_device_id * id_table;
  int (* probe) (struct spi_device *spi);
  int (* remove) (struct spi_device *spi);
  void (* shutdown) (struct spi_device *spi);
  int (* suspend) (struct spi_device *spi, pm_message_t mesg);
  int (* resume) (struct spi_device *spi);
  struct device_driver driver;
};  

Members:

  • id_table - List of SPI devices supported by this driver
  • probe - Binds this driver to the spi device. Drivers can verify that the device is actually present, and may need to configure characteristics (such as bits_per_word) which weren't needed for the initial configuration done during system setup.
  • remove - Unbinds this driver from the spi device
  • shutdown - Standard shutdown callback used during system state transitions such as powerdown/halt and kexec
  • suspend - Standard suspend callback used during system state transitions
  • resume - Standard resume callback used during system state transitions
  • driver - SPI device drivers should initialize the name and owner field of this structure.

Description:

This represents the kind of device driver that uses SPI messages to interact with the hardware at the other end of a SPI link. It's called a protocol driver because it works through messages rather than talking directly to SPI hardware (which is what the underlying SPI controller driver does to pass those messages). These protocols are defined in the specification for the device(s) supported by the driver.

As a rule, those device protocols represent the lowest level interface supported by a driver, and it will support upper level interfaces too. Examples of such upper levels include frameworks like MTD, networking, MMC, RTC, filesystem character device nodes, and hardware monitoring.

  • spi_unregister_driver - reverse effect of spi_register_driver

Synopsis:

void spi_unregister_driver ( struct spi_driver * sdrv )

Arguments:

  • sdrv - the driver to unregister

Context:

can sleep

  • struct spi_master - interface to SPI master controller

Synopsis:

struct spi_master {
  struct device dev;
  s16 bus_num;
  u16 num_chipselect;
  u16 dma_alignment;
  u16 mode_bits;
  u16 flags;
#define SPI_MASTER_HALF_DUPLEX	BIT(0)
#define SPI_MASTER_NO_RX	BIT(1)
#define SPI_MASTER_NO_TX	BIT(2)
  int (* setup) (struct spi_device *spi);
  int (* transfer) (struct spi_device *spi,struct spi_message *mesg);
  void (* cleanup) (struct spi_device *spi);
  int (* lock_bus) (struct spi_device *spi);
  int (* unlock_bus) (struct spi_device *spi);
};  

Members:

  • dev - device interface to this driver
  • bus_num - board-specific (and often SOC-specific) identifier for a given SPI controller.
  • num_chipselect - chipselects are used to distinguish individual SPI slaves, and are numbered from zero to num_chipselects. each slave has a chipselect signal, but it's common that not every chipselect is connected to a slave.
  • dma_alignment - SPI controller constraint on DMA buffers alignment.
  • mode_bits - flags understood by this controller driver
  • flags - other constraints relevant to this driver
  • setup - updates the device mode and clocking records used by a device's SPI controller; protocol code may call this. This must fail if an unrecognized or unsupported mode is requested. It's always safe to call this unless transfers are pending on the device whose settings are being modified.
  • transfer - adds a message to the controller's transfer queue.
  • cleanup - frees controller-specific state
  • lock_bus - lock SPI bus for exclusive access
  • unlock_bus - unlock SPI bus so other devices can access

Description:

Each SPI master controller can communicate with one or more spi_device children. These make a small bus, sharing MOSI, MISO and SCK signals but not chip select signals. Each device may be configured to use a different clock rate, since those shared signals are ignored unless the chip is selected.

The driver for an SPI controller manages access to those devices through a queue of spi_message transactions, copying data between CPU memory and an SPI slave device. For each such message it queues, it calls the message's completion function when the transaction completes.

  • struct spi_transfer - a read/write buffer pair

Synopsis:

struct spi_transfer {
  const void * tx_buf;
  void * rx_buf;
  unsigned len;
  dma_addr_t tx_dma;
  dma_addr_t rx_dma;
  unsigned cs_change:1;
  u8 bits_per_word;
  u16 delay_usecs;
  u32 speed_hz;
  struct list_head transfer_list;
};  

Members:

  • tx_buf - data to be written (dma-safe memory), or NULL
  • rx_buf - data to be read (dma-safe memory), or NULL
  • len - size of rx and tx buffers (in bytes)
  • tx_dma - DMA address of tx_buf, if spi_message.is_dma_mapped
  • rx_dma - DMA address of rx_buf, if spi_message.is_dma_mapped
  • cs_change - affects chipselect after this transfer completes
  • bits_per_word - select a bits_per_word other than the device default for this transfer. If 0 the default (from spi_device) is used.
  • delay_usecs - microseconds to delay after this transfer before (optionally) changing the chipselect status, then starting the next transfer or completing this spi_message.
  • speed_hz - Select a speed other than the device default for this transfer. If 0 the default (from spi_device) is used.
  • transfer_list - transfers are sequenced through spi_message.transfers

Description:

SPI transfers always write the same number of bytes as they read. Protocol drivers should always provide rx_buf and/or tx_buf. In some cases, they may also want to provide DMA addresses for the data being transferred; that may reduce overhead, when the underlying driver uses dma.

If the transmit buffer is null, zeroes will be shifted out while filling rx_buf. If the receive buffer is null, the data shifted in will be discarded. Only len bytes shift out (or in). It's an error to try to shift out a partial word. (For example, by shifting out three bytes with word size of sixteen or twenty bits; the former uses two bytes per word, the latter uses four bytes.)

In-memory data values are always in native CPU byte order, translated from the wire byte order (big-endian except with SPI_LSB_FIRST). So for example when bits_per_word is sixteen, buffers are 2N bytes long (len = 2N) and hold N sixteen bit words in CPU byte order.

When the word size of the SPI transfer is not a power-of-two multiple of eight bits, those in-memory words include extra bits. In-memory words are always seen by protocol drivers as right-justified, so the undefined (rx) or unused (tx) bits are always the most significant bits.

All SPI transfers start with the relevant chipselect active. Normally it stays selected until after the last transfer in a message. Drivers can affect the chipselect signal using cs_change.

(i) If the transfer isn't the last one in the message, this flag is used to make the chipselect briefly go inactive in the middle of the message. Toggling chipselect in this way may be needed to terminate a chip command, letting a single spi_message perform all of group of chip transactions together.

(ii) When the transfer is the last one in the message, the chip may stay selected until the next transfer. On multi-device SPI busses with nothing blocking messages going to other devices, this is just a performance hint; starting a message to another device deselects this one. But in other cases, this can be used to ensure correctness. Some devices need protocol transactions to be built from a series of spi_message submissions, where the content of one message is determined by the results of previous messages and where the whole transaction ends when the chipselect goes intactive.

The code that submits an spi_message (and its spi_transfers) to the lower layers is responsible for managing its memory. Zero-initialize every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them until its completion callback.

  • struct spi_message - one multi-segment SPI transaction

Synopsis:

struct spi_message {
  struct list_head transfers;
  struct spi_device * spi;
  unsigned is_dma_mapped:1;
  void (* complete) (void *context);
  void * context;
  unsigned actual_length;
  int status;
  struct list_head queue;
  void * state;
};  

Members:

  • transfers - list of transfer segments in this transaction
  • spi - SPI device to which the transaction is queued
  • is_dma_mapped - if true, the caller provided both dma and cpu virtual addresses for each transfer buffer
  • complete - called to report transaction completions
  • context - the argument to complete when it's called
  • actual_length - the total number of bytes that were transferred in all successful segments
  • status - zero for success, else negative errno
  • queue - for use by whichever driver currently owns the message
  • state - for use by whichever driver currently owns the message

Description:

A spi_message is used to execute an atomic sequence of data transfers, each represented by a struct spi_transfer. The sequence is atomic in the sense that no other spi_message may use that SPI bus until that sequence completes. On some systems, many such sequences can execute as as single programmed DMA transfer. On all systems, these messages are queued, and might complete after transactions to other devices. Messages sent to a given spi_device are alway executed in FIFO order.

The code that submits an spi_message (and its spi_transfers) to the lower layers is responsible for managing its memory. Zero-initialize every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them until its completion callback.

  • spi_write - SPI synchronous write

Synopsis:

int spi_write ( struct spi_device * spi )

Arguments:

  • spi - device to which data will be written
  • buf - data buffer
  • len - data buffer size

Context:

can sleep

Description:

This writes the buffer and returns zero or a negative error code. Callable only from contexts that can sleep.

  • spi_read - SPI synchronous read

Synopsis:

int spi_read ( struct spi_device * spi )

Arguments:

  • spi - device from which data will be read
  • buf - data buffer
  • len - data buffer size

Context:

can sleep

Description:

This reads the buffer and returns zero or a negative error code. Callable only from contexts that can sleep.

  • spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read

Synopsis:

ssize_t spi_w8r8 ( struct spi_device * spi )

Arguments:

  • spi - device with which data will be exchanged
  • cmd - command to be written before data is read back

Context:

can sleep

Description:

This returns the (unsigned) eight bit number returned by the device, or else a negative error code. Callable only from contexts that can sleep.

  • spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read

Synopsis:

ssize_t spi_w8r16 ( struct spi_device * spi )

Arguments:

  • spi - device with which data will be exchanged
  • cmd - command to be written before data is read back

Context:

can sleep

Description:

This returns the (unsigned) sixteen bit number returned by the device, or else a negative error code. Callable only from contexts that can sleep.

The number is returned in wire-order, which is at least sometimes big-endian.

  • struct spi_board_info - board-specific template for a SPI device

Synopsis:

struct spi_board_info {
  char modalias[SPI_NAME_SIZE];
  const void * platform_data;
  void * controller_data;
  int irq;
  u32 max_speed_hz;
  u16 bus_num;
  u16 chip_select;
  u8 mode;
};  

Members:

  • modalias[SPI_NAME_SIZE] - Initializes spi_device.modalias; identifies the driver.
  • platform_data - Initializes spi_device.platform_data; the particular data stored there is driver-specific.
  • controller_data - Initializes spi_device.controller_data; some controllers need hints about hardware setup, e.g. for DMA.
  • irq - Initializes spi_device.irq; depends on how the board is wired.
  • max_speed_hz - Initializes spi_device.max_speed_hz; based on limits from the chip datasheet and board-specific signal quality issues.
  • bus_num - Identifies which spi_master parents the spi_device; unused by spi_new_device, and otherwise depends on board wiring.
  • chip_select - Initializes spi_device.chip_select; depends on how the board is wired.
  • mode - Initializes spi_device.mode; based on the chip datasheet, board wiring (some devices support both 3WIRE and standard modes), and possibly presence of an inverter in the chipselect path.

Description:

When adding new SPI devices to the device tree, these structures serve as a partial device template. They hold information which can't always be determined by drivers. Information that probe can establish (such as the default transfer wordsize) is not included here.

These structures are used in two places. Their primary role is to be stored in tables of board-specific device descriptors, which are declared early in board initialization and then used (much later) to populate a controller's device tree after the that controller's driver initializes. A secondary (and atypical) role is as a parameter to spi_new_device call, which happens after those controller drivers are active in some dynamic board configuration models.

  • spi_register_board_info - register SPI devices for a given board

Synopsis:

int spi_register_board_info ( struct spi_board_info const * info )

Arguments:

  • info - array of chip descriptors
  • n - how many descriptors are provided

Context:

can sleep

Description:

Board-specific early init code calls this (probably during arch_initcall) with segments of the SPI device table. Any device nodes are created later, after the relevant parent SPI controller (bus_num) is defined. We keep this table of devices forever, so that reloading a controller driver will not make Linux forget about these hard-wired devices.

Other code can also call this, e.g. a particular add-on board might provide SPI devices through its expansion connector, so code initializing that board would naturally declare its SPI devices.

The board info passed can safely be __initdata … but be careful of any embedded pointers (platform_data, etc), they're copied as-is.

  • spi_register_driver - register a SPI driver

Synopsis:

int spi_register_driver ( struct spi_driver * sdrv )

Arguments:

  • sdrv - the driver to register

Context:

can sleep

  • spi_alloc_device - Allocate a new SPI device

Synopsis:

struct spi_device * spi_alloc_device ( struct spi_master * master )

Arguments:

  • master - Controller to which device is connected

Context:

can sleep

Description:

Allows a driver to allocate and initialize a spi_device without registering it immediately. This allows a driver to directly fill the spi_device with device parameters before calling spi_add_device on it.

Caller is responsible to call spi_add_device on the returned spi_device structure to add it to the SPI master. If the caller needs to discard the spi_device without adding it, then it should call spi_dev_put on it.

Returns a pointer to the new device, or NULL.

  • spi_add_device - Add spi_device allocated with spi_alloc_device

Synopsis:

int spi_add_device ( struct spi_device * spi )

Arguments:

  • spi - spi_device to register

Description:

Companion function to spi_alloc_device. Devices allocated with spi_alloc_device can be added onto the spi bus with this function.

Returns 0 on success; negative errno on failure

  • spi_new_device - instantiate one new SPI device

Synopsis:

struct spi_device * spi_new_device ( struct spi_master * master )

Arguments:

  • master - Controller to which device is connected
  • chip - Describes the SPI device

Context:

can sleep

Description:

On typical mainboards, this is purely internal; and it's not needed after board init creates the hard-wired devices. Some development platforms may not be able to use spi_register_board_info though, and this is exported so that for example a USB or parport based adapter driver could add devices (which it would learn about out-of-band).

Returns the new device, or NULL.

  • spi_alloc_master - allocate SPI master controller

Synopsis:

struct spi_master * spi_alloc_master ( struct device * dev )

Arguments:

  • dev - the controller, possibly using the platform_bus
  • size - how much zeroed driver-private data to allocate; the pointer to this memory is in the driver_data field of the returned device, accessible with spi_master_get_devdata.

Context:

can sleep

Description:

This call is used only by SPI master controller drivers, which are the only ones directly touching chip registers. It's how they allocate an spi_master structure, prior to calling spi_register_master.

This must be called from context that can sleep. It returns the SPI master structure on success, else NULL.

The caller is responsible for assigning the bus number and initializing the master's methods before calling spi_register_master; and (after errors adding the device) calling spi_master_put to prevent a memory leak.

  • spi_register_master - register SPI master controller

Synopsis:

int spi_register_master ( struct spi_master * master )

Arguments:

  • master - initialized master, originally from spi_alloc_master

Context:

can sleep

Description:

SPI master controllers connect to their drivers using some non-SPI bus, such as the platform bus. The final stage of probe in that code includes calling spi_register_master to hook up to this SPI bus glue.

SPI controllers use board specific (often SOC specific) bus numbers, and board-specific addressing for SPI devices combines those numbers with chip select numbers. Since SPI does not directly support dynamic device identification, boards need configuration tables telling which chip is at which address.

This must be called from context that can sleep. It returns zero on success, else a negative error code (dropping the master's refcount). After a successful return, the caller is responsible for calling spi_unregister_master.

  • spi_unregister_master - unregister SPI master controller

Synopsis:

void spi_unregister_master ( struct spi_master * master )

Arguments:

  • master - the master being unregistered

Context:

can sleep

Description:

This call is used only by SPI master controller drivers, which are the only ones directly touching chip registers.

This must be called from context that can sleep.

  • spi_busnum_to_master - look up master associated with bus_num

Synopsis:

struct spi_master * spi_busnum_to_master ( u16 bus_num )

Arguments:

  • bus_num - the master's bus number

Context:

can sleep

Description:

This call may be used with devices that are registered after arch init time. It returns a refcounted pointer to the relevant spi_master (which the caller must release), or NULL if there is no such master registered.

  • spi_setup - setup SPI mode and clock rate

Synopsis:

int spi_setup ( struct spi_device * spi )

Arguments:

  • spi - the device whose settings are being modified

Context:

can sleep, and no requests are queued to the device

Description:

SPI protocol drivers may need to update the transfer mode if the device doesn't work with its default. They may likewise need to update clock rates or word sizes from initial values. This function changes those settings, and must be called from a context that can sleep. Except for SPI_CS_HIGH, which takes effect immediately, the changes take effect the next time the device is selected and data is transferred to or from it. When this function returns, the spi device is deselected.

Note that this call will fail if the protocol driver specifies an option that the underlying controller or its driver does not support. For example, not all hardware supports wire transfers using nine bit words, LSB-first wire encoding, or active-high chipselects.

  • spi_async - asynchronous SPI transfer

Synopsis:

int spi_async ( struct spi_device * spi )

Arguments:

  • spi - device with which data will be exchanged
  • message - describes the data transfers, including completion callback

Context:

any (irqs may be blocked, etc)

Description:

This call may be used in_irq and other contexts which can't sleep, as well as from task contexts which can sleep.

The completion callback is invoked in a context which can't sleep. Before that invocation, the value of message→status is undefined. When the callback is issued, message→status holds either zero (to indicate complete success) or a negative error code. After that callback returns, the driver which issued the transfer request may deallocate the associated memory; it's no longer in use by any SPI core or controller driver code.

Note that although all messages to a spi_device are handled in FIFO order, messages may go to different devices in other orders. Some device might be higher priority, or have various hard access time requirements, for example.

On detection of any fault during the transfer, processing of the entire message is aborted, and the device is deselected. Until returning from the associated message completion callback, no other spi_message queued to that device will be processed. (This rule applies equally to all the synchronous transfer calls, which are wrappers around this core asynchronous primitive.)

  • spi_lock_bus - lock SPI bus for exclusive access

Synopsis:

int spi_lock_bus ( struct spi_device * spi )

Arguments:

  • spi - device which want to lock the bus

Context:

any

Description:

Once the caller owns exclusive access to the SPI bus, only messages for this device will be transferred. Messages for other devices are queued but not transferred until the bus owner unlock the bus.

The caller may call spi_lock_bus before spi_sync or spi_async. So this call may be used in irq and other contexts which can't sleep, as well as from task contexts which can sleep.

It returns zero on success, else a negative error code: -ENOSYS: spi master driver does not implement this function -ENOLCK: cannot lock the bus

  • spi_unlock_bus - unlock SPI bus

Synopsis:

int spi_unlock_bus ( struct spi_device * spi )

Arguments:

  • spi - device which want to unlock the bus

Context:

any

Description:

The caller has called spi_lock_bus to lock the bus. It calls spi_unlock_bus to release the bus so messages for other devices can be transferred.

If the caller did not call spi_lock_bus before, spi_unlock_bus will return -ENOLCK.

It returns zero on success, else a negative error code: -ENOSYS: spi master driver does not implement this function -ENOLCK: cannot unlock the bus

  • spi_sync - blocking/synchronous SPI data transfers

Synopsis:

int spi_sync ( struct spi_device * spi )

Arguments:

  • spi - device with which data will be exchanged
  • message - describes the data transfers

Context:

can sleep

Description:

This call may only be used from a context that may sleep. The sleep is non-interruptible, and has no timeout. Low-overhead controller drivers may DMA directly into and out of the message buffers.

Note that the SPI device's chip select is active during the message, and then is normally disabled between messages. Drivers for some frequently-used devices may want to minimize costs of selecting a chip, by leaving it selected in anticipation that the next message will go to the same chip. (That may increase power usage.)

Also, the caller is guaranteeing that the memory associated with the message will not be freed before this call returns.

It returns zero on success, else a negative error code.

  • spi_write_then_read - SPI synchronous write followed by read

Synopsis:

int spi_write_then_read ( struct spi_device * spi )

Arguments:

  • spi - device with which data will be exchanged
  • txbuf - data to be written (need not be dma-safe)
  • n_tx - size of txbuf, in bytes
  • rxbuf - buffer into which data will be read (need not be dma-safe)
  • n_rx - size of rxbuf, in bytes

Context:

can sleep

Description:

This performs a half duplex MicroWire style transaction with the device, sending txbuf and then reading rxbuf. The return value is zero for success, else a negative errno status code. This call may only be used from a context that may sleep.

Parameters to this routine are always copied using a small buffer; portable code should never use this for more than 32 bytes. Performance-sensitive or bulk transfer code should instead use spi_{async,sync}() calls with dma-safe buffers.

I2C and SMBus Subsystem

I2C (or without fancy typography, “I2C”) is an acronym for the “Inter-IC” bus, a simple bus protocol which is widely used where low data rate communications suffice. Since it's also a licensed trademark, some vendors use another name (such as “Two-Wire Interface”, TWI) for the same bus. I2C only needs two signals (SCL for clock, SDA for data), conserving board real estate and minimizing signal quality issues. Most I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet found wide use. I2C is a multi-master bus; open drain signaling is used to arbitrate between masters, as well as to handshake and to synchronize clocks from slower clients.

The Linux I2C programming interfaces support only the master side of bus interactions, not the slave side. The programming interface is structured around two kinds of driver, and two kinds of device. An I2C “Adapter Driver” abstracts the controller hardware; it binds to a physical device (perhaps a PCI device or platform_device) and exposes a struct i2c_adapter representing each I2C bus segment it manages. On each I2C bus segment will be I2C devices represented by a struct i2c_client. Those devices will be bound to a struct i2c_driver, which should follow the standard Linux driver model. (At this writing, a legacy model is more widely used.) There are functions to perform various I2C protocol operations; at this writing all such functions are usable only from task context.

The System Management Bus (SMBus) is a sibling protocol. Most SMBus systems are also I2C conformant. The electrical constraints are tighter for SMBus, and it standardizes particular protocol messages and idioms. Controllers that support I2C can also support most SMBus operations, but SMBus controllers don't support all the protocol options that an I2C controller will. There are functions to perform various SMBus protocol operations, either using I2C primitives or by issuing SMBus commands to i2c_adapter devices which don't support those I2C operations.

  • struct i2c_driver - represent an I2C device driver

Synopsis:

struct i2c_driver {
  unsigned int class;
  int (* attach_adapter) (struct i2c_adapter *);
  int (* detach_adapter) (struct i2c_adapter *);
  int (* probe) (struct i2c_client *, const struct i2c_device_id *);
  int (* remove) (struct i2c_client *);
  void (* shutdown) (struct i2c_client *);
  int (* suspend) (struct i2c_client *, pm_message_t mesg);
  int (* resume) (struct i2c_client *);
  int (* command) (struct i2c_client *client, unsigned int cmd, void *arg);
  struct device_driver driver;
  const struct i2c_device_id * id_table;
  int (* detect) (struct i2c_client *, int kind, struct i2c_board_info *);
  const struct i2c_client_address_data * address_data;
  struct list_head clients;
};  

Members:

  • class - What kind of i2c device we instantiate (for detect)
  • attach_adapter - Callback for bus addition (for legacy drivers)
  • detach_adapter - Callback for bus removal (for legacy drivers)
  • probe - Callback for device binding
  • remove - Callback for device unbinding
  • shutdown - Callback for device shutdown
  • suspend - Callback for device suspend
  • resume - Callback for device resume
  • command - Callback for bus-wide signaling (optional)
  • driver - Device driver model driver
  • id_table - List of I2C devices supported by this driver
  • detect - Callback for device detection
  • address_data - The I2C addresses to probe, ignore or force (for detect)
  • clients - List of detected clients we created (for i2c-core use only)

Description:

The driver.owner field should be set to the module owner of this driver. The driver.name field should be set to the name of this driver.

For automatic device detection, both detect and address_data must be defined. class should also be set, otherwise only devices forced with module parameters will be created. The detect function must fill at least the name field of the i2c_board_info structure it is handed upon successful detection, and possibly also the flags field.

If detect is missing, the driver will still work fine for enumerated devices. Detected devices simply won't be supported. This is expected for the many I2C/SMBus devices which can't be detected reliably, and the ones which can always be enumerated in practice.

The i2c_client structure which is handed to the detect callback is not a real i2c_client. It is initialized just enough so that you can call i2c_smbus_read_byte_data and friends on it. Don't do anything else with it. In particular, calling dev_dbg and friends on it is not allowed.

  • struct i2c_client - represent an I2C slave device

Synopsis:

struct i2c_client {
  unsigned short flags;
  unsigned short addr;
  char name[I2C_NAME_SIZE];
  struct i2c_adapter * adapter;
  struct i2c_driver * driver;
  struct device dev;
  int irq;
  unsigned long irq_flags;
  struct list_head detected;
};  

Members:

  • flags - I2C_CLIENT_TEN indicates the device uses a ten bit chip address; I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking
  • addr - Address used on the I2C bus connected to the parent adapter.
  • name[I2C_NAME_SIZE] - Indicates the type of the device, usually a chip name that's generic enough to hide second-sourcing and compatible revisions.
  • adapter - manages the bus segment hosting this I2C device
  • driver - device's driver, hence pointer to access routines
  • dev - Driver model device node for the slave.
  • irq - indicates the IRQ generated by this device (if any)
  • irq_flags - The flags passed to request_irq
  • detected - member of an i2c_driver.clients list or i2c-core's userspace_devices list

Description:

An i2c_client identifies a single device (i.e. chip) connected to an i2c bus. The behaviour exposed to Linux is defined by the driver managing the device.

  • struct i2c_board_info - template for device creation

Synopsis:

struct i2c_board_info {
  char type[I2C_NAME_SIZE];
  unsigned short flags;
  unsigned short addr;
  void * platform_data;
  struct dev_archdata * archdata;
  int irq;
  unsigned long irq_flags;
};  

Members:

  • type[I2C_NAME_SIZE] - chip type, to initialize i2c_client.name
  • flags - to initialize i2c_client.flags
  • addr - stored in i2c_client.addr
  • platform_data - stored in i2c_client.dev.platform_data
  • archdata - copied into i2c_client.dev.archdata
  • irq - stored in i2c_client.irq
  • irq_flags - The flags passed to request_irq for i2c_client.irq

Description:

I2C doesn't actually support hardware probing, although controllers and devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's a device at a given address. Drivers commonly need more information than that, such as chip type, configuration, associated IRQ, and so on.

i2c_board_info is used to build tables of information listing I2C devices that are present. This information is used to grow the driver model tree. For mainboards this is done statically using i2c_register_board_info; bus numbers identify adapters that aren't yet available. For add-on boards, i2c_new_device does this dynamically with the adapter already known.

  • I2C_BOARD_INFO - macro used to list an i2c device and its address

Synopsis:

I2C_BOARD_INFO ( dev_type )

Arguments:

  • dev_type - identifies the device type
  • dev_addr - the device's address on the bus.

Description:

This macro initializes essential fields of a struct i2c_board_info, declaring what has been provided on a particular board. Optional fields (such as associated irq, or device-specific platform_data) are provided using conventional syntax.

  • i2c_lock_adapter - Prevent access to an I2C bus segment

Synopsis:

void i2c_lock_adapter ( struct i2c_adapter * adapter )

Arguments:

  • adapter - Target I2C bus segment
  • i2c_unlock_adapter - Reauthorize access to an I2C bus segment

Synopsis:

void i2c_unlock_adapter ( struct i2c_adapter * adapter )

Arguments:

  • adapter - Target I2C bus segment
  • struct i2c_msg - an I2C transaction segment beginning with START

Synopsis:

struct i2c_msg {
  __u16 addr;
  __u16 flags;
#define I2C_M_TEN		0x0010
#define I2C_M_RD		0x0001
#define I2C_M_NOSTART		0x4000
#define I2C_M_REV_DIR_ADDR	0x2000
#define I2C_M_IGNORE_NAK	0x1000
#define I2C_M_NO_RD_ACK		0x0800
#define I2C_M_RECV_LEN		0x0400
  __u16 len;
  __u8 * buf;
};  

Members:

  • addr - Slave address, either seven or ten bits. When this is a ten bit address, I2C_M_TEN must be set in flags and the adapter must support I2C_FUNC_10BIT_ADDR.
  • flags - I2C_M_RD is handled by all adapters. No other flags may be provided unless the adapter exported the relevant I2C_FUNC_* flags through i2c_check_functionality.
  • len - Number of data bytes in buf being read from or written to the I2C slave address. For read transactions where I2C_M_RECV_LEN is set, the caller guarantees that this buffer can hold up to 32 bytes in addition to the initial length byte sent by the slave (plus, if used, the SMBus PEC); and this value will be incremented by the number of block data bytes received.
  • buf - The buffer into which data is read, or from which it's written.

Description:

An i2c_msg is the low level representation of one segment of an I2C transaction. It is visible to drivers in the i2c_transfer() procedure, to userspace from i2c-dev, and to I2C adapter drivers through the i2c_adapter.master_xfer() method.

Except when I2C protocol mangling is used, all I2C adapters implement the standard rules for I2C transactions. Each transaction begins with a START. That is followed by the slave address, and a bit encoding read versus write. Then follow all the data bytes, possibly including a byte with SMBus PEC. The transfer terminates with a NAK, or when all those bytes have been transferred and ACKed. If this is the last message in a group, it is followed by a STOP. Otherwise it is followed by the next i2c_msg transaction segment, beginning with a (repeated) START.

Alternatively, when the adapter supports I2C_FUNC_PROTOCOL_MANGLING then passing certain flags may have changed those standard protocol behaviors. Those flags are only for use with broken/nonconforming slaves, and with adapters which are known to support the specific mangling options they need (one or more of IGNORE_NAK, NO_RD_ACK, NOSTART, and REV_DIR_ADDR).

  • i2c_register_board_info - statically declare I2C devices

Synopsis:

int i2c_register_board_info ( int busnum )

Arguments:

  • busnum - identifies the bus to which these devices belong
  • info - vector of i2c device descriptors
  • len - how many descriptors in the vector; may be zero to reserve the specified bus number.

Description:

Systems using the Linux I2C driver stack can declare tables of board info while they initialize. This should be done in board-specific init code near arch_initcall time, or equivalent, before any I2C adapter driver is registered. For example, mainboard init code could define several devices, as could the init code for each daughtercard in a board stack.

The I2C devices will be created later, after the adapter for the relevant bus has been registered. After that moment, standard driver model tools are used to bind new style I2C drivers to the devices. The bus number for any device declared using this routine is not available for dynamic allocation.

The board info passed can safely be __initdata, but be careful of embedded pointers (for platform_data, functions, etc) since that won't be copied.

  • i2c_verify_client - return parameter as i2c_client, or NULL

Synopsis:

struct i2c_client * i2c_verify_client ( struct device * dev )

Arguments:

  • dev - device, probably from some driver model iterator

Description:

When traversing the driver model tree, perhaps using driver model iterators like device_for_each_child(), you can't assume very much about the nodes you find. Use this function to avoid oopses caused by wrongly treating some non-I2C device as an i2c_client.

  • i2c_new_device - instantiate an i2c device

Synopsis:

struct i2c_client * i2c_new_device ( struct i2c_adapter * adap )

Arguments:

  • adap - the adapter managing the device
  • info - describes one I2C device; bus_num is ignored

Context:

can sleep

Description:

Create an i2c device. Binding is handled through driver model probe/remove methods. A driver may be bound to this device when we return from this function, or any later moment (e.g. maybe hotplugging will load the driver module). This call is not appropriate for use by mainboard initialization logic, which usually runs during an arch_initcall long before any i2c_adapter could exist.

This returns the new i2c client, which may be saved for later use with i2c_unregister_device; or NULL to indicate an error.

  • i2c_unregister_device - reverse effect of i2c_new_device

Synopsis:

void i2c_unregister_device ( struct i2c_client * client )

Arguments:

  • client - value returned from i2c_new_device

Context:

can sleep

  • i2c_new_dummy - return a new i2c device bound to a dummy driver

Synopsis:

struct i2c_client * i2c_new_dummy ( struct i2c_adapter * adapter )

Arguments:

  • adapter - the adapter managing the device
  • address - seven bit address to be used

Context:

can sleep

Description:

This returns an I2C client bound to the dummy driver, intended for use with devices that consume multiple addresses. Examples of such chips include various EEPROMS (like 24c04 and 24c08 models).

These dummy devices have two main uses. First, most I2C and SMBus calls except i2c_transfer need a client handle; the dummy will be that handle. And second, this prevents the specified address from being bound to a different driver.

This returns the new i2c client, which should be saved for later use with i2c_unregister_device; or NULL to indicate an error.

  • i2c_add_adapter - declare i2c adapter, use dynamic bus number

Synopsis:

int i2c_add_adapter ( struct i2c_adapter * adapter )

Arguments:

  • adapter - the adapter to add

Context:

can sleep

Description:

This routine is used to declare an I2C adapter when its bus number doesn't matter. Examples: for I2C adapters dynamically added by USB links or PCI plugin cards.

When this returns zero, a new bus number was allocated and stored in adap→nr, and the specified adapter became available for clients. Otherwise, a negative errno value is returned.

  • i2c_add_numbered_adapter - declare i2c adapter, use static bus number

Synopsis:

int i2c_add_numbered_adapter ( struct i2c_adapter * adap )

Arguments:

  • adap - the adapter to register (with adap→nr initialized)

Context:

can sleep

Description:

This routine is used to declare an I2C adapter when its bus number matters. For example, use it for I2C adapters from system-on-chip CPUs, or otherwise built in to the system's mainboard, and where i2c_board_info is used to properly configure I2C devices.

If no devices have pre-been declared for this bus, then be sure to register the adapter before any dynamically allocated ones. Otherwise the required bus ID may not be available.

When this returns zero, the specified adapter became available for clients using the bus number provided in adap→nr. Also, the table of I2C devices pre-declared using i2c_register_board_info is scanned, and the appropriate driver model device nodes are created. Otherwise, a negative errno value is returned.

  • i2c_del_adapter - unregister I2C adapter

Synopsis:

int i2c_del_adapter ( struct i2c_adapter * adap )

Arguments:

  • adap - the adapter being unregistered

Context:

can sleep

Description:

This unregisters an I2C adapter which was previously registered by i2c_add_adapter or i2c_add_numbered_adapter.

  • i2c_del_driver - unregister I2C driver

Synopsis:

void i2c_del_driver ( struct i2c_driver * driver )

Arguments:

  • driver - the driver being unregistered

Context:

can sleep

  • i2c_use_client - increments the reference count of the i2c client structure

Synopsis:

struct i2c_client * i2c_use_client ( struct i2c_client * client )

Arguments:

  • client - the client being referenced

Description:

Each live reference to a client should be refcounted. The driver model does that automatically as part of driver binding, so that most drivers don't

need to do this explicitly:

they hold a reference until they're unbound from the device.

A pointer to the client with the incremented reference counter is returned.

  • i2c_release_client - release a use of the i2c client structure

Synopsis:

void i2c_release_client ( struct i2c_client * client )

Arguments:

  • client - the client being no longer referenced

Description:

Must be called when a user of a client is finished with it.

  • i2c_transfer - execute a single or combined I2C message

Synopsis:

int i2c_transfer ( struct i2c_adapter * adap )

Arguments:

  • adap - Handle to I2C bus
  • msgs - One or more messages to execute before STOP is issued to terminate the operation; each message begins with a START.
  • num - Number of messages to be executed.

Description:

Returns negative errno, else the number of messages executed.

Note that there is no requirement that each message be sent to the same slave address, although that is the most common model.

  • i2c_master_send - issue a single I2C message in master transmit mode

Synopsis:

int i2c_master_send ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • buf - Data that will be written to the slave
  • count - How many bytes to write

Description:

Returns negative errno, or else the number of bytes written.

  • i2c_master_recv - issue a single I2C message in master receive mode

Synopsis:

int i2c_master_recv ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • buf - Where to store data read from slave
  • count - How many bytes to read

Description:

Returns negative errno, or else the number of bytes read.

  • i2c_smbus_read_byte - SMBus receive byte protocol

Synopsis:

s32 i2c_smbus_read_byte ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device

Description:

This executes the SMBus receive byte protocol, returning negative errno else the byte received from the device.

  • i2c_smbus_write_byte - SMBus send byte protocol

Synopsis:

s32 i2c_smbus_write_byte ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • value - Byte to be sent

Description:

This executes the SMBus send byte protocol, returning negative errno else zero on success.

  • i2c_smbus_read_byte_data - SMBus read byte protocol

Synopsis:

s32 i2c_smbus_read_byte_data ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave

Description:

This executes the SMBus read byte protocol, returning negative errno else a data byte received from the device.

  • i2c_smbus_write_byte_data - SMBus write byte protocol

Synopsis:

s32 i2c_smbus_write_byte_data ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave
  • value - Byte being written

Description:

This executes the SMBus write byte protocol, returning negative errno else zero on success.

  • i2c_smbus_read_word_data - SMBus read word protocol

Synopsis:

s32 i2c_smbus_read_word_data ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave

Description:

This executes the SMBus read word protocol, returning negative errno else a 16-bit unsigned word received from the device.

  • i2c_smbus_write_word_data - SMBus write word protocol

Synopsis:

s32 i2c_smbus_write_word_data ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave
  • value - 16-bit word being written

Description:

This executes the SMBus write word protocol, returning negative errno else zero on success.

  • i2c_smbus_process_call - SMBus process call protocol

Synopsis:

s32 i2c_smbus_process_call ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave
  • value - 16-bit word being written

Description:

This executes the SMBus process call protocol, returning negative errno else a 16-bit unsigned word received from the device.

  • i2c_smbus_read_block_data - SMBus block read protocol

Synopsis:

s32 i2c_smbus_read_block_data ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave
  • values - Byte array into which data will be read; big enough to hold the data returned by the slave. SMBus allows at most 32 bytes.

Description:

This executes the SMBus block read protocol, returning negative errno else the number of data bytes in the slave's response.

Note that using this function requires that the client's adapter support the I2C_FUNC_SMBUS_READ_BLOCK_DATA functionality. Not all adapter drivers support this; its emulation through I2C messaging relies on a specific mechanism (I2C_M_RECV_LEN) which may not be implemented.

  • i2c_smbus_write_block_data - SMBus block write protocol

Synopsis:

s32 i2c_smbus_write_block_data ( struct i2c_client * client )

Arguments:

  • client - Handle to slave device
  • command - Byte interpreted by slave
  • length - Size of data block; SMBus allows at most 32 bytes
  • values - Byte array which will be written.

Description:

This executes the SMBus block write protocol, returning negative errno else zero on success.

  • i2c_smbus_xfer - execute SMBus protocol operations

Synopsis:

s32 i2c_smbus_xfer ( struct i2c_adapter * adapter )

Arguments:

  • adapter - Handle to I2C bus
  • addr - Address of SMBus slave on that bus
  • flags - I2C_CLIENT_* flags (usually zero or I2C_CLIENT_PEC)
  • read_write - I2C_SMBUS_READ or I2C_SMBUS_WRITE
  • command - Byte interpreted by slave, for protocols which use such bytes
  • protocol - SMBus protocol operation to execute, such as I2C_SMBUS_PROC_CALL
  • data - Data to be read or written

Description:

This executes an SMBus protocol operation, and returns a negative errno code else zero on success.

About This Book

Authors

Legal Notice

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of Linux.