FreeBSD developers' handbook.2001

FreeBSD Developers’ Handbook

The FreeBSD Documentation Project

FreeBSD Developers’ Handbook by The FreeBSD Documentation Project Published August 2000

Copyright © 2000, 2001 by The FreeBSD Documentation Project

Welcome to the Developers’ Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the FreeBSD documentation project mailing list <[e-mail]>. The latest version of this document is always available from the FreeBSD World Wide Web server (http://www.FreeBSD.org/). It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server (ftp://ftp.FreeBSD.org/pub/FreeBSD/doc) or one of the numerous mirror sites (http://www.freebsd.org/handbook/mirrors-ftp.html).

Redistribution and use in source (SGML DocBook) and ’compiled’ forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without

modification, are permitted provided that the following conditions are met:

1.Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.

2.Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents
I. Introduction ...............................................................................................................................................................		8
1 Developing on FreeBSD.....................................................................................................................................		9
2 The BSD Vision .................................................................................................................................................		1
3 Architectural Overview ......................................................................................................................................		2
4 The Layout of /usr/src ........................................................................................................................................		3
II. Basics.........................................................................................................................................................................		4
5 Programming Tools ............................................................................................................................................		5
5.1	Synopsis.................................................................................................................................................	5
5.2	Introduction............................................................................................................................................	5
5.3	Introduction to Programming ................................................................................................................	5
5.4	Compiling with cc.................................................................................................................................	8
5.5 Make ....................................................................................................................................................		16
5.6	Debugging............................................................................................................................................	21
5.7	Using Emacs as a Development Environment.....................................................................................	25
5.8	Further Reading ...................................................................................................................................	35
6 Secure Programming ........................................................................................................................................		37
6.1	Synopsis...............................................................................................................................................	37
6.2	Secure Design Methodology................................................................................................................	37
6.3	Buffer Overflows .................................................................................................................................	37
6.4	SetUID issues.......................................................................................................................................	40
6.5	Limiting your program’s environment.................................................................................................	40
6.6	Trust .....................................................................................................................................................	42
6.7	Race Conditions...................................................................................................................................	42
III. Kernel ....................................................................................................................................................................		43
7 History of the Unix Kernel...............................................................................................................................		44
8 Locking Notes ..................................................................................................................................................		45
8.1	Mutexes................................................................................................................................................	45
8.2 Lock Manager Locks ...........................................................................................................................		48
8.3	Atomically Protected Variables ...........................................................................................................	48
IV. Memory Management..........................................................................................................................................		49
9 Virtual Memory System ...................................................................................................................................		50
9.1 The FreeBSD VM System ...................................................................................................................		50
10 DMA...............................................................................................................................................................		54
10.1 DMA: What it is and How it Works ..................................................................................................		54
V. I/O System...............................................................................................................................................................		67
11 UFS.................................................................................................................................................................		68

3

VI. Interprocess Communication ..............................................................................................................................		69
12 Signals	............................................................................................................................................................	70
VII. Networking ..........................................................................................................................................................		71
13 Sockets ...........................................................................................................................................................		72
13.1 .............................................................................................................................................	Synopsis	72
13.2 ..................................................................................................................	Networking and Diversity	72
13.3 ............................................................................................................................................	Protocols	72
13.4 ............................................................................................................................The Sockets Model		75
13.5 ................................................................................................................	Essential Socket Functions	75
13.6 ................................................................................................................................	Helper Functions	91
13.7 ............................................................................................................................	Concurrent Servers	94
14 IPv6 Internals .................................................................................................................................................		97
14.1 ................................................................................................................	IPv6/IPsec Implementation	97
VIII. Network Filesystems........................................................................................................................................		118
15 AFS...............................................................................................................................................................		119
IX. Terminal Handling .............................................................................................................................................		120
16 Syscons.........................................................................................................................................................		121
X. Sound.....................................................................................................................................................................		122
17 OSS...............................................................................................................................................................		123
XI. Device Drivers .....................................................................................................................................................		124
18 Writing .................................................................................................................FreeBSD Device Drivers		125
18.1 ......................................................................................................................................	Introduction	125
18.2 ...........................................................................................Dynamic Kernel Linker Facility - KLD		125
18.3 ................................................................................................................	Accessing a device driver	127
18.4 ............................................................................................................................	Character Devices	127
18.5 ...............................................................................................................................Network Drivers		131
19 ISA device ........................................................................................................................................drivers		133
19.1 ...........................................................................................................................................	Synopsis	133
19.2 .............................................................................................................................	Basic information	133
19.3 ...............................................................................................................................	Device _ t pointer	135
19.4 .............................	Config file and the order of identifying and probing during auto - configuration	136
19.5 .........................................................................................................................................Resources		138
19.6 ......................................................................................................................Bus memory mapping		141
19.7 ................................................................................................................................................DMA		149
19.8 ..................................................................................................................................xxx_isa_probe		151
19.9 .................................................................................................................................xxx_isa_attach		158
19.10 ..............................................................................................................................xxx_isa_detach		162
19.11 .........................................................................................................................xxx_isa_shutdown		163

4

20 PCI Devices..................................................................................................................................................		165
20.1 Probe and Attach..............................................................................................................................		165
20.2 Bus Resources..................................................................................................................................		169
21 Common Access Method SCSI Controllers.................................................................................................		173
21.1	Synopsis...........................................................................................................................................	173
21.2	General architecture.........................................................................................................................	173
21.3	Polling..............................................................................................................................................	194
21.4 Asynchronous Events ......................................................................................................................		195
21.5	Interrupts..........................................................................................................................................	196
21.6 Errors Summary...............................................................................................................................		203
21.7 Timeout Handling ............................................................................................................................		204
22 USB Devices ................................................................................................................................................		206
22.1	Introduction......................................................................................................................................	206
22.2	Host Controllers...............................................................................................................................	207
22.3 USB Device Information .................................................................................................................		209
22.4	Device probe and attach...................................................................................................................	211
22.5	USB Drivers Protocol Information ..................................................................................................	212
23 NewBus ........................................................................................................................................................		215
XII. Architectures .....................................................................................................................................................		216
24 x86 Assembly Language Programming .......................................................................................................		217
24.1	Synopsis...........................................................................................................................................	217
24.2 The Tools .........................................................................................................................................		217
24.3 System Calls ....................................................................................................................................		218
24.4	Return Values...................................................................................................................................	221
24.5	Creating Portable Code....................................................................................................................	222
24.6 Our First Program ............................................................................................................................		227
24.7	Writing Unix Filters.........................................................................................................................	229
24.8	Buffered Input and Output...............................................................................................................	232
24.9 Command Line Arguments..............................................................................................................		240
24.10 Unix Environment..........................................................................................................................		244
24.11 Working with Files.........................................................................................................................		250
24.12 One-Pointed Mind .........................................................................................................................		262
24.13 Using the FPU................................................................................................................................		272
24.14 Caveats...........................................................................................................................................		305
24.15 Acknowledgements........................................................................................................................		306
25 Alpha ............................................................................................................................................................		308
26 IA-64 ............................................................................................................................................................		309
XIII. Debugging.........................................................................................................................................................		310
27 Truss .............................................................................................................................................................		311

5

XIV. Compatibility Layers	.......................................................................................................................................312
28 Linux ............................................................................................................................................................	313
XV. Appendices .........................................................................................................................................................	314
Bibliography......................................................................................................................................................	315
Index..................................................................................................................................................................	315

6

List of Tables
8-1. Mutex List..............................................................................................................................................................	46
8-2. lockmgr(9) Lock List.............................................................................................................................................	48
List of Examples
5-1. A sample .emacs file............................................................................................................................................	28

7

I. Introduction

Chapter 1 Developing on FreeBSD

This will need to discuss FreeBSD as a development platform, the vision of BSD, architectural overview, layout of /usr/src, history, etc.

Thank you for considering FreeBSD as your development platform! We hope it will not let you down.

9

Chapter 2 The BSD Vision

1