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