The Linux Kernel API

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.

Table of Contents

1. Driver Basics

1.1. Driver Entry and Exit points

module_init

module_exit

1.2. Atomics

atomic_read

atomic_set

atomic_add

atomic_sub

atomic_sub_and_test

atomic_inc

atomic_dec

atomic_dec_and_test

atomic_inc_and_test

atomic_add_negative

1.3. Delaying, scheduling, and timer routines

schedule_timeout

2. Data Types

2.1. Doubly Linked Lists

list_add

list_add_tail

list_del

list_del_init

list_empty

list_splice

list_entry

list_for_each

3. Basic C Library Functions

3.1. String Conversions

simple_strtol

simple_strtoll

simple_strtoul

simple_strtoull

vsprintf

sprintf

3.2. String Manipulation

strcpy

strncpy

strcat

strncat

strcmp

strncmp

strchr

strrchr

strlen

strnlen

strpbrk

strtok

memset

bcopy

memcpy

memmove

memcmp

memscan

strstr

memchr

3.3. Bit Operations

set_bit

clear_bit

change_bit

test_and_set_bit

test_and_clear_bit

test_and_change_bit

test_bit

find_first_zero_bit

find_next_zero_bit

ffz

ffs

hweight32

4. Memory Management in Linux

4.1. The Slab Cache

kmem_cache_create

kmem_cache_shrink

kmem_cache_destroy

kmem_cache_alloc

kmalloc

kmem_cache_free

kfree

5. The proc filesystem

5.1. sysctl interface

register_sysctl_table

unregister_sysctl_table

proc_dostring

proc_dointvec

proc_dointvec_minmax

proc_doulongvec_minmax

proc_doulongvec_ms_jiffies_minmax

proc_dointvec_jiffies

6. The Linux VFS

6.1. The Directory Cache

d_invalidate

d_find_alias

prune_dcache

shrink_dcache_sb

have_submounts

shrink_dcache_parent

d_alloc

d_instantiate

d_alloc_root

d_lookup

d_validate

d_delete

d_rehash

d_move

d_path

is_subdir

find_inode_number

d_drop

d_add

dget

d_unhashed

6.2. Inode Handling

mark_inode_dirty

write_inode_now

clear_inode

invalidate_inodes

get_empty_inode

iunique

insert_inode_hash

remove_inode_hash

iput

100

bmap

101

update_atime

102

make_bad_inode

103

is_bad_inode

104

6.3. Registration and Superblocks

105

register_filesystem

105

unregister_filesystem

106

wait_on_super

107

get_super

108

6.4. File Locks

109

posix_lock_file

109

get_lease

110

lease_get_mtime

111

posix_block_lock

112

posix_unblock_lock

113

lock_may_read

114

lock_may_write

116

fcntl_getlease

117

fcntl_setlease

118

sys_flock

119

get_locks_status

120

7. Linux Networking

122

7.1. Socket Buffer Functions

122

skb_queue_empty

122

skb_get

123

kfree_skb

123

skb_cloned

124

skb_shared

125

skb_unshare

126

skb_peek

128

skb_peek_tail

129

skb_queue_len

130

skb_queue_head

130

skb_queue_head

132

skb_queue_tail

133

skb_queue_tail

134

skb_dequeue

135

skb_dequeue

135

skb_insert

136

skb_append

137

skb_unlink

138

skb_dequeue_tail

139

skb_dequeue_tail

140

skb_put

141

skb_push

142

skb_pull

144

skb_headroom

145

skb_tailroom

145

skb_reserve

146

skb_trim

147

skb_orphan

148

skb_queue_purge

149

skb_queue_purge

150

dev_alloc_skb

151

dev_alloc_skb

153

skb_cow

154

skb_over_panic

155

skb_under_panic

156

alloc_skb

157

kfree_skb

158

skb_clone

159

skb_copy

160

pskb_copy

161

pskb_expand_head

162

skb_copy_expand

164

pskb_pull_tail

165

7.2. Socket Filter

166

sk_run_filter

167

sk_chk_filter

168

8. Network device support

170

8.1. Driver Support

170

init_etherdev

170

alloc_etherdev

171

init_fddidev

172

alloc_fddidev

173

init_hippi_dev

174

alloc_hippi_dev

175

init_trdev

176

alloc_trdev

177

init_fcdev

178

alloc_fcdev

180

dev_add_pack

181

dev_remove_pack

182

dev_get_by_name

182

dev_get_by_name

183

dev_get

184

dev_get_by_index

185

dev_get_by_index

186

dev_alloc_name

187

dev_alloc

189

netdev_state_change

190

dev_load

191

dev_open

191

dev_close

192

register_netdevice_notifier

193

unregister_netdevice_notifier

194

dev_queue_xmit

195

netif_rx

196

net_call_rx_atomic

198

register_gifconf

198

netdev_set_master

199

dev_set_promiscuity

201

dev_set_allmulti

202

dev_ioctl

203

dev_new_index

204

register_netdevice

205

netdev_finish_unregister

206

unregister_netdevice

207

8.2. 8390 Based Network Cards

208

ei_open

208

ei_close

209

ei_tx_timeout

210

ei_interrupt

211

ethdev_init

212

NS8390_init

213

8.3. Synchronous PPP

214

sppp_input

214

sppp_close

215

sppp_open

216

sppp_reopen

217

sppp_change_mtu

219

sppp_do_ioctl

219

sppp_attach

221

sppp_detach

222

9. Module Loading

223

request_module

223

call_usermodehelper

224

10. Hardware Interfaces

226

10.1. Interrupt Handling

226

disable_irq_nosync

226

disable_irq

227

enable_irq

228

probe_irq_mask

229

10.2. MTRR Handling

230

mtrr_add

230

mtrr_del

232

10.3. PCI Support Library

233

pci_find_slot

233

pci_find_subsys

234

pci_find_device

235

pci_find_class

237

pci_find_capability

238

pci_find_parent_resource

239

pci_set_power_state

240

pci_enable_device

241

pci_disable_device

242

pci_release_regions

243

pci_request_regions

244

pci_match_device

246

pci_register_driver

247

pci_unregister_driver

248

pci_insert_device

249

pci_remove_device

250

pci_dev_driver

251

pci_set_master

251

pci_setup_device

252

pci_pool_create

253

pci_pool_destroy

255

pci_pool_alloc

256

pci_pool_free

257

10.4. MCA Architecture

258

10.4.1. MCA Device Functions

259

mca_find_adapter

259

mca_find_unused_adapter

260

mca_read_stored_pos

261

mca_read_pos

262

mca_write_pos

263

mca_set_adapter_name

264

mca_set_adapter_procfn

265

mca_is_adapter_used

266

mca_mark_as_used

267

mca_mark_as_unused

268

mca_get_adapter_name

269

mca_isadapter

270

mca_isenabled

271

10.4.2. MCA Bus DMA

272

mca_enable_dma

273

mca_disable_dma

273

mca_set_dma_addr

274

mca_get_dma_addr

275

mca_set_dma_count

276

mca_get_dma_residue

277

mca_set_dma_io

278

mca_set_dma_mode

279

11. The Device File System

282

devfs_register

282

devfs_unregister

283

devfs_mk_symlink

284

devfs_mk_dir

286

devfs_find_handle

287

devfs_get_flags

288

devfs_get_maj_min

289

devfs_get_handle_from_inode

291

devfs_generate_path

291

devfs_get_ops

293

devfs_set_file_size

294

devfs_get_info

295

devfs_set_info

295

devfs_get_parent

296

devfs_get_first_child

297

devfs_get_next_sibling

298

devfs_auto_unregister

299

devfs_get_unregister_slave

300

devfs_register_chrdev

301

devfs_register_blkdev

303

devfs_unregister_chrdev

304

devfs_unregister_blkdev

305

12. Power Management

307

pm_register

307

pm_unregister

308

pm_unregister_all

309

pm_send

310

pm_send_all

311

pm_find

313

13. Block Devices

315

blk_cleanup_queue

315

blk_queue_headactive

316

blk_queue_make_request

317

blk_init_queue

318

generic_make_request

320

submit_bh

322

ll_rw_block

323

end_that_request_first

324

14. Miscellaneous Devices

327

misc_register

327

misc_deregister

328

15. Video4Linux

330

video_register_device

330

video_unregister_device

331

16. Sound Devices

333

register_sound_special

333

register_sound_mixer

334

register_sound_midi

335

register_sound_dsp

336

register_sound_synth

337

unregister_sound_special

338

unregister_sound_mixer

339

unregister_sound_midi

340

unregister_sound_dsp

341

unregister_sound_synth

342

17. USB Devices

344

usb_register

344

usb_scan_devices

345

usb_deregister

345

usb_alloc_bus

346

usb_free_bus

347

usb_register_bus

348

usb_deregister_bus

349

usb_match_id

350

usb_alloc_urb

353

usb_free_urb

354

usb_control_msg

355

usb_bulk_msg

357

18. 16x50 UART Driver

359

register_serial

359

unregister_serial

360

19. Z85230 Support Library

362

z8530_interrupt

362

z8530_sync_open

363

z8530_sync_close

364

z8530_sync_dma_open

365

z8530_sync_dma_close

366

z8530_sync_txdma_open

367

z8530_sync_txdma_close

368

z8530_describe

369

z8530_init

370

z8530_shutdown

371

z8530_channel_load

372

z8530_null_rx

373

z8530_queue_xmit

374

z8530_get_stats

376

20. Frame Buffer Library

377

20.1. Frame Buffer Memory

377

register_framebuffer

377

unregister_framebuffer

378

20.2. Frame Buffer Console

379

fbcon_redraw_clear

379

fbcon_redraw_bmove

381

20.3. Frame Buffer Colormap

382

fb_alloc_cmap

382

fb_copy_cmap

383

fb_get_cmap

385

fb_set_cmap

386

fb_default_cmap

387

fb_invert_cmaps

388

20.4. Frame Buffer Generic Functions

389

fbgen_get_fix

390

fbgen_get_var

391

fbgen_set_var

392

fbgen_get_cmap

393

fbgen_set_cmap

394

fbgen_pan_display

396

fbgen_do_set_var

397

fbgen_set_disp

398

fbgen_install_cmap

399

fbgen_update_var

400

fbgen_switch

401

fbgen_blank

402

20.5. Frame Buffer Video Mode Database

403

fb_find_mode

404

fb_try_mode

406

20.6. Frame Buffer Macintosh Video Mode Database

407

console_getmode

407

console_setmode

408

console_setcmap

409

console_powermode

410

mac_vmode_to_var

411

Chapter 1. Driver Basics

1.1. Driver Entry and Exit points

module_init

Name

module_init— driver initialization entry point

Synopsis

module_init ( x);

Arguments

function to be run at kernel boot time or module insertion

