The Linux Kernel API

Chapter 8. Network device support

sppp_do_ioctl

Name

sppp_do_ioctl - Ioctl handler for ppp/hdlc

Synopsis

int sppp_do_ioctl (struct net_device * dev, struct ifreq * ifr,

int cmd);

Arguments

dev

Device subject to ioctl

ifr

Interface request block from the user

cmd

Command that is being issued

Description

This function handles the ioctls that may be issued by the user to control the settings of

a PPP/HDLC link. It does both busy and security checks. This function is intended to

220

Chapter 8. Network device support

be wrapped by callers who wish to add additional ioctl calls of their own.

sppp_attach

Name

sppp_attach - attach synchronous PPP/HDLC to a device

Synopsis

void sppp_attach (struct ppp_device * pd);

Arguments

PPP device to initialise

Description

This initialises the PPP/HDLC support on an interface. At the time of calling the dev

element must point to the network device that this interface is attached to. The interface

should not yet be registered.

221

Chapter 9. Module Loading

request_module

Name

request_module - try to load a kernel module

Synopsis

int request_module (const char * module_name);

Arguments

module_name

Name of module

Description

Load a module using the user mode module loader. The function returns zero on

success or a negative errno code on failure. Note that a successful module load does not

mean the module did not then unload and exit on an error of its own. Callers must

check that the service they requested is now available not blindly invoke it.

If module auto-loading support is disabled then this function becomes a no-operation.

223

Chapter 10. Hardware Interfaces

10.1. Interrupt Handling

disable_irq_nosync

Name

disable_irq_nosync - disable an irq without waiting

Synopsis

void disable_irq_nosync (unsigned int irq);

Arguments

irq

Interrupt to disable

Description

Disable the selected interrupt line. Disables and Enables are nested. Unlike

disable_irq, this function does not ensure existing instances of the IRQ handler

226

Chapter 10. Hardware Interfaces

have completed before returning.

This function may be called from IRQ context.

disable_irq

Name

disable_irq - disable an irq and wait for completion

Synopsis

void disable_irq (unsigned int irq);

Arguments

irq

Interrupt to disable

Description

Disable the selected interrupt line. Enables and Disables are nested. This function waits

for any pending IRQ handlers for this interrupt to complete before returning. If you use

this function while holding a resource the IRQ handler may need you will deadlock.

227

Chapter 10. Hardware Interfaces

This function may be called - with care - from IRQ context.

enable_irq

Name

enable_irq - enable handling of an irq

Synopsis

void enable_irq (unsigned int irq);

Arguments

irq

Interrupt to enable

Description

Undoes the effect of one call to disable_irq. If this matches the last disable,

processing of interrupts on this IRQ line is re-enabled.

This function may be called from IRQ context.

228

Chapter 10. Hardware Interfaces

probe_irq_mask

Name

probe_irq_mask - scan a bitmap of interrupt lines

Synopsis

unsigned int probe_irq_mask (unsigned long val);

Arguments

val

mask of interrupts to consider

Description

Scan the ISA bus interrupt lines and return a bitmap of active interrupts. The interrupt

probe logic state is then returned to its previous value.

229

Chapter 10. Hardware Interfaces

Note

we need to scan all the irq’s even though we will only return ISA irq numbers - just so

that we reset them all to a known state.

10.2. MTRR Handling

mtrr_add

Name

mtrr_add - Add a memory type region

Synopsis

int mtrr_add (unsigned long base, unsigned long size, unsigned

int type, char increment);

Arguments

base

Physical base address of region

230

Chapter 10. Hardware Interfaces

size

Physical size of region

type

Type of MTRR desired

increment

If this is true do usage counting on the region

Description

Memory type region registers control the caching on newer Intel and non Intel

processors. This function allows drivers to request an MTRR is added. The details and

hardware specifics of each processor’s implementation are hidden from the caller, but

nevertheless the caller should expect to need to provide a power of two size on an

equivalent power of two boundary.

If the region cannot be added either because all regions are in use or the CPU cannot

support it a negative value is returned. On success the register number for this entry is

returned, but should be treated as a cookie only.

On a multiprocessor machine the changes are made to all processors. This is required

on x86 by the Intel processors.

The available types are

MTRR_TYPE_UNCACHABLE - No caching

MTRR_TYPE_WRBACK - Write data back in bursts whenever

MTRR_TYPE_WRCOMB - Write data back soon but allow bursts

MTRR_TYPE_WRTHROUGH - Cache reads but not writes

231

Chapter 10. Hardware Interfaces

size

Size of region

Description

If register is supplied then base and size are ignored. This is how drivers should call it.

Releases an MTRR region. If the usage count drops to zero the register is freed and the

region returns to default state. On success the register is returned, on failure a negative

error code.

10.3. PCI Support Library

pci_find_slot

Name

pci_find_slot - locate PCI device from a given PCI slot

Synopsis

struct pci_dev * pci_find_slot (unsigned int bus, unsigned int

devfn);

233

Chapter 10. Hardware Interfaces

Arguments

bus

number of PCI bus on which desired PCI device resides

devfn

encodes number of PCI slot in which the desired PCI device resides and the

logical device number within that slot in case of multi-function devices.

Description

Given a PCI bus and slot/function number, the desired PCI device is located in system

global list of PCI devices. If the device is found, a pointer to its data structure is

returned. If no device is found, NULL is returned.

pci_find_subsys

Name

pci_find_subsys - begin or continue searching for a PCI device by

vendor/subvendor/device/subdevice id

Synopsis

struct pci_dev * pci_find_subsys (unsigned int vendor, unsigned

int device, unsigned int ss_vendor, unsigned int ss_device,

234

Chapter 10. Hardware Interfaces

const struct pci_dev * from);

Arguments

vendor

PCI vendor id to match, or PCI_ANY_ID to match all vendor ids

device

PCI device id to match, or PCI_ANY_ID to match all device ids

ss_vendor

PCI subsystem vendor id to match, or PCI_ANY_ID to match all vendor ids

ss_device

PCI subsystem device id to match, or PCI_ANY_ID to match all device ids

from

Previous PCI device found in search, or NULL for new search.

Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching

vendor, device, ss_vendor and ss_device, a pointer to its device structure is

returned. Otherwise, NULL is returned. A new search is initiated by passing NULL to the

from argument. Otherwise if from is not NULL, searches continue from next device on

the global list.

235

Chapter 10. Hardware Interfaces

pci_find_device

Name

pci_find_device - begin or continue searching for a PCI device by

vendor/device id

Synopsis

struct pci_dev * pci_find_device (unsigned int vendor, unsigned

int device, const struct pci_dev * from);

Arguments

vendor

PCI vendor id to match, or PCI_ANY_ID to match all vendor ids

device

PCI device id to match, or PCI_ANY_ID to match all device ids

from

Previous PCI device found in search, or NULL for new search.

236

Chapter 10. Hardware Interfaces

Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching

vendor and device, a pointer to its device structure is returned. Otherwise, NULL is

returned. A new search is initiated by passing NULL to the from argument. Otherwise

if from is not NULL, searches continue from next device on the global list.

pci_find_class

Name

pci_find_class - begin or continue searching for a PCI device by class

Synopsis

struct pci_dev * pci_find_class (unsigned int class, const

struct pci_dev * from);

Arguments

class

search for a PCI device with this class designation

237

Chapter 10. Hardware Interfaces

from

Previous PCI device found in search, or NULL for new search.

Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching

class, a pointer to its device structure is returned. Otherwise, NULL is returned. A new

search is initiated by passing NULL to the from argument. Otherwise if from is not

NULL, searches continue from next device on the global list.

pci_find_capability

Name

pci_find_capability— query for devices’ capabilities

Synopsis

int pci_find_capability (struct pci_dev * dev, int cap);

238

Chapter 10. Hardware Interfaces

Arguments

dev

PCI device to query

cap

capability code

Description

