Eric Lee / smarc-fsl-linux-kernel

1

<?xml version="1.0" encoding="UTF-8"?>

1

<?xml version="1.0" encoding="UTF-8"?>

2

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

2

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

3

"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

3

"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

4

5

5

6

6

7

<title>The Linux Kernel API</title>

7

<title>The Linux Kernel API</title>

8

9

9

10

<para>

10

<para>

11

This documentation is free software; you can redistribute

11

This documentation is free software; you can redistribute

12

it and/or modify it under the terms of the GNU General Public

12

it and/or modify it under the terms of the GNU General Public

13

License as published by the Free Software Foundation; either

13

License as published by the Free Software Foundation; either

14

version 2 of the License, or (at your option) any later

14

version 2 of the License, or (at your option) any later

15

version.

15

version.

16

</para>

16

</para>

17

18

<para>

18

<para>

19

This program is distributed in the hope that it will be

19

This program is distributed in the hope that it will be

20

useful, but WITHOUT ANY WARRANTY; without even the implied

20

useful, but WITHOUT ANY WARRANTY; without even the implied

21

warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

21

warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

22

See the GNU General Public License for more details.

22

See the GNU General Public License for more details.

23

</para>

23

</para>

24

25

<para>

25

<para>

26

You should have received a copy of the GNU General Public

26

You should have received a copy of the GNU General Public

27

License along with this program; if not, write to the Free

27

License along with this program; if not, write to the Free

28

Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

28

Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

29

MA 02111-1307 USA

29

MA 02111-1307 USA

30

</para>

30

</para>

31

32

<para>

32

<para>

33

For more details see the file COPYING in the source

33

For more details see the file COPYING in the source

34

distribution of Linux.

34

distribution of Linux.

35

</para>

35

</para>

36

</legalnotice>

36

</legalnotice>

37

</bookinfo>

37

</bookinfo>

38

39

39

40

41

41

42

<title>Driver Basics</title>

42

<title>Driver Basics</title>

43

<sect1><title>Driver Entry and Exit points</title>

43

<sect1><title>Driver Entry and Exit points</title>

44

!Iinclude/linux/init.h

44

!Iinclude/linux/init.h

45

</sect1>

45

</sect1>

46

47

<sect1><title>Atomic and pointer manipulation</title>

47

<sect1><title>Atomic and pointer manipulation</title>

48

!Iinclude/asm-i386/atomic.h

48

!Iinclude/asm-i386/atomic.h

49

!Iinclude/asm-i386/unaligned.h

49

!Iinclude/asm-i386/unaligned.h

50

</sect1>

50

</sect1>

51

52

<sect1><title>Delaying, scheduling, and timer routines</title>

52

<sect1><title>Delaying, scheduling, and timer routines</title>

53

!Iinclude/linux/sched.h

53

!Iinclude/linux/sched.h

54

!Ekernel/sched.c

54

!Ekernel/sched.c

55

!Ekernel/timer.c

55

!Ekernel/timer.c

56

</sect1>

56

</sect1>

57

<sect1><title>High-resolution timers</title>

57

<sect1><title>High-resolution timers</title>

58

!Iinclude/linux/ktime.h

58

!Iinclude/linux/ktime.h

59

!Iinclude/linux/hrtimer.h

59

!Iinclude/linux/hrtimer.h

60

!Ekernel/hrtimer.c

60

!Ekernel/hrtimer.c

61

</sect1>

61

</sect1>

62

<sect1><title>Workqueues and Kevents</title>

62

<sect1><title>Workqueues and Kevents</title>

63

!Ekernel/workqueue.c

63

!Ekernel/workqueue.c

64

</sect1>

64

</sect1>

65

<sect1><title>Internal Functions</title>

65

<sect1><title>Internal Functions</title>

66

!Ikernel/exit.c

66

!Ikernel/exit.c

67

!Ikernel/signal.c

67

!Ikernel/signal.c

68

!Iinclude/linux/kthread.h

68

!Iinclude/linux/kthread.h

69

!Ekernel/kthread.c

69

!Ekernel/kthread.c

70

</sect1>

70

</sect1>

71

72

<sect1><title>Kernel objects manipulation</title>

72

<sect1><title>Kernel objects manipulation</title>

73

<!--

73

<!--

74

X!Iinclude/linux/kobject.h

74

X!Iinclude/linux/kobject.h

75

-->

75

-->

76

!Elib/kobject.c

76

!Elib/kobject.c

77

</sect1>

77

</sect1>

78

79

<sect1><title>Kernel utility functions</title>

79

<sect1><title>Kernel utility functions</title>

80

!Iinclude/linux/kernel.h

80

!Iinclude/linux/kernel.h

81

!Ekernel/printk.c

81

!Ekernel/printk.c

82

!Ekernel/panic.c

82

!Ekernel/panic.c

83

!Ekernel/sys.c

83

!Ekernel/sys.c

84

!Ekernel/rcupdate.c

84

!Ekernel/rcupdate.c

85

</sect1>

85

</sect1>

86

87

</chapter>

87

</chapter>

88

89

89

90

<title>Data Types</title>

90

<title>Data Types</title>

91

<sect1><title>Doubly Linked Lists</title>

91

<sect1><title>Doubly Linked Lists</title>

92

!Iinclude/linux/list.h

92

!Iinclude/linux/list.h

93

</sect1>

93

</sect1>

94

</chapter>

94

</chapter>

95

96

96

97

<title>Basic C Library Functions</title>

97

<title>Basic C Library Functions</title>

98

99

<para>

99

<para>

100

When writing drivers, you cannot in general use routines which are

100

When writing drivers, you cannot in general use routines which are

101

from the C Library. Some of the functions have been found generally

101

from the C Library. Some of the functions have been found generally

102

useful and they are listed below. The behaviour of these functions

102

useful and they are listed below. The behaviour of these functions

103

may vary slightly from those defined by ANSI, and these deviations

103

may vary slightly from those defined by ANSI, and these deviations

104

are noted in the text.

104

are noted in the text.

105

</para>

105

</para>

106

107

<sect1><title>String Conversions</title>

107

<sect1><title>String Conversions</title>

108

!Ilib/vsprintf.c

108

!Ilib/vsprintf.c

109

!Elib/vsprintf.c

109

!Elib/vsprintf.c

110

</sect1>

110

</sect1>

111

<sect1><title>String Manipulation</title>

111

<sect1><title>String Manipulation</title>

112

<!-- All functions are exported at now

112

<!-- All functions are exported at now

113

X!Ilib/string.c

113

X!Ilib/string.c

114

-->

114

-->

115

!Elib/string.c

115

!Elib/string.c

116

</sect1>

116

</sect1>

117

<sect1><title>Bit Operations</title>

117

<sect1><title>Bit Operations</title>

118

!Iinclude/asm-i386/bitops.h

118

!Iinclude/asm-i386/bitops.h

119

</sect1>

119

</sect1>

120

</chapter>

120

</chapter>

121

122

122

123

<title>Basic Kernel Library Functions</title>

123

<title>Basic Kernel Library Functions</title>

124

125

<para>

125

<para>

126

The Linux kernel provides more basic utility functions.

126

The Linux kernel provides more basic utility functions.

127

</para>

127

</para>

128

129

<sect1><title>Bitmap Operations</title>

129

<sect1><title>Bitmap Operations</title>

130

!Elib/bitmap.c

130

!Elib/bitmap.c

131

!Ilib/bitmap.c

131

!Ilib/bitmap.c

132

</sect1>

132

</sect1>

133

134

<sect1><title>Command-line Parsing</title>

134

<sect1><title>Command-line Parsing</title>

135

!Elib/cmdline.c

135

!Elib/cmdline.c

136

</sect1>

136

</sect1>

137

138

<sect1><title>CRC Functions</title>

138

<sect1><title>CRC Functions</title>

139

!Elib/crc16.c

139

!Elib/crc16.c

140

!Elib/crc32.c

140

!Elib/crc32.c

141

!Elib/crc-ccitt.c

141

!Elib/crc-ccitt.c

142

</sect1>

142

</sect1>

143

</chapter>

143

</chapter>

144

145

145

146

<title>Memory Management in Linux</title>

146

<title>Memory Management in Linux</title>

147

<sect1><title>The Slab Cache</title>

147

<sect1><title>The Slab Cache</title>

148

!Iinclude/linux/slab.h

148

!Iinclude/linux/slab.h

149

!Emm/slab.c

149

!Emm/slab.c

150

</sect1>

150

</sect1>

151

<sect1><title>User Space Memory Access</title>

151

<sect1><title>User Space Memory Access</title>

152

!Iinclude/asm-i386/uaccess.h

152

!Iinclude/asm-i386/uaccess.h

153