Description

module_init will add the driver initialization routine in the “ initcall.int” code

segment if the driver is checked as “y” or static, or else it will wrap the driver

Chapter 1. Driver Basics

initialization routine with init_module which is used by insmod and modprobe when

the driver is used as a module.

module_exit

Name

module_exit - driver exit entry point

Synopsis

module_exit ( x);

Arguments

function to be run when driver is removed

Description

module_exit will wrap the driver clean-up code with cleanup_module when used

with rmmod when the driver is a module. If the driver is statically compiled into the

kernel, module_exit has no effect.

Chapter 1. Driver Basics

atomic_sub

Name

atomic_sub - subtract the atomic variable

Synopsis

void atomic_sub (int i, atomic_t * v);

Arguments

integer value to subtract

pointer of type atomic_t

Description

Atomically subtracts i from v. Note that the guaranteed useful range of an atomic_t is

only 24 bits.

Chapter 1. Driver Basics

atomic_sub_and_test

Name

atomic_sub_and_test - subtract value from variable and test result

Synopsis

int atomic_sub_and_test (int i, atomic_t * v);

Arguments

integer value to subtract

pointer of type atomic_t

Description

Atomically subtracts i from v and returns true if the result is zero, or false for all other

cases. Note that the guaranteed useful range of an atomic_t is only 24 bits.

Chapter 1. Driver Basics

atomic_dec_and_test

Name

atomic_dec_and_test— decrement and test

Synopsis

int atomic_dec_and_test (atomic_t * v);

Arguments

pointer of type atomic_t

Description

Atomically decrements v by 1 and returns true if the result is 0, or false for all other

cases. Note that the guaranteed useful range of an atomic_t is only 24 bits.

Chapter 1. Driver Basics

atomic_inc_and_test

Name

atomic_inc_and_test— increment and test

Synopsis

int atomic_inc_and_test (atomic_t * v);

Arguments

pointer of type atomic_t

Description

Atomically increments v by 1 and returns true if the result is zero, or false for all other

cases. Note that the guaranteed useful range of an atomic_t is only 24 bits.

Chapter 1. Driver Basics

atomic_add_negative

Name

atomic_add_negative - add and test if negative

Synopsis

int atomic_add_negative (int i, atomic_t * v);

Arguments

integer value to add

pointer of type atomic_t

Description

Atomically adds i to v and returns true if the result is negative, or false when result is

greater than or equal to zero. Note that the guaranteed useful range of an atomic_t is

only 24 bits.

Chapter 1. Driver Basics

1.3. Delaying, scheduling, and timer routines

schedule_timeout

Name

schedule_timeout— sleep until timeout

Synopsis

signed long schedule_timeout (signed long timeout);

Arguments

timeout

timeout value in jiffies

Description

Make the current task sleep until timeout jiffies have elapsed. The routine will return

immediately unless the current task state has been set (see set_current_state).

You can set the task state as follows -

TASK_UNINTERRUPTIBLE - at least timeout jiffies are guaranteed to pass before the

routine returns. The routine will return 0

Chapter 1. Driver Basics

TASK_INTERRUPTIBLE - the routine may return early if a signal is delivered to the

current task. In this case the remaining time in jiffies will be returned, or 0 if the timer

expired in time

The current task state is guaranteed to be TASK_RUNNING when this routine returns.

Specifying a timeout value of MAX_SCHEDULE_TIMEOUT will schedule the CPU

away without a bound on the timeout. In this case the return value will be

MAX_SCHEDULE_TIMEOUT.

In all cases the return value is guaranteed to be non-negative.

Chapter 2. Data Types

Description

Insert a new entry after the specified head. This is good for implementing stacks.

list_add_tail

Name

list_add_tail - add a new entry

Synopsis

void list_add_tail (struct list_head * new, struct list_head *

head);

Arguments

new

new entry to be added

head

list head to add it before

Chapter 2. Data Types

Description

Insert a new entry before the specified head. This is useful for implementing queues.

list_del

Name

list_del - deletes entry from list.

Synopsis

void list_del (struct list_head * entry);

Arguments

entry

the element to delete from the list.

Note

list_empty on entry does not return true after this, the entry is in an undefined state.

Chapter 3. Basic C Library Functions

When writing drivers, you cannot in general use routines which are from the C Library.

Some of the functions have been found generally useful and they are listed below. The

behaviour of these functions may vary slightly from those defined by ANSI, and these

deviations are noted in the text.

3.1. String Conversions

simple_strtol

Name

simple_strtol - convert a string to a signed long

Synopsis

long simple_strtol (const char * cp, char ** endp, unsigned int

base);

Arguments

The start of the string

Chapter 3. Basic C Library Functions

endp

A pointer to the end of the parsed string will be placed here

base

The number base to use

simple_strtoll

Name

simple_strtoll - convert a string to a signed long long

Synopsis

long long simple_strtoll (const char * cp, char ** endp,

unsigned int base);

Arguments

The start of the string

Chapter 3. Basic C Library Functions

endp

A pointer to the end of the parsed string will be placed here

base

The number base to use

simple_strtoul

Name

simple_strtoul - convert a string to an unsigned long

Synopsis

unsigned long simple_strtoul (const char * cp, char ** endp,

unsigned int base);

Arguments

The start of the string

Chapter 3. Basic C Library Functions

endp

A pointer to the end of the parsed string will be placed here

base

The number base to use

simple_strtoull

Name

simple_strtoull - convert a string to an unsigned long long

Synopsis

unsigned long long simple_strtoull (const char * cp, char **

endp, unsigned int base);

Arguments

The start of the string

Chapter 3. Basic C Library Functions

endp

A pointer to the end of the parsed string will be placed here

base

The number base to use

vsprintf

Name

vsprintf - Format a string and place it in a buffer

Synopsis

int vsprintf (char * buf, const char * fmt, va_list args);

Arguments

buf

The buffer to place the result into

fmt

The format string to use

Chapter 3. Basic C Library Functions

args

Arguments for the format string

Description

Call this function if you are already dealing with a va_list. You probably want sprintf

instead.

sprintf

Name

sprintf - Format a string and place it in a buffer

Synopsis

int sprintf (char * buf, const char * fmt,

);

Arguments

buf

The buffer to place the result into

Chapter 3. Basic C Library Functions

src

Where to copy the string from

count

The maximum number of bytes to copy

Description

Note that unlike userspace strncpy, this does not NUL-pad the buffer. However, the

result is not NUL-terminated if the source exceeds count bytes.

strcat

Name

strcat - Append one NUL-terminated string to another

Synopsis

char * strcat (char * dest, const char * src);

Chapter 3. Basic C Library Functions

Arguments

dest

The string to be appended to

src

The string to append to it

strncat

Name

strncat - Append a length-limited, NUL-terminated string to another

Synopsis

char * strncat (char * dest, const char * src, size_t count);

Arguments

dest

The string to be appended to

Chapter 3. Basic C Library Functions

Arguments

src

Where to copy from

dest

Where to copy to

count

The size of the area.

Description

Note that this is the same as memcpy, with the arguments reversed. memcpy is the

standard, bcopy is a legacy BSD function.

You should not use this function to access IO space, use memcpy_toio or

memcpy_fromio instead.

memcpy

Name

memcpy - Copy one area of memory to another

Chapter 3. Basic C Library Functions

memmove

Name

memmove - Copy one area of memory to another

Synopsis

void * memmove (void * dest, const void * src, size_t count);

Arguments

dest

Where to copy to

src

Where to copy from

count

The size of the area.

Description

Unlike memcpy, memmove copes with overlapping areas.

Chapter 3. Basic C Library Functions

memscan

Name

memscan - Find a character in an area of memory.

Synopsis

void * memscan (void * addr, int c, size_t size);

Arguments

addr

The memory area

The byte to search for

size

The size of the area.

Description

returns the address of the first occurrence of c, or 1 byte past the area if c is not found

Chapter 3. Basic C Library Functions

memchr

Name

memchr - Find a character in an area of memory.

Synopsis

void * memchr (const void * s, int c, size_t n);

Arguments

The memory area

The byte to search for

The size of the area.

Description

returns the address of the first occurrence of c, or NULL if c is not found

Chapter 3. Basic C Library Functions

3.3. Bit Operations

set_bit

Name

set_bit - Atomically set a bit in memory

Synopsis

void set_bit (int nr, volatile void * addr);

Arguments

the bit to set

addr

the address to start counting from

Description

This function is atomic and may not be reordered. See set_bit if you do not

require the atomic guarantees. Note that nr may be almost arbitrarily large; this

function is not restricted to acting on a single-word quantity.

Chapter 3. Basic C Library Functions

set_bit

Name

set_bit - Set a bit in memory

Synopsis

void set_bit (int nr, volatile void * addr);

Arguments

the bit to set

addr

the address to start counting from

Description

Unlike set_bit, this function is non-atomic and may be reordered. If it’s called on the

same region of memory simultaneously, the effect may be that only one operation

succeeds.

Chapter 3. Basic C Library Functions

clear_bit

Name

clear_bit - Clears a bit in memory

Synopsis

void clear_bit (int nr, volatile void * addr);

Arguments

Bit to clear

addr

Address to start counting from

Description

clear_bit is atomic and may not be reordered. However, it does not contain a

memory barrier, so if it is used for locking purposes, you should call

Chapter 3. Basic C Library Functions

smp_mb before_clear_bit and/or smp_mb after_clear_bit in order to

ensure changes are visible on other processors.

change_bit

Name

change_bit - Toggle a bit in memory

Synopsis

void change_bit (int nr, volatile void * addr);

Arguments

Bit to clear

addr

Address to start counting from

Chapter 3. Basic C Library Functions

Description

change_bit is atomic and may not be reordered. Note that nr may be almost

arbitrarily large; this function is not restricted to acting on a single-word quantity.

test_and_set_bit

Name

test_and_set_bit - Set a bit and return its old value

Synopsis

int test_and_set_bit (int nr, volatile void * addr);

Arguments

Bit to set

addr

Address to count from

Chapter 3. Basic C Library Functions

Description

This operation is atomic and cannot be reordered. It also implies a memory barrier.

test_and_set_bit

Name

test_and_set_bit - Set a bit and return its old value

Synopsis

int test_and_set_bit (int nr, volatile void * addr);

Arguments

Bit to set

addr

Address to count from

Chapter 3. Basic C Library Functions

Description

This operation is non-atomic and can be reordered. If two examples of this operation

race, one can appear to succeed but actually fail. You must protect multiple accesses

with a lock.

test_and_clear_bit

Name

test_and_clear_bit - Clear a bit and return its old value

Synopsis

int test_and_clear_bit (int nr, volatile void * addr);

Arguments

Bit to set

addr

Address to count from

Chapter 3. Basic C Library Functions

Description

