Documentation/core-api/kernel-api.rst

   1 ====================
   2 The Linux Kernel API
   3 ====================
   4
   5
   6 List Management Functions
   7 =========================
   8
   9 .. kernel-doc:: include/linux/list.h
  10    :internal:
  11
  12 Basic C Library Functions
  13 =========================
  14
  15 When writing drivers, you cannot in general use routines which are from
  16 the C Library. Some of the functions have been found generally useful
  17 and they are listed below. The behaviour of these functions may vary
  18 slightly from those defined by ANSI, and these deviations are noted in
  19 the text.
  20
  21 String Conversions
  22 ------------------
  23
  24 .. kernel-doc:: lib/vsprintf.c
  25    :export:
  26
  27 .. kernel-doc:: include/linux/kernel.h
  28    :functions: kstrtol
  29
  30 .. kernel-doc:: include/linux/kernel.h
  31    :functions: kstrtoul
  32
  33 .. kernel-doc:: lib/kstrtox.c
  34    :export:
  35
  36 String Manipulation
  37 -------------------
  38
  39 .. kernel-doc:: lib/string.c
  40    :export:
  41
  42 Basic Kernel Library Functions
  43 ==============================
  44
  45 The Linux kernel provides more basic utility functions.
  46
  47 Bit Operations
  48 --------------
  49
  50 .. kernel-doc:: arch/x86/include/asm/bitops.h
  51    :internal:
  52
  53 Bitmap Operations
  54 -----------------
  55
  56 .. kernel-doc:: lib/bitmap.c
  57    :doc: bitmap introduction
  58
  59 .. kernel-doc:: include/linux/bitmap.h
  60    :doc: declare bitmap
  61
  62 .. kernel-doc:: include/linux/bitmap.h
  63    :doc: bitmap overview
  64
  65 .. kernel-doc:: include/linux/bitmap.h
  66    :doc: bitmap bitops
  67
  68 .. kernel-doc:: lib/bitmap.c
  69    :export:
  70
  71 .. kernel-doc:: lib/bitmap.c
  72    :internal:
  73
  74 .. kernel-doc:: include/linux/bitmap.h
  75    :internal:
  76
  77 Command-line Parsing
  78 --------------------
  79
  80 .. kernel-doc:: lib/cmdline.c
  81    :export:
  82
  83 Sorting
  84 -------
  85
  86 .. kernel-doc:: lib/sort.c
  87    :export:
  88
  89 .. kernel-doc:: lib/list_sort.c
  90    :export:
  91
  92 Text Searching
  93 --------------
  94
  95 .. kernel-doc:: lib/textsearch.c
  96    :doc: ts_intro
  97
  98 .. kernel-doc:: lib/textsearch.c
  99    :export:
 100
 101 .. kernel-doc:: include/linux/textsearch.h
 102    :functions: textsearch_find textsearch_next \
 103                textsearch_get_pattern textsearch_get_pattern_len
 104
 105 CRC and Math Functions in Linux
 106 ===============================
 107
 108 CRC Functions
 109 -------------
 110
 111 .. kernel-doc:: lib/crc4.c
 112    :export:
 113
 114 .. kernel-doc:: lib/crc7.c
 115    :export:
 116
 117 .. kernel-doc:: lib/crc8.c
 118    :export:
 119
 120 .. kernel-doc:: lib/crc16.c
 121    :export:
 122
 123 .. kernel-doc:: lib/crc32.c
 124
 125 .. kernel-doc:: lib/crc-ccitt.c
 126    :export:
 127
 128 .. kernel-doc:: lib/crc-itu-t.c
 129    :export:
 130
 131 Base 2 log and power Functions
 132 ------------------------------
 133
 134 .. kernel-doc:: include/linux/log2.h
 135    :internal:
 136
 137 Division Functions
 138 ------------------
 139
 140 .. kernel-doc:: include/asm-generic/div64.h
 141    :functions: do_div
 142
 143 .. kernel-doc:: include/linux/math64.h
 144    :internal:
 145
 146 .. kernel-doc:: lib/div64.c
 147    :functions: div_s64_rem div64_u64_rem div64_u64 div64_s64
 148
 149 .. kernel-doc:: lib/gcd.c
 150    :export:
 151
 152 UUID/GUID
 153 ---------
 154
 155 .. kernel-doc:: lib/uuid.c
 156    :export:
 157
 158 Memory Management in Linux
 159 ==========================
 160
 161 The Slab Cache
 162 --------------
 163
 164 .. kernel-doc:: include/linux/slab.h
 165    :internal:
 166
 167 .. kernel-doc:: mm/slab.c
 168    :export:
 169
 170 .. kernel-doc:: mm/util.c
 171    :export:
 172
 173 User Space Memory Access
 174 ------------------------
 175
 176 .. kernel-doc:: arch/x86/include/asm/uaccess.h
 177    :internal:
 178
 179 .. kernel-doc:: arch/x86/lib/usercopy_32.c
 180    :export:
 181
 182 More Memory Management Functions
 183 --------------------------------
 184
 185 .. kernel-doc:: mm/readahead.c
 186    :export:
 187
 188 .. kernel-doc:: mm/filemap.c
 189    :export:
 190
 191 .. kernel-doc:: mm/memory.c
 192    :export:
 193
 194 .. kernel-doc:: mm/vmalloc.c
 195    :export:
 196
 197 .. kernel-doc:: mm/page_alloc.c
 198    :internal:
 199
 200 .. kernel-doc:: mm/mempool.c
 201    :export:
 202
 203 .. kernel-doc:: mm/dmapool.c
 204    :export:
 205
 206 .. kernel-doc:: mm/page-writeback.c
 207    :export:
 208
 209 .. kernel-doc:: mm/truncate.c
 210    :export:
 211
 212 Kernel IPC facilities
 213 =====================
 214
 215 IPC utilities
 216 -------------
 217
 218 .. kernel-doc:: ipc/util.c
 219    :internal:
 220
 221 FIFO Buffer
 222 ===========
 223
 224 kfifo interface
 225 ---------------
 226
 227 .. kernel-doc:: include/linux/kfifo.h
 228    :internal:
 229
 230 relay interface support
 231 =======================
 232
 233 Relay interface support is designed to provide an efficient mechanism
 234 for tools and facilities to relay large amounts of data from kernel
 235 space to user space.
 236
 237 relay interface
 238 ---------------
 239
 240 .. kernel-doc:: kernel/relay.c
 241    :export:
 242
 243 .. kernel-doc:: kernel/relay.c
 244    :internal:
 245
 246 Module Support
 247 ==============
 248
 249 Module Loading
 250 --------------
 251
 252 .. kernel-doc:: kernel/kmod.c
 253    :export:
 254
 255 Inter Module support
 256 --------------------
 257
 258 Refer to the file kernel/module.c for more information.
 259
 260 Hardware Interfaces
 261 ===================
 262
 263 Interrupt Handling
 264 ------------------
 265
 266 .. kernel-doc:: kernel/irq/manage.c
 267    :export:
 268
 269 DMA Channels
 270 ------------
 271
 272 .. kernel-doc:: kernel/dma.c
 273    :export:
 274
 275 Resources Management
 276 --------------------
 277
 278 .. kernel-doc:: kernel/resource.c
 279    :internal:
 280
 281 .. kernel-doc:: kernel/resource.c
 282    :export:
 283
 284 MTRR Handling
 285 -------------
 286
 287 .. kernel-doc:: arch/x86/kernel/cpu/mtrr/main.c
 288    :export:
 289
 290 Security Framework
 291 ==================
 292
 293 .. kernel-doc:: security/security.c
 294    :internal:
 295
 296 .. kernel-doc:: security/inode.c
 297    :export:
 298
 299 Audit Interfaces
 300 ================
 301
 302 .. kernel-doc:: kernel/audit.c
 303    :export:
 304
 305 .. kernel-doc:: kernel/auditsc.c
 306    :internal:
 307
 308 .. kernel-doc:: kernel/auditfilter.c
 309    :internal:
 310
 311 Accounting Framework
 312 ====================
 313
 314 .. kernel-doc:: kernel/acct.c
 315    :internal:
 316
 317 Block Devices
 318 =============
 319
 320 .. kernel-doc:: block/blk-core.c
 321    :export:
 322
 323 .. kernel-doc:: block/blk-core.c
 324    :internal:
 325
 326 .. kernel-doc:: block/blk-map.c
 327    :export:
 328
 329 .. kernel-doc:: block/blk-sysfs.c
 330    :internal:
 331
 332 .. kernel-doc:: block/blk-settings.c
 333    :export:
 334
 335 .. kernel-doc:: block/blk-exec.c
 336    :export:
 337
 338 .. kernel-doc:: block/blk-flush.c
 339    :export:
 340
 341 .. kernel-doc:: block/blk-lib.c
 342    :export:
 343
 344 .. kernel-doc:: block/blk-tag.c
 345    :export:
 346
 347 .. kernel-doc:: block/blk-tag.c
 348    :internal:
 349
 350 .. kernel-doc:: block/blk-integrity.c
 351    :export:
 352
 353 .. kernel-doc:: kernel/trace/blktrace.c
 354    :internal:
 355
 356 .. kernel-doc:: block/genhd.c
 357    :internal:
 358
 359 .. kernel-doc:: block/genhd.c
 360    :export:
 361
 362 Char devices
 363 ============
 364
 365 .. kernel-doc:: fs/char_dev.c
 366    :export:
 367
 368 Clock Framework
 369 ===============
 370
 371 The clock framework defines programming interfaces to support software
 372 management of the system clock tree. This framework is widely used with
 373 System-On-Chip (SOC) platforms to support power management and various
 374 devices which may need custom clock rates. Note that these "clocks"
 375 don't relate to timekeeping or real time clocks (RTCs), each of which
 376 have separate frameworks. These :c:type:`struct clk <clk>`
 377 instances may be used to manage for example a 96 MHz signal that is used
 378 to shift bits into and out of peripherals or busses, or otherwise
 379 trigger synchronous state machine transitions in system hardware.
 380
 381 Power management is supported by explicit software clock gating: unused
 382 clocks are disabled, so the system doesn't waste power changing the
 383 state of transistors that aren't in active use. On some systems this may
 384 be backed by hardware clock gating, where clocks are gated without being
 385 disabled in software. Sections of chips that are powered but not clocked
 386 may be able to retain their last state. This low power state is often
 387 called a *retention mode*. This mode still incurs leakage currents,
 388 especially with finer circuit geometries, but for CMOS circuits power is
 389 mostly used by clocked state changes.
 390
 391 Power-aware drivers only enable their clocks when the device they manage
 392 is in active use. Also, system sleep states often differ according to
 393 which clock domains are active: while a "standby" state may allow wakeup
 394 from several active domains, a "mem" (suspend-to-RAM) state may require
 395 a more wholesale shutdown of clocks derived from higher speed PLLs and
 396 oscillators, limiting the number of possible wakeup event sources. A
 397 driver's suspend method may need to be aware of system-specific clock
 398 constraints on the target sleep state.
 399
 400 Some platforms support programmable clock generators. These can be used
 401 by external chips of various kinds, such as other CPUs, multimedia
 402 codecs, and devices with strict requirements for interface clocking.
 403
 404 .. kernel-doc:: include/linux/clk.h
 405    :internal:
 406
 407 Synchronization Primitives
 408 ==========================
 409
 410 Read-Copy Update (RCU)
 411 ----------------------
 412
 413 .. kernel-doc:: include/linux/rcupdate.h
 414
 415 .. kernel-doc:: include/linux/rcupdate_wait.h
 416
 417 .. kernel-doc:: include/linux/rcutree.h
 418
 419 .. kernel-doc:: kernel/rcu/tree.c
 420
 421 .. kernel-doc:: kernel/rcu/tree_plugin.h
 422
 423 .. kernel-doc:: kernel/rcu/tree_exp.h
 424
 425 .. kernel-doc:: kernel/rcu/update.c
 426
 427 .. kernel-doc:: include/linux/srcu.h
 428
 429 .. kernel-doc:: kernel/rcu/srcutree.c
 430
 431 .. kernel-doc:: include/linux/rculist_bl.h
 432
 433 .. kernel-doc:: include/linux/rculist.h
 434
 435 .. kernel-doc:: include/linux/rculist_nulls.h
 436
 437 .. kernel-doc:: include/linux/rcu_sync.h
 438
 439 .. kernel-doc:: kernel/rcu/sync.c
 440