Tell if a device supports a given PCI capability. Returns the address of the requested

capability structure within the device’s PCI configuration space or 0 in case the device

does not support it. Possible values for cap:

PCI_CAP_ID_PM Power Management

PCI_CAP_ID_AGP Accelerated Graphics Port

PCI_CAP_ID_VPD Vital Product Data

PCI_CAP_ID_SLOTID Slot Identification

PCI_CAP_ID_MSI Message Signalled Interrupts

PCI_CAP_ID_CHSWP CompactPCI HotSwap

pci_find_parent_resource

Name

pci_find_parent_resource - return resource region of parent bus of given

239

Chapter 10. Hardware Interfaces

region

Synopsis

struct resource * pci_find_parent_resource (const struct pci_dev

* dev, struct resource * res);

Arguments

dev

PCI device structure contains resources to be searched

res

child resource record for which parent is sought

Description

For given resource region of given device, return the resource region of parent bus the

given region is contained in or where it should be allocated from.

240

Chapter 10. Hardware Interfaces

pci_set_power_state

Name

pci_set_power_state - Set power management state of a device.

Synopsis

int pci_set_power_state (struct pci_dev * dev, int new_state);

Arguments

dev

PCI device for which PM is set

new_state

new power management statement (0 == D0, 3 == D3, etc.)

Description

Set power management state of a device. For transitions from state D3 it isn’t as

straightforward as one could assume since many devices forget their configuration

space during wakeup. Returns old power state.

241

Chapter 10. Hardware Interfaces

pci_enable_device

Name

pci_enable_device - Initialize device before it’s used by a driver.

Synopsis

int pci_enable_device (struct pci_dev * dev);

Arguments

dev

PCI device to be initialized

Description

Initialize device before it’s used by a driver. Ask low-level code to enable I/O and

memory. Wake up the device if it was suspended. Beware, this function can fail.

242

Chapter 10. Hardware Interfaces

pci_release_regions

Name

pci_release_regions— Release reserved PCI I/O and memory resources

Synopsis

void pci_release_regions (struct pci_dev * pdev);

Arguments

pdev

PCI device whose resources were previously reserved by pci_request_regions

Description

Releases all PCI I/O and memory resources previously reserved by a successful call to

pci_request_regions. Call this function only after all use of the PCI regions has ceased.

244

Chapter 10. Hardware Interfaces

pci_request_regions

Name

pci_request_regions— Reserved PCI I/O and memory resources

Synopsis

int pci_request_regions (struct pci_dev * pdev, char *

res_name);

Arguments

pdev

PCI device whose resources are to be reserved

res_name

-- undescribed --

Description

Mark all PCI regions associated with PCI device pdev as being reserved by owner

res_name. Do not access any address inside the PCI regions unless this call returns

successfully.

Returns 0 on success, or EBUSY on error. A warning message is also printed on failure.

245

Chapter 10. Hardware Interfaces

pci_match_device

Name

pci_match_device - Tell if a PCI device structure has a matching PCI device id

structure

Synopsis

const struct pci_device_id * pci_match_device (const struct

pci_device_id * ids, const struct pci_dev * dev);

Arguments

ids

array of PCI device id structures to search in

dev

the PCI device structure to match against

246

Chapter 10. Hardware Interfaces

Description

Used by a driver to check whether a PCI device present in the system is in its list of

supported devices.Returns the matching pci_device_id structure or NULL if there is no

match.

pci_register_driver

Name

pci_register_driver - register a new pci driver

Synopsis

int pci_register_driver (struct pci_driver * drv);

Arguments

drv

the driver structure to register

247

Chapter 10. Hardware Interfaces

Description

Adds the driver structure to the list of registered drivers Returns the number of pci

devices which were claimed by the driver during registration. The driver remains

registered even if the return value is zero.

pci_unregister_driver

Name

pci_unregister_driver - unregister a pci driver

Synopsis

void pci_unregister_driver (struct pci_driver * drv);

Arguments

drv

the driver structure to unregister

248

Chapter 10. Hardware Interfaces

Description

Deletes the driver structure from the list of registered PCI drivers, gives it a chance to

clean up by calling its remove function for each device it was responsible for, and

marks those devices as driverless.

pci_insert_device

Name

pci_insert_device— insert a hotplug device

Synopsis

void pci_insert_device (struct pci_dev * dev, struct pci_bus *

bus);

Arguments

dev

the device to insert

bus

where to insert it

249

Chapter 10. Hardware Interfaces

Description

Add a new device to the device lists and notify userspace (/sbin/hotplug).

pci_remove_device

Name

pci_remove_device— remove a hotplug device

Synopsis

void pci_remove_device (struct pci_dev * dev);

Arguments

dev

the device to remove

Description

Delete the device structure from the device lists and notify userspace (/sbin/hotplug).

250

Chapter 10. Hardware Interfaces

pci_setup_device

Name

pci_setup_device - fill in class and map information of a device

Synopsis

int pci_setup_device (struct pci_dev * dev);

Arguments

dev

the device structure to fill

Description

Initialize the device structure with information about the device’s vendor,class,memory

and IO-space addresses,IRQ lines etc. Called at initialisation of the PCI subsystem and

by CardBus services. Returns 0 on success and -1 if unknown type of device (not

normal, bridge or CardBus).

253

Chapter 10. Hardware Interfaces

pci_pool_create

Name

pci_pool_create - Creates a pool of pci consistent memory blocks, for dma.

Synopsis

struct pci_pool * pci_pool_create (const char * name, struct

pci_dev * pdev, size_t size, size_t align, size_t allocation,

int flags);

Arguments

name

name of pool, for diagnostics

pdev

pci device that will be doing the DMA

size

size of the blocks in this pool.

align

alignment requirement for blocks; must be a power of two

254

Chapter 10. Hardware Interfaces

allocation

returned blocks won’t cross this boundary (or zero)

flags

SLAB_* flags (not all are supported).

Description

Returns a pci allocation pool with the requested characteristics, or null if one can’t be

created. Given one of these pools, pci_pool_alloc may be used to allocate memory.

Such memory will all have “consistent” DMA mappings, accessible by the device and

its driver without using cache flushing primitives. The actual size of blocks allocated

may be larger than requested because of alignment.

If allocation is nonzero, objects returned from pci_pool_alloc won’t cross that size

boundary. This is useful for devices which have addressing restrictions on individual

DMA transfers, such as not crossing boundaries of 4KBytes.

pci_pool_destroy

Name

pci_pool_destroy - destroys a pool of pci memory blocks.

Synopsis

void pci_pool_destroy (struct pci_pool * pool);

255

Chapter 10. Hardware Interfaces

Arguments

pool

pci pool that will be destroyed

Description

Caller guarantees that no more memory from the pool is in use, and that nothing will

try to use the pool after this call.

pci_pool_alloc

Name

pci_pool_alloc - get a block of consistent memory

Synopsis

void * pci_pool_alloc (struct pci_pool * pool, int mem_flags,

dma_addr_t * handle);

256

Chapter 10. Hardware Interfaces

Arguments

pool

pci pool that will produce the block

mem_flags

SLAB_KERNEL or SLAB_ATOMIC

handle

pointer to dma address of block

Description

This returns the kernel virtual address of a currently unused block, and reports its dma

address through the handle. If such a memory block can’t be allocated, null is returned.

pci_pool_free

Name

pci_pool_free - put block back into pci pool

Synopsis