!Earch/i386/lib/usercopy.c

153

!Earch/i386/lib/usercopy.c

154

</sect1>

154

</sect1>

155

<sect1><title>More Memory Management Functions</title>

155

<sect1><title>More Memory Management Functions</title>

156

!Iinclude/linux/rmap.h

156

!Iinclude/linux/rmap.h

157

!Emm/readahead.c

157

!Emm/readahead.c

158

!Emm/filemap.c

158

!Emm/filemap.c

159

!Emm/memory.c

159

!Emm/memory.c

160

!Emm/vmalloc.c

160

!Emm/vmalloc.c

161

!Emm/mempool.c

161

!Emm/mempool.c

162

!Emm/page-writeback.c

162

!Emm/page-writeback.c

163

!Emm/truncate.c

163

!Emm/truncate.c

164

</sect1>

164

</sect1>

165

</chapter>

165

</chapter>

166

167

168

168

169

<title>Kernel IPC facilities</title>

169

<title>Kernel IPC facilities</title>

170

171

<sect1><title>IPC utilities</title>

171

<sect1><title>IPC utilities</title>

172

!Iipc/util.c

172

!Iipc/util.c

173

</sect1>

173

</sect1>

174

</chapter>

174

</chapter>

175

176

176

177

<title>FIFO Buffer</title>

177

<title>FIFO Buffer</title>

178

<sect1><title>kfifo interface</title>

178

<sect1><title>kfifo interface</title>

179

!Iinclude/linux/kfifo.h

179

!Iinclude/linux/kfifo.h

180

!Ekernel/kfifo.c

180

!Ekernel/kfifo.c

181

</sect1>

181

</sect1>

182

</chapter>

182

</chapter>

183

184

184

185

<title>The Linux VFS</title>

185

<title>The Linux VFS</title>

186

<sect1><title>The Filesystem types</title>

186

<sect1><title>The Filesystem types</title>

187

!Iinclude/linux/fs.h

187

!Iinclude/linux/fs.h

188

</sect1>

188

</sect1>

189

<sect1><title>The Directory Cache</title>

189

<sect1><title>The Directory Cache</title>

190

!Efs/dcache.c

190

!Efs/dcache.c

191

!Iinclude/linux/dcache.h

191

!Iinclude/linux/dcache.h

192

</sect1>

192

</sect1>

193

<sect1><title>Inode Handling</title>

193

<sect1><title>Inode Handling</title>

194

!Efs/inode.c

194

!Efs/inode.c

195

!Efs/bad_inode.c

195

!Efs/bad_inode.c

196

</sect1>

196

</sect1>

197

<sect1><title>Registration and Superblocks</title>

197

<sect1><title>Registration and Superblocks</title>

198

!Efs/super.c

198

!Efs/super.c

199

</sect1>

199

</sect1>

200

<sect1><title>File Locks</title>

200

<sect1><title>File Locks</title>

201

!Efs/locks.c

201

!Efs/locks.c

202

!Ifs/locks.c

202

!Ifs/locks.c

203

</sect1>

203

</sect1>

204

<sect1><title>Other Functions</title>

204

<sect1><title>Other Functions</title>

205

!Efs/mpage.c

205

!Efs/mpage.c

206

!Efs/namei.c

206

!Efs/namei.c

207

!Efs/buffer.c

207

!Efs/buffer.c

208

!Efs/bio.c

208

!Efs/bio.c

209

!Efs/seq_file.c

209

!Efs/seq_file.c

210

!Efs/filesystems.c

210

!Efs/filesystems.c

211

!Efs/fs-writeback.c

211

!Efs/fs-writeback.c

212

!Efs/block_dev.c

212

!Efs/block_dev.c

213

</sect1>

213

</sect1>

214

</chapter>

214

</chapter>

215

216

216

217

<title>The proc filesystem</title>

217

<title>The proc filesystem</title>

218

219

<sect1><title>sysctl interface</title>

219

<sect1><title>sysctl interface</title>

220

!Ekernel/sysctl.c

220

!Ekernel/sysctl.c

221

</sect1>

221

</sect1>

222

223

<sect1><title>proc filesystem interface</title>

223

<sect1><title>proc filesystem interface</title>

224

!Ifs/proc/base.c

224

!Ifs/proc/base.c

225

</sect1>

225

</sect1>

226

</chapter>

226

</chapter>

227

228

228

229

<title>The Filesystem for Exporting Kernel Objects</title>

229

<title>The Filesystem for Exporting Kernel Objects</title>

230

!Efs/sysfs/file.c

230

!Efs/sysfs/file.c

231

!Efs/sysfs/symlink.c

231

!Efs/sysfs/symlink.c

232

!Efs/sysfs/bin.c

232

!Efs/sysfs/bin.c

233

</chapter>

233

</chapter>

234

235

235

236

<title>The debugfs filesystem</title>

236

<title>The debugfs filesystem</title>

237

238

<sect1><title>debugfs interface</title>

238

<sect1><title>debugfs interface</title>

239

!Efs/debugfs/inode.c

239

!Efs/debugfs/inode.c

240

!Efs/debugfs/file.c

240

!Efs/debugfs/file.c

241

</sect1>

241

</sect1>

242

</chapter>

242

</chapter>

243

244

244

245

<title>relay interface support</title>

245

<title>relay interface support</title>

246

247

<para>

247

<para>

248

Relay interface support

248

Relay interface support

249

is designed to provide an efficient mechanism for tools and

249

is designed to provide an efficient mechanism for tools and

250

facilities to relay large amounts of data from kernel space to

250

facilities to relay large amounts of data from kernel space to

251

user space.

251

user space.

252

</para>

252

</para>

253

254

<sect1><title>relay interface</title>

254

<sect1><title>relay interface</title>

255

!Ekernel/relay.c

255

!Ekernel/relay.c

256

!Ikernel/relay.c

256

!Ikernel/relay.c

257

</sect1>

257

</sect1>

258

</chapter>

258

</chapter>

259

260

260

261

<title>Linux Networking</title>

261

<title>Linux Networking</title>

262

<sect1><title>Networking Base Types</title>

262

<sect1><title>Networking Base Types</title>

263

!Iinclude/linux/net.h

263

!Iinclude/linux/net.h

264

</sect1>

264

</sect1>

265

<sect1><title>Socket Buffer Functions</title>

265

<sect1><title>Socket Buffer Functions</title>

266

!Iinclude/linux/skbuff.h

266

!Iinclude/linux/skbuff.h

267

!Iinclude/net/sock.h

267

!Iinclude/net/sock.h

268

!Enet/socket.c

268

!Enet/socket.c

269

!Enet/core/skbuff.c

269

!Enet/core/skbuff.c

270

!Enet/core/sock.c

270

!Enet/core/sock.c

271

!Enet/core/datagram.c

271

!Enet/core/datagram.c

272

!Enet/core/stream.c

272

!Enet/core/stream.c

273

</sect1>

273

</sect1>

274

<sect1><title>Socket Filter</title>

274

<sect1><title>Socket Filter</title>

275

!Enet/core/filter.c

275

!Enet/core/filter.c

276

</sect1>

276

</sect1>

277

<sect1><title>Generic Network Statistics</title>

277

<sect1><title>Generic Network Statistics</title>

278

!Iinclude/linux/gen_stats.h

278

!Iinclude/linux/gen_stats.h

279

!Enet/core/gen_stats.c

279

!Enet/core/gen_stats.c

280

!Enet/core/gen_estimator.c

280

!Enet/core/gen_estimator.c

281

</sect1>

281

</sect1>

282

<sect1><title>SUN RPC subsystem</title>

282

<sect1><title>SUN RPC subsystem</title>

283

<!-- The !D functionality is not perfect, garbage has to be protected by comments

283

<!-- The !D functionality is not perfect, garbage has to be protected by comments

284

!Dnet/sunrpc/sunrpc_syms.c

284

!Dnet/sunrpc/sunrpc_syms.c

285

-->

285

-->

286

!Enet/sunrpc/xdr.c

286

!Enet/sunrpc/xdr.c

287

!Enet/sunrpc/svcsock.c

287

!Enet/sunrpc/svcsock.c

288

!Enet/sunrpc/sched.c

288

!Enet/sunrpc/sched.c

289

</sect1>

289

</sect1>

290

</chapter>

290

</chapter>

291

292

292

293

<title>Network device support</title>

293

<title>Network device support</title>

294

<sect1><title>Driver Support</title>

294

<sect1><title>Driver Support</title>

295

!Enet/core/dev.c

295

!Enet/core/dev.c

296

!Enet/ethernet/eth.c

296

!Enet/ethernet/eth.c

297

!Iinclude/linux/etherdevice.h

297

!Iinclude/linux/etherdevice.h