This operation is atomic and cannot be reordered. It also implies a memory barrier.

test_and_clear_bit

Name

test_and_clear_bit - Clear a bit and return its old value

Synopsis

int test_and_clear_bit (int nr, volatile void * addr);

Arguments

Bit to set

addr

Address to count from

Chapter 3. Basic C Library Functions

Description

This operation is non-atomic and can be reordered. If two examples of this operation

race, one can appear to succeed but actually fail. You must protect multiple accesses

with a lock.

test_and_change_bit

Name

test_and_change_bit - Change a bit and return its new value

Synopsis

int test_and_change_bit (int nr, volatile void * addr);

Arguments

Bit to set

addr

Address to count from

Chapter 3. Basic C Library Functions

Description

This operation is atomic and cannot be reordered. It also implies a memory barrier.

test_bit

Name

test_bit - Determine whether a bit is set

Synopsis

int test_bit (int nr, const volatile void * addr);

Arguments

bit number to test

addr

Address to start counting from

Chapter 3. Basic C Library Functions

find_first_zero_bit

Name

find_first_zero_bit - find the first zero bit in a memory region

Synopsis

int find_first_zero_bit (void * addr, unsigned size);

Arguments

addr

The address to start the search at

size

The maximum size to search

Description

Returns the bit-number of the first zero bit, not the number of the byte containing a bit.

Chapter 3. Basic C Library Functions

find_next_zero_bit

Name

find_next_zero_bit - find the first zero bit in a memory region

Synopsis

int find_next_zero_bit (void * addr, int size, int offset);

Arguments

addr

The address to base the search on

size

The maximum size to search

offset

The bitnumber to start searching at

Chapter 4. Memory Management in

Linux

4.1. The Slab Cache

kmem_cache_create

Name

kmem_cache_create— Create a cache.

Synopsis

kmem_cache_t * kmem_cache_create (const char * name, size_t

size, size_t offset, unsigned long flags, void (*ctor) (void*,

kmem_cache_t *, unsigned long), void (*dtor) (void*,

kmem_cache_t *, unsigned long));

Arguments

name

A string which is used in /proc/slabinfo to identify this cache.

Chapter 4. Memory Management in Linux

size

The size of objects to be created in this cache.

offset

The offset to use within the page.

flags

SLAB flags

ctor

A constructor for the objects.

dtor

A destructor for the objects.

Description

Returns a ptr to the cache on success, NULL on failure. Cannot be called within a int,

but can be interrupted. The ctor is run when new pages are allocated by the cache and

the dtor is run before the pages are handed back. The flags are

SLAB_POISON - Poison the slab with a known test pattern (a5a5a5a5) to catch

references to uninitialised memory.

SLAB_RED_ZONE - Insert ‘Red’ zones around the allocated memory to check for buffer

overruns.

SLAB_NO_REAP - Don’t automatically reap this cache when we’re under memory

pressure.

SLAB_HWCACHE_ALIGN - Align the objects in this cache to a hardware cacheline. This

can be beneficial if you’re counting cycles as closely as davem.

Chapter 4. Memory Management in Linux

kmem_cache_shrink

Name

kmem_cache_shrink— Shrink a cache.

Synopsis

int kmem_cache_shrink (kmem_cache_t * cachep);

Arguments

cachep

The cache to shrink.

Description

Releases as many slabs as possible for a cache. To help debugging, a zero exit status

indicates all slabs were released.

Chapter 4. Memory Management in Linux

kmem_cache_destroy

Name

kmem_cache_destroy - delete a cache

Synopsis

int kmem_cache_destroy (kmem_cache_t * cachep);

Arguments

cachep

the cache to destroy

Description

Remove a kmem_cache_t object from the slab cache. Returns 0 on success.

It is expected this function will be called by a module when it is unloaded. This will

remove the cache completely, and avoid a duplicate cache being allocated each time a

module is loaded and unloaded, if the module doesn’t have persistent in-kernel storage

across loads and unloads.

The caller must guarantee that noone will allocate memory from the cache during the

kmem_cache_destroy.

Chapter 4. Memory Management in Linux

kmem_cache_alloc

Name

kmem_cache_alloc— Allocate an object

Synopsis

void * kmem_cache_alloc (kmem_cache_t * cachep, int flags);

Arguments

cachep

The cache to allocate from.

flags

See kmalloc.

Description

Allocate an object from this cache. The flags are only relevant if the cache has no

available objects.

Chapter 4. Memory Management in Linux

kmalloc

Name

kmalloc— allocate memory

Synopsis

void * kmalloc (size_t size, int flags);

Arguments

size

how many bytes of memory are required.

flags

the type of memory to allocate.

Description

kmalloc is the normal method of allocating memory in the kernel.

The flagsargument may be one of:

Chapter 4. Memory Management in Linux

GFP_USER - Allocate memory on behalf of user. May sleep.

GFP_KERNEL - Allocate normal kernel ram. May sleep.

GFP_ATOMIC - Allocation will not sleep. Use inside interrupt handlers.

Additionally, the GFP_DMA flag may be set to indicate the memory must be suitable for

DMA. This can mean different things on different platforms. For example, on i386, it

means that the memory must come from the first 16MB.

kmem_cache_free

Name

kmem_cache_free— Deallocate an object

Synopsis

void kmem_cache_free (kmem_cache_t * cachep, void * objp);

Arguments

cachep

The cache the allocation was from.

Chapter 5. The proc filesystem

5.1. sysctl interface

register_sysctl_table

Name

register_sysctl_table - register a sysctl heirarchy

Synopsis

struct ctl_table_header * register_sysctl_table (ctl_table *

table, int insert_at_head);

Arguments

table

the top-level table structure

insert_at_head

whether the entry should be inserted in front or at the end

Chapter 5. The proc filesystem

Description

with a ctl_name of 0 terminates the table.

The members of the &ctl_table structure are used as follows:

ctl_name - This is the numeric sysctl value used by sysctl(2). The number must be

unique within that level of sysctl

procname - the name of the sysctl file under /proc/sys. Set to NULL to not enter a sysctl

file

data - a pointer to data for use by proc_handler

maxlen - the maximum size in bytes of the data

mode - the file permissions for the /proc/sys file, and for sysctl(2)

child - a pointer to the child sysctl table if this entry is a directory, or NULL.

proc_handler - the text handler routine (described below)

strategy - the strategy routine (described below)

de - for internal use by the sysctl routines

extra1, extra2 - extra pointers usable by the proc handler routines

Leaf nodes in the sysctl tree will be represented by a single file under /proc; non-leaf

nodes will be represented by directories.

sysctl(2) can automatically manage read and write requests through the sysctl table. The

data and maxlen fields of the ctl_table struct enable minimal validation of the values

being written to be performed, and the mode field allows minimal authentication.

More sophisticated management can be enabled by the provision of a strategy routine

with the table entry. This will be called before any automatic read or write of the data is

performed.

The strategy routine may return

< 0 - Error occurred (error is passed to user process)

Chapter 5. The proc filesystem

0 - OK - proceed with automatic read or write.

> 0 - OK - read or write has been done by the strategy routine, so return immediately.

There must be a proc_handler routine for any terminal nodes mirrored under /proc/sys

(non-terminals are handled by a built-in directory handler). Several default handlers are

available to cover common cases -

proc_dostring, proc_dointvec, proc_dointvec_jiffies,

proc_dointvec_minmax, proc_doulongvec_ms_jiffies_minmax,

proc_doulongvec_minmax

It is the handler’s job to read the input buffer from user memory and process it. The

handler should return 0 on success.

This routine returns NULL on a failure to register, and a pointer to the table header on

success.

unregister_sysctl_table

Name

unregister_sysctl_table— unregister a sysctl table heirarchy

Synopsis

void unregister_sysctl_table (struct ctl_table_header * header);

Chapter 5. The proc filesystem

Arguments

header

the header returned from register_sysctl_table

Description

Unregisters the sysctl table and all children. proc entries may not actually be removed

until they are no longer used by anyone.

proc_dostring

Name

proc_dostring - read a string sysctl

Synopsis

int proc_dostring (ctl_table * table, int write, struct file *

filp, void * buffer, size_t * lenp);

Chapter 5. The proc filesystem

Arguments

table

the sysctl table

write

TRUE if this is a write to the sysctl file

filp

the file structure

buffer

the user buffer

lenp

the size of the user buffer

Description

Reads/writes a string from/to the user buffer. If the kernel buffer provided is not large

enough to hold the string, the string is truncated. The copied string is

NULL-terminated. If the string is being read by the user process, it is copied and a

newline ’\n’ is added. It is truncated if the buffer is not large enough.

Returns 0 on success.

Chapter 5. The proc filesystem

proc_dointvec

Name

proc_dointvec - read a vector of integers

Synopsis

int proc_dointvec (ctl_table * table, int write, struct file *

filp, void * buffer, size_t * lenp);

Arguments

table

the sysctl table

write

TRUE if this is a write to the sysctl file

filp

the file structure

buffer

the user buffer

lenp

the size of the user buffer

Chapter 5. The proc filesystem

Description

Reads/writes up to table->maxlen/sizeof(unsigned int) integer values from/to the user

buffer, treated as an ASCII string.

Returns 0 on success.

proc_dointvec_minmax

Name

proc_dointvec_minmax - read a vector of integers with min/max values

Synopsis

int proc_dointvec_minmax (ctl_table * table, int write, struct

file * filp, void * buffer, size_t * lenp);

Arguments

table

the sysctl table

write

TRUE if this is a write to the sysctl file

Chapter 5. The proc filesystem

filp

the file structure

buffer

the user buffer

lenp

the size of the user buffer

Description

Reads/writes up to table->maxlen/sizeof(unsigned int) integer values from/to the user

buffer, treated as an ASCII string.

This routine will ensure the values are within the range specified by table->extra1 (min)

and table->extra2 (max).

Returns 0 on success.

proc_doulongvec_minmax

Name

proc_doulongvec_minmax - read a vector of long integers with min/max values

Chapter 5. The proc filesystem

Synopsis

int proc_doulongvec_minmax (ctl_table * table, int write, struct

file * filp, void * buffer, size_t * lenp);

Arguments

table

the sysctl table

write

TRUE if this is a write to the sysctl file

filp

the file structure

buffer

the user buffer

lenp

the size of the user buffer

Description

Reads/writes up to table->maxlen/sizeof(unsigned long) unsigned long values from/to

the user buffer, treated as an ASCII string.

This routine will ensure the values are within the range specified by table->extra1 (min)

and table->extra2 (max).

Chapter 5. The proc filesystem

Returns 0 on success.

proc_doulongvec_ms_jiffies_minmax

Name

proc_doulongvec_ms_jiffies_minmax— read a vector of millisecond

values with min/max values

Synopsis