void pci_pool_free (struct pci_pool * pool, void * vaddr,

257

Chapter 10. Hardware Interfaces

Description

Search the MCA configuration for adapters matching the 16bit ID given. The first time

it should be called with start as zero and then further calls made passing the return

value of the previous call until MCA_NOTFOUND is returned.

Disabled adapters are not reported.

mca_find_unused_adapter

Name

mca_find_unused_adapter— scan for unused adapters

Synopsis

int mca_find_unused_adapter (int id, int start);

Arguments

MCA identification to search for

start

starting slot

260

Chapter 10. Hardware Interfaces

Description

Search the MCA configuration for adapters matching the 16bit ID given. The first time

it should be called with start as zero and then further calls made passing the return

value of the previous call until MCA_NOTFOUND is returned.

Adapters that have been claimed by drivers and those that are disabled are not reported.

This function thus allows a driver to scan for further cards when some may already be

driven.

mca_read_stored_pos

Name

mca_read_stored_pos - read POS register from boot data

Synopsis

unsigned char mca_read_stored_pos (int slot, int reg);

Arguments

slot

slot number to read from

261

Chapter 10. Hardware Interfaces

reg

Description

Fetch a POS value that was stored at boot time by the kernel when it scanned the MCA

space. The register value is returned. Missing or invalid registers report 0.

mca_read_pos

Name

mca_read_pos - read POS register from card

Synopsis

unsigned char mca_read_pos (int slot, int reg);

Arguments

slot

slot number to read from

262

Chapter 10. Hardware Interfaces

reg

Description

Fetch a POS value directly from the hardware to obtain the current value. This is much

slower than mca_read_stored_pos and may not be invoked from interrupt context. It

handles the deep magic required for onboard devices transparently.

mca_write_pos

Name

mca_write_pos - read POS register from card

Synopsis

void mca_write_pos (int slot, int reg, unsigned char byte);

Arguments

slot

slot number to read from

263

Chapter 10. Hardware Interfaces

reg

byte

byte to write to the POS registers

Description

Store a POS value directly from the hardware. You should not normally need to use this

function and should have a very good knowledge of MCA bus before you do so. Doing

this wrongly can damage the hardware.

This function may not be used from interrupt context.

Note that this a technically a Bad Thing, as IBM tech stuff says you should only set

POS values through their utilities. However, some devices such as the 3c523

recommend that you write back some data to make sure the configuration is consistent.

I’d say that IBM is right, but I like my drivers to work.

This function can’t do checks to see if multiple devices end up with the same resources,

so you might see magic smoke if someone screws up.

mca_set_adapter_name

Name

mca_set_adapter_name - Set the description of the card

264

Chapter 10. Hardware Interfaces

Synopsis

void mca_set_adapter_name (int slot, char* name);

Arguments

slot

slot to name

name

text string for the namen

Description

This function sets the name reported via /proc for this adapter slot. This is for user

information only. Setting a name deletes any previous name.

mca_set_adapter_procfn

Name

mca_set_adapter_procfn— Set the /proc callback

265

Chapter 10. Hardware Interfaces

Synopsis

void mca_set_adapter_procfn (int slot, MCA_ProcFn procfn, void*

dev);

Arguments

slot

slot to configure

procfn

callback function to call for /proc

dev

device information passed to the callback

Description

This sets up an information callback for /proc/mca/slot?. The function is called with the

buffer, slot, and device pointer (or some equally informative context information, or

nothing, if you prefer), and is expected to put useful information into the buffer. The

adapter name, ID, and POS registers get printed before this is called though, so don’t do

it again.

This should be called with a NULL procfnwhen a module unregisters, thus

preventing kernel crashes and other such nastiness.

266

Chapter 11. The Device File System

devfs_register

Name

devfs_register - Register a device entry.

Synopsis

devfs_handle_t devfs_register (devfs_handle_t dir, const char *

name, unsigned int flags, unsigned int major, unsigned int

minor, umode_t mode, void * ops, void * info);

Arguments

dir

The handle to the parent devfs directory entry. If this is NULL the new name is

relative to the root of the devfs.

name

The name of the entry.

flags

A set of bitwise-ORed flags (DEVFS_FL_*).

282

Chapter 11. The Device File System

major

The major number. Not needed for regular files.

minor

The minor number. Not needed for regular files.

mode

The default file mode.

ops

The &file_operations or &block_device_operations structure. This must not be

externally deallocated.

info

An arbitrary pointer which will be written to the private_data field of the

&file structure passed to the device driver. You can set this to whatever you like,

and change it once the file is opened (the next file opened will not see this change).

Description

Returns a handle which may later be used in a call to devfs_unregister. On failure

NULL is returned.

283

Chapter 11. The Device File System

Synopsis

int devfs_mk_symlink (devfs_handle_t dir, const char * name,

unsigned int flags, const char * link, devfs_handle_t * handle,

void * info);

Arguments

dir

The handle to the parent devfs directory entry. If this is NULL the new name is

relative to the root of the devfs.

name

The name of the entry.

flags

A set of bitwise-ORed flags (DEVFS_FL_*).

link

The destination name.

handle

The handle to the symlink entry is written here. This may be NULL.

info

An arbitrary pointer which will be associated with the entry.

285

Chapter 11. The Device File System

Description

Returns 0 on success, else a negative error code is returned.

devfs_mk_dir

Name

devfs_mk_dir - Create a directory in the devfs namespace.

Synopsis

devfs_handle_t devfs_mk_dir (devfs_handle_t dir, const char *

name, void * info);

Arguments

dir

The handle to the parent devfs directory entry. If this is NULL the new name is

relative to the root of the devfs.

name

The name of the entry.

286

Chapter 11. The Device File System

info

An arbitrary pointer which will be associated with the entry.

Description

Use of this function is optional. The devfs_register function will automatically

create intermediate directories as needed. This function is provided for efficiency

reasons, as it provides a handle to a directory. Returns a handle which may later be used

in a call to devfs_unregister. On failure NULL is returned.

devfs_find_handle

Name

devfs_find_handle - Find the handle of a devfs entry.

Synopsis

devfs_handle_t devfs_find_handle (devfs_handle_t dir, const char

* name, unsigned int major, unsigned int minor, char type, int

traverse_symlinks);

287

Chapter 11. The Device File System

Arguments

dir

The handle to the parent devfs directory entry. If this is NULL the name is relative

to the root of the devfs.

name

The name of the entry.

major

The major number. This is used if name is NULL.

minor

The minor number. This is used if name is NULL.

type

The type of special file to search for. This may be either DEVFS_SPECIAL_CHR or

DEVFS_SPECIAL_BLK.

traverse_symlinks

If TRUE then symlink entries in the devfs namespace are traversed. Symlinks

pointing out of the devfs namespace will cause a failure. Symlink traversal

consumes stack space.

Description

Returns a handle which may later be used in a call to devfs_unregister,

devfs_get_flags, or devfs_set_flags. On failure NULL is returned.

288

Chapter 11. The Device File System

devfs_get_maj_min

Name

devfs_get_maj_min - Get the major and minor numbers for a devfs entry.

Synopsis

int devfs_get_maj_min (devfs_handle_t de, unsigned int * major,

unsigned int * minor);

Arguments

The handle to the device entry.

major

The major number is written here. This may be NULL.

minor

The minor number is written here. This may be NULL.

Description

Returns 0 on success, else a negative error code.

290

Chapter 11. The Device File System

devfs_generate_path

Name

devfs_generate_path - Generate a pathname for an entry, relative to the devfs

root.

Synopsis

int devfs_generate_path (devfs_handle_t de, char * path, int

buflen);

Arguments

The devfs entry.

path

The buffer to write the pathname to. The pathname and ’\0’ terminator will be

written at the end of the buffer.

buflen

The length of the buffer.

292

Chapter 11. The Device File System

Description

Returns the offset in the buffer where the pathname starts on success, else a negative

error code.

devfs_get_ops

Name

devfs_get_ops - Get the device operations for a devfs entry.

Synopsis

void * devfs_get_ops (devfs_handle_t de);

Arguments

The handle to the device entry.

Description

Returns a pointer to the device operations on success, else NULL.

293

Chapter 11. The Device File System

devfs_auto_unregister

Name

devfs_auto_unregister - Configure a devfs entry to be automatically

unregistered.

Synopsis

void devfs_auto_unregister (devfs_handle_t master,

devfs_handle_t slave);

Arguments

master

The master devfs entry. Only one slave may be registered.

slave

The devfs entry which will be automatically unregistered when the master entry is

unregistered. It is illegal to call devfs_unregister on this entry.

300

Chapter 11. The Device File System

devfs_register_chrdev

Name

devfs_register_chrdev - Optionally register a conventional character driver.

Synopsis

int devfs_register_chrdev (unsigned int major, const char *

name, struct file_operations * fops);

Arguments

major

The major number for the driver.

name

The name of the driver (as seen in /proc/devices).

fops

The &file_operations structure pointer.

Description

This function will register a character driver provided the “devfs=only” option was not

provided at boot time. Returns 0 on success, else a negative error code on failure.

302

Chapter 11. The Device File System

devfs_register_blkdev

Name

devfs_register_blkdev - Optionally register a conventional block driver.

Synopsis

int devfs_register_blkdev (unsigned int major, const char *

name, struct block_device_operations * bdops);

Arguments

major

The major number for the driver.

name

The name of the driver (as seen in /proc/devices).

bdops

The &block_device_operations structure pointer.

303

Chapter 11. The Device File System

Description

This function will register a block driver provided the “devfs=only” option was not

provided at boot time. Returns 0 on success, else a negative error code on failure.

devfs_unregister_chrdev

Name

devfs_unregister_chrdev— Optionally unregister a conventional character

driver.

Synopsis

int devfs_unregister_chrdev (unsigned int major, const char *

name);

Arguments

major

The major number for the driver.

name

The name of the driver (as seen in /proc/devices).

304

Chapter 11. The Device File System

Description

This function will unregister a character driver provided the “devfs=only” option was

not provided at boot time. Returns 0 on success, else a negative error code on failure.

devfs_unregister_blkdev

Name

devfs_unregister_blkdev— Optionally unregister a conventional block driver.

Synopsis

int devfs_unregister_blkdev (unsigned int major, const char *

name);

Arguments

major

The major number for the driver.

name

The name of the driver (as seen in /proc/devices).

305

Chapter 12. Power Management

Description

Add a device to the list of devices that wish to be notified about power management

events. A &pm_dev structure is returned on success, on failure the return is NULL.

The callback function will be called in process context and it may sleep.

pm_unregister

Name

pm_unregister - unregister a device with power management

Synopsis

void pm_unregister (struct pm_dev * dev);

Arguments

dev

device to unregister

308

Chapter 12. Power Management

Description

Unregister every device that would call the callback passed. This is primarily meant as

a helper function for loadable modules. It enables a module to give up all its managed

devices without keeping its own private list.

pm_send

Name

pm_send - send request to a single device

Synopsis

int pm_send (struct pm_dev * dev, pm_request_t rqst, void *

data);

Arguments

dev

device to send to

rqst

power management request

310

Chapter 12. Power Management

data

data for the callback

Description

Issue a power management request to a given device. The PM_SUSPEND and

PM_RESUME events are handled specially. The data field must hold the intended next

state. No call is made if the state matches.

BUGS

what stops two power management requests occuring in parallel and conflicting.

WARNING

Calling pm_send directly is not generally recommended, in paticular there is no locking

against the pm_dev going away. The caller must maintain all needed locking or have

’inside knowledge’ on the safety. Also remember that this function is not locked against

pm_unregister. This means that you must handle SMP races on callback

execution and unload yourself.

311

Chapter 12. Power Management

pm_send_all

Name

pm_send_all - send request to all managed devices

Synopsis

int pm_send_all (pm_request_t rqst, void * data);

Arguments

rqst

power management request

data

data for the callback

Description

Issue a power management request to a all devices. The PM_SUSPEND events are

handled specially. Any device is permitted to fail a suspend by returning a non zero

(error) value from its callback function. If any device vetoes a suspend request then all

other devices that have suspended during the processing of this request are restored to

their previous state.

312

Chapter 12. Power Management

WARNING

This function takes the pm_devs_lock. The lock is not dropped until the callbacks have

completed. This prevents races against pm locking functions, races against module

unload pm_unregister code. It does mean however that you must not issue pm_

functions within the callback or you will deadlock and users will hate you.

Zero is returned on success. If a suspend fails then the status from the device that

vetoes the suspend is returned.

BUGS

what stops two power management requests occuring in parallel and conflicting.

pm_find

Name

pm_find - find a device

Synopsis

struct pm_dev * pm_find (pm_dev_t type, struct pm_dev * from);

313

Chapter 12. Power Management

Arguments

type

type of device

from

where to start looking

Description

Scan the power management list for devices of a specific type. The return value for a

matching device may be passed to further calls to this function to find further matches.

A NULL indicates the end of the list.

To search from the beginning pass NULL as the from value.

The caller MUST hold the pm_devs_lock lock when calling this function. The instant

that the lock is dropped all pointers returned may become invalid.

314

Chapter 13. Block Devices

blk_cleanup_queue

Name

blk_cleanup_queue - release a request_queue_t when it is no longer needed

Synopsis

void blk_cleanup_queue (request_queue_t * q);

Arguments

the request queue to be released

Description

blk_cleanup_queue is the pair to blk_init_queue. It should be called when a request

queue is being released; typically when a block device is being de-registered. Currently,

its primary task it to free all the &struct request structures that were allocated to the

queue.

Chapter 13. Block Devices

Caveat

Hopefully the low level driver will have finished any outstanding requests first...

blk_queue_headactive

Name

blk_queue_headactive - indicate whether head of request queue may be active

Synopsis

void blk_queue_headactive (request_queue_t * q, int active);

Arguments

The queue which this applies to.

active

A flag indication where the head of the queue is active.

316

Chapter 13. Block Devices

Description

The driver for a block device may choose to leave the currently active request on the

request queue, removing it only when it has completed. The queue handling routines

assume this by default for safety reasons and will not involve the head of the request

queue in any merging or reordering of requests when the queue is unplugged (and thus

may be working on this particular request).

If a driver removes requests from the queue before processing them, then it may

indicate that it does so, there by allowing the head of the queue to be involved in

merging and reordering. This is done be calling blk_queue_headactive with an

active flag of 0.

If a driver processes several requests at once, it must remove them (or at least all but

one of them) from the request queue.

When a queue is plugged the head will be assumed to be inactive.

blk_queue_make_request

Name

blk_queue_make_request— define an alternate make_request function for a

device

Synopsis

void blk_queue_make_request (request_queue_t * q,

make_request_fn * mfn);

317

Chapter 13. Block Devices

Arguments

the request queue for the device to be affected

mfn

the alternate make_request function

Description

The normal way for &struct buffer_heads to be passed to a device driver is for them to

be collected into requests on a request queue, and then to allow the device driver to

select requests off that queue when it is ready. This works well for many block devices.

However some block devices (typically virtual devices such as md or lvm) do not

benefit from the processing on the request queue, and are served best by having the

requests passed directly to them. This can be achieved by providing a function to

blk_queue_make_request.

Caveat

The driver that does this *must* be able to deal appropriately with buffers in

“highmemory”, either by calling bh_kmap to get a kernel mapping, to by calling

create_bounce to create a buffer in normal memory.

318

Chapter 13. Block Devices

blk_init_queue

Name

blk_init_queue - prepare a request queue for use with a block device

Synopsis

void blk_init_queue (request_queue_t * q, request_fn_proc *

rfn);

Arguments

The &request_queue_t to be initialised

rfn

The function to be called to process requests that have been placed on the queue.

Description

If a block device wishes to use the standard request handling procedures, which sorts

requests and coalesces adjacent requests, then it must call blk_init_queue. The

function rfnwill be called when there are requests on the queue that need to be

processed. If the device supports plugging, then rfnmay not be called immediately

when requests are available on the queue, but may be called at some time later instead.

319

Chapter 13. Block Devices

Plugged queues are generally unplugged when a buffer belonging to one of the requests

on the queue is needed, or due to memory pressure.

rfn is not required, or even expected, to remove all requests off the queue, but only as

many as it can handle at a time. If it does leave requests on the queue, it is responsible

for arranging that the requests get dealt with eventually.

A global spin lock $io_request_lock must be held while manipulating the requests on

the request queue.

The request on the head of the queue is by default assumed to be potentially active, and

it is not considered for re-ordering or merging whenever the given queue is unplugged.

This behaviour can be changed with blk_queue_headactive.

Note

blk_init_queue must be paired with a blk_cleanup_queue call when the block

device is deactivated (such as at module unload).

generic_make_request

Name

generic_make_request—

Synopsis

void generic_make_request (int rw, struct buffer_head * bh);

320

Chapter 13. Block Devices

Arguments

READ, WRITE, or READA - what sort of I/O is desired.

The buffer head describing the location in memory and on the device.

Description

generic_make_request is used to make I/O requests of block devices. It is passed a

&struct buffer_head and a &rw value. The READ and WRITE options are (hopefully)

obvious in meaning. The READA value means that a read is required, but that the driver

is free to fail the request if, for example, it cannot get needed resources immediately.

generic_make_request does not return any status. The success/failure status of the

request, along with notification of completion, is delivered asynchronously through the

bh->b_end_io function described (one day) else where.

The caller of generic_make_request must make sure that b_page, b_addr, b_size are set

to describe the memory buffer, that b_rdev and b_rsector are set to describe the device

address, and the b_end_io and optionally b_private are set to describe how completion

notification should be signaled. BH_Mapped should also be set (to confirm that b_dev

and b_blocknr are valid).

generic_make_request and the drivers it calls may use b_reqnext, and may change

b_rdev and b_rsector. So the values of these fields should NOT be depended on after

the call to generic_make_request. Because of this, the caller should record the device

address information in b_dev and b_blocknr.

321

Chapter 13. Block Devices

Apart from those fields mentioned above, no other fields, and in particular, no other

flags, are changed by generic_make_request or any lower level drivers.

submit_bh

Name

submit_bh—

Synopsis

void submit_bh (int rw, struct buffer_head * bh);

Arguments

whether to READ or WRITE, or maybe to READA (read ahead)

The &struct buffer_head which describes the I/O

322

Chapter 13. Block Devices

Description

submit_bh is very similar in purpose to generic_make_request, and uses that

function to do most of the work.

The extra functionality provided by submit_bh is to determine b_rsector from

b_blocknr and b_size, and to set b_rdev from b_dev. This is is appropriate for IO

requests that come from the buffer cache and page cache which (currently) always use

aligned blocks.

ll_rw_block

Name

ll_rw_block - level access to block devices

Synopsis

void ll_rw_block (int rw, int nr, struct buffer_head * * bhs);

Arguments

whether to READ or WRITE or maybe READA (readahead)

323

Chapter 13. Block Devices

number of &struct buffer_heads in the array

bhs

array of pointers to &struct buffer_head

Description

ll_rw_block takes an array of pointers to &struct buffer_heads, and requests an I/O

operation on them, either a READ or a WRITE. The third READA option is described in

the documentation for generic_make_request which ll_rw_block calls.

This function provides extra functionality that is not in generic_make_request that

is relevant to buffers in the buffer cache or page cache. In particular it drops any buffer

that it cannot get a lock on (with the BH_Lock state bit), any buffer that appears to be

clean when doing a write request, and any buffer that appears to be up-to-date when

doing read request. Further it marks as clean buffers that are processed for writing (the

buffer cache wont assume that they are actually clean until the buffer gets unlocked).

ll_rw_block sets b_end_io to simple completion handler that marks the buffer

up-to-date (if approriate), unlocks the buffer and wakes any waiters. As client that

needs a more interesting completion routine should call submit_bh (or

generic_make_request) directly.

Caveat

All of the buffers must be for the same device, and must also be

324

Chapter 13. Block Devices

end_that_request_first

Name

end_that_request_first - end I/O on one buffer.

Synopsis

int end_that_request_first (struct request * req, int uptodate,

char * name);

Arguments

req

the request being processed

uptodate

0 for I/O error

name

the name printed for an I/O error

Description

Ends I/O on the first buffer attached to req, and sets it up for the next buffer_head (if

any) in the cluster.

325

Chapter 14. Miscellaneous Devices

misc_register

Name

misc_register - register a miscellaneous device

Synopsis

int misc_register (struct miscdevice * misc);

Arguments

misc

device structure

Description

MISC_DYNAMIC_MINOR a minor number is assigned and placed in the minor field of

the structure. For other cases the minor number requested is used.

The structure passed is linked into the kernel and may not be destroyed until it has been

unregistered.

Chapter 14. Miscellaneous Devices

A zero is returned on success and a negative errno code for failure.

misc_deregister

Name

misc_deregister— unregister a miscellaneous device

Synopsis

int misc_deregister (struct miscdevice * misc);

Arguments

misc

device to unregister

Description

Unregister a miscellaneous device that was previously successfully registered with

misc_register. Success is indicated by a zero return, a negative errno code indicates

an error.

328

Chapter 15. Video4Linux

The registration code assigns minor numbers based on the type requested. -ENFILE is

returned in all the device slots for this category are full. If not then the minor field is set

and the driver initialize function is called (if non NULL).

Zero is returned on success.

Valid types are

VFL_TYPE_GRABBER - A frame grabber

VFL_TYPE_VTX - A teletext device

VFL_TYPE_VBI - Vertical blank data (undecoded)

VFL_TYPE_RADIO - A radio card

video_unregister_device

Name

video_unregister_device— unregister a video4linux device

Synopsis

void video_unregister_device (struct video_device * vfd);

331

Chapter 16. Sound Devices

Description

Allocate a special sound device by minor number from the sound subsystem. The

allocated number is returned on succes. On failure a negative error code is returned.

register_sound_mixer

Name

register_sound_mixer— register a mixer device

Synopsis

int register_sound_mixer (struct file_operations * fops, int

dev);

Arguments

fops

File operations for the driver

dev

Unit number to allocate

334

Chapter 16. Sound Devices

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

Name

register_sound_midi— register a midi device

Synopsis

int register_sound_midi (struct file_operations * fops, int

dev);

Arguments

fops

File operations for the driver

dev

Unit number to allocate

335

Chapter 16. Sound Devices

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

Name

register_sound_dsp - register a DSP device

Synopsis

int register_sound_dsp (struct file_operations * fops, int dev);

Arguments

fops

File operations for the driver

dev

Unit number to allocate

336

Chapter 16. Sound Devices

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

register_sound_synth

Name

register_sound_synth— register a synth device

Synopsis

int register_sound_synth (struct file_operations * fops, int

dev);

Arguments

fops

File operations for the driver

337

Chapter 16. Sound Devices

dev

Unit number to allocate

Description

Allocate a synth device. Unit is the number of the synth device requested. Pass -1 to

request the next free synth unit. On success the allocated number is returned, on failure

a negative error code is returned.

unregister_sound_special

Name

unregister_sound_special— unregister a special sound device

Synopsis

void unregister_sound_special (int unit);

Arguments

unit

unit number to allocate

338

Chapter 16. Sound Devices

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.

unregister_sound_synth

Name

unregister_sound_synth— unregister a synth device

Synopsis

void unregister_sound_synth (int unit);

Arguments

unit

unit number to allocate

342

Chapter 17. USB Devices

usb_register

Name

usb_register - register a USB driver

Synopsis

int usb_register (struct usb_driver * new_driver);

Arguments

new_driver

USB operations for the driver

Description

Registers a USB driver with the USB core. The list of unattached interfaces will be

rescanned whenever a new driver is added, allowing the new driver to attach to any

recognized devices. Returns a negative error code on failure and 0 on success.

Chapter 17. USB Devices

usb_scan_devices

Name

usb_scan_devices— scans all unclaimed USB interfaces

Synopsis

void usb_scan_devices ( void);

Arguments

void

no arguments

Description

Goes through all unclaimed USB interfaces, and offers them to all registered USB

drivers through the ’probe’ function. This will automatically be called after

usb_register is called. It is called by some of the USB subsystems after one of their

subdrivers are registered.

345

Chapter 17. USB Devices

usb_alloc_bus

Name

usb_alloc_bus - creates a new USB host controller structure

Synopsis

struct usb_bus * usb_alloc_bus (struct usb_operations * op);

Arguments

pointer to a struct usb_operations that this bus structure should use

Description

Creates a USB host controller bus structure with the specified usb_operations and

initializes all the necessary internal objects. (For use only by USB Host Controller

Drivers.)

If no memory is available, NULL is returned.

The caller should call usb_free_bus when it is finished with the structure.

347

Chapter 17. USB Devices

usb_match_id

Name

usb_match_id— find first usb_device_id matching device or interface

Synopsis

const struct usb_device_id * usb_match_id (struct usb_device *

dev, struct usb_interface * interface, const struct

usb_device_id * id);

Arguments

dev

the device whose descriptors are considered when matching

interface

the interface of interest

array of usb_device_id structures, terminated by zero entry

351

Chapter 17. USB Devices

Description

usb_match_id searches an array of usb_device_id’s and returns the first one matching

the device or interface, or null. This is used when binding (or rebinding) a driver to an

interface. Most USB device drivers will use this indirectly, through the usb core, but

some layered driver frameworks use it directly. These device tables are exported with

MODULE_DEVICE_TABLE, through modutils and “modules.usbmap”, to support the

driver loading functionality of USB hotplugging.

What Matches

The “match_flags” element in a usb_device_id controls which members are used. If the

corresponding bit is set, the value in the device_id must match its corresponding

member in the device or interface descriptor, or else the device_id does not match.

“driver_info” is normally used only by device drivers, but you can create a wildcard

“matches anything” usb_device_id as a driver’s “modules.usbmap” entry if you provide

an id with only a nonzero “driver_info” field. If you do this, the USB device driver’s

probe routine should use additional intelligence to decide whether to bind to the

specified interface.

What Makes Good usb_device_id Tables

The match algorithm is very simple, so that intelligence in driver selection must come

from smart driver id records. Unless you have good reasons to use another selection

policy, provide match elements only in related groups, and order match specifiers from

specific to general. Use the macros provided for that purpose if you can.

The most specific match specifiers use device descriptor data. These are commonly

used with product-specific matches; the USB_DEVICE macro lets you provide vendor

and product IDs, and you can also matche against ranges of product revisions. These

are widely used for devices with application or vendor specific bDeviceClass values.

352

Chapter 17. USB Devices

Matches based on device class/subclass/protocol specifications are slightly more

general; use the USB_DEVICE_INFO macro, or its siblings. These are used with

single-function devices where bDeviceClass doesn’t specify that each interface has its

own class.

Matches based on interface class/subclass/protocol are the most general; they let

drivers bind to any interface on a multiple-function device. Use the

USB_INTERFACE_INFO macro, or its siblings, to match class-per-interface style

devices (as recorded in bDeviceClass).

Within those groups, remember that not all combinations are meaningful. For example,

don’t give a product version range without vendor and product IDs; or specify a

protocol without its associated class and subclass.

usb_alloc_urb

Name

usb_alloc_urb - creates a new urb for a USB driver to use

Synopsis

urb_t * usb_alloc_urb (int iso_packets);

353

Chapter 17. USB Devices

Arguments

iso_packets

number of iso packets for this urb

Description

Creates an urb for the USB driver to use and returns a pointer to it. If no memory is

available, NULL is returned.

If the driver want to use this urb for interrupt, control, or bulk endpoints, pass ’0’ as the

number of iso packets.

The driver should call usb_free_urb when it is finished with the urb.

usb_free_urb

Name

usb_free_urb - frees the memory used by a urb

Synopsis

void usb_free_urb (urb_t* urb);

354

Chapter 17. USB Devices

Arguments

urb

pointer to the urb to free

Description

If an urb is created with a call to usb_create_urb it should be cleaned up with a call

to usb_free_urb when the driver is finished with it.

usb_control_msg

Name

usb_control_msg - Builds a control urb, sends it off and waits for completion

Synopsis

int usb_control_msg (struct usb_device * dev, unsigned int pipe,

u8 request,

u8 requesttype,

u16 value,

u16 index, void *

data,

u16 size, int timeout);

355

Chapter 17. USB Devices

Arguments

dev

pointer to the usb device to send the message to

pipe

endpoint “pipe” to send the message to

request

USB message request value

requesttype

USB message request type value

value

USB message value

index

USB message index value

data

pointer to the data to send

size

length in bytes of the data to send

timeout

time to wait for the message to complete before timing out (if 0 the wait is

forever)

356

Chapter 17. USB Devices

Description

This function sends a simple control message to a specified endpoint and waits for the

message to complete, or timeout.

If successful, it returns 0, othwise a negative error number.

Don’t use this function from within an interrupt context, like a bottom half handler. If

you need a asyncronous message, or need to send a message from within interrupt

context, use usb_submit_urb

usb_bulk_msg

Name

usb_bulk_msg - Builds a bulk urb, sends it off and waits for completion

Synopsis

int usb_bulk_msg (struct usb_device * usb_dev, unsigned int

pipe, void * data, int len, int * actual_length, int timeout);

Arguments

usb_dev

pointer to the usb device to send the message to

357

Chapter 17. USB Devices

pipe

endpoint “pipe” to send the message to

data

pointer to the data to send

len

length in bytes of the data to send

actual_length

pointer to a location to put the actual length transferred in bytes

timeout

time to wait for the message to complete before timing out (if 0 the wait is

forever)

Description

This function sends a simple bulk message to a specified endpoint and waits for the

message to complete, or timeout.

If successful, it returns 0, othwise a negative error number. The number of actual bytes

transferred will be plaed in the actual_timeout paramater.

Don’t use this function from within an interrupt context, like a bottom half handler. If

you need a asyncronous message, or need to send a message from within interrupt

context, use usb_submit_urb

358

Chapter 18. 16x50 UART Driver

register_serial

Name

register_serial - configure a 16x50 serial port at runtime

Synopsis

int register_serial (struct serial_struct * req);

Arguments

req

request structure

Description

Configure the serial port specified by the request. If the port exists and is in use an error

is returned. If the port is not currently in the table it is added.

The port is then probed and if neccessary the IRQ is autodetected If this fails an error is

returned.

Chapter 18. 16x50 UART Driver

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

unregister_serial

Name

unregister_serial— deconfigure a 16x50 serial port

Synopsis

void unregister_serial (int line);

Arguments

line

line to deconfigure

Description

The port specified is deconfigured and its resources are freed. Any user of the port is

disconnected as if carrier was dropped. Line is the port number returned by

register_serial.

360

Chapter 19. Z85230 Support Library

Description

A Z85[2]30 device has stuck its hand in the air for attention. We scan both the channels

on the chip for events and then call the channel specific call backs for each channel that

has events. We have to use callback functions because the two channels can be in

different modes.

z8530_sync_open

Name

z8530_sync_open - Open a Z8530 channel for PIO

Synopsis

int z8530_sync_open (struct net_device * dev, struct

z8530_channel * c);

Arguments

dev

The network interface we are using

363

Chapter 19. Z85230 Support Library

The Z8530 channel to open in synchronous PIO mode

Description

Switch a Z8530 into synchronous mode without DMA assist. We raise the RTS/DTR

and commence network operation.

z8530_sync_close

Name

z8530_sync_close - Close a PIO Z8530 channel

Synopsis

int z8530_sync_close (struct net_device * dev, struct

z8530_channel * c);

Arguments

dev

Network device to close

364

Chapter 19. Z85230 Support Library

Z8530 channel to disassociate and move to idle

Description

Close down a Z8530 interface and switch its interrupt handlers to discard future events.

z8530_sync_dma_open

Name

z8530_sync_dma_open - Open a Z8530 for DMA I/O

Synopsis

int z8530_sync_dma_open (struct net_device * dev, struct

z8530_channel * c);

Arguments

dev

The network device to attach

365

Chapter 19. Z85230 Support Library

The Z8530 channel to configure in sync DMA mode.

Description

Set up a Z85x30 device for synchronous DMA in both directions. Two ISA DMA

channels must be available for this to work. We assume ISA DMA driven I/O and PC

limits on access.

z8530_sync_dma_close

Name

z8530_sync_dma_close— Close down DMA I/O

Synopsis

int z8530_sync_dma_close (struct net_device * dev, struct

z8530_channel * c);

366

Chapter 19. Z85230 Support Library

Arguments

dev

Network device to detach

Z8530 channel to move into discard mode

Description

Shut down a DMA mode synchronous interface. Halt the DMA, and free the buffers.

z8530_sync_txdma_open

Name

z8530_sync_txdma_open - Open a Z8530 for TX driven DMA

Synopsis

int z8530_sync_txdma_open (struct net_device * dev, struct

z8530_channel * c);

367

Chapter 19. Z85230 Support Library

Arguments

dev

The network device to attach

The Z8530 channel to configure in sync DMA mode.

Description

Set up a Z85x30 device for synchronous DMA tranmission. One ISA DMA channel

must be available for this to work. The receive side is run in PIO mode, but then it has

the bigger FIFO.

z8530_sync_txdma_close

Name

z8530_sync_txdma_close - Close down a TX driven DMA channel

Synopsis

int z8530_sync_txdma_close (struct net_device * dev, struct

z8530_channel * c);

368

Chapter 19. Z85230 Support Library

Arguments

dev

Network device to detach

Z8530 channel to move into discard mode

Description

Shut down a DMA/PIO split mode synchronous interface. Halt the DMA, and free the

buffers.

z8530_describe

Name

z8530_describe - Uniformly describe a Z8530 port

Synopsis

void z8530_describe (struct z8530_dev * dev, char * mapping,

unsigned long io);

369

Chapter 19. Z85230 Support Library

Arguments

dev

Z8530 device to describe

mapping

string holding mapping type (eg “I/O” or “Mem”)

the port value in question

Description

Describe a Z8530 in a standard format. We must pass the I/O as the port offset isnt

predictable. The main reason for this function is to try and get a common format of

report.

z8530_init

Name

z8530_init - Initialise a Z8530 device

370

Chapter 19. Z85230 Support Library

Synopsis

int z8530_init (struct z8530_dev * dev);

Arguments

dev

Z8530 device to initialise.

Description

Configure up a Z8530/Z85C30 or Z85230 chip. We check the device is present, identify

the type and then program it to hopefully keep quite and behave. This matters a lot,

a Z8530 in the wrong state will sometimes get into stupid modes generating 10Khz

interrupt streams and the like.

We set the interrupt handler up to discard any events, in case we get them during reset

or setp.

Return 0 for success, or a negative value indicating the problem in errno form.

371

Chapter 19. Z85230 Support Library

z8530_shutdown

Name

z8530_shutdown - Shutdown a Z8530 device

Synopsis

int z8530_shutdown (struct z8530_dev * dev);

Arguments

dev

The Z8530 chip to shutdown

Description

We set the interrupt handlers to silence any interrupts. We then reset the chip and wait

100uS to be sure the reset completed. Just in case the caller then tries to do stuff.

372

Chapter 19. Z85230 Support Library

z8530_channel_load

Name

z8530_channel_load - Load channel data

Synopsis

int z8530_channel_load (struct z8530_channel * c, u8 * rtable);

Arguments

Z8530 channel to configure

rtable

table of register, value pairs

FIXME

ioctl to allow user uploaded tables

Load a Z8530 channel up from the system data. We use +16 to indicate the “prime”

registers. The value 255 terminates the table.

373

Chapter 19. Z85230 Support Library

z8530_null_rx

Name

z8530_null_rx - Discard a packet

Synopsis

void z8530_null_rx (struct z8530_channel * c, struct sk_buff *

skb);

Arguments

The channel the packet arrived on

skb

The buffer

Description

We point the receive handler at this function when idle. Instead of syncppp processing

the frames we get to throw them away.

374

Chapter 19. Z85230 Support Library

z8530_queue_xmit

Name

z8530_queue_xmit— Queue a packet

Synopsis

int z8530_queue_xmit (struct z8530_channel * c, struct sk_buff *

skb);

Arguments

The channel to use

skb

The packet to kick down the channel

Description

Queue a packet for transmission. Because we have rather hard to hit interrupt latencies

for the Z85230 per packet even in DMA mode we do the flip to DMA buffer if needed

here not in the IRQ.

375

Chapter 20. 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 800x600 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.

20.1. Frame Buffer Memory

register_framebuffer

Name

register_framebuffer— registers a frame buffer device

Chapter 20. Frame Buffer Library

Synopsis

void fbcon_redraw_clear (struct vc_data * conp, struct display *

p, int sy, int sx, int height, int width);

Arguments

conp

stucture pointing to current active virtual console

display structure

starting Y coordinate

starting X coordinate

height

height of area to clear

width

width of area to clear

Description

Clears a specified area of the screen. All dimensions are in pixels.

380

Chapter 20. Frame Buffer Library

destination X coordinate

height of area to copy

width of area to copy

Description

Copies an area of the screen to another area of the same screen. All dimensions are in

pixels.

Note that this function cannot be used together with ypan or ywrap.

20.3. Frame Buffer Colormap

fb_alloc_cmap

Name

fb_alloc_cmap - allocate a colormap

382

Chapter 20. Frame Buffer Library

Synopsis

int fb_alloc_cmap (struct fb_cmap * cmap, int len, int transp);

Arguments

cmap

frame buffer colormap structure

len

length of cmap

transp

boolean, 1 if there is transparency, 0 otherwise

Description

Allocates memory for a colormap cmap. len is the number of entries in the palette.

Returns -1 errno on error, or zero on success.

383

Chapter 20. Frame Buffer Library

Arguments

cmap

frame buffer colormap

kspc

boolean, 0 copy local, 1 put_user function

getcolreg

pointer to a function to get a color register

info

frame buffer info structure

Description

Get a colormap cmap for a screen of device info.

Returns negative errno on error, or zero on success.

fb_set_cmap

Name

fb_set_cmap - set the colormap

386

Chapter 20. Frame Buffer Library

Synopsis

int fb_set_cmap (struct fb_cmap * cmap, int kspc, int

(*setcolreg) (u_int, u_int, u_int, u_int, u_int, struct fb_info

*), struct fb_info * info);

Arguments

cmap

frame buffer colormap structure

kspc

boolean, 0 copy local, 1 get_user function

setcolreg

-- undescribed --

info

frame buffer info structure

Description

Sets the colormap cmap for a screen of device info.

Returns negative errno on error, or zero on success.

387

Chapter 20. Frame Buffer Library

fb_default_cmap

Name

fb_default_cmap— get default colormap

Synopsis

struct fb_cmap * fb_default_cmap (int len);

Arguments

len

size of palette for a depth

Description

Gets the default colormap for a specific screen depth. len is the size of the palette for a

particular screen depth.

Returns pointer to a frame buffer colormap structure.

388

Chapter 20. Frame Buffer Library

Description

Get the fixed information part of the display and place it into fix for virtual console

con on device info.

Returns negative errno on error, or zero on success.

fbgen_get_var

Name

fbgen_get_var - get user defined part of display

Synopsis

int fbgen_get_var (struct fb_var_screeninfo * var, int con,

struct fb_info * info);

Arguments

var

fb_var_screeninfo structure

con

virtual console number

391

Chapter 20. Frame Buffer Library

info

frame buffer info structure

Description

Get the user defined part of the display and place it into var for virtual console conon

device info.

Returns negative errno on error, or zero for success.

fbgen_set_var

Name

fbgen_set_var - set the user defined part of display

Synopsis

int fbgen_set_var (struct fb_var_screeninfo * var, int con,

struct fb_info * info);

392

Chapter 20. Frame Buffer Library

Arguments

var

fb_var_screeninfo user defined part of the display

con

virtual console number

info

frame buffer info structure

Description

Set the user defined part of the display as dictated by var for virtual console conon

device info.

Returns negative errno on error, or zero for success.

fbgen_get_cmap

Name

fbgen_get_cmap - get the colormap

393

Chapter 20. Frame Buffer Library

Synopsis

int fbgen_get_cmap (struct fb_cmap * cmap, int kspc, int con,

struct fb_info * info);

Arguments

cmap

frame buffer colormap structure

kspc

boolean, 0 copy local, 1 put_user function

con

virtual console number

info

frame buffer info structure

Description

Gets the colormap for virtual console conand places it into cmap for device info.

Returns negative errno on error, or zero for success.

394

Chapter 20. Frame Buffer Library

Description

Sets the colormap cmap for virtual console conon device info.

Returns negative errno on error, or zero for success.

fbgen_pan_display

Name

fbgen_pan_display - pan or wrap the display

Synopsis

int fbgen_pan_display (struct fb_var_screeninfo * var, int con,

struct fb_info * info);

Arguments

var

frame buffer user defined part of display

con

virtual console number

396

Chapter 20. Frame Buffer Library

info

frame buffer info structure

Description

Pan or wrap virtual console con for device info.

This call looks only at xoffset, yoffset and the FB_VMODE_YWRAP flag in var.

Returns negative errno on error, or zero for success.

fbgen_do_set_var

Name

fbgen_do_set_var— change the video mode

Synopsis

int fbgen_do_set_var (struct fb_var_screeninfo * var, int

isactive, struct fb_info_gen * info);

397

Chapter 20. Frame Buffer Library

Arguments

var

frame buffer user defined part of display

isactive

boolean, 0 inactive, 1 active

info

generic frame buffer info structure

Description

Change the video mode settings for device info. If isactive is non-zero, the

changes will be activated immediately.

Return negative errno on error, or zero for success.

fbgen_set_disp

Name

fbgen_set_disp - set generic display

398

Chapter 20. Frame Buffer Library

Synopsis

int fbgen_update_var (int con, struct fb_info * info);

Arguments

con

virtual console number

info

frame buffer info structure

Description

Updates the user defined part of the display (’var’ structure) on virtual console con for

device info. This function is called by fbcon.c.

Returns negative errno on error, or zero for success.

fbgen_switch

Name

fbgen_switch - switch to a different virtual console.

401

Chapter 20. Frame Buffer Library

20.5. Frame Buffer Video Mode Database

fb_find_mode

Name

fb_find_mode— finds a valid video mode

Synopsis

int

init fb_find_mode (struct fb_var_screeninfo * var, struct

fb_info * info, const char * mode_option, const struct

fb_videomode * db, unsigned int dbsize, const struct

fb_videomode * default_mode, unsigned int default_bpp);

Arguments

var

frame buffer user defined part of display

info

frame buffer info structure

mode_option

string video mode to find

404

Chapter 20. Frame Buffer Library

video mode database

dbsize

size of db

default_mode

default video mode to fall back to

default_bpp

default color depth in bits per pixel

Description

Finds a suitable video mode, starting with the specified mode in mode_optionwith

fallback to default_mode. If default_mode fails, all modes in the video mode

database will be tried.

Valid mode specifiers for mode_option:

<xres>x<yres>[-<bpp>][@<refresh>] or <name>[-<bpp>][@<refresh>]

with <xres>, <yres>, <bpp> and <refresh> decimal numbers and <name> a string.

NOTE

The passed struct var is _not_ cleared! This allows you to supply values for e.g. the

grayscale and accel_flags fields.

Returns zero for failure, 1 if using specified mode_option, 2 if using specified

mode_option with an ignored refresh rate, 3 if default mode is used, 4 if fall back to

any valid mode.

405

Chapter 20. Frame Buffer Library

Arguments

mode

virtual console mode structure

Description

Populates mode with the current mode held in the global display_info structure.

Note, this function is only for XPMAC compatibility.

Returns zero.

console_setmode

Name

console_setmode— sets current console mode

Synopsis

int console_setmode (struct vc_mode * mode, int doit);

408

Chapter 20. Frame Buffer Library

Arguments

mode

virtual console mode structure

doit

boolean, 0 test mode, 1 test and activate mode

Description

Sets mode for all virtual consoles if doit is non-zero, otherwise, test a mode for

validity.

Note, this function is only for XPMAC compatibility.

Returns negative errno on error, or zero for success.

console_setcmap

Name

console_setcmap - sets palette color map for console

Synopsis

int console_setcmap (int n_entries, unsigned char * red,

unsigned char * green, unsigned char * blue);

409

Chapter 20. Frame Buffer Library

Arguments

n_entries

number of entries in the palette (max 16)

red

value for red component of palette

green

value for green component of palette

blue

value for blue component of palette

Description

Sets global palette_cmap structure and activates the palette on the current console.

Note, this function is only for XPMAC compatibility.

Returns negative errno on error, or zero for success.

410

Chapter 20. Frame Buffer Library

console_powermode

Name

console_powermode— sets monitor power mode

Synopsis

int console_powermode (int mode);

Arguments

mode

power state to set

Description

Sets power state as dictated by mode.

Note that this function is only for XPMAC compatibility and doesn’t do much.

Returns 0 for VC_POWERMODE_INQUIRY, -EINVAL for VESA power settings, or

-ENIXIO on failure.

411

Chapter 20. Frame Buffer Library

mac_vmode_to_var

Name

mac_vmode_to_var— converts vmode/cmode pair to var structure

Synopsis

int mac_vmode_to_var (int vmode, int cmode, struct

fb_var_screeninfo

* var);

Arguments

vmode

MacOS video mode

cmode

MacOS color mode

var

frame buffer video mode structure

Description

Converts a MacOS vmode/cmode pair to a frame buffer video mode structure.

Returns negative errno on error, or zero for success.

412

Chapter 20. Frame Buffer Library

Description

Converts a frame buffer video mode structure to a MacOS vmode/cmode pair.

Returns negative errno on error, or zero for success.

mac_map_monitor_sense

Name

mac_map_monitor_sense - Convert monitor sense to vmode

Synopsis

int mac_map_monitor_sense (int sense);

Arguments

sense

Macintosh monitor sense number

Description

Converts a Macintosh monitor sense number to a MacOS vmode number.

414

Chapter 20. Frame Buffer Library

Returns MacOS vmode video mode number.

mac_find_mode

Name

mac_find_mode - find a video mode

Synopsis

int

init mac_find_mode (struct fb_var_screeninfo * var, struct

fb_info * info, const char * mode_option, unsigned int

default_bpp);

Arguments

var

frame buffer user defined part of display

info

frame buffer info structure

mode_option

video mode name (see mac_modedb[])

415

Chapter 20. Frame Buffer Library

default_bpp

default color depth in bits per pixel

Description

Finds a suitable video mode. Tries to set mode specified by mode_option. If the

name of the wanted mode begins with ’mac’, the Mac video mode database will be

used, otherwise it will fall back to the standard video mode database.

Note

Function marked as init and can only be used during system boot.

Returns error code from fb_find_mode (see fb_find_mode function).

20.7. Frame Buffer Fonts

fbcon_find_font

Name

fbcon_find_font— find a font

416

The Linux Kernel API - page 2