298

<!-- FIXME: Removed for now since no structured comments in source

298

<!-- FIXME: Removed for now since no structured comments in source

299

X!Enet/core/wireless.c

299

X!Enet/core/wireless.c

300

-->

300

-->

301

</sect1>

301

</sect1>

302

<sect1><title>Synchronous PPP</title>

302

<sect1><title>Synchronous PPP</title>

303

!Edrivers/net/wan/syncppp.c

303

!Edrivers/net/wan/syncppp.c

304

</sect1>

304

</sect1>

305

</chapter>

305

</chapter>

306

307

307

308

<title>Module Support</title>

308

<title>Module Support</title>

309

<sect1><title>Module Loading</title>

309

<sect1><title>Module Loading</title>

310

!Ekernel/kmod.c

310

!Ekernel/kmod.c

311

</sect1>

311

</sect1>

312

<sect1><title>Inter Module support</title>

312

<sect1><title>Inter Module support</title>

313

<para>

313

<para>

314

Refer to the file kernel/module.c for more information.

314

Refer to the file kernel/module.c for more information.

315

</para>

315

</para>

316

<!-- FIXME: Removed for now since no structured comments in source

316

<!-- FIXME: Removed for now since no structured comments in source

317

X!Ekernel/module.c

317

X!Ekernel/module.c

318

-->

318

-->

319

</sect1>

319

</sect1>

320

</chapter>

320

</chapter>

321

322

322

323

<title>Hardware Interfaces</title>

323

<title>Hardware Interfaces</title>

324

<sect1><title>Interrupt Handling</title>

324

<sect1><title>Interrupt Handling</title>

325

!Ekernel/irq/manage.c

325

!Ekernel/irq/manage.c

326

</sect1>

326

</sect1>

327

328

<sect1><title>Resources Management</title>

328

<sect1><title>Resources Management</title>

329

!Ikernel/resource.c

329

!Ikernel/resource.c

330

</sect1>

330

</sect1>

331

332

<sect1><title>MTRR Handling</title>

332

<sect1><title>MTRR Handling</title>

333

!Earch/i386/kernel/cpu/mtrr/main.c

333

!Earch/i386/kernel/cpu/mtrr/main.c

334

</sect1>

334

</sect1>

335

336

<sect1><title>PCI Support Library</title>

336

<sect1><title>PCI Support Library</title>

337

!Edrivers/pci/pci.c

337

!Edrivers/pci/pci.c

338

!Edrivers/pci/pci-driver.c

338

!Edrivers/pci/pci-driver.c

339

!Edrivers/pci/remove.c

339

!Edrivers/pci/remove.c

340

!Edrivers/pci/pci-acpi.c

340

!Edrivers/pci/pci-acpi.c

341

!Edrivers/pci/search.c

341

!Edrivers/pci/search.c

342

!Edrivers/pci/msi.c

342

!Edrivers/pci/msi.c

343

!Edrivers/pci/bus.c

343

!Edrivers/pci/bus.c

344

<!-- FIXME: Removed for now since no structured comments in source

344

<!-- FIXME: Removed for now since no structured comments in source

345

X!Edrivers/pci/hotplug.c

345

X!Edrivers/pci/hotplug.c

346

-->

346

-->

347

!Edrivers/pci/probe.c

347

!Edrivers/pci/probe.c

348

!Edrivers/pci/rom.c

348

!Edrivers/pci/rom.c

349

</sect1>

349

</sect1>

350

<sect1><title>PCI Hotplug Support Library</title>

350

<sect1><title>PCI Hotplug Support Library</title>

351

!Edrivers/pci/hotplug/pci_hotplug_core.c

351

!Edrivers/pci/hotplug/pci_hotplug_core.c

352

</sect1>

352

</sect1>

353

<sect1><title>MCA Architecture</title>

353

<sect1><title>MCA Architecture</title>

354

<sect2><title>MCA Device Functions</title>

354

<sect2><title>MCA Device Functions</title>

355

<para>

355

<para>

356

Refer to the file arch/i386/kernel/mca.c for more information.

356

Refer to the file arch/i386/kernel/mca.c for more information.

357

</para>

357

</para>

358

<!-- FIXME: Removed for now since no structured comments in source

358

<!-- FIXME: Removed for now since no structured comments in source

359

X!Earch/i386/kernel/mca.c

359

X!Earch/i386/kernel/mca.c

360

-->

360

-->

361

</sect2>

361

</sect2>

362

362

363

!Iinclude/asm-i386/mca_dma.h

363

!Iinclude/asm-i386/mca_dma.h

364

</sect2>

364

</sect2>

365

</sect1>

365

</sect1>

366

</chapter>

366

</chapter>

367

368

368

369

<title>Firmware Interfaces</title>

369

<title>Firmware Interfaces</title>

370

<sect1><title>DMI Interfaces</title>

370

<sect1><title>DMI Interfaces</title>

371

!Edrivers/firmware/dmi_scan.c

371

!Edrivers/firmware/dmi_scan.c

372

</sect1>

372

</sect1>

373

</chapter>

373

</chapter>

374

375

375

376

<title>Security Framework</title>

376

<title>Security Framework</title>

377

!Esecurity/security.c

377

!Esecurity/security.c

378

</chapter>

378

</chapter>

379

380

380

381

<title>Audit Interfaces</title>

381

<title>Audit Interfaces</title>

382

!Ekernel/audit.c

382

!Ekernel/audit.c

383

!Ikernel/auditsc.c

383

!Ikernel/auditsc.c

384

!Ikernel/auditfilter.c

384

!Ikernel/auditfilter.c

385

</chapter>

385

</chapter>

386

387

387

388

<title>Accounting Framework</title>

388

<title>Accounting Framework</title>

389

!Ikernel/acct.c

389

!Ikernel/acct.c

390

</chapter>

390

</chapter>

391

392

392

393

<title>Power Management</title>

393

<title>Power Management</title>

394

!Ekernel/power/pm.c

394

!Ekernel/power/pm.c

395

</chapter>

395

</chapter>

396

397

397

398

<title>Device drivers infrastructure</title>

398

<title>Device drivers infrastructure</title>

399

<sect1><title>Device Drivers Base</title>

399

<sect1><title>Device Drivers Base</title>

400

<!--

400

<!--

401

X!Iinclude/linux/device.h

401

X!Iinclude/linux/device.h

402

-->

402

-->

403

!Edrivers/base/driver.c

403

!Edrivers/base/driver.c

404

!Edrivers/base/core.c

404

!Edrivers/base/core.c

405

!Edrivers/base/class.c

405

!Edrivers/base/class.c

406

!Edrivers/base/firmware_class.c

406

!Edrivers/base/firmware_class.c

407

!Edrivers/base/transport_class.c

407

!Edrivers/base/transport_class.c

408

!Edrivers/base/dmapool.c

408

!Edrivers/base/dmapool.c

409

<!-- Cannot be included, because

409

<!-- Cannot be included, because

410

attribute_container_add_class_device_adapter

410

attribute_container_add_class_device_adapter

411

and attribute_container_classdev_to_container

411

and attribute_container_classdev_to_container

412

exceed allowed 44 characters maximum

412

exceed allowed 44 characters maximum

413

X!Edrivers/base/attribute_container.c

413

X!Edrivers/base/attribute_container.c

414

-->

414

-->

415

!Edrivers/base/sys.c

415

!Edrivers/base/sys.c

416

<!--

416

<!--

417

X!Edrivers/base/interface.c

417

X!Edrivers/base/interface.c

418

-->

418

-->

419

!Edrivers/base/platform.c

419

!Edrivers/base/platform.c

420

!Edrivers/base/bus.c

420

!Edrivers/base/bus.c

421

</sect1>

421

</sect1>

422

<sect1><title>Device Drivers Power Management</title>

422

<sect1><title>Device Drivers Power Management</title>

423

!Edrivers/base/power/main.c

423

!Edrivers/base/power/main.c

424

!Edrivers/base/power/resume.c

424

!Edrivers/base/power/resume.c

425

!Edrivers/base/power/suspend.c

425

!Edrivers/base/power/suspend.c

426

</sect1>

426

</sect1>

427

<sect1><title>Device Drivers ACPI Support</title>

427

<sect1><title>Device Drivers ACPI Support</title>

428

<!-- Internal functions only

428

<!-- Internal functions only

429

X!Edrivers/acpi/sleep/main.c

429

X!Edrivers/acpi/sleep/main.c

430

X!Edrivers/acpi/sleep/wakeup.c

430

X!Edrivers/acpi/sleep/wakeup.c

431

X!Edrivers/acpi/motherboard.c

431

X!Edrivers/acpi/motherboard.c

432

X!Edrivers/acpi/bus.c