int proc_doulongvec_ms_jiffies_minmax (ctl_table * table, int

write, struct file * filp, void * buffer, size_t * lenp);

Arguments

table

the sysctl table

write

TRUE if this is a write to the sysctl file

filp

the file structure

Chapter 5. The proc filesystem

buffer

the user buffer

lenp

the size of the user buffer

Description

Reads/writes up to table->maxlen/sizeof(unsigned long) unsigned long values from/to

the user buffer, treated as an ASCII string. The values are treated as milliseconds, and

converted to jiffies when they are stored.

This routine will ensure the values are within the range specified by table->extra1 (min)

and table->extra2 (max).

Returns 0 on success.

proc_dointvec_jiffies

Name

proc_dointvec_jiffies - read a vector of integers as seconds

Synopsis

int proc_dointvec_jiffies (ctl_table * table, int write, struct

file * filp, void * buffer, size_t * lenp);

Chapter 5. The proc filesystem

Arguments

table

the sysctl table

write

TRUE if this is a write to the sysctl file

filp

the file structure

buffer

the user buffer

lenp

the size of the user buffer

Description

Reads/writes up to table->maxlen/sizeof(unsigned int) integer values from/to the user

buffer, treated as an ASCII string. The values read are assumed to be in seconds, and

are converted into jiffies.

Returns 0 on success.

Chapter 6. The Linux VFS

6.1. The Directory Cache

d_invalidate

Name

d_invalidate— invalidate a dentry

Synopsis

int d_invalidate (struct dentry * dentry);

Arguments

dentry

dentry to invalidate

Description

Try to invalidate the dentry if it turns out to be possible. If there are other dentries that

can be reached through this one we can’t delete it and we return -EBUSY. On success

Chapter 6. The Linux VFS

we return 0.

no dcache lock.

d_find_alias

Name

d_find_alias - grab a hashed alias of inode

Synopsis

struct dentry * d_find_alias (struct inode * inode);

Arguments

inode

inode in question

Description

If inode has a hashed alias - acquire the reference to alias and return it. Otherwise

return NULL. Notice that if inode is a directory there can be only one alias and it can

be unhashed only if it has no children.

Chapter 6. The Linux VFS

prune_dcache

Name

prune_dcache - shrink the dcache

Synopsis

void prune_dcache (int count);

Arguments

count

number of entries to try and free

Description

Shrink the dcache. This is done when we need more memory, or simply when we need

to unmount something (at which point we need to unuse all dentries).

This function may fail to free any resources if all the dentries are in use.

Chapter 6. The Linux VFS

d_alloc

Name

d_alloc - allocate a dcache entry

Synopsis

struct dentry * d_alloc (struct dentry * parent, const struct

qstr * name);

Arguments

parent

parent of entry to allocate

name

qstr of the name

Description

Allocates a dentry. It returns NULL if there is insufficient memory available. On a

success the dentry is returned. The name passed in is copied and the copy passed in

may be reused after this call.

Chapter 6. The Linux VFS

d_instantiate

Name

d_instantiate - fill in inode information for a dentry

Synopsis

void d_instantiate (struct dentry * entry, struct inode *

inode);

Arguments

entry

dentry to complete

inode

inode to attach to this dentry

Description

Fill in inode information in the entry.

This turns negative dentries into productive full members of society.

NOTE! This assumes that the inode count has been incremented (or otherwise set) by

the caller to indicate that it is now in use by the dcache.

Chapter 6. The Linux VFS

d_alloc_root

Name

d_alloc_root— allocate root dentry

Synopsis

struct dentry * d_alloc_root (struct inode * root_inode);

Arguments

root_inode

inode to allocate the root for

Description

Allocate a root (“/”) dentry for the inode given. The inode is instantiated and returned.

NULL is returned if there is insufficient memory or the inode passed is NULL.

Chapter 6. The Linux VFS

d_lookup

Name

d_lookup - search for a dentry

Synopsis

struct dentry * d_lookup (struct dentry * parent, struct qstr *

name);

Arguments

parent

parent dentry

name

qstr of name we wish to find

Description

Searches the children of the parent dentry for the name in question. If the dentry is

found its reference count is incremented and the dentry is returned. The caller must use

d_put to free the entry when it has finished using it. NULL is returned on failure.

Chapter 6. The Linux VFS

d_validate

Name

d_validate - verify dentry provided from insecure source

Synopsis

int d_validate (struct dentry * dentry, struct dentry *

dparent);

Arguments

dentry

The dentry alleged to be valid child of dparent

dparent

The parent dentry (known to be valid)

Description

An insecure source has sent us a dentry, here we verify it and dget it. This is used by

ncpfs in its readdir implementation. Zero is returned in the dentry is invalid.

Chapter 6. The Linux VFS

d_path

Name

d_path - return the path of a dentry

Synopsis

char * d_path (struct dentry * dentry, struct vfsmount *

vfsmnt, struct dentry * root, struct vfsmount * rootmnt, char *

buffer, int buflen);

Arguments

dentry

dentry to report

vfsmnt

vfsmnt to which the dentry belongs

root

root dentry

rootmnt

vfsmnt to which the root dentry belongs

Chapter 6. The Linux VFS

buffer

buffer to return value in

buflen

buffer length

Description

Convert a dentry into an ASCII path name. If the entry has been deleted the string “

(deleted)” is appended. Note that this is ambiguous. Returns the buffer.

“buflen” should be PAGE_SIZE or more. Caller holds the dcache_lock.

is_subdir

Name

is_subdir - is new dentry a subdirectory of old_dentry

Synopsis

int is_subdir (struct dentry * new_dentry, struct dentry *

old_dentry);

Chapter 6. The Linux VFS

Arguments

new_dentry

new dentry

old_dentry

old dentry

Description

Returns 1 if new_dentry is a subdirectory of the parent (at any depth). Returns 0

otherwise.

find_inode_number

Name

find_inode_number - check for dentry with name

Synopsis

ino_t find_inode_number (struct dentry * dir, struct qstr *

name);

Chapter 6. The Linux VFS

Arguments

dir

directory to check

name

Name to find.

Description

Check whether a dentry already exists for the given name, and return the inode number

if it has an inode. Otherwise 0 is returned.

This routine is used to post-process directory listings for filesystems using synthetic

inode numbers, and is necessary to keep getcwd working.

d_drop

Name

d_drop - drop a dentry

Synopsis

void d_drop (struct dentry * dentry);

Chapter 6. The Linux VFS

Arguments

dentry

dentry to drop

Description

d_drop unhashes the entry from the parent dentry hashes, so that it won’t be found

through a VFS lookup any more. Note that this is different from deleting the dentry -

d_delete will try to mark the dentry negative if possible, giving a successful _negative_

lookup, while d_drop will just make the cache lookup fail.

d_drop is used mainly for stuff that wants to invalidate a dentry for some reason (NFS

timeouts or autofs deletes).

d_add

Name

d_add - add dentry to hash queues

Chapter 6. The Linux VFS

Synopsis

void d_add (struct dentry * entry, struct inode * inode);

Arguments

entry

dentry to add

inode

The inode to attach to this dentry

Description

This adds the entry to the hash queues and initializes inode. The entry was actually

filled in earlier during d_alloc.

dget

Name

dget - get a reference to a dentry

Chapter 6. The Linux VFS

Synopsis

struct dentry * dget (struct dentry * dentry);

Arguments

dentry

dentry to get a reference to

Description

Given a dentry or NULL pointer increment the reference count if appropriate and return

the dentry. A dentry will not be destroyed when it has references. dget should never be

called for dentries with zero reference counter. For these cases (preferably none,

functions in dcache.c are sufficient for normal needs and they take necessary

precautions) you should hold dcache_lock and call dget_locked instead of dget.

d_unhashed

Name

d_unhashed - is dentry hashed

Chapter 6. The Linux VFS

Synopsis

void mark_inode_dirty (struct inode * inode, int flags);

Arguments

inode

inode to mark

flags

what kind of dirty (i.e. I_DIRTY_SYNC) Mark an inode as dirty. Callers should

use mark_inode_dirty or mark_inode_dirty_sync.

write_inode_now

Name

write_inode_now - write an inode to disk

Synopsis

void write_inode_now (struct inode * inode, int sync);

Chapter 6. The Linux VFS

Arguments

inode

inode to write to disk

sync

whether the write should be synchronous or not

Description

This function commits an inode to disk immediately if it is dirty. This is primarily

needed by knfsd.

clear_inode

Name

clear_inode - clear an inode

Synopsis

void clear_inode (struct inode * inode);

Chapter 6. The Linux VFS

Arguments

inode

inode to clear

Description

This is called by the filesystem to tell us that the inode is no longer useful. We just

terminate it with extreme prejudice.

invalidate_inodes

Name

invalidate_inodes - discard the inodes on a device

Synopsis

int invalidate_inodes (struct super_block * sb);

Chapter 6. The Linux VFS

Arguments

superblock

Description

Discard all of the inodes for a given superblock. If the discard fails because there are

busy inodes then a non zero value is returned. If the discard is successful all the inodes

have been discarded.

get_empty_inode

Name

get_empty_inode— obtain an inode

Synopsis

struct inode * get_empty_inode ( void);

Chapter 6. The Linux VFS

Arguments

void

no arguments

Description

This is called by things like the networking layer etc that want to get an inode without

any inode number, or filesystems that allocate new inodes with no pre-existing

information.

On a successful return the inode pointer is returned. On a failure a NULL pointer is

returned. The returned inode is not on any superblock lists.

iunique

Name

iunique - get a unique inode number

Synopsis

ino_t iunique (struct super_block * sb, ino_t max_reserved);

Chapter 6. The Linux VFS

Arguments

superblock

max_reserved

highest reserved inode number

Description

Obtain an inode number that is unique on the system for a given superblock. This is

used by file systems that have no natural permanent inode numbering system. An inode

number is returned that is higher than the reserved limit but unique.

BUGS

With a large number of inodes live on the file system this function currently becomes

quite slow.

insert_inode_hash

Name

insert_inode_hash— hash an inode

Chapter 6. The Linux VFS

Synopsis

void insert_inode_hash (struct inode * inode);

Arguments

inode

unhashed inode

Description

Add an inode to the inode hash for this superblock. If the inode has no superblock it is

added to a separate anonymous chain.

remove_inode_hash

Name

remove_inode_hash - remove an inode from the hash

Synopsis

void remove_inode_hash (struct inode * inode);

Chapter 6. The Linux VFS

Arguments

inode

inode of file

block

block to find

Description

Returns the block number on the device holding the inode that is the disk block number

for the block of the file requested. That is, asked for block 4 of inode 1 the function will

return the disk block relative to the disk start that holds that block of the file.

update_atime

Name

update_atime - update the access time

Synopsis

