xref: /illumos-gate/usr/src/uts/common/mapfiles/README (revision 3e3ca1ce)
2# This file and its contents are supplied under the terms of the
3# Common Development and Distribution License ("CDDL"), version 1.0.
4# You may only use this file in accordance with the terms of version
5# 1.0 of the CDDL.
7# A full copy of the text of the CDDL should have accompanied this
8# source.  A copy of the CDDL is also available via the Internet at
9# http://www.illumos.org/license/CDDL.
13# Copyright 2016 Joyent, Inc.
16Kernel Module Build Time Symbol Verification
19Historically, kernel modules have all been built as relocatable objects.
20They are not dynamic objects and dependency information is always noted
21in individual makefiles. Along with this, there has never been any
22verification of the symbols that are being used. This means that it's
23possible for a kernel module author to refer to a symbol that doesn't
24exist and not find out until they try to install the module.
26To help find these problems at build time, we provide an opt-in system
27for modules to use, leveraging the link-editor's '-z defs' option.  This
28option ensures that there are no unknown definitons at link-edit time.
29To supply these definitions we supply a series of mapfiles in this
32These mapfiles are not the traditional versioning mapfiles like those in
33usr/src/lib/README.mapfiles! Please review the following differences
36* These mapfiles do not declare any versions!
37* These mapfiles do not use the 'SYMBOL_VERSION' directive, instead they
38  use the 'SYMBOL_SCOPE' directive.
39* These mapfiles do not hide symbols! Library mapfiles always have
40  something to catch all local symbols. That should *never* be used
41  here. These mapfiles should not affect visibility.
42* All symbols in these mapfiles should be marked 'EXTERN' to indicate
43  that they are not provided by the kernel module but by another.
44* These mapfiles do not declare what is or isn't a public interface,
45  though they are often grouped around interfaces, to make it easier for
46  a driver author to get this right.
48Mapfiles are organized based on kernel module. For example the GLDv3
49device driver interface is provided by the 'mac' module and thus is
50found in the file 'mac.mapfile'. The DDI is currently in the 'ddi'
51mapfile. Functions that are found in genunix and unix that aren't in
52the DDI should not be put in that mapfile.
54Note, the existing files may not be complete. These are intended to only
55have the public interfaces provided by modules and thus should not
56include every symbol in them. As the need arises, add new symbols or
57modules as appropriate.
59To opt a module into this, first declare a series of MAPFILES that they
60should check against in the module. This should be a series of one or
61more files, for example:
63MAPFILES += ddi mac
65Next, you should add an include of Makefile.mapfile right before you
66include Makefile.targ. You can do this with the following line:
68include $(UTSBASE)/Makefile.mapfile