432

X!Edrivers/acpi/bus.c

433

-->

433

-->

434

!Edrivers/acpi/scan.c

434

!Edrivers/acpi/scan.c

435

!Idrivers/acpi/scan.c

435

!Idrivers/acpi/scan.c

436

<!-- No correct structured comments

436

<!-- No correct structured comments

437

X!Edrivers/acpi/pci_bind.c

437

X!Edrivers/acpi/pci_bind.c

438

-->

438

-->

439

</sect1>

439

</sect1>

440

<sect1><title>Device drivers PnP support</title>

440

<sect1><title>Device drivers PnP support</title>

441

!Edrivers/pnp/core.c

441

!Edrivers/pnp/core.c

442

<!-- No correct structured comments

442

<!-- No correct structured comments

443

X!Edrivers/pnp/system.c

443

X!Edrivers/pnp/system.c

444

-->

444

-->

445

!Edrivers/pnp/card.c

445

!Edrivers/pnp/card.c

446

!Edrivers/pnp/driver.c

446

!Edrivers/pnp/driver.c

447

!Edrivers/pnp/manager.c

447

!Edrivers/pnp/manager.c

448

!Edrivers/pnp/support.c

448

!Edrivers/pnp/support.c

449

</sect1>

449

</sect1>

450

</chapter>

450

</chapter>

451

452

452

453

<title>Block Devices</title>

453

<title>Block Devices</title>

454

!Eblock/ll_rw_blk.c

454

!Eblock/ll_rw_blk.c

455

</chapter>

455

</chapter>

456

457

458

<title>Char devices</title>

459

!Efs/char_dev.c

460

</chapter>

461

457

462

458

<title>Miscellaneous Devices</title>

463

<title>Miscellaneous Devices</title>

459

!Edrivers/char/misc.c

464

!Edrivers/char/misc.c

460

</chapter>

465

</chapter>

461

466

462

467

463

<title>Parallel Port Devices</title>

468

<title>Parallel Port Devices</title>

464

!Iinclude/linux/parport.h

469

!Iinclude/linux/parport.h

465

!Edrivers/parport/ieee1284.c

470

!Edrivers/parport/ieee1284.c

466

!Edrivers/parport/share.c

471

!Edrivers/parport/share.c

467

!Idrivers/parport/daisy.c

472

!Idrivers/parport/daisy.c

468

</chapter>

473

</chapter>

469

474

470

475

471

<title>Video4Linux</title>

476

<title>Video4Linux</title>

472

!Edrivers/media/video/videodev.c

477

!Edrivers/media/video/videodev.c

473

</chapter>

478

</chapter>

474

479

475

480

476

<title>Sound Devices</title>

481

<title>Sound Devices</title>

477

!Iinclude/sound/core.h

482

!Iinclude/sound/core.h

478

!Esound/sound_core.c

483

!Esound/sound_core.c

479

!Iinclude/sound/pcm.h

484

!Iinclude/sound/pcm.h

480

!Esound/core/pcm.c

485

!Esound/core/pcm.c

481

!Esound/core/device.c

486

!Esound/core/device.c

482

!Esound/core/info.c

487

!Esound/core/info.c

483

!Esound/core/rawmidi.c

488

!Esound/core/rawmidi.c

484

!Esound/core/sound.c

489

!Esound/core/sound.c

485

!Esound/core/memory.c

490

!Esound/core/memory.c

486

!Esound/core/pcm_memory.c

491

!Esound/core/pcm_memory.c

487

!Esound/core/init.c

492

!Esound/core/init.c

488

!Esound/core/isadma.c

493

!Esound/core/isadma.c

489

!Esound/core/control.c

494

!Esound/core/control.c

490

!Esound/core/pcm_lib.c

495

!Esound/core/pcm_lib.c

491

!Esound/core/hwdep.c

496

!Esound/core/hwdep.c

492

!Esound/core/pcm_native.c

497

!Esound/core/pcm_native.c

493

!Esound/core/memalloc.c

498

!Esound/core/memalloc.c

494

<!-- FIXME: Removed for now since no structured comments in source

499

<!-- FIXME: Removed for now since no structured comments in source

495

X!Isound/sound_firmware.c

500

X!Isound/sound_firmware.c

496

-->

501

-->

497

</chapter>

502

</chapter>

498

503

499

504

500

<title>16x50 UART Driver</title>

505

<title>16x50 UART Driver</title>

501

!Iinclude/linux/serial_core.h

506

!Iinclude/linux/serial_core.h

502

!Edrivers/serial/serial_core.c

507

!Edrivers/serial/serial_core.c

503

!Edrivers/serial/8250.c

508

!Edrivers/serial/8250.c

504

</chapter>

509

</chapter>

505

510

506

511

507

<title>Z85230 Support Library</title>

512

<title>Z85230 Support Library</title>

508

!Edrivers/net/wan/z85230.c

513

!Edrivers/net/wan/z85230.c

509

</chapter>

514

</chapter>

510

515

511

516

512

<title>Frame Buffer Library</title>

517

<title>Frame Buffer Library</title>

513

518

514

<para>

519

<para>

515

The frame buffer drivers depend heavily on four data structures.

520

The frame buffer drivers depend heavily on four data structures.

516

These structures are declared in include/linux/fb.h. They are

521

These structures are declared in include/linux/fb.h. They are

517

fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.

522

fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.

518

The last three can be made available to and from userland.

523

The last three can be made available to and from userland.

519

</para>

524

</para>

520

525

521

<para>

526

<para>

522

fb_info defines the current state of a particular video card.

527

fb_info defines the current state of a particular video card.

523

Inside fb_info, there exists a fb_ops structure which is a

528

Inside fb_info, there exists a fb_ops structure which is a

524

collection of needed functions to make fbdev and fbcon work.

529

collection of needed functions to make fbdev and fbcon work.

525

fb_info is only visible to the kernel.

530

fb_info is only visible to the kernel.

526

</para>

531

</para>

527

532

528

<para>

533

<para>

529

fb_var_screeninfo is used to describe the features of a video card

534

fb_var_screeninfo is used to describe the features of a video card

530

that are user defined. With fb_var_screeninfo, things such as

535

that are user defined. With fb_var_screeninfo, things such as

531

depth and the resolution may be defined.

536

depth and the resolution may be defined.

532

</para>

537

</para>

533

538

534

<para>

539

<para>

535

The next structure is fb_fix_screeninfo. This defines the

540

The next structure is fb_fix_screeninfo. This defines the

536

properties of a card that are created when a mode is set and can't

541

properties of a card that are created when a mode is set and can't

537

be changed otherwise. A good example of this is the start of the

542

be changed otherwise. A good example of this is the start of the

538

frame buffer memory. This "locks" the address of the frame buffer

543

frame buffer memory. This "locks" the address of the frame buffer

539

memory, so that it cannot be changed or moved.

544

memory, so that it cannot be changed or moved.

540

</para>

545

</para>

541

546

542

<para>

547

<para>

543

The last structure is fb_monospecs. In the old API, there was

548

The last structure is fb_monospecs. In the old API, there was

544

little importance for fb_monospecs. This allowed for forbidden things

549

little importance for fb_monospecs. This allowed for forbidden things

545

such as setting a mode of 800x600 on a fix frequency monitor. With

550

such as setting a mode of 800x600 on a fix frequency monitor. With

546

the new API, fb_monospecs prevents such things, and if used

551

the new API, fb_monospecs prevents such things, and if used

547

correctly, can prevent a monitor from being cooked. fb_monospecs

552

correctly, can prevent a monitor from being cooked. fb_monospecs

548

will not be useful until kernels 2.5.x.

553

will not be useful until kernels 2.5.x.

549

</para>

554

</para>

550

555

551

<sect1><title>Frame Buffer Memory</title>

556

<sect1><title>Frame Buffer Memory</title>

552

!Edrivers/video/fbmem.c

557

!Edrivers/video/fbmem.c

553

</sect1>

558

</sect1>

554

<!--

559

<!--

555

<sect1><title>Frame Buffer Console</title>

560

<sect1><title>Frame Buffer Console</title>

556

X!Edrivers/video/console/fbcon.c

561

X!Edrivers/video/console/fbcon.c

557

</sect1>

562

</sect1>

558

-->

563

-->

559

<sect1><title>Frame Buffer Colormap</title>

564

<sect1><title>Frame Buffer Colormap</title>

560

!Edrivers/video/fbcmap.c

565

!Edrivers/video/fbcmap.c

561

</sect1>

566

</sect1>

562

<!-- FIXME:

567

<!-- FIXME:

563

drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment

568

drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment

564

out until somebody adds docs. KAO

569

out until somebody adds docs. KAO

565

<sect1><title>Frame Buffer Generic Functions</title>

570

<sect1><title>Frame Buffer Generic Functions</title>

566

X!Idrivers/video/fbgen.c

571

X!Idrivers/video/fbgen.c

567

</sect1>

572

</sect1>

568

KAO -->

573

KAO -->

569

<sect1><title>Frame Buffer Video Mode Database</title>

574

<sect1><title>Frame Buffer Video Mode Database</title>

570

!Idrivers/video/modedb.c

575

!Idrivers/video/modedb.c

571

!Edrivers/video/modedb.c

576

!Edrivers/video/modedb.c

572

</sect1>

577

</sect1>

573

<sect1><title>Frame Buffer Macintosh Video Mode Database</title>

578

<sect1><title>Frame Buffer Macintosh Video Mode Database</title>

574

!Edrivers/video/macmodes.c

579

!Edrivers/video/macmodes.c

575

</sect1>

580

</sect1>

576

<sect1><title>Frame Buffer Fonts</title>

581

<sect1><title>Frame Buffer Fonts</title>

577

<para>

582

<para>

578

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

583

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

579

</para>

584

</para>

580

<!-- FIXME: Removed for now since no structured comments in source

585

<!-- FIXME: Removed for now since no structured comments in source

581

X!Idrivers/video/console/fonts.c

586

X!Idrivers/video/console/fonts.c

582

-->

587

-->

583

</sect1>

588

</sect1>

584

</chapter>

589

</chapter>

585

</book>

590

</book>

586

591

GITLAB

Eric Lee / smarc-fsl-linux-kernel

[PATCH] cdev documentation

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
 <book id="LinuxKernelAPI">
  <bookinfo>
   <title>The Linux Kernel API</title>
   <legalnotice>
    <para>
      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.
    </para>
    <para>
      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.
    </para>
    <para>
      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
    </para>
    <para>
      For more details see the file COPYING in the source
      distribution of Linux.
    </para>
   </legalnotice>
  </bookinfo>
 <toc></toc>
   <chapter id="Basics">
      <title>Driver Basics</title>
      <sect1><title>Driver Entry and Exit points</title>
 !Iinclude/linux/init.h
      </sect1>
      <sect1><title>Atomic and pointer manipulation</title>
 !Iinclude/asm-i386/atomic.h
 !Iinclude/asm-i386/unaligned.h
      </sect1>
      <sect1><title>Delaying, scheduling, and timer routines</title>
 !Iinclude/linux/sched.h
 !Ekernel/sched.c
 !Ekernel/timer.c
      </sect1>
      <sect1><title>High-resolution timers</title>
 !Iinclude/linux/ktime.h
 !Iinclude/linux/hrtimer.h
 !Ekernel/hrtimer.c
      </sect1>
      <sect1><title>Workqueues and Kevents</title>
 !Ekernel/workqueue.c
      </sect1>
      <sect1><title>Internal Functions</title>
 !Ikernel/exit.c
 !Ikernel/signal.c
 !Iinclude/linux/kthread.h
 !Ekernel/kthread.c
      </sect1>
      <sect1><title>Kernel objects manipulation</title>
 <!--
 X!Iinclude/linux/kobject.h
 -->
 !Elib/kobject.c
      </sect1>
      <sect1><title>Kernel utility functions</title>
 !Iinclude/linux/kernel.h
 !Ekernel/printk.c
 !Ekernel/panic.c
 !Ekernel/sys.c
 !Ekernel/rcupdate.c
      </sect1>
   </chapter>
   <chapter id="adt">
      <title>Data Types</title>
      <sect1><title>Doubly Linked Lists</title>
 !Iinclude/linux/list.h
      </sect1>
   </chapter>
   <chapter id="libc">
      <title>Basic C Library Functions</title>
      <para>
        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.
      </para>
      <sect1><title>String Conversions</title>
 !Ilib/vsprintf.c
 !Elib/vsprintf.c
      </sect1>
      <sect1><title>String Manipulation</title>
 <!-- All functions are exported at now
 X!Ilib/string.c
  -->
 !Elib/string.c
      </sect1>
      <sect1><title>Bit Operations</title>
 !Iinclude/asm-i386/bitops.h
      </sect1>
   </chapter>
   <chapter id="kernel-lib">
      <title>Basic Kernel Library Functions</title>
      <para>
        The Linux kernel provides more basic utility functions.
      </para>
      <sect1><title>Bitmap Operations</title>
 !Elib/bitmap.c
 !Ilib/bitmap.c
      </sect1>
      <sect1><title>Command-line Parsing</title>
 !Elib/cmdline.c
      </sect1>
      <sect1><title>CRC Functions</title>
 !Elib/crc16.c
 !Elib/crc32.c
 !Elib/crc-ccitt.c
      </sect1>
   </chapter>
   <chapter id="mm">
      <title>Memory Management in Linux</title>
      <sect1><title>The Slab Cache</title>
 !Iinclude/linux/slab.h
 !Emm/slab.c
      </sect1>
      <sect1><title>User Space Memory Access</title>
 !Iinclude/asm-i386/uaccess.h
 !Earch/i386/lib/usercopy.c
      </sect1>
      <sect1><title>More Memory Management Functions</title>
 !Iinclude/linux/rmap.h
 !Emm/readahead.c
 !Emm/filemap.c
 !Emm/memory.c
 !Emm/vmalloc.c
 !Emm/mempool.c
 !Emm/page-writeback.c
 !Emm/truncate.c
      </sect1>
   </chapter>
   <chapter id="ipc">
      <title>Kernel IPC facilities</title>
      <sect1><title>IPC utilities</title>
 !Iipc/util.c
      </sect1>
   </chapter>
   <chapter id="kfifo">
      <title>FIFO Buffer</title>
      <sect1><title>kfifo interface</title>
 !Iinclude/linux/kfifo.h
 !Ekernel/kfifo.c
      </sect1>
   </chapter>
   <chapter id="vfs">
      <title>The Linux VFS</title>
      <sect1><title>The Filesystem types</title>
 !Iinclude/linux/fs.h
      </sect1>
      <sect1><title>The Directory Cache</title>
 !Efs/dcache.c
 !Iinclude/linux/dcache.h
      </sect1>
      <sect1><title>Inode Handling</title>
 !Efs/inode.c
 !Efs/bad_inode.c
      </sect1>
      <sect1><title>Registration and Superblocks</title>
 !Efs/super.c
      </sect1>
      <sect1><title>File Locks</title>
 !Efs/locks.c
 !Ifs/locks.c
      </sect1>
      <sect1><title>Other Functions</title>
 !Efs/mpage.c
 !Efs/namei.c
 !Efs/buffer.c
 !Efs/bio.c
 !Efs/seq_file.c
 !Efs/filesystems.c
 !Efs/fs-writeback.c
 !Efs/block_dev.c
      </sect1>
   </chapter>
   <chapter id="proc">
      <title>The proc filesystem</title>
      <sect1><title>sysctl interface</title>
 !Ekernel/sysctl.c
      </sect1>
      <sect1><title>proc filesystem interface</title>
 !Ifs/proc/base.c
      </sect1>
   </chapter>
   <chapter id="sysfs">
      <title>The Filesystem for Exporting Kernel Objects</title>
 !Efs/sysfs/file.c
 !Efs/sysfs/symlink.c
 !Efs/sysfs/bin.c
   </chapter>
   <chapter id="debugfs">
      <title>The debugfs filesystem</title>
      <sect1><title>debugfs interface</title>
 !Efs/debugfs/inode.c
 !Efs/debugfs/file.c
      </sect1>
   </chapter>
   <chapter id="relayfs">
      <title>relay interface support</title>
      <para>
 	Relay interface support
 	is designed to provide an efficient mechanism for tools and
 	facilities to relay large amounts of data from kernel space to
 	user space.
      </para>
      <sect1><title>relay interface</title>
 !Ekernel/relay.c
 !Ikernel/relay.c
      </sect1>
   </chapter>
   <chapter id="netcore">
      <title>Linux Networking</title>
      <sect1><title>Networking Base Types</title>
 !Iinclude/linux/net.h
      </sect1>
      <sect1><title>Socket Buffer Functions</title>
 !Iinclude/linux/skbuff.h
 !Iinclude/net/sock.h
 !Enet/socket.c
 !Enet/core/skbuff.c
 !Enet/core/sock.c
 !Enet/core/datagram.c
 !Enet/core/stream.c
      </sect1>
      <sect1><title>Socket Filter</title>
 !Enet/core/filter.c
      </sect1>
      <sect1><title>Generic Network Statistics</title>
 !Iinclude/linux/gen_stats.h
 !Enet/core/gen_stats.c
 !Enet/core/gen_estimator.c
      </sect1>
      <sect1><title>SUN RPC subsystem</title>
 <!-- The !D functionality is not perfect, garbage has to be protected by comments
 !Dnet/sunrpc/sunrpc_syms.c
 -->
 !Enet/sunrpc/xdr.c
 !Enet/sunrpc/svcsock.c
 !Enet/sunrpc/sched.c
      </sect1>
   </chapter>
   <chapter id="netdev">
      <title>Network device support</title>
      <sect1><title>Driver Support</title>
 !Enet/core/dev.c
 !Enet/ethernet/eth.c
 !Iinclude/linux/etherdevice.h
 <!-- FIXME: Removed for now since no structured comments in source
 X!Enet/core/wireless.c
 -->
      </sect1>
      <sect1><title>Synchronous PPP</title>
 !Edrivers/net/wan/syncppp.c
      </sect1>
   </chapter>
   <chapter id="modload">
      <title>Module Support</title>
      <sect1><title>Module Loading</title>
 !Ekernel/kmod.c
      </sect1>
      <sect1><title>Inter Module support</title>
         <para>
            Refer to the file kernel/module.c for more information.
         </para>
 <!-- FIXME: Removed for now since no structured comments in source
 X!Ekernel/module.c
 -->
      </sect1>
   </chapter>
   <chapter id="hardware">
      <title>Hardware Interfaces</title>
      <sect1><title>Interrupt Handling</title>
 !Ekernel/irq/manage.c
      </sect1>
      <sect1><title>Resources Management</title>
 !Ikernel/resource.c
      </sect1>
      <sect1><title>MTRR Handling</title>
 !Earch/i386/kernel/cpu/mtrr/main.c
      </sect1>
      <sect1><title>PCI Support Library</title>
 !Edrivers/pci/pci.c
 !Edrivers/pci/pci-driver.c
 !Edrivers/pci/remove.c
 !Edrivers/pci/pci-acpi.c
 !Edrivers/pci/search.c
 !Edrivers/pci/msi.c
 !Edrivers/pci/bus.c
 <!-- FIXME: Removed for now since no structured comments in source
 X!Edrivers/pci/hotplug.c
 -->
 !Edrivers/pci/probe.c
 !Edrivers/pci/rom.c
      </sect1>
      <sect1><title>PCI Hotplug Support Library</title>
 !Edrivers/pci/hotplug/pci_hotplug_core.c
      </sect1>
      <sect1><title>MCA Architecture</title>
 	<sect2><title>MCA Device Functions</title>
            <para>
               Refer to the file arch/i386/kernel/mca.c for more information.
            </para>
 <!-- FIXME: Removed for now since no structured comments in source
 X!Earch/i386/kernel/mca.c
 -->
 	</sect2>
 	<sect2><title>MCA Bus DMA</title>
 !Iinclude/asm-i386/mca_dma.h
 	</sect2>
      </sect1>
   </chapter>
   <chapter id="firmware">
      <title>Firmware Interfaces</title>
      <sect1><title>DMI Interfaces</title>
 !Edrivers/firmware/dmi_scan.c
      </sect1>
   </chapter>
   <chapter id="security">
      <title>Security Framework</title>
 !Esecurity/security.c
   </chapter>
   <chapter id="audit">
      <title>Audit Interfaces</title>
 !Ekernel/audit.c
 !Ikernel/auditsc.c
 !Ikernel/auditfilter.c
   </chapter>
   <chapter id="accounting">
      <title>Accounting Framework</title>
 !Ikernel/acct.c
   </chapter>
   <chapter id="pmfuncs">
      <title>Power Management</title>
 !Ekernel/power/pm.c
   </chapter>
   <chapter id="devdrivers">
      <title>Device drivers infrastructure</title>
      <sect1><title>Device Drivers Base</title>
 <!--
 X!Iinclude/linux/device.h
 -->
 !Edrivers/base/driver.c
 !Edrivers/base/core.c
 !Edrivers/base/class.c
 !Edrivers/base/firmware_class.c
 !Edrivers/base/transport_class.c
 !Edrivers/base/dmapool.c
 <!-- Cannot be included, because
      attribute_container_add_class_device_adapter
  and attribute_container_classdev_to_container
      exceed allowed 44 characters maximum
 X!Edrivers/base/attribute_container.c
 -->
 !Edrivers/base/sys.c
 <!--
 X!Edrivers/base/interface.c
 -->
 !Edrivers/base/platform.c
 !Edrivers/base/bus.c
      </sect1>
      <sect1><title>Device Drivers Power Management</title>
 !Edrivers/base/power/main.c
 !Edrivers/base/power/resume.c
 !Edrivers/base/power/suspend.c
      </sect1>
      <sect1><title>Device Drivers ACPI Support</title>
 <!-- Internal functions only
 X!Edrivers/acpi/sleep/main.c
 X!Edrivers/acpi/sleep/wakeup.c
 X!Edrivers/acpi/motherboard.c
 X!Edrivers/acpi/bus.c
 -->
 !Edrivers/acpi/scan.c
 !Idrivers/acpi/scan.c
 <!-- No correct structured comments
 X!Edrivers/acpi/pci_bind.c
 -->
      </sect1>
      <sect1><title>Device drivers PnP support</title>
 !Edrivers/pnp/core.c
 <!-- No correct structured comments
 X!Edrivers/pnp/system.c
  -->
 !Edrivers/pnp/card.c
 !Edrivers/pnp/driver.c
 !Edrivers/pnp/manager.c
 !Edrivers/pnp/support.c
      </sect1>
   </chapter>
   <chapter id="blkdev">
      <title>Block Devices</title>
 !Eblock/ll_rw_blk.c
   </chapter>
+  <chapter id="chrdev">
+	<title>Char devices</title>
+!Efs/char_dev.c
+  </chapter>
   <chapter id="miscdev">
      <title>Miscellaneous Devices</title>
 !Edrivers/char/misc.c
   </chapter>
   <chapter id="parportdev">
      <title>Parallel Port Devices</title>
 !Iinclude/linux/parport.h
 !Edrivers/parport/ieee1284.c
 !Edrivers/parport/share.c
 !Idrivers/parport/daisy.c
   </chapter>
   <chapter id="viddev">
      <title>Video4Linux</title>
 !Edrivers/media/video/videodev.c
   </chapter>
   <chapter id="snddev">
      <title>Sound Devices</title>
 !Iinclude/sound/core.h
 !Esound/sound_core.c
 !Iinclude/sound/pcm.h
 !Esound/core/pcm.c
 !Esound/core/device.c
 !Esound/core/info.c
 !Esound/core/rawmidi.c
 !Esound/core/sound.c
 !Esound/core/memory.c
 !Esound/core/pcm_memory.c
 !Esound/core/init.c
 !Esound/core/isadma.c
 !Esound/core/control.c
 !Esound/core/pcm_lib.c
 !Esound/core/hwdep.c
 !Esound/core/pcm_native.c
 !Esound/core/memalloc.c
 <!-- FIXME: Removed for now since no structured comments in source
 X!Isound/sound_firmware.c
 -->
   </chapter>
   <chapter id="uart16x50">
      <title>16x50 UART Driver</title>
 !Iinclude/linux/serial_core.h
 !Edrivers/serial/serial_core.c
 !Edrivers/serial/8250.c
   </chapter>
   <chapter id="z85230">
      <title>Z85230 Support Library</title>
 !Edrivers/net/wan/z85230.c
   </chapter>
   <chapter id="fbdev">
      <title>Frame Buffer Library</title>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <sect1><title>Frame Buffer Memory</title>
 !Edrivers/video/fbmem.c
      </sect1>
 <!--
      <sect1><title>Frame Buffer Console</title>
 X!Edrivers/video/console/fbcon.c
      </sect1>
 -->
      <sect1><title>Frame Buffer Colormap</title>
 !Edrivers/video/fbcmap.c
      </sect1>
 <!-- FIXME:
   drivers/video/fbgen.c has no docs, which stuffs up the sgml.  Comment
   out until somebody adds docs.  KAO
      <sect1><title>Frame Buffer Generic Functions</title>
 X!Idrivers/video/fbgen.c
      </sect1>
 KAO -->
      <sect1><title>Frame Buffer Video Mode Database</title>
 !Idrivers/video/modedb.c
 !Edrivers/video/modedb.c
      </sect1>
      <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
 !Edrivers/video/macmodes.c
      </sect1>
      <sect1><title>Frame Buffer Fonts</title>
         <para>
            Refer to the file drivers/video/console/fonts.c for more information.
         </para>
 <!-- FIXME: Removed for now since no structured comments in source
 X!Idrivers/video/console/fonts.c
 -->
      </sect1>
   </chapter>
 </book>

 /*
  *  linux/fs/char_dev.c
  *
  *  Copyright (C) 1991, 1992  Linus Torvalds
  */
 #include <linux/init.h>
 #include <linux/fs.h>
 #include <linux/slab.h>
 #include <linux/string.h>
 #include <linux/major.h>
 #include <linux/errno.h>
 #include <linux/module.h>
 #include <linux/smp_lock.h>
 #include <linux/seq_file.h>
 #include <linux/kobject.h>
 #include <linux/kobj_map.h>
 #include <linux/cdev.h>
 #include <linux/mutex.h>
 #include <linux/backing-dev.h>
 #ifdef CONFIG_KMOD
 #include <linux/kmod.h>
 #endif
 /*
  * capabilities for /dev/mem, /dev/kmem and similar directly mappable character
  * devices
  * - permits shared-mmap for read, write and/or exec
  * - does not permit private mmap in NOMMU mode (can't do COW)
  * - no readahead or I/O queue unplugging required
  */
 struct backing_dev_info directly_mappable_cdev_bdi = {
 	.capabilities	= (
 #ifdef CONFIG_MMU
 		/* permit private copies of the data to be taken */
 		BDI_CAP_MAP_COPY |
 #endif
 		/* permit direct mmap, for read, write or exec */
 		BDI_CAP_MAP_DIRECT |
 		BDI_CAP_READ_MAP | BDI_CAP_WRITE_MAP | BDI_CAP_EXEC_MAP),
 };
 static struct kobj_map *cdev_map;
 static DEFINE_MUTEX(chrdevs_lock);
 static struct char_device_struct {
 	struct char_device_struct *next;
 	unsigned int major;
 	unsigned int baseminor;
 	int minorct;
 	char name[64];
 	struct file_operations *fops;
 	struct cdev *cdev;		/* will die */
 } *chrdevs[CHRDEV_MAJOR_HASH_SIZE];
 /* index in the above */
 static inline int major_to_index(int major)
 {
 	return major % CHRDEV_MAJOR_HASH_SIZE;
 }
 #ifdef CONFIG_PROC_FS
 void chrdev_show(struct seq_file *f, off_t offset)
 {
 	struct char_device_struct *cd;
 	if (offset < CHRDEV_MAJOR_HASH_SIZE) {
 		mutex_lock(&chrdevs_lock);
 		for (cd = chrdevs[offset]; cd; cd = cd->next)
 			seq_printf(f, "%3d %s\n", cd->major, cd->name);
 		mutex_unlock(&chrdevs_lock);
 	}
 }
 #endif /* CONFIG_PROC_FS */
 /*
  * Register a single major with a specified minor range.
  *
  * If major == 0 this functions will dynamically allocate a major and return
  * its number.
  *
  * If major > 0 this function will attempt to reserve the passed range of
  * minors and will return zero on success.
  *
  * Returns a -ve errno on failure.
  */
 static struct char_device_struct *
 __register_chrdev_region(unsigned int major, unsigned int baseminor,
 			   int minorct, const char *name)
 {
 	struct char_device_struct *cd, **cp;
 	int ret = 0;
 	int i;
 	cd = kzalloc(sizeof(struct char_device_struct), GFP_KERNEL);
 	if (cd == NULL)
 		return ERR_PTR(-ENOMEM);
 	mutex_lock(&chrdevs_lock);
 	/* temporary */
 	if (major == 0) {
 		for (i = ARRAY_SIZE(chrdevs)-1; i > 0; i--) {
 			if (chrdevs[i] == NULL)
 				break;
 		}
 		if (i == 0) {
 			ret = -EBUSY;
 			goto out;
 		}
 		major = i;
 		ret = major;
 	}
 	cd->major = major;
 	cd->baseminor = baseminor;
 	cd->minorct = minorct;
 	strncpy(cd->name,name, 64);
 	i = major_to_index(major);
 	for (cp = &chrdevs[i]; *cp; cp = &(*cp)->next)
 		if ((*cp)->major > major ||
 		    ((*cp)->major == major &&
 		     (((*cp)->baseminor >= baseminor) ||
 		      ((*cp)->baseminor + (*cp)->minorct > baseminor))))
 			break;
 	/* Check for overlapping minor ranges.  */
 	if (*cp && (*cp)->major == major) {
 		int old_min = (*cp)->baseminor;
 		int old_max = (*cp)->baseminor + (*cp)->minorct - 1;
 		int new_min = baseminor;
 		int new_max = baseminor + minorct - 1;
 		/* New driver overlaps from the left.  */
 		if (new_max >= old_min && new_max <= old_max) {
 			ret = -EBUSY;
 			goto out;
 		}
 		/* New driver overlaps from the right.  */
 		if (new_min <= old_max && new_min >= old_min) {
 			ret = -EBUSY;
 			goto out;
 		}
 	}
 	cd->next = *cp;
 	*cp = cd;
 	mutex_unlock(&chrdevs_lock);
 	return cd;
 out:
 	mutex_unlock(&chrdevs_lock);
 	kfree(cd);
 	return ERR_PTR(ret);
 }
 static struct char_device_struct *
 __unregister_chrdev_region(unsigned major, unsigned baseminor, int minorct)
 {
 	struct char_device_struct *cd = NULL, **cp;
 	int i = major_to_index(major);
 	mutex_lock(&chrdevs_lock);
 	for (cp = &chrdevs[i]; *cp; cp = &(*cp)->next)
 		if ((*cp)->major == major &&
 		    (*cp)->baseminor == baseminor &&
 		    (*cp)->minorct == minorct)
 			break;
 	if (*cp) {
 		cd = *cp;
 		*cp = cd->next;
 	}
 	mutex_unlock(&chrdevs_lock);
 	return cd;
 }