void update_atime (struct inode * inode);

102

Chapter 6. The Linux VFS

Arguments

inode

inode accessed

Description

Update the accessed time on an inode and mark it for writeback. This function

automatically handles read only file systems and media, as well as the “noatime” flag

and inode specific “noatime” markers.

make_bad_inode

Name

make_bad_inode - mark an inode bad due to an I/O error

Synopsis

void make_bad_inode (struct inode * inode);

103

Chapter 6. The Linux VFS

Arguments

inode

Inode to mark bad

Description

When an inode cannot be read due to a media or remote network failure this function

makes the inode “bad” and causes I/O operations on it to fail from this point on.

is_bad_inode

Name

is_bad_inode - is an inode errored

Synopsis

int is_bad_inode (struct inode * inode);

104

Chapter 6. The Linux VFS

Arguments

the file system structure

Description

Adds the file system passed to the list of file systems the kernel is aware of for mount

and other syscalls. Returns 0 on success, or a negative errno code on an error.

The &struct file_system_type that is passed is linked into the kernel structures and must

not be freed until the file system has been unregistered.

unregister_filesystem

Name

unregister_filesystem— unregister a file system

Synopsis

int unregister_filesystem (struct file_system_type * fs);

106

Chapter 6. The Linux VFS

Arguments

filesystem to unregister

Description

Remove a file system that was previously successfully registered with the kernel. An

error is returned if the file system is not found. Zero is returned on a success.

Once this function has returned the &struct file_system_type structure may be freed or

reused.

wait_on_super

Name

wait_on_super - wait on a superblock

Synopsis

void wait_on_super (struct super_block * sb);

107

Chapter 6. The Linux VFS

Arguments

superblock to wait on

Description

Waits for a superblock to become unlocked and then returns. It does not take the lock.

This is an internal function. See wait_on_super.

get_super

Name

get_super - get the superblock of a device

Synopsis

struct super_block * get_super (kdev_t dev);

108

Chapter 6. The Linux VFS

Arguments

dev

device to get the superblock for

Description

Scans the superblock list and finds the superblock of the file system mounted on the

device given. NULL is returned if no match is found.

6.4. File Locks

posix_lock_file

Name

posix_lock_file—

Synopsis

int posix_lock_file (struct file * filp, struct file_lock *

caller, unsigned int wait);

109

Chapter 6. The Linux VFS

Arguments

filp

The file to apply the lock to

caller

The lock to be applied

wait

1 to retry automatically, 0 to return -EAGAIN

Description

Add a POSIX style lock to a file. We merge adjacent locks whenever possible. POSIX

locks are sorted by owner task, then by starting address

Kai Petzke writes

To make freeing a lock much faster, we keep a pointer to the lock before the actual one.

But the real gain of the new coding was, that lock_it and unlock_it became one

function.

To all purists

Yes, I use a few goto’s. Just pass on to the next function.

110

Chapter 6. The Linux VFS

get_lease

Name

get_lease - revoke all outstanding leases on file

Synopsis

int get_lease (struct inode * inode, unsigned int mode);

Arguments

inode

the inode of the file to return

mode

the open mode (read or write)

Description

get_lease (inlined for speed) has checked there already is a lease on this file. Leases are

broken on a call to open or truncate. This function can sleep unless you specified

O_NONBLOCK to your open.

111

Chapter 6. The Linux VFS

lease_get_mtime

Name

lease_get_mtime—

Synopsis

time_t lease_get_mtime (struct inode * inode);

Arguments

inode

the inode

Description

This is to force NFS clients to flush their caches for files with exclusive leases. The

justification is that if someone has an exclusive lease, then they could be modifiying it.

112

Chapter 6. The Linux VFS

posix_block_lock

Name

posix_block_lock - blocks waiting for a file lock

Synopsis

void posix_block_lock (struct file_lock * blocker, struct

file_lock * waiter);

Arguments

blocker

the lock which is blocking

waiter

the lock which conflicts and has to wait

Description

lockd needs to block waiting for locks.

113

Chapter 6. The Linux VFS

lock_may_read

Name

lock_may_read - checks that the region is free of locks

Synopsis

int lock_may_read (struct inode * inode, loff_t start, unsigned

long len);

Arguments

inode

the inode that is being read

start

the first byte to read

len

the number of bytes to read

Description

Emulates Windows locking requirements. Whole-file mandatory locks (share modes)

can prohibit a read and byte-range POSIX locks can prohibit a read if they overlap.

115

Chapter 6. The Linux VFS

N.B. this function is only ever called from knfsd and ownership of locks is never

checked.

lock_may_write

Name

lock_may_write - checks that the region is free of locks

Synopsis

int lock_may_write (struct inode * inode, loff_t start, unsigned

long len);

Arguments

inode

the inode that is being written

start

the first byte to write

len

the number of bytes to write

116

Chapter 6. The Linux VFS

Description

Emulates Windows locking requirements. Whole-file mandatory locks (share modes)

can prohibit a write and byte-range POSIX locks can prohibit a write if they overlap.

N.B. this function is only ever called from knfsd and ownership of locks is never

checked.

fcntl_getlease

Name

fcntl_getlease - Enquire what lease is currently active

Synopsis

int fcntl_getlease (struct file * filp);

Arguments

filp

the file

117

Chapter 6. The Linux VFS

Description

The value returned by this function will be one of

F_RDLCK to indicate a read-only (type II) lease is held.

F_WRLCK to indicate an exclusive lease is held.

XXX

sfr & i disagree over whether F_INPROGRESS should be returned to userspace.

fcntl_setlease

Name

fcntl_setlease - sets a lease on an open file

Synopsis

int fcntl_setlease (unsigned int fd, struct file * filp, long

arg);

118

Chapter 6. The Linux VFS

Arguments

open file descriptor

filp

file pointer

arg

type of lease to obtain

Description

Call this fcntl to establish a lease on the file. Note that you also need to call F_SETSIG

to receive a signal when the lease is broken.

sys_flock

Name

sys_flock - flock system call.

Synopsis

asmlinkage long sys_flock (unsigned int fd, unsigned int cmd);

119

Chapter 6. The Linux VFS

Arguments

the file descriptor to lock.

cmd

the type of lock to apply.

Description

Apply a FL_FLOCK style lock to an open file descriptor. The cmd can be one of

LOCK_SH -- a shared lock.

LOCK_EX -- an exclusive lock.

LOCK_UN -- remove an existing lock.

LOCK_MAND -- a ‘mandatory’ flock. This exists to emulate Windows Share Modes.

LOCK_MAND can be combined with LOCK_READ or LOCK_WRITE to allow other

processes read and write access respectively.

120

Chapter 6. The Linux VFS

get_locks_status

Name

get_locks_status— reports lock usage in /proc/locks

Synopsis

int get_locks_status (char * buffer, char ** start, off_t

offset, int length);

Arguments

buffer

address in userspace to write into

start

offset

how far we are through the buffer

length

how much to read

121

Chapter 7. Linux Networking

skb_cloned

Name

skb_cloned - is the buffer a clone

Synopsis

int skb_cloned (struct sk_buff * skb);

Arguments

skb

buffer to check

Description

Returns true if the buffer was generated with skb_clone and is one of multiple shared

copies of the buffer. Cloned buffers are shared data so must not be written to under

normal circumstances.

125

Chapter 7. Linux Networking

skb_unshare

Name

skb_unshare - make a copy of a shared buffer

Synopsis

struct sk_buff * skb_unshare (struct sk_buff * skb, int pri);

Arguments

skb

buffer to check

pri

priority for memory allocation

Description

If the socket buffer is a clone then this function creates a new copy of the data, drops a

reference count on the old copy and returns the new copy with the reference count at 1.

If the buffer is not a clone the original buffer is returned. When called with a spinlock

held or from interrupt state primust be GFP_ATOMIC

NULL is returned on a memory allocation failure.

127

Chapter 7. Linux Networking

skb_peek

Name

skb_peek—

Synopsis

struct sk_buff * skb_peek (struct sk_buff_head * list_);

Arguments

list_

list to peek at

Description

Peek an &sk_buff. Unlike most other operations you _MUST_ be careful with this one.

A peek leaves the buffer on the list and someone else may run off with it. You must

hold the appropriate locks or have a private queue to do this.

Returns NULL for an empty list or a pointer to the head element. The reference count is

not incremented and the reference is therefore volatile. Use with caution.

128

Chapter 7. Linux Networking

skb_peek_tail

Name

skb_peek_tail—

Synopsis

struct sk_buff * skb_peek_tail (struct sk_buff_head * list_);

Arguments

list_

list to peek at

Description

Peek an &sk_buff. Unlike most other operations you _MUST_ be careful with this one.

A peek leaves the buffer on the list and someone else may run off with it. You must

hold the appropriate locks or have a private queue to do this.

Returns NULL for an empty list or a pointer to the tail element. The reference count is

not incremented and the reference is therefore volatile. Use with caution.

129

Chapter 7. Linux Networking

skb_queue_head

Name

skb_queue_head - queue a buffer at the list head

Synopsis

void skb_queue_head (struct sk_buff_head * list, struct

sk_buff * newsk);

Arguments

list

list to use

newsk

buffer to queue

Description

Queue a buffer at the start of a list. This function takes no locks and you must therefore

hold required locks before calling it.

A buffer cannot be placed on two lists at the same time.

131

Chapter 7. Linux Networking

skb_queue_head

Name

skb_queue_head - queue a buffer at the list head

Synopsis

void skb_queue_head (struct sk_buff_head * list, struct sk_buff

* newsk);

Arguments

list

list to use

newsk

buffer to queue

Description

Queue a buffer at the start of the list. This function takes the list lock and can be used

safely with other locking &sk_buff functions safely.

A buffer cannot be placed on two lists at the same time.

132

Chapter 7. Linux Networking

skb_queue_tail

Name

skb_queue_tail - queue a buffer at the list tail

Synopsis

void skb_queue_tail (struct sk_buff_head * list, struct

sk_buff * newsk);

Arguments

list

list to use

newsk

buffer to queue

Description

Queue a buffer at the end of a list. This function takes no locks and you must therefore

hold required locks before calling it.

A buffer cannot be placed on two lists at the same time.

133

Chapter 7. Linux Networking

skb_queue_tail

Name

skb_queue_tail - queue a buffer at the list tail

Synopsis

void skb_queue_tail (struct sk_buff_head * list, struct sk_buff

* newsk);

Arguments

list

list to use

newsk

buffer to queue

Description

Queue a buffer at the tail of the list. This function takes the list lock and can be used

safely with other locking &sk_buff functions safely.

A buffer cannot be placed on two lists at the same time.

134

Chapter 7. Linux Networking

skb_dequeue

Name

skb_dequeue - remove from the head of the queue

Synopsis