+/**
+ * register_chrdev_region() - register a range of device numbers
+ * @from: the first in the desired range of device numbers; must include
+ *        the major number.
+ * @count: the number of consecutive device numbers required
+ * @name: the name of the device or driver.
+ *
+ * Return value is zero on success, a negative error code on failure.
+ */
 int register_chrdev_region(dev_t from, unsigned count, const char *name)
 {
 	struct char_device_struct *cd;
 	dev_t to = from + count;
 	dev_t n, next;
 	for (n = from; n < to; n = next) {
 		next = MKDEV(MAJOR(n)+1, 0);
 		if (next > to)
 			next = to;
 		cd = __register_chrdev_region(MAJOR(n), MINOR(n),
 			       next - n, name);
 		if (IS_ERR(cd))
 			goto fail;
 	}
 	return 0;
 fail:
 	to = n;
 	for (n = from; n < to; n = next) {
 		next = MKDEV(MAJOR(n)+1, 0);
 		kfree(__unregister_chrdev_region(MAJOR(n), MINOR(n), next - n));
 	}
 	return PTR_ERR(cd);
 }
+/**
+ * alloc_chrdev_region() - register a range of char device numbers
+ * @dev: output parameter for first assigned number
+ * @baseminor: first of the requested range of minor numbers
+ * @count: the number of minor numbers required
+ * @name: the name of the associated device or driver
+ *
+ * Allocates a range of char device numbers.  The major number will be
+ * chosen dynamically, and returned (along with the first minor number)
+ * in @dev.  Returns zero or a negative error code.
+ */
 int alloc_chrdev_region(dev_t *dev, unsigned baseminor, unsigned count,
 			const char *name)
 {
 	struct char_device_struct *cd;
 	cd = __register_chrdev_region(0, baseminor, count, name);
 	if (IS_ERR(cd))
 		return PTR_ERR(cd);
 	*dev = MKDEV(cd->major, cd->baseminor);
 	return 0;
 }
 /**
  * register_chrdev() - Register a major number for character devices.
  * @major: major device number or 0 for dynamic allocation
  * @name: name of this range of devices
  * @fops: file operations associated with this devices
  *
  * If @major == 0 this functions will dynamically allocate a major and return
  * its number.
  *
  * If @major > 0 this function will attempt to reserve a device with the given
  * major number and will return zero on success.
  *
  * Returns a -ve errno on failure.
  *
  * The name of this device has nothing to do with the name of the device in
  * /dev. It only helps to keep track of the different owners of devices. If
  * your module name has only one type of devices it's ok to use e.g. the name
  * of the module here.
  *
  * This function registers a range of 256 minor numbers. The first minor number
  * is 0.
  */
 int register_chrdev(unsigned int major, const char *name,
 		    const struct file_operations *fops)
 {
 	struct char_device_struct *cd;
 	struct cdev *cdev;
 	char *s;
 	int err = -ENOMEM;
 	cd = __register_chrdev_region(major, 0, 256, name);
 	if (IS_ERR(cd))
 		return PTR_ERR(cd);
 	cdev = cdev_alloc();
 	if (!cdev)
 		goto out2;
 	cdev->owner = fops->owner;
 	cdev->ops = fops;
 	kobject_set_name(&cdev->kobj, "%s", name);
 	for (s = strchr(kobject_name(&cdev->kobj),'/'); s; s = strchr(s, '/'))
 		*s = '!';
 	err = cdev_add(cdev, MKDEV(cd->major, 0), 256);
 	if (err)
 		goto out;
 	cd->cdev = cdev;
 	return major ? 0 : cd->major;
 out:
 	kobject_put(&cdev->kobj);
 out2:
 	kfree(__unregister_chrdev_region(cd->major, 0, 256));
 	return err;
 }
+/**
+ * unregister_chrdev_region() - return a range of device numbers
+ * @from: the first in the range of numbers to unregister
+ * @count: the number of device numbers to unregister
+ *
+ * This function will unregister a range of @count device numbers,
+ * starting with @from.  The caller should normally be the one who
+ * allocated those numbers in the first place...
+ */
 void unregister_chrdev_region(dev_t from, unsigned count)
 {
 	dev_t to = from + count;
 	dev_t n, next;
 	for (n = from; n < to; n = next) {
 		next = MKDEV(MAJOR(n)+1, 0);
 		if (next > to)
 			next = to;
 		kfree(__unregister_chrdev_region(MAJOR(n), MINOR(n), next - n));
 	}
 }
 int unregister_chrdev(unsigned int major, const char *name)
 {
 	struct char_device_struct *cd;
 	cd = __unregister_chrdev_region(major, 0, 256);
 	if (cd && cd->cdev)
 		cdev_del(cd->cdev);
 	kfree(cd);
 	return 0;
 }
 static DEFINE_SPINLOCK(cdev_lock);
 static struct kobject *cdev_get(struct cdev *p)
 {
 	struct module *owner = p->owner;
 	struct kobject *kobj;
 	if (owner && !try_module_get(owner))
 		return NULL;
 	kobj = kobject_get(&p->kobj);
 	if (!kobj)
 		module_put(owner);
 	return kobj;
 }
 void cdev_put(struct cdev *p)
 {
 	if (p) {
 		struct module *owner = p->owner;
 		kobject_put(&p->kobj);
 		module_put(owner);
 	}
 }
 /*
  * Called every time a character special file is opened
  */
 int chrdev_open(struct inode * inode, struct file * filp)
 {
 	struct cdev *p;
 	struct cdev *new = NULL;
 	int ret = 0;
 	spin_lock(&cdev_lock);
 	p = inode->i_cdev;
 	if (!p) {
 		struct kobject *kobj;
 		int idx;
 		spin_unlock(&cdev_lock);
 		kobj = kobj_lookup(cdev_map, inode->i_rdev, &idx);
 		if (!kobj)
 			return -ENXIO;
 		new = container_of(kobj, struct cdev, kobj);
 		spin_lock(&cdev_lock);
 		p = inode->i_cdev;
 		if (!p) {
 			inode->i_cdev = p = new;
 			inode->i_cindex = idx;
 			list_add(&inode->i_devices, &p->list);
 			new = NULL;
 		} else if (!cdev_get(p))
 			ret = -ENXIO;
 	} else if (!cdev_get(p))
 		ret = -ENXIO;
 	spin_unlock(&cdev_lock);
 	cdev_put(new);
 	if (ret)
 		return ret;
 	filp->f_op = fops_get(p->ops);
 	if (!filp->f_op) {
 		cdev_put(p);
 		return -ENXIO;
 	}
 	if (filp->f_op->open) {
 		lock_kernel();
 		ret = filp->f_op->open(inode,filp);
 		unlock_kernel();
 	}
 	if (ret)
 		cdev_put(p);
 	return ret;
 }
 void cd_forget(struct inode *inode)
 {
 	spin_lock(&cdev_lock);
 	list_del_init(&inode->i_devices);
 	inode->i_cdev = NULL;
 	spin_unlock(&cdev_lock);
 }
 static void cdev_purge(struct cdev *cdev)
 {
 	spin_lock(&cdev_lock);
 	while (!list_empty(&cdev->list)) {
 		struct inode *inode;
 		inode = container_of(cdev->list.next, struct inode, i_devices);
 		list_del_init(&inode->i_devices);
 		inode->i_cdev = NULL;
 	}
 	spin_unlock(&cdev_lock);
 }
 /*
  * Dummy default file-operations: the only thing this does
  * is contain the open that then fills in the correct operations
  * depending on the special file...
  */
 const struct file_operations def_chr_fops = {
 	.open = chrdev_open,
 };
 static struct kobject *exact_match(dev_t dev, int *part, void *data)
 {
 	struct cdev *p = data;
 	return &p->kobj;
 }
 static int exact_lock(dev_t dev, void *data)
 {
 	struct cdev *p = data;
 	return cdev_get(p) ? 0 : -1;
 }
+/**
+ * cdev_add() - add a char device to the system
+ * @p: the cdev structure for the device
+ * @dev: the first device number for which this device is responsible
+ * @count: the number of consecutive minor numbers corresponding to this
+ *         device
+ *
+ * cdev_add() adds the device represented by @p to the system, making it
+ * live immediately.  A negative error code is returned on failure.
+ */
 int cdev_add(struct cdev *p, dev_t dev, unsigned count)
 {
 	p->dev = dev;
 	p->count = count;
 	return kobj_map(cdev_map, dev, count, NULL, exact_match, exact_lock, p);
 }
 static void cdev_unmap(dev_t dev, unsigned count)
 {
 	kobj_unmap(cdev_map, dev, count);
 }
+/**
+ * cdev_del() - remove a cdev from the system
+ * @p: the cdev structure to be removed
+ *
+ * cdev_del() removes @p from the system, possibly freeing the structure
+ * itself.
+ */
 void cdev_del(struct cdev *p)
 {
 	cdev_unmap(p->dev, p->count);
 	kobject_put(&p->kobj);
 }
 static void cdev_default_release(struct kobject *kobj)
 {
 	struct cdev *p = container_of(kobj, struct cdev, kobj);
 	cdev_purge(p);
 }
 static void cdev_dynamic_release(struct kobject *kobj)
 {
 	struct cdev *p = container_of(kobj, struct cdev, kobj);
 	cdev_purge(p);
 	kfree(p);
 }
 static struct kobj_type ktype_cdev_default = {
 	.release	= cdev_default_release,
 };
 static struct kobj_type ktype_cdev_dynamic = {
 	.release	= cdev_dynamic_release,
 };
+/**
+ * cdev_alloc() - allocate a cdev structure
+ *
+ * Allocates and returns a cdev structure, or NULL on failure.
+ */
 struct cdev *cdev_alloc(void)
 {
 	struct cdev *p = kzalloc(sizeof(struct cdev), GFP_KERNEL);
 	if (p) {
 		p->kobj.ktype = &ktype_cdev_dynamic;
 		INIT_LIST_HEAD(&p->list);
 		kobject_init(&p->kobj);
 	}
 	return p;
 }
+/**
+ * cdev_init() - initialize a cdev structure
+ * @cdev: the structure to initialize
+ * @fops: the file_operations for this device
+ *
+ * Initializes @cdev, remembering @fops, making it ready to add to the
+ * system with cdev_add().
+ */
 void cdev_init(struct cdev *cdev, const struct file_operations *fops)
 {
 	memset(cdev, 0, sizeof *cdev);
 	INIT_LIST_HEAD(&cdev->list);
 	cdev->kobj.ktype = &ktype_cdev_default;
 	kobject_init(&cdev->kobj);
 	cdev->ops = fops;
 }
 static struct kobject *base_probe(dev_t dev, int *part, void *data)
 {
 	if (request_module("char-major-%d-%d", MAJOR(dev), MINOR(dev)) > 0)
 		/* Make old-style 2.4 aliases work */
 		request_module("char-major-%d", MAJOR(dev));
 	return NULL;
 }
 void __init chrdev_init(void)
 {
 	cdev_map = kobj_map_init(base_probe, &chrdevs_lock);
 }
 /* Let modules do char dev stuff */
 EXPORT_SYMBOL(register_chrdev_region);
 EXPORT_SYMBOL(unregister_chrdev_region);
 EXPORT_SYMBOL(alloc_chrdev_region);
 EXPORT_SYMBOL(cdev_init);
 EXPORT_SYMBOL(cdev_alloc);
 EXPORT_SYMBOL(cdev_del);
 EXPORT_SYMBOL(cdev_add);
 EXPORT_SYMBOL(register_chrdev);
 EXPORT_SYMBOL(unregister_chrdev);
 EXPORT_SYMBOL(directly_mappable_cdev_bdi);