struct sk_buff * skb_dequeue (struct sk_buff_head * list);

Arguments

list

list to dequeue from

Description

Remove the head of the list. This function does not take any locks so must be used with

appropriate locks held only. The head item is returned or NULL if the list is empty.

135

Chapter 7. Linux Networking

skb_dequeue

Name

skb_dequeue - remove from the head of the queue

Synopsis

struct sk_buff * skb_dequeue (struct sk_buff_head * list);

Arguments

list

list to dequeue from

Description

Remove the head of the list. The list lock is taken so the function may be used safely

with other locking list functions. The head item is returned or NULL if the list is empty.

136

Chapter 7. Linux Networking

skb_insert

Name

skb_insert - insert a buffer

Synopsis

void skb_insert (struct sk_buff * old, struct sk_buff * newsk);

Arguments

old

buffer to insert before

newsk

buffer to insert

Description

Place a packet before a given packet in a list. The list locks are taken and this function

is atomic with respect to other list locked calls A buffer cannot be placed on two lists at

the same time.

137

Chapter 7. Linux Networking

skb_append

Name

skb_append - append a buffer

Synopsis

void skb_append (struct sk_buff * old, struct sk_buff * newsk);

Arguments

old

buffer to insert after

newsk

buffer to insert

Description

Place a packet after a given packet in a list. The list locks are taken and this function is

atomic with respect to other list locked calls. A buffer cannot be placed on two lists at

the same time.

138

Chapter 7. Linux Networking

skb_unlink

Name

skb_unlink - remove a buffer from a list

Synopsis

void skb_unlink (struct sk_buff * skb);

Arguments

skb

buffer to remove

Description

Place a packet after a given packet in a list. The list locks are taken and this function is

atomic with respect to other list locked calls

Works even without knowing the list it is sitting on, which can be handy at times. It

also means that THE LIST MUST EXIST when you unlink. Thus a list must have its

contents unlinked before it is destroyed.

139

Chapter 7. Linux Networking

skb_dequeue_tail

Name

skb_dequeue_tail - remove from the tail of the queue

Synopsis

struct sk_buff * skb_dequeue_tail (struct sk_buff_head *

list);

Arguments

list

list to dequeue from

Description

Remove the tail of the list. This function does not take any locks so must be used with

appropriate locks held only. The tail item is returned or NULL if the list is empty.

140

Chapter 7. Linux Networking

skb_dequeue_tail

Name

skb_dequeue_tail - remove from the head of the queue

Synopsis

struct sk_buff * skb_dequeue_tail (struct sk_buff_head * list);

Arguments

list

list to dequeue from

Description

Remove the head of the list. The list lock is taken so the function may be used safely

with other locking list functions. The tail item is returned or NULL if the list is empty.

141

Chapter 7. Linux Networking

skb_put

Name

skb_put - add data to a buffer

Synopsis

unsigned char * skb_put (struct sk_buff * skb, unsigned int

len);

Arguments

skb

buffer to use

len

amount of data to add

Description

This function extends the used data area of the buffer. If this would exceed the total

buffer size the kernel will panic. A pointer to the first byte of the extra data is returned.

142

Chapter 7. Linux Networking

skb_push

Name

skb_push - add data to the start of a buffer

Synopsis

unsigned char * skb_push (struct sk_buff * skb, unsigned int

len);

Arguments

skb

buffer to use

len

amount of data to add

Description

This function extends the used data area of the buffer at the buffer start. If this would

exceed the total buffer headroom the kernel will panic. A pointer to the first byte of the

extra data is returned.

143

Chapter 7. Linux Networking

skb_pull

Name

skb_pull - remove data from the start of a buffer

Synopsis

unsigned char * skb_pull (struct sk_buff * skb, unsigned int

len);

Arguments

skb

buffer to use

len

amount of data to remove

Description

This function removes data from the start of a buffer, returning the memory to the

headroom. A pointer to the next data in the buffer is returned. Once the data has been

pulled future pushes will overwrite the old data.

144

Chapter 7. Linux Networking

skb_reserve

Name

skb_reserve— adjust headroom

Synopsis

void skb_reserve (struct sk_buff * skb, unsigned int len);

Arguments

skb

buffer to alter

len

bytes to move

Description

Increase the headroom of an empty &sk_buff by reducing the tail room. This is only

allowed for an empty buffer.

147

Chapter 7. Linux Networking

skb_trim

Name

skb_trim - remove end from a buffer

Synopsis

void skb_trim (struct sk_buff * skb, unsigned int len);

Arguments

skb

buffer to alter

len

new length

Description

Cut the length of a buffer down by removing data from the tail. If the buffer is already

under the length specified it is not modified.

148

Chapter 7. Linux Networking

skb_orphan

Name

skb_orphan - orphan a buffer

Synopsis

void skb_orphan (struct sk_buff * skb);

Arguments

skb

buffer to orphan

Description

If a buffer currently has an owner then we call the owner’s destructor function and

make the skb unowned. The buffer continues to exist but is no longer charged to its

former owner.

149

Chapter 7. Linux Networking

skb_queue_purge

Name

skb_queue_purge - empty a list

Synopsis

void skb_queue_purge (struct sk_buff_head * list);

Arguments

list

list to empty

Description

Delete all buffers on an &sk_buff list. Each buffer is removed from the list and one

reference dropped. This function takes the list lock and is atomic with respect to other

list locking functions.

150

Chapter 7. Linux Networking

skb_queue_purge

Name

skb_queue_purge - empty a list

Synopsis

void skb_queue_purge (struct sk_buff_head * list);

Arguments

list

list to empty

Description

Delete all buffers on an &sk_buff list. Each buffer is removed from the list and one

reference dropped. This function does not take the list lock and the caller must hold the

relevant locks to use it.

151

Chapter 7. Linux Networking

dev_alloc_skb

Name

dev_alloc_skb - allocate an skbuff for sending

Synopsis

struct sk_buff * dev_alloc_skb (unsigned int length, int

gfp_mask);

Arguments

length

length to allocate

gfp_mask

get_free_pages mask, passed to alloc_skb

Description

Allocate a new &sk_buff and assign it a usage count of one. The buffer has unspecified

headroom built in. Users should allocate the headroom they think they need without

accounting for the built in space. The built in space is used for optimisations.

NULL is returned in there is no free memory.

152

Chapter 7. Linux Networking

dev_alloc_skb

Name

dev_alloc_skb - allocate an skbuff for sending

Synopsis

struct sk_buff * dev_alloc_skb (unsigned int length);

Arguments

length

length to allocate

Description

Allocate a new &sk_buff and assign it a usage count of one. The buffer has unspecified

headroom built in. Users should allocate the headroom they think they need without

accounting for the built in space. The built in space is used for optimisations.

NULL is returned in there is no free memory. Although this function allocates memory it

can be called from an interrupt.

153

Chapter 7. Linux Networking

skb_cow

Name

skb_cow - copy header of skb when it is required

Synopsis

int skb_cow (struct sk_buff * skb, unsigned int headroom);

Arguments

skb

buffer to cow

headroom

needed headroom

Description

If the skb passed lacks sufficient headroom or its data part is shared, data is reallocated.

If reallocation fails, an error is returned and original skb is not changed.

154

Chapter 7. Linux Networking

gfp_mask

allocation mask

Description

Allocate a new &sk_buff. The returned buffer has no headroom and a tail room of size

bytes. The object has a reference count of one. The return is the buffer. On a failure the

return is NULL.

Buffers may only be allocated from interrupts using a gfp_mask of GFP_ATOMIC.

kfree_skb

Name

kfree_skb - private function

Synopsis

void kfree_skb (struct sk_buff * skb);

158

Chapter 7. Linux Networking

Arguments

skb

buffer

Description

Free an sk_buff. Release anything attached to the buffer. Clean the state. This is an

internal helper function. Users should always call kfree_skb

skb_clone

Name

skb_clone - duplicate an sk_buff

Synopsis

struct sk_buff * skb_clone (struct sk_buff * skb, int gfp_mask);

159

Chapter 7. Linux Networking

Arguments

skb

buffer to clone

gfp_mask

allocation priority

Description

Duplicate an &sk_buff. The new one is not owned by a socket. Both copies share the

same packet data but not structure. The new buffer has a reference count of 1. If the

allocation fails the function returns NULL otherwise the new buffer is returned.

If this function is called from an interrupt gfp_mask must be GFP_ATOMIC.

skb_copy

Name

skb_copy - create private copy of an sk_buff

Synopsis

struct sk_buff * skb_copy (const struct sk_buff * skb, int

gfp_mask);

160

Chapter 7. Linux Networking

Arguments

skb

buffer to copy

gfp_mask

allocation priority

Description

Make a copy of both an &sk_buff and its data. This is used when the caller wishes to

modify the data and needs a private copy of the data to alter. Returns NULL on failure or

the pointer to the buffer on success. The returned buffer has a reference count of 1.

As by-product this function converts non-linear &sk_buff to linear one, so that

&sk_buff becomes completely private and caller is allowed to modify all the data of

returned buffer. This means that this function is not recommended for use in

circumstances when only header is going to be modified. Use pskb_copy instead.

pskb_copy

Name

pskb_copy - create copy of an sk_buff with private head.

161

Chapter 7. Linux Networking

Synopsis

struct sk_buff * pskb_copy (struct sk_buff * skb, int gfp_mask);

Arguments

skb

buffer to copy

gfp_mask

allocation priority

Description

Make a copy of both an &sk_buff and part of its data, located in header. Fragmented

data remain shared. This is used when the caller wishes to modify only header of

&sk_buff and needs private copy of the header to alter. Returns NULL on failure or the

pointer to the buffer on success. The returned buffer has a reference count of 1.

pskb_expand_head

Name

pskb_expand_head— reallocate header of sk_buff

162

Chapter 7. Linux Networking

Synopsis

int pskb_expand_head (struct sk_buff * skb, int nhead, int

ntail, int gfp_mask);

Arguments

skb

buffer to reallocate

nhead

room to add at head

ntail

room to add at tail

gfp_mask

allocation priority

Description

Expands (or creates identical copy, if &nhead and &ntail are zero) header of skb.

&sk_buff itself is not changed. &sk_buff MUST have reference count of 1. Returns

zero in the case of success or error, if expansion failed. In the last case, &sk_buff is not

changed.

All the pointers pointing into skb header may change and must be reloaded after call to

this function.

163

Chapter 7. Linux Networking

skb_copy_expand

Name

skb_copy_expand— copy and expand sk_buff

Synopsis

struct sk_buff * skb_copy_expand (const struct sk_buff * skb,

int newheadroom, int newtailroom, int gfp_mask);

Arguments

skb

buffer to copy

newheadroom

new free bytes at head

newtailroom

new free bytes at tail

gfp_mask

allocation priority

164

Chapter 7. Linux Networking

Description

Make a copy of both an &sk_buff and its data and while doing so allocate additional

space.

This is used when the caller wishes to modify the data and needs a private copy of the

data to alter as well as more space for new fields. Returns NULL on failure or the pointer

to the buffer on success. The returned buffer has a reference count of 1.

You must pass GFP_ATOMIC as the allocation priority if this function is called from an

interrupt.

pskb_pull_tail

Name

pskb_pull_tail - advance tail of skb header

Synopsis

unsigned char * pskb_pull_tail (struct sk_buff * skb, int

delta);

165

Chapter 7. Linux Networking

Arguments

skb

buffer to reallocate

delta

number of bytes to advance tail

Description

The function makes a sense only on a fragmented &sk_buff, it expands header moving

its tail forward and copying necessary data from fragmented part.

&sk_buff MUST have reference count of 1.

Returns NULL (and &sk_buff does not change) if pull failed or value of new tail of skb

in the case of success.

All the pointers pointing into skb header may change and must be reloaded after call to

this function.

166

Chapter 7. Linux Networking

Description

Decode and apply filter instructions to the skb->data. Return length to keep, 0 for none.

skb is the data we are filtering, filter is the array of filter instructions, and len is the

number of filter blocks in the array.

sk_chk_filter

Name

sk_chk_filter - verify socket filter code

Synopsis

int sk_chk_filter (struct sock_filter * filter, int flen);

Arguments

filter

filter to verify

flen

length of filter

168

Chapter 7. Linux Networking

Description

Check the user’s filter code. If we let some ugly filter code slip through kaboom! The

filter must contain no references or jumps that are out of range, no illegal instructions

and no backward jumps. It must end with a RET instruction

Returns 0 if the rule set is legal or a negative errno code if not.

169

Chapter 8. Network device support

8.1. Driver Support

init_etherdev

Name

init_etherdev - Register ethernet device

Synopsis

struct net_device * init_etherdev (struct net_device * dev, int

sizeof_priv);

Arguments

dev

An ethernet device structure to be filled in, or NULL if a new struct should be

allocated.

sizeof_priv

Size of additional driver-private structure to be allocated for this ethernet device

Chapter 8. Network device support

Description

Fill in the fields of the device structure with ethernet-generic values.

If no device structure is passed, a new one is constructed, complete with a private data

area of size sizeof_priv. A 32-byte (not bit) alignment is enforced for this private

data area.

If an empty string area is passed as dev->name, or a new structure is made, a new name

string is constructed.

alloc_etherdev

Name

alloc_etherdev - Register ethernet device

Synopsis

struct net_device * alloc_etherdev (int sizeof_priv);

Arguments

sizeof_priv

Size of additional driver-private structure to be allocated for this ethernet device

171

Chapter 8. Network device support

Description

Fill in the fields of the device structure with ethernet-generic values.

Constructs a new net device, complete with a private data area of size sizeof_priv.

A 32-byte (not bit) alignment is enforced for this private data area.

init_fddidev

Name

init_fddidev— Register FDDI device

Synopsis

struct net_device * init_fddidev (struct net_device * dev, int

sizeof_priv);

Arguments

dev

A FDDI device structure to be filled in, or NULL if a new struct should be

allocated.

172

Chapter 8. Network device support

sizeof_priv

Size of additional driver-private structure to be allocated for this ethernet device

Description

Fill in the fields of the device structure with FDDI-generic values.

If no device structure is passed, a new one is constructed, complete with a private data

area of size sizeof_priv. A 32-byte (not bit) alignment is enforced for this private

data area.

If an empty string area is passed as dev->name, or a new structure is made, a new name

string is constructed.

alloc_fddidev

Name

alloc_fddidev - Register FDDI device

Synopsis

struct net_device * alloc_fddidev (int sizeof_priv);

173

Chapter 8. Network device support

Arguments

sizeof_priv

Size of additional driver-private structure to be allocated for this FDDI device

Description

Fill in the fields of the device structure with FDDI-generic values.

Constructs a new net device, complete with a private data area of size sizeof_priv.

A 32-byte (not bit) alignment is enforced for this private data area.

init_hippi_dev

Name

init_hippi_dev - Register HIPPI device

Synopsis

struct net_device * init_hippi_dev (struct net_device * dev, int

sizeof_priv);

174

Chapter 8. Network device support

Arguments

dev

A HIPPI device structure to be filled in, or NULL if a new struct should be

allocated.

sizeof_priv

Size of additional driver-private structure to be allocated for this ethernet device

Description

Fill in the fields of the device structure with HIPPI-generic values.

If no device structure is passed, a new one is constructed, complete with a private data

area of size sizeof_priv. A 32-byte (not bit) alignment is enforced for this private

data area.

If an empty string area is passed as dev->name, or a new structure is made, a new name

string is constructed.

alloc_hippi_dev

Name

alloc_hippi_dev— Register HIPPI device

175

Chapter 8. Network device support

Synopsis

struct net_device * alloc_hippi_dev (int sizeof_priv);

Arguments

sizeof_priv

Size of additional driver-private structure to be allocated for this HIPPI device

Description

Fill in the fields of the device structure with HIPPI-generic values.

Constructs a new net device, complete with a private data area of size sizeof_priv.

A 32-byte (not bit) alignment is enforced for this private data area.

init_trdev

Name

init_trdev - Register token ring device

176

Chapter 8. Network device support

Synopsis

struct net_device * init_trdev (struct net_device * dev, int

sizeof_priv);

Arguments

dev

A token ring device structure to be filled in, or NULL if a new struct should be

allocated.

sizeof_priv

Size of additional driver-private structure to be allocated for this ethernet device

Description

Fill in the fields of the device structure with token ring-generic values.

If no device structure is passed, a new one is constructed, complete with a private data

area of size sizeof_priv. A 32-byte (not bit) alignment is enforced for this private

data area.

If an empty string area is passed as dev->name, or a new structure is made, a new name

string is constructed.

177

Chapter 8. Network device support

alloc_trdev

Name

alloc_trdev - Register token ring device

Synopsis

struct net_device * alloc_trdev (int sizeof_priv);

Arguments

sizeof_priv

Size of additional driver-private structure to be allocated for this token ring device

Description

Fill in the fields of the device structure with token ring-generic values.

Constructs a new net device, complete with a private data area of size sizeof_priv.

A 32-byte (not bit) alignment is enforced for this private data area.

178

Chapter 8. Network device support

init_fcdev

Name

init_fcdev— Register fibre channel device

Synopsis

struct net_device * init_fcdev (struct net_device * dev, int

sizeof_priv);

Arguments

dev

A fibre channel device structure to be filled in, or NULL if a new struct should be

allocated.

sizeof_priv

Size of additional driver-private structure to be allocated for this ethernet device

Description

Fill in the fields of the device structure with fibre channel-generic values.

If no device structure is passed, a new one is constructed, complete with a private data

area of size sizeof_priv. A 32-byte (not bit) alignment is enforced for this private

data area.

179

Chapter 8. Network device support

If an empty string area is passed as dev->name, or a new structure is made, a new name

string is constructed.

alloc_fcdev

Name

alloc_fcdev— Register fibre channel device

Synopsis

struct net_device * alloc_fcdev (int sizeof_priv);

Arguments

sizeof_priv

Size of additional driver-private structure to be allocated for this fibre channel

device

Description

Fill in the fields of the device structure with fibre channel-generic values.

180

Chapter 8. Network device support

Constructs a new net device, complete with a private data area of size sizeof_priv.

A 32-byte (not bit) alignment is enforced for this private data area.

dev_add_pack

Name

dev_add_pack— add packet handler

Synopsis

void dev_add_pack (struct packet_type * pt);

Arguments

packet type declaration

Description

Add a protocol handler to the networking stack. The passed &packet_type is linked into

kernel lists and may not be freed until it has been removed from the kernel lists.

181

Chapter 8. Network device support

dev_remove_pack

Name

dev_remove_pack— remove packet handler

Synopsis

void dev_remove_pack (struct packet_type * pt);

Arguments

packet type declaration

Description

Remove a protocol handler that was previously added to the kernel protocol handlers

by dev_add_pack. The passed &packet_type is removed from the kernel lists and can

be freed or reused once this function returns.

182

Chapter 8. Network device support

dev_get_by_name

Name

dev_get_by_name - find a device by its name

Synopsis

struct net_device * dev_get_by_name (const char * name);

Arguments

name

name to find

Description

Find an interface by name. Must be called under RTNL semaphore or

dev_base_lock. If the name is found a pointer to the device is returned. If the name

is not found then NULL is returned. The reference counters are not incremented so the

caller must be careful with locks.

183

Chapter 8. Network device support

dev_get_by_name

Name

dev_get_by_name - find a device by its name

Synopsis

struct net_device * dev_get_by_name (const char * name);

Arguments

name

name to find

Description

Find an interface by name. This can be called from any context and does its own

locking. The returned handle has the usage count incremented and the caller must use

dev_put to release it when it is no longer needed. NULL is returned if no matching

device is found.

184

Chapter 8. Network device support

dev_get

Name

dev_get - test if a device exists

Synopsis

int dev_get (const char * name);

Arguments

name

name to test for

Description

Test if a name exists. Returns true if the name is found. In order to be sure the name is

not allocated or removed during the test the caller must hold the rtnl semaphore.

This function primarily exists for back compatibility with older drivers.

185

Chapter 8. Network device support

dev_get_by_index

Name

dev_get_by_index— find a device by its ifindex

Synopsis

struct net_device * dev_get_by_index (int ifindex);

Arguments

ifindex

index of device

Description

Search for an interface by index. Returns NULL if the device is not found or a pointer to

the device. The device has not had its reference counter increased so the caller must be

careful about locking. The caller must hold either the RTNL semaphore or

dev_base_lock.

186

Chapter 8. Network device support

dev_get_by_index

Name

dev_get_by_index— find a device by its ifindex

Synopsis

struct net_device * dev_get_by_index (int ifindex);

Arguments

ifindex

index of device

Description

Search for an interface by index. Returns NULL if the device is not found or a pointer

to the device. The device returned has had a reference added and the pointer is safe

until the user calls dev_put to indicate they have finished with it.

187

Chapter 8. Network device support

dev_alloc_name

Name

dev_alloc_name - allocate a name for a device

Synopsis

int dev_alloc_name (struct net_device * dev, const char * name);

Arguments

dev

device

name

name format string

Description

Passed a format string - eg "ltd" it will try and find a suitable id. Not efficient for many

devices, not called a lot. The caller must hold the dev_base or rtnl lock while allocating

the name and adding the device in order to avoid duplicates. Returns the number of the

unit assigned or a negative errno code.

188

Chapter 8. Network device support

dev_alloc

Name

dev_alloc - allocate a network device and name

Synopsis

struct net_device * dev_alloc (const char * name, int * err);

Arguments

name

name format string

err

error return pointer

Description

Passed a format string, eg. "ltd", it will allocate a network device and space for the

name. NULL is returned if no memory is available. If the allocation succeeds then the

name is assigned and the device pointer returned. NULL is returned if the name

allocation failed. The cause of an error is returned as a negative errno code in the

variable err points to.

189

Chapter 8. Network device support

The caller must hold the dev_base or RTNL locks when doing this in order to avoid

duplicate name allocations.

netdev_state_change

Name

netdev_state_change— device changes state

Synopsis

void netdev_state_change (struct net_device * dev);

Arguments

dev

device to cause notification

Description

Called to indicate a device has changed state. This function calls the notifier chains for

netdev_chain and sends a NEWLINK message to the routing socket.

190

Chapter 8. Network device support

dev_load

Name

dev_load - load a network module

Synopsis

void dev_load (const char * name);

Arguments

name

name of interface

Description

If a network interface is not present and the process has suitable privileges this function

loads the module. If module loading is not available in this kernel then it becomes a

nop.

191

Chapter 8. Network device support

dev_open

Name

dev_open - prepare an interface for use.

Synopsis

int dev_open (struct net_device * dev);

Arguments

dev

device to open

Description

Takes a device from down to up state. The device’s private open function is invoked and

then the multicast lists are loaded. Finally the device is moved into the up state and a

NETDEV_UP message is sent to the netdev notifier chain.

Calling this function on an active interface is a nop. On a failure a negative errno code

is returned.

192

Chapter 8. Network device support

dev_close

Name

dev_close - shutdown an interface.

Synopsis

int dev_close (struct net_device * dev);

Arguments

dev

device to shutdown

Description

This function moves an active device into down state. A NETDEV_GOING_DOWN is sent

to the netdev notifier chain. The device is then deactivated and finally a NETDEV_DOWN

is sent to the notifier chain.

193

Chapter 8. Network device support

register_netdevice_notifier

Name

register_netdevice_notifier— register a network notifier block

Synopsis

int register_netdevice_notifier (struct notifier_block

* nb);

Arguments

notifier

Description

linked into the kernel structures and must not be reused until it has been unregistered. A

negative errno code is returned on a failure.

194

Chapter 8. Network device support

unregister_netdevice_notifier

Name

unregister_netdevice_notifier— unregister a network notifier block

Synopsis

int unregister_netdevice_notifier (struct notifier_block

* nb);

Arguments

notifier

Description

Unregister a notifier previously registered by register_netdevice_notifier. The

notifier is unlinked into the kernel structures and may then be reused. A negative errno

code is returned on a failure.

195

Chapter 8. Network device support

dev_queue_xmit

Name

dev_queue_xmit - transmit a buffer

Synopsis

int dev_queue_xmit (struct sk_buff * skb);

Arguments

skb

buffer to transmit

Description

Queue a buffer for transmission to a network device. The caller must have set the

device and priority and built the buffer before calling this function. The function can be

called from an interrupt.

A negative errno code is returned on a failure. A success does not guarantee the frame

will be transmitted as it may be dropped due to congestion or traffic shaping.

196

Chapter 8. Network device support

netif_rx

Name

netif_rx - post buffer to the network code

Synopsis

int netif_rx (struct sk_buff * skb);

Arguments

skb

buffer to post

Description

This function receives a packet from a device driver and queues it for the upper

(protocol) levels to process. It always succeeds. The buffer may be dropped during

processing for congestion control or by the protocol layers.

return values

NET_RX_SUCCESS (no congestion) NET_RX_CN_LOW (low congestion)

NET_RX_CN_MOD (moderate congestion) NET_RX_CN_HIGH (high congestion)

197

Chapter 8. Network device support

register_gifconf

Name

register_gifconf— register a SIOCGIF handler

Synopsis

int register_gifconf (unsigned int family, gifconf_func_t *

gifconf);

Arguments

family

Address family

gifconf

Function handler

Description

not be freed or reused until it has been replaced by another handler.

199

Chapter 8. Network device support

netdev_set_master

Name

netdev_set_master— set up master/slave pair

Synopsis

int netdev_set_master (struct net_device * slave, struct

net_device * master);

Arguments

slave

slave device

master

new master device

Description

Changes the master device of the slave. Pass NULL to break the bonding. The caller

must hold the RTNL semaphore. On a failure a negative errno code is returned. On

success the reference counts are adjusted, RTM_NEWLINK is sent to the routing socket

and the function returns zero.

200

Chapter 8. Network device support

dev_set_promiscuity

Name

dev_set_promiscuity - update promiscuity count on a device

Synopsis

void dev_set_promiscuity (struct net_device * dev, int inc);

Arguments

dev

device

inc

modifier

Description

Add or remove promsicuity from a device. While the count in the device remains above

zero the interface remains promiscuous. Once it hits zero the device reverts back to

201

Chapter 8. Network device support

Description

Add or remove reception of all multicast frames to a device. While the count in the

device remains above zero the interface remains listening to all interfaces. Once it hits

zero the device reverts back to normal filtering operation. A negative incvalue is used

to drop the counter when releasing a resource needing all multicasts.

dev_ioctl

Name

dev_ioctl - network device ioctl

Synopsis

int dev_ioctl (unsigned int cmd, void * arg);

Arguments

cmd

command to issue

arg

pointer to a struct ifreq in user space

203

Chapter 8. Network device support

Description

Issue ioctl functions to devices. This is normally called by the user space syscall

interfaces but can sometimes be useful for other purposes. The return value is the return

from the syscall if positive or a negative errno code on error.

dev_new_index

Name

dev_new_index - allocate an ifindex

Synopsis

int dev_new_index ( void);

Arguments

void

no arguments

Description

204

Chapter 8. Network device support

Returns a suitable unique value for a new device interface number. The caller must hold

the rtnl semaphore or the dev_base_lock to be sure it remains unique.

register_netdevice

Name

register_netdevice - register a network device

Synopsis

int register_netdevice (struct net_device * dev);

Arguments

dev

device to register

Description

Take a completed network device structure and add it to the kernel interfaces. A

NETDEV_REGISTER message is sent to the netdev notifier chain. 0 is returned on

205

Chapter 8. Network device support

success. A negative errno code is returned on a failure to set up the device, or if the

name is a duplicate.

Callers must hold the rtnl semaphore. See the comment at the end of Space.c for details

about the locking. You may want register_netdev instead of this.

BUGS

The locking appears insufficient to guarantee two parallel registers will not get the

same name.

netdev_finish_unregister

Name

netdev_finish_unregister— complete unregistration

Synopsis

int netdev_finish_unregister (struct net_device * dev);

206

Chapter 8. Network device support

Arguments

dev

device

Description

This function shuts down a device interface and removes it from the kernel tables. On

success 0 is returned, on a failure a negative errno code is returned.

Callers must hold the rtnl semaphore. See the comment at the end of Space.c for details

about the locking. You may want unregister_netdev instead of this.

8.2. 8390 Based Network Cards

ei_open

Name

ei_open - Open/initialize the board.

Synopsis

int ei_open (struct net_device * dev);

208

Chapter 8. Network device support

Arguments

dev

network device to initialize

Description

This routine goes all-out, setting everything up anew at each open, even though many

of these registers should only need to be set once at boot.

ei_close

Name

ei_close - shut down network device

Synopsis

int ei_close (struct net_device * dev);

209

Chapter 8. Network device support

Arguments

dev

network device which has apparently fallen asleep

Description

Called by kernel when device never acknowledges a transmit has completed (or failed)

- i.e. never posted a Tx related interrupt.

ei_interrupt

Name

ei_interrupt - handle the interrupts from an 8390

Synopsis

void ei_interrupt (int irq, void * dev_id, struct pt_regs *

regs);

211

Chapter 8. Network device support

Arguments

irq

interrupt number

dev_id

a pointer to the net_device

regs

unused

Description

Handle the ether interface interrupts. We pull packets from the 8390 via the card

specific functions and fire them at the networking stack. We also handle transmit

completions and wake the transmit path if neccessary. We also update the counters and

do other housekeeping as needed.

ethdev_init

Name

ethdev_init - init rest of 8390 device struct

212

Chapter 8. Network device support

Synopsis

int ethdev_init (struct net_device * dev);

Arguments

dev

network device structure to init

Description

Initialize the rest of the 8390 device structure. Do NOT init this, as it is used by 8390

based modular drivers too.

NS8390_init

Name

NS8390_init— initialize 8390 hardware

Synopsis

void NS8390_init (struct net_device * dev, int startp);

213

Chapter 8. Network device support

Synopsis

void sppp_input (struct net_device * dev, struct sk_buff * skb);

Arguments

dev

The device it arrived on

skb

The buffer to process

Description

This can be called directly by cards that do not have timing constraints but is normally

called from the network layer after interrupt servicing to process frames queued via

netif_rx.

We process the options in the card. If the frame is destined for the protocol stacks then

it requeues the frame for the upper level protocol. If it is a control from it is processed

and discarded here.

215

Chapter 8. Network device support

sppp_close

Name

sppp_close - close down a synchronous PPP or Cisco HDLC link

Synopsis

int sppp_close (struct net_device * dev);

Arguments

dev

The network device to drop the link of

Description

This drops the logical interface to the channel. It is not done politely as we assume we

will also be dropping DTR. Any timeouts are killed.

216

Chapter 8. Network device support

sppp_open

Name

sppp_open - open a synchronous PPP or Cisco HDLC link

Synopsis

int sppp_open (struct net_device * dev);

Arguments

dev

Network device to activate

Description

Close down any existing synchronous session and commence from scratch. In the PPP

case this means negotiating LCP/IPCP and friends, while for Cisco HDLC we simply

need to start sending keepalives

217

Chapter 8. Network device support

sppp_reopen

Name

sppp_reopen - notify of physical link loss

Synopsis

int sppp_reopen (struct net_device * dev);

Arguments

dev

Device that lost the link

Description

This function informs the synchronous protocol code that the underlying link died (for

example a carrier drop on X.21)

We increment the magic numbers to ensure that if the other end failed to notice we will

correctly start a new session. It happens do to the nature of telco circuits is that you can

lose carrier on one endonly.

Having done this we go back to negotiating. This function may be called from an

interrupt context.

218

Chapter 8. Network device support

sppp_change_mtu

Name

sppp_change_mtu - Change the link MTU

Synopsis

int sppp_change_mtu (struct net_device * dev, int new_mtu);

Arguments

dev

Device to change MTU on

new_mtu

New MTU

Description

Change the MTU on the link. This can only be called with the link down. It returns an

error if the link is up or the mtu is out of range.

219

The Linux Kernel API - page 1