Part II Transition Information for Developers

Changes in the C language and its related tools are among the most obvious differences between the SunOS release 4 and the Solaris 7 operating environments. These changes affect all developers to varying degrees. The operating system kernel and its interfaces have also changed significantly since the SunOS release 4 software. This part of the guide describes these differences, points out similarities between releases, provides information you need to port existing software, or to write new software for the Solaris 7 operating environment, and explains the implications for your programming environment.

Chapter 15 Compilers, Linkers, and Debuggers

This chapter discusses the changes to compilers, linkers, and debuggers.

• "Compilers"

• "Linkers"

• "Debuggers"

Compilers

The single most significant change for developers migrating from the SunOS release 4 to the Solaris 7 operating environment is the unbundling of the C compiler. One of the factors that allowed the compiler to be unbunddled is the dynamic kernel. The compiler is no long required to reconfigure the kernel as devices are now automatically loaded by the kernel as needed.

The Sun WorkShop^TM provides an ANSI C compatible compiler along with an extensive debugging and program development environment. This compiler produces executables in executable and linking format (ELF), the native object format of Solaris 7. lint and the lint libraries are also provided as part of the Sun WorkShop.

For details on the Sun WorkShop, see http://www.sun.com

The guide Making the Transition to ANSI C describes the differences between the C language implemented in the bundled SunOS 4 C compiler and as implemented by the unbundled Sun WorkShop C compiler and should be consulted when porting source. The guide is a developer product available from http://docs.sun.com Sun WorkShop Compiler C 4.2 AnswerBook Collection.

The Sun WorkShop C Compiler provides a special option flag, -Xs, that warns about language constructs that have differing behavior between K&R C and ANSI C. This is described in Sun WorkShop C User's Guide, which is also a developer product available from http://docs.sun.com in the Sun WorkShop Compiler C 4.2 AnswerBook Collection.

Linkers

There are several changes to the link editor, ld(1), in this release. The most important change is its ability to handle the new ELF native file format.

The recommended method for building libraries and executables is through the compiler driver rather than by invoking the linker directly. The compiler automatically supplies several files needed by the linker.

You cannot mix libraries--32-bit programs must link with 32-bit libraries and 64-bit programs must link with 64-bit libraries. ELF32 objects link with other ELF32 objects and ELF64 objects link with other ELF64 objects.

Link Editor Option Differences

Some options have been renamed in the new linker, some have remained the same, and others are no longer needed. Table 15-1 compares the SunOS release 4 ld command to the Solaris 7 ld command.

The sections following Table 15-1 explain how certain linking tasks are affected by the option differences.

Building Shared Libraries

The procedure for building shared libraries in the Solaris 7 operating environment requires the -G option. In the SunOS release 4 software, the linker infers that a shared library is being built if the -e option is absent. As shared libraries may have entry points, this option can no longer be used.

Building Executables

The -Bdynamic and -Bstatic options are still available, but their behavior is different. These options now refer to library inclusions to the executable rather than to the binding. Executable binding is set exclusively with the new -dy and -dn options in the Solaris 7 software. The -dy option is the default. It is required to create a dynamically linked executable. The -dn option is required to create a statically linked executable.

The -Bdynamic and -Bstatic options apply only when using the -dy option. -Bdynamic tells the link editor to include shared libraries, while -Bstatic tells it to include archive libraries. These options act as a toggle governing subsequent -l arguments until the next -Bdynamic or -Bstatic option is encountered.

The following examples show SunOS release 4 and Solaris 7 commands that can be used to create similar executables.

• sunos4.1% ld -Bstatic test.o -lx

  Uses libx.a and creates a static executable

• sunos5.x% cc -dn test.o -lx

  Uses libx.a and creates a static executable

• sunos4.1% ld -Bdynamic test.o -lx

  Uses libx.so and creates a dynamic executable

• sunos5.x% cc test.o -lx

  Uses libx.so and creates a dynamic executable

• sunos4.1% ld -Bdynamic test.o -Bstatic -lx

  Uses libx.a and creates a dynamic executable

• sunos5.x% cc test.o -Bstatic -lx

  Uses libx.a and creates a dynamic executable

Specifying Library Search Paths

In the SunOS release 4 software, directories specified with the -L option were searched at link time and the information retained for use at execution time. This behavior is now divided between the -L and -R options. The -L option specifies the directories to search at link time; the -R option tells the linker the search paths to be retained for use at run time. See "Search Path Rules", in the next section for more information.

As with the -Bdynamic and -Bstatic options, the position of the -L option has significance; it applies only to the subsequent -l options.

Search Path Rules

The dynamic linker and the runtime linker determine their search paths through a different algorithm from that used by the SunOS release 4 linker.

The examples below compare the search paths for the dynamic linker and the runtime linker for SunOS release 4 and the Solaris 7 operating environment. Notice that in the latter, the search path for the link editor and the runtime linker are affected by the LD_LIBRARY_PATH setting. However, the runtime linker permits programs to find shared libraries without having to set LD_LIBRARY_PATH and makes the loading of shared libraries even more efficient. In Solaris 7, use $ORIGIN instead, since you must build your program with a built-in library path relative to where prog is installed. For example .../package/bin/prog uses .../package/lib/libmine.so.1.

SunOS release 4 linker search paths:

• Link Editor: -L, LD_LIBRARY_PATH, /usr/lib, /usr/local/lib

• Runtime Linker: LD_LIBRARY_PATH, -L, /usr/lib, /usr/local/lib

Solaris 7 linker search paths (with LD_LIBRARY_PATH=dirlist1):

• Link Editor: -L, dirlist1, /usr/ccs/lib, /usr/lib

• Runtime Linker: dirlist1, -R, /usr/lib

Solaris 7 linker search paths (with LD_LIBRARY_PATH=dirlist1,dirlist2):

• Link Editor: dirlist1, -L, dirlist2, /usr/ccs/lib, /usr/lib

• Runtime Linker: dirlist1, dirlist2, -R, /usr/lib

Solaris 7 linker search paths using $ORIGIN

• Runtime Linker: -R, $ORIGIN/../lib

Also, with Solaris 7, LD_LIBRARY_PATH_64 is a 64-bit only version of LD_LIBRARY_PATH.

Version Numbering

The SunOS release 4 software supported both major and minor version numbers on shared libraries. The Solaris 7 operating environment supports only the major version number. For binary compatibility support, major and minor version numbers are recognized on SunOS release 4 shared libraries. These libraries are required to retain the SunOS release 4 major and minor version numbers.

Table 15-2 shows versions of SunOS release 4 and Solaris 7 shared libraries.

In SunOS release 4 system software, when the -l option was specified, the build environment linker searched for a library with both major and minor numbers. For example, if -ldl was specified, the library, libdl.so.1.0 was linked. In the Solaris 7 environment, even though major numbers are still supported, the default behavior of the link editor is to ignore version numbers. Using the previous example, the build environment link editor now searches for libdl.so and a symbolic link points to a specific version file.

The recording of a dependency in a dynamic executable or shared object is, by default, the file name of the associated shared object as it is referenced by the link editor. To provide a more consistent means of specifying dependencies, shared objects can record within themselves the file name by which they should be referenced at runtime. This is specified with the -h option when linking the library file.

Symbolic links have been created for most libraries in this release. You should build any new shared libraries with major numbers, then create a symbolic link to the version of the library that is used most often.

Examples

A new utility, dump(1), makes it easier to debug object files or to check the static and dynamic linking, see "Backing Up and Restoring Files"). The dump -L option displays the information needed by the runtime linker that is contained in the executable. This information is contained in the dynamic section of an ELF file. The RPATH entry displays search paths specified by the -R option to ld.

The following example:

• Builds a shared library, libx.so.1, using libx.o

• Creates a link from libx.so.1 to libx.so

• Shows dump output, including the SONAME field, which stores the information passed with the -h option.

examples% cc -G -o libx.so.1 -h libx.so.1 libx.o

examples% cp libx.so.1 /mylibs
examples% ln -s /mylibs/libx.so.1 /mylibs/libx.so
examples% dump -Lv libx.so.1

libx.so.1:

  **** DYNAMIC SECTION INFORMATION ****
.dynamic :
[INDEX] Tag      Value
[1]     INIT     0x3b8
[2]     FINI     0x3f4
[3]     SONAME   libx.so.1
[4]     HASH     0x94
[5]     STRTAB   0x33c
[6]     SYMTAB   0x14c
[7]     STRSZ    0x62
[8]     SYMENT   0x10
[9]     PLTGOT   0x10404
[10]    PLTSZ    0xc
[11]    PLTREL   0x7
[12]    JMPREL   0x3ac
[13]    RELA     0x3a0
[14]    RELASZ   0x18
[15]    RELAENT  0xc

If a library needs other dynamic libraries, they should be specified along with an RPATH, as the next example shows.

The next example compiles prog.c, dynamically linking libx.so (as built in the previous example), and specifies that the binary retain the current directory information for execution. This example shows the output of dump from the compiled program, prog.c. Here, the information stored in the SONAME field of the previous example is shown as NEEDED by prog. When prog is run, it will use libx.so.1 even if libx.so is linked to a different version.

examples% cc -o prog prog.c -L/mylibs -R/mylibs -lx
example% dump -Lv prog

prog:

  **** DYNAMIC SECTION INFORMATION ****
.dynamic :
[INDEX]   Tag   Value
[1]  NEEDED   libx.so.1
[2]  NEEDED   libc.so.1
[3]  INIT     0x1b1ac
[4]  FINI     0x1b248
[5]  RPATH    /mylibs
[6]  HASH     0x100e8
[7]  STRTAB   0x17f90
[8]  SYMTAB   0x12be0
[9]  STRSZ    0x31e1
[10] SYMENT   0x10
[11] DEBUG    0x0
[12] PLTGOT   0x2b25c
[13] PLTSZ    0x30
[14] PLTREL   0x7
[15] JMPREL   0x1b180
[16] RELA     0x1b174
[17] RELASZ   0x3c
[18] RELAENT  0xc

Debuggers

This section describes changes to debugging tools.

dbx and dbxtool

The dbx and dbxtool tools are no longer available with default system software. Enhanced versions of these tools are available as part of Sun WorkShop, an unbundled product.

adb and kadb

The adb and kadb tools are available in the Solaris 7 operating environment. They offer the same capabilities as the SunOS release 4 tools. kadb has been enhanced to recognize multiple processors. The processor ID is displayed in the kadb prompt. In the following examples, it is 0.

To make kernel debugging under the Solaris 7 operating environment easier:

• Enable savecore (uncomment the savecore lines in the /etc/init.d/sysetup file)

• Boot under kadb (type $c when the system crashes)

• Use adb and crash

Also, adb has been enhanced for 64-bit:

• Extend format letters for ?, /, = modifiers. K used for printing long or pointer in hexadecimal (displays 4 bytes for 32 bit programs and 8 bytes for 64-bit programs).

• Path for 64-bit SPARC macros: /usr/lib/adb/sparcv9 and /usr/platform/platformname/lib/adb/sparcv9.

kadb Macros

The kadb macros described below are particularly useful with the new multithreaded kernel.

thread displays the current thread. The current thread pointer is in SPARC global register g7.

kadb[0]: <g7$<thread

threadlist shows the stack traces of all the kernel threads in the system. This can be a long list.

kadb[0]: $<threadlist

mutex shows you the address of the owning thread. The following example uses the global unsafe driver mutex.

kadb[0]: unsafe_driver$<mutex

kadb[0]: moddebug/W 0x80000000

moddebug

moddebug enables you to watch module loading. See the end of <sys/modctl.h> for legal values for moddebug for debugging purposes only.

Debugging a Live Kernel

Use the following command to debug a live kernel.

# adb -k /dev/ksyms /dev/mem

/dev/ksyms is a pseudo device that contains the complete name list of the running kernel.

truss Command

truss is a new utility, provided to trace system calls performed, signals received, and machine faults incurred. It also has an option that enables entry and exit tracing of user-level function calls executed by the traced process. truss offers several significant improvements over the SunOS release 4 trace(1) command, including the ability to follow forked processes and to deal with multithreaded processes.

Also, the truss utility traces the system calls, signals, and machine faults of a process. It has been enhanced with a new option to enable entry and exit tracing of user-level function calls executed by the traced process.

The following example shows a summary of traced calls for the date command. With the -c option, truss does not display the trace line by line. Instead, it counts the system calls, signals, and faults, and displays a summary.

example% truss -c date
Fri Sep 18 14:31:30 PDT 1992
syscall      seconds   calls  errors
_exit            .00       1
read             .00       7
write            .00       1
open             .03      12
close            .00      12
time             .00       1
brk              .01       4
lseek            .00       1
fstat            .00       4
ioctl            .00       1
execve           .00       1
mmap             .01      17
munmap           .00       8
                ----     ---    ---
sys totals:      .05      70      0
usr time:        .03
elapsed:         .28

See the truss(1) man page for complete details on all truss options. There are a number of other Solaris 7 debugging tools based on proc(4) such as pmap(1).

Chapter 16 Tools and Resources

This chapter discusses the changes to tools and resources for the development environment.

• "ioctl() Requests"

• "ptrace() Request Values"

• "Libraries"

• "Using make"

• "Using SCCS"

• "Determining Application Compatibility"

• "Packaging Applications"

• "Toolkits"

• "Finding SunOS release 4 Tools"

ioctl() Requests

All ioctls related to dkio(7I), filio, mtio(7I), sockio(7I), streamio(7I), termio(7I), and termios(7I) are supported in this release.

A few incompatibilities exist between the SunOS release 4 termios structure and Solaris 7 termios structure. For example, the Solaris 7 termios structure does not include a c_line field.

The following ioctls requests, defined in <sys/ttold.h>, are not implemented in this release.

• TIOCMODG

• OTTYDISC

• TABLDISC

• KBLDISC

• TIOCMIDS

• TIOCSETX

• NETLDISC

• NTABLDISC

• TIOCGETX

• NTTYDISC

• MOUSELDISC

The following ttycom ioctl requests are not in the Solaris 7 operating environment.

• TIOCSCTTY

• TIOCNOTTY

• TIOCISPACE

• TIOCPKT

• TIOCGETPGRP

• TIOCISIZE

• TIOCUCNTL

• TIOCOUTQ

• TIOCTCNTL

• TIOCCONS

Table 16-1 shows the ioctls supported in the Solaris 7 operating environment.

ptrace() Request Values

The ptrace() facility is implemented on top of /proc. New applications should use proc(4) directly.

The ptrace() routine in Solaris 7 software is present solely to support applications running in BCP mode. It uses integers 1 - 9 as request values, while the SunOS release 4 routine defines request values as symbolic constants in <sys/ptrace.h>. The following SunOS release 4 request symbolic constants are compatible with Solaris 7 software.

• PTRACE_TRACEME

• PTRACE_PEEKTEXT

• PTRACE_PEEKDATA

• PTRACE_PEEKUSER

• PTRACE_POKETEXT

• PTRACE_POKEDATA

• PTRACE_POKEUSER

• PTRACE_CONT

• PTRACE_KILL

• PTRACE_SINGLESTEP

The SunOS release 4 PTRACE_CONT addr argument specifies where the stopped process should resume execution, unless addr = 1, in which case execution resumes from where the process had stopped. The equivalent Solaris 7 request 7 requires that addr always be equal to 1 and that execution always resumes from where the process stopped. Also, the Solaris 7 request 7 cancels all pending signals before the process resumes execution except those specified by data. The SunOS release 4 PTRACE_CONT does not cancel all pending signals.

Table 16-2 shows SunOS release 4 valid requests that are not supported by the Solaris 7 ptrace() routine.

Libraries

This release is compliant with the System V Interface Definition, Third Edition (SVID 3). Programs written with the SunOS release 4.1 System V libraries are easy to port to this release. Programs using the SunOS release 4 BSD C library require more effort.

Reorganized Libraries

Several functions and groups of functions were moved into different libraries. This can cause references to these functions to be flagged as undefined when compiling a SunOS release 4 application in the Solaris 7 environment.

After a compile, check the man page of any functions flagged as undefined. The synopsis lists both the -l linker option and any include files that you need to resolve the symbol.

Shared Libraries

Shared libraries do not currently support minor version numbers.

Files for shared initialized data (.sa) are no longer required; no .sa files are provided with the Solaris 7 software.

Resource Limits

In previous releases, static table allocations were used for resources such as file descriptors and active processes. These resources are now dynamically allocated, so they are limited by the physical memory available. Table 16-3 shows the resource limits.

Any shared objects that need the networking libraries must be dynamically linked. The networking libraries require libdl.so.1. An archive library is not available.

Table 16-4 shows SunOS release 4 and Solaris 7 libraries and their locations.

Using make

There are two make utilities available in the Solaris 7 operating environment. The default version, /usr/ccs/bin/make, is identical to the SunOS release 4 make command. The SVR4 version is available in /usr/ccs/lib/svr4-make.

Using the default version, your Makefiles will not need changes. However, some of the commands used in your Makefiles may have changed. For example, install(1), commonly used in Makefiles, could produce unexpected results because of changes to the options, as shown in the following examples.

• In a SunOS release 4 Makefile - install:

  install -o bin -g bin -m 444 target.c /usr/bin/target

• In a SunOS release 5.7 Makefile - install:

  install -u bin -g bin -m 444 target.c /usr/bin/target

The version of install(1B) in /usr/ueb is compatible with the SunOS release 4 version.

Check the compatibility tables in Appendix A, Commands Reference Table, for information about individual interfaces.

Using SCCS

The Solaris 7 operating environment source code control system (SCCS) is slightly different from the SunOS release 4 version. The same set of commands and subcommands are supported in both environments. SCCS directories and s.files used on SunOS release 4 systems work equally well on Solaris 7 systems.

In the SunOS release 4 software, the SCCS commands were located in the /usr/sccs directory. These commands are located with the other programming tools in /usr/ccs/bin in the Solaris 7 operating environment.

One difference between SunOS release 4 and Solaris 7 utilities is the handling of unreadable s.files. The SunOS release 4 commands print an error and continue when they encounter an unreadable s.file. The Solaris 7 commands silently ignore the error.

Determining Application Compatibility

Although the Binary Compatibility Package is not provided as a development environment, it requires sound programming practices that can improve binary compatibility with future releases.

The Binary Compatibility Package provides compatibility for dynamically linked and statically linked applications, as well as hybrids that are partially static and partially dynamically linked.

The Binary Compatibility Package works with well-behaved user applications. Well-behaved applications do not:

• Trap directly to the kernel

• Write directly to any system files

• Use /dev/kmem, /dev/mem, or libkvm

• Use unpublished SunOS interfaces

• Rely on customer-supplied drivers

Applications that are not well-behaved can produce unpredictable results.

Information on using the Binary Compatibility Package is available in Binary Compatibility Guide.

Packaging Applications

The Solaris 7 operating environment is bundled in units called packages. These packages contain all the files and information you need to add or remove software from your system.

A package consists of the following components:

• pkginfo file - This is an ASCII file that sets characteristics of the package. It consists of a list of macro=value pairs that describe the package and set control parameters for its installation. See the pkginfo(4) man page for more information.

• prototype file - This is an ASCII file that defines the contents of the package. It contains one entry for each deliverable object (for example, files, directories, and links). It also contains installation entries for package information files-such as pkginfo, depend, and copyright-and scripts. See the prototype(4) man page for more information.

• copyright file -This is an ASCII file that provides a copyright notice for the package. Its contents (including comment lines) are displayed during package installation. See the copyright(4) man page for more information.

• Package contents - The contents of the package.

• Scripts - Scripts can be used to control installation or removal of a package, to request input from the user, or to perform an action on all objects of a particular class. Scripts must be executable by the Bourne shell.

Add-on application software should be packaged so it can be installed on a Solaris 7 system from diskette, tape, or CD-ROM. Application Packaging Developer's Guide provides guidelines for building your packages.

Packaging Utilities

Several utilities are provided to create and manipulate packages. Table 16-5 lists commands that are useful for creating packages.

Table 16-6 lists commands that are useful for adding and removing packages.

Table 16-7 lists commands that provide information about packages.

Toolkits

This section discusses OPEN LOOK Intrinsics ToolKit (OLIT) and XView^TM.

OLIT

The OPEN LOOK Intrinsics Toolkit (OLIT) is based on Xt Intrinsics. It provides a set of functions common to many widget sets to create, employ, and destroy user interface components for an X environment.

XView

The XView Window Toolkit provides an implementation of the OPEN LOOK Graphical User Interface (GUI) specification. It provides a migration path for SunView^TM applications.

XView uses variable-length attribute-value lists based on varargs to specify objects to be created, such as windows, menus, and scrollbars. This eliminates most of the boilerplate software usually found in procedural interfaces, since the usual behavior is already defined.

Finding SunOS release 4 Tools

Most SunOS release 4 programming tools are still available and stil provide the same capabilities, but many are in new locations. All bundled programming tools are now in the /usr/ccs/bin library except cpp, which is now in the /usr/ccs/lib library. Table 16-8 shows the programming tools and their SunOS release 4 locations.

Table 16-9 lists the new Solaris 7 programming tools and their descriptions.

Table 16-10 lists the SunOS release 4 commands that are unbundled in SunOS release 5.7.

Chapter 17 Networking and Internationalization

This chapter discusses Solaris 7 networking features as they relate to the programming environment, as well as issues concerning the improved internationalization features.

• "Networking"

• "Internationalization"

Networking

The Solaris 7 operating environment includes the following networking features:

• Distributed file system (DFS), which centralizes the file system utilities

• Network information services plus (NIS+) including NFS

• Name service switch file

See NIS+ Transition Guide and NFS Administration Guide for more information on using these services.

NIS, NIS+

The Solaris 7 operating environment supports the network information service (NIS), the SunOS release 4 name service, and the network information services plus (NIS+), an enterprise-naming service of heterogenous distributed systems. See "NIS+" for the nature of NIS+ support available in the Solaris 7 operating environment.

NIS+ provides improved security, a more detailed model for objects in the name space, and faster updates than NIS.

The NIS+ programmer interfaces are documented in section 3N of the man Pages(3): Library Routines.

nsswitch.conf File

The nsswitch.conf file simplifies name service administration. Applications can use this file to select a name service. This information no longer needs to be hard-coded into the service. See the nsswitch.conf(4) man page for more information on the format of this file.

Network Interface Tap

The Network Interface Tap (NIT) provided in SunOS release 4 is no longer required. Now Ethernet drivers are real STREAMS drivers that can be opened and communicated with directly.

See pfmod(7M), bufmod(7M), and dlpi(7P)

The Solaris 7 Ethernet drivers and other data link drivers support the connectionless Data Link Provider Interface (DLPI) Version 2 specification.

Sockets

Sockets are supported in the Solaris 7 operating environment. Unlike the SunOS release 4 software, sockets are no longer implemented completely in the kernel. They are now in a library, libsocket, implemented on STREAMS.

Internationalization

Most of the changes in the Solaris 7 operating environment improve on previous internationalization features. For complete information on internationalization support, see Developer's Guide to Internationalization.

Application developers concerned with internationalizing their programs should follow these guidelines:

• Call setlocale(3C) to set up the LANG environment variable

• Use standard code sets and follow 8-bit boundaries

• Use strftime(3C) to print the date and time

• Replace strcmp(3) with strcoll(3C) for user-visible collation

• Call gettext(3C) or catget(3C) to retrieve translated strings from locale-specific message catalogs

Character Support

The Solaris 7 operating environment supports extended UNIX code (EUC), VTF8, PCK, and B165. This allows multibyte and multiple code sets on one system.

The SunOS release 4 software supported single-byte representation of non-ASCII characters. The Solaris 7 operating environment supports multibyte representation. This support is needed for Asian language character sets, which contain thousands of characters.

The multibyte functions are included in libc and provide the following features:

• Multibyte-to-wide character conversions

• Wide character standard I/O

• Wide character classification

• Wide character formatting

The Solaris 7 operating environment supports multibyte file names; however, login and machine names should be restricted to ASCII characters.

Message Catalogs

SunOS release 4 support for message catalogs is enhanced in the Solaris 7 operating environment to enable the creation of message catalogs using multibyte characters.

Using message catalogs, an application can display messages at run-time in the native language in which an application was run. These message catalogs must first be created for the native language specified by the language locale.

Locale Database

The SunOS release 5.7 locale database (/usr/lib/locale/locale) is completely different from the locale database of SunOS release 5. This is transparent to the user, however.

Commands

Most of the system commands in the Solaris 7 operating environment have been messaged. Many of these commands can pass through multibyte character representations. The increased number of messaged commands makes localization efforts easier.

The installtxt(1) command has been replaced with msgfmt(1). Use the new xgettext(1) command to extract messages.

Changes to strftime(3C) affect date and time formats. Shell programs that rely on the output format of the date(1) command will have to be updated to handle the new format.

chrtbl(8) and catdef(8) are replaced by localedef(1).

Libraries

The /usr/xpg2lib/libxpg2.a archive library is no longer available. These routines have been included in libc.

Table 17-1 shows the new location of these interfaces.

Programs that use these routines no longer need to pass -lxpg2 to the C compiler although some may need to include libintl.h. (See Table 17-1 for these routines.)

The catgetmsg(3C) routine is no longer available.

The order of locale categories in the string returned by setlocale(3C) differs between the SunOS release 4 and the Solaris 7 software. This string is normally used by a subsequent call to setlocale(3C), and the order should not matter. Applications should not rely on a specific order of locale categories.

Chapter 18 System and Device Configuration

The operating system kernel and its interfaces have changed significantly. Binary compatibility is not provided for SunOS release 4 device drivers. This chapter discusses changes in the Solaris 7 operating environment that affect kernel and system developers.

• "System Configuration"

• "Reconfiguration Boot"

• "Device Naming From a Developer's Perspective"

System Configuration

Changes related to system configuration include the dynamically loaded kernel and kernel layout, the config and boot commands, and the /etc/system file.

Dynamically Loaded Kernel

Unlike previous SunOS releases, the kernel is now dynamically configured. The kernel now consists of a small static core and many dynamically loadable kernel modules. Drivers, file systems, STREAMS modules, and other modules are loaded automatically as needed, either at boot time or at runtime. When these modules are no longer in use, they may be unloaded. Modules are kept in memory until that memory is needed. modinfo(1M) provides information about the modules currently loaded on a system.

The modload(1M) and modunload(1M) commands are still available in this release but they perform differently. They have more limited usage and are no longer sufficient to correctly install a loadable driver onto the system. modunload now includes the capability to unload all unloadable (and not busy) modules. Use modunload as follows.

# modunload -i 0

Kernel Layout

The contents of the kernel, which were formerly in a single file, /vmunix, are now contained in modules in a directory hierarchy. By default, the directory hierarchy is/platform/'uname -i'/kernel, /kernel, and /usr/kernel.

The directory search path for modules can be set by the moddir variable in the /etc/system file (see the system(4) man page). Typically, /platform/'uname -i'/kernel/unix is the first portion of the kernel to be loaded (see the kernel(1M) man page).

config Command

In the SunOS release 4 software, the config command was used to generate system configuration files that enabled /vmunix to be relinked from object files. The need for this command has been removed by the following Solaris 7 features:

• Loadable modules

• The /etc/system file (see the system(4) man page)

• Device tree information from the OpenBoot PROM (OBP)

• The driver.conf files in /kernel/drv and /usr/kernel/drv

/etc/system File

System configuration information is now set in the /etc/system file. This file also modifies the kernel's treatment of loadable modules. The file contains commands of the form:

set parameter=value

For example, in the SunOS release 4 software, MAXUSERS was set using config(8). In the Solaris 7 operating environment, it is set in the /etc/system file with the following line:

set maxusers = number

Commands that affect loadable modules are of the form:

set module:variable=value

Changes made to the /etc/system file only take effect when you reboot your system (see the system(4) man pages).

boot Command

In this release, the following boot programs are available:

• ufsboot - To boot from a disk or a CD

• inetboot - To boot from across the network

  When booting from a disk, the PROM assumes that the primary boot block resides in blocks 1 - 15 of the local disk. Use installboot(1M) to create the boot block.

  # installboot /usr/platform/'uname -i'/lib/fs/ufs/bootblk \ /dev/rdsk/c0t3d0s0

The system firmware loads the primary bootstrap (the boot block) program into memory and runs it. The boot block is a UFS file system reader. It loads the secondary boot program (/platform/'uname -i'/ufsboot) into memory.

ufsboot loads kernel/unix, then /kernel/unix uses ufsboot to load modules from the kernel directory hierarchy until it is able to mount the root file system.

During these operations, the boot block and ufsboot use the drivers provided by the firmware; neither ufsboot nor the boot block contains any driver code. The ufsboot code does not have to change to incorporate a new SBus card with a new disk type since ufsboot uses the SBus card PROM driver.

When booting over the network, the boot program performs as it did for a diskless boot in the SunOS release 4 software. However, the boot program is now called inetboot and the client vfstab file entries are different. See System Administration Guide, Volume I for information on diskless booting.

Summary of Boot Differences

Table 18-1 summarizes the differences in the boot sequence between the SunOS release 4 and the Solaris 7 operating environment.

Reconfiguration Boot

A reconfiguration boot tells the system to probe for all connected devices and build the names for them in /devices and /dev. A reconfiguration boot, performed when adding new hardware to the system, is triggered by booting with the -r option.

ok> boot -r

If another device of an existing type (with the driver already installed) is added, and you forget to do a reconfiguration boot, use the following commands to tell the system to recognize the new device.

# touch /reconfigure
# _INIT_RECONFIG=YES /etc/init.d/drvconfig
# _INIT_RECONFIG=YES /etc/init.d/devlinks

Device Naming From a Developer's Perspective

This section expands on the discussion in "Device Naming Conventions", focusing on aspects of device naming that concern system and kernel developers.

/devices

The /devices tree represents the tree of devices recognized by the kernel. This tree is configured by the drvconfig(1M) program. drvconfig is normally run only when the system is booted with the -r flag (see "Reconfiguration Boot"). drvconfig configures /devices with information about devices (with drivers) that are connected and ready at boot time.

Entries are exported by device drivers calling ddi_create_minor_node(9F) when they have determined that a device exists.

Use the add_drv(1M) command to add a device to the system. If the driver was successfully added, add_drv will also run drvconfig.

/dev

In this release, /dev is managed by utility programs that create symbolic links to the real entries in /devices. The programs are:

• disks(1M)

• tapes(1M)

• ports(1M)

• devlinks(1M)

  You can run a script to create the appropriate links from /dev to /devices. The /dev names have the advantage of being simpler and more familiar, while the /devices names are unique names for the hardware.

Device Driver Naming

Each device in the system is driven by a device driver. Device drivers manage many instances of a device. Devices are named in several ways:

• Physical names

• Logical names

• Instance names

Physical Names

Physical names are stored in /devices. They describe the hardware, and vary with the platform and configuration. For example:

/devices/vme/xdc@6d,ee80/xd@0,0:g

Physical names can be used to identify which piece of hardware is in use. For example, xdc@6d,ee80 refers to the disk controller at address 0xee80 in VME A16, D32 space. See the vme(4) and driver.conf(4) man pages.

Logical Names

Logical names are stored in /dev. They attempt to abstract most of the nature of physical device names that are specific to the platform. Logical names might be appropriate for an xd device, such as:

/dev/dsk/c2d0s6 (controller 2, slave 0, slice 6 (4.x partition "g"))

or an sd device, such as:

/dev/dsk/c0t3d0s0 (controller 0, target 3, lun 0, slice 0 (4.x partition "a"))

The logical name conveys nothing about the type of controller. It does not differentiate between SCSI and IPI; they are both just disks.

Disk Names

Disk names use the SVR4 convention of slice numbers 0-7 instead of the letters a-h used in the SunOS release 4 software.

Disk names also use the SVR4 convention of /dev/dsk/* for block disk devices and /dev/rdsk/* for raw disks. For more information, see System Administration Guide, Volume I.

Instance Names

Instance names refer to the nth device in the system (for example, sd20).

Instance names are occasionally reported in driver error messages. You can determine the binding of an instance name to a physical name by looking at dmesg(1M) output, as in the following example.

sd9 at esp2: target 1 lun 1
sd9 is /sbus@1,f8000000/esp@0,800000/sd@1,0
     <SUN0424 cyl 1151 alt 2 hd 9 sec 80>

Once the instance name has been assigned to a device, it remains bound to that device.

Instance numbers are encoded in a device's minor number. To keep instance numbers consistent across reboots, the system records them in the /etc/path_to_inst file. This file is read only at boot time, and is currently updated by the add_drv(1M) and drvconfig(1M) commands. See the path_to_inst(4) man page for more information.

Chapter 19 Device Drivers and STREAMS

This chapter discusses device driver issues such as changes to device driver interfaces, the devinfo command, porting considerations, STREAMS, and Solaris 7 driver architecture.

• "Device Drivers and STREAMS Device Drivers"

• "Device Driver Commands"

See the following guides for more information on the topics discussed in this chapter:

• STREAMS Programming Guide

• System Interface Guide

• System Administration Guide, Volume I

Device Drivers and STREAMS Device Drivers

Some of the many changes to device drivers in the Solaris 7 operating environment include the new DDI/DKI routines, Solaris SPARC DDI-specific routines, new software properties, and loadable drivers. In addition, many previous device issues have become opaque to the driver including interrupts, DVMA, and memory mapping.

Device Driver Interfaces

In previous SunOS releases, a driver writer had to cope with changes in the device driver interfaces. Usually, there was a porting effort with each release of the operating system. In addition, the interfaces for each platform varied, so device drivers often required separate releases for each platform. Third-party device driver releases often included complex scripts that would reconfigure and rebuild the operating system in order to integrate a device driver. It was costly to support and maintain device drivers.

Unlike previous releases of SunOS systems (SunOS release 4.1.3 software and earlier), the device driver interfaces in the Solaris 7 operating environment are formalized and are referred to as the Solaris 7 SPARC DDI/DKI. The Solaris 7 SPARC DDI/DKI provides binary compatibility of device drivers across all supported platforms and for all future releases of the Solaris 7 operating environment on those platforms.

The term DDI/DKI is derived from the original specification as supplied in the SVR4 release. It stands for device driver interface/driver kernel interface. The interfaces are divided into three groups:

• DDI/DKI

• DKI only

• DDI only

DDI/DKI

The DDI/DKI interfaces were standardized in SVR4, and are generic across all implementations of SVR4, regardless of the platform on which they are running.

DKI

The DKI-only interfaces are generic like the DDI/DKI interfaces and are supported in all SVR4 implementations. However, they are not guaranteed to be supported in future releases of System V.

DDI

The DDI-only interfaces are intended to be architecture-specific; for example, methods to access and control-device and system-specific hardware (that is, I/O registers, DMA services, interrupts, and memory mapping). These interfaces are not guaranteed to work in other SVR4 implementations.

This group of features effectively lowers the cost of driver support and maintenance. These features, combined with the large number of SPARC platforms, are helpful to many new third-party hardware developers.

With this level of binary compatibility, third-party hardware developers can now "shrink-wrap" their DDI-compliant device drivers with their driver hardware. Installing a new driver package can now be entirely automated. The self-configuring kernel removes the necessity for recompiling the kernel to add or remove a driver. Thus, a DDI-compliant device driver for Solaris 7 environments can be treated like any other consumer software product.

In the Solaris 7, DDI/DKI the DDI-only interfaces are generic to all systems that support the Solaris 7 DDI/DKI. Note that the interfaces that make up the common SCSI architecture (SCSA), and the locking interfaces used to make the driver behave correctly in a multithreaded kernel, are also considered DDI-only interfaces in the Solaris 7 operating environment.

SCSA shields device drivers from details specific to the platform relating to host adapter implementations. With SCSA, a SCSI driver can run on all supported platforms.

A device driver that restricts itself to using only interfaces in the categories desribed above is said to be Solaris 7 DDI/DKI compliant. A Solaris 7 DDI/DKI compliant device driver is commonly referred to as a DDI-compliant device driver.

Documentation

The man pages for the driver routines, structures, and support routines that comprise the DDI/DKI can be found in the sections of man Pages(1M): System Administration Commands listed below. See the Intro(9) man page for more information about these sections.

• Section 9E - Driver entry points

• Section 9F - Driver support functions

• Section 9S - Kernel structures

A Device Driver Developers Kit (DDK) is available separately.

devinfo Command

The Solaris 7 devinfo command performs a different function from the SunOS release 4 version. The new prtconf(1M) command provides the information that the SunOS release 4 devinfo command formerly displayed. The following examples show the output of each command.

4.1system% devinfo
Node 'SUNW,Sun 4/50', unit #0 (no driver)
        Node 'packages', unit #0 (no driver)
        Node 'openprom', unit #0 (no driver)
        Node 'zs', unit #0
        Node 'zs', unit #1
        Node 'audio', unit #0
        Node 'eeprom', unit #0 (no driver)
        Node 'counter-timer', unit #0 (no driver)
        Node 'memory-error', unit #0 (no driver)
        Node 'interrupt-enable', unit #0 (no driver)
        Node 'auxiliary-io', unit #0 (no driver)
        Node 'sbus', unit #0
                Node 'dma', unit #0
                Node 'esp', unit #0
                        Node 'sr', unit #0
                        Node 'sd', unit #0
                Node 'le', unit #0
                Node 'cgsix', unit #0
        Node 'memory', unit #0 (no driver)
        Node 'virtual-memory', unit #0 (no driver)
        Node 'fd', unit #0
        Node 'options', unit #0 (no driver)

5.3system% prtconf
System Configuration:  Sun Microsystems  sun4c
Memory size: 32 Megabytes
System Peripherals (Software Nodes):

SUNW,Sun 4_75
    packages (driver not attached)
        disk-label (driver not attached)
        deblocker (driver not attached)
        obp-tftp (driver not attached)
    openprom (driver not attached)
    zs, instance #0
    zs, instance #1
    audio (driver not attached)
    eeprom (driver not attached)
    counter-timer (driver not attached)
    memory-error (driver not attached)
    interrupt-enable (driver not attached)
    auxiliary-io (driver not attached)
    sbus, instance #0
        dma, instance #0
        esp, instance #0
            sd (driver not attached)
            st (driver not attached)
            sd, instance #0
            sd, instance #1 (driver not attached)
            sd, instance #2 (driver not attached)
            sd, instance #3
            sd, instance #4 (driver not attached)
            sd, instance #5 (driver not attached)
            sd, instance #6
        le, instance #0
        cgsix, instance #0
    memory (driver not attached)
    virtual-memory (driver not attached)
    fd (driver not attached)
    options, instance #0
    pseudo, instance #0

Porting Considerations

With the self-configuring kernel, Solaris 7 drivers will look more like SBus drivers than other types. All drivers are loadable, and no kernel configuration is required.

Under the SunOS release 4 software, only one processor could be in the kernel at any one time. This was accomplished by using a master lock around the entire kernel. When a processor wanted to execute kernel code, it would acquire the lock (excluding other processors from running the code protected by the lock) and it would release the lock when it finished.

The Solaris 7 kernel is multithreaded. Instead of one master lock, there are many smaller locks that protect smaller regions of code. For example, there may be a kernel lock that protects access to a particular vnode, and one that protects an inode. Only one processor can be running code dealing with that vnode at a time, but another could be accessing an inode. This allows a greater amount of concurrency.

The multithreaded kernel will have a major impact on how you design the driver. The old model of using splN/splr pairs no longer works (on a uniprocessor or a multiprocessor system). Instead, you have a choice of MT-style locks. The most common of these for drivers will be mutual exclusion locks, mutexes, and condition variables (which are an approximate equivalent of sleep()/wakeup() synchronization).

The SpIN/pplr pair does block interrupts, but the effect is useless in protecting data structures in a multiprocessor environment.

The old notion that you owned the processor until you explicitly called sleep() is no longer true. Because of kernel pre-emption, the CPU is switched from thread to thread so you must use the appropriate MT lock primitives to guard against concurrent access to device registers, shared data structures, and the like.

A large percentage of the driver code for simple device drivers, which consist primarily of calls to kernel interface routines, will change, but in straightforward ways. For complex device drivers (such as a SCSI driver) which contain large amounts of device-specific handling code, only a small percentage of the driver--the driver interfaces--changes. This driver interface can be a kernel-to-driver interface, a driver-to-kernel interface, or a driver-to-driver interface.

Before you determine how you will support a driver in the Solaris 7 operating environment, refamiliarize yourself with how the driver works. Determine what the SunOS release 4 driver did (not the specific implementation, but general behavior). What interfaces did it export? What ioctl()s did it provide? How did the hardware work and what peculiarities of the hardware did the driver support? Did the driver support multiple open() calls?

The following changes affect drivers and should be considered:

• The entry points to drivers are very different

• ANSI C requirements:

  • volatile keyword

  • const keyword

  • Function prototype declarations

• Relocated or renamed header files (most, if not all, system header files are now in /usr/include/sys)

• Most structures have become opaque or are no longer needed. For example:

  • struct user

  • struct proc

  • struct dev_info

STREAMS

Some areas of change for STREAMS modules are transparent I/O controls, automatic pushing of modules on a stream, and new message types.

Transparent ioctl()s

In the SunOS release 4 software, you had to know that a particular driver was a STREAMS driver before making ioctl() requests.

For non-STREAMS drivers, you could do a direct ioctl() request:

ioctl(fd, DRIVER_IOCTL, arg);

For a STREAMS driver, you had to set up a strioctl structure and then use:

ioctl(fd, I_STR, &strioctl);

There was no easy way to determine whether a driver was STREAMS-based. Now, unrecognized ioctls to the stream head are passed on to the driver, eliminating the need to know whether a driver was STREAMS-based.

Message types added in the Solaris 7 software support transparent ioctls. There are now "copy in" and "copy out" messages to inform the STREAM head to transfer user data to and from the kernel.

For more information on writing STREAMS drivers, see the STREAMS Programming Guide.

autopush Command

The SunOS release 4 streamtab structure enabled a driver to specify that certain STREAMS modules be pushed when the device was open().

In the Solaris 7 operating environment, the system administrator and the autopush(1M) command specify when a STREAMS module is pushed. If required, autopush can be run at driver installation.

See STREAMS Programming Guide for more information about pushing STREAMS modules.

Solaris 2.x Driver Architecture

To achieve binary compatibility across all currently supported hardware platforms, the DDI interfaces were carefully designed around architectural abstractions. The underlying abstraction, the device tree, is an extension of the devinfo tree in the original SPARCstation^TM design. Each node in the device tree is described by a device information structure or "dev_info node." The bottom-most nodes in the tree are termed leaf nodes. Most devices (such as disks and tape drives, framebuffers, I/O cards, and network interfaces) are examples of leaf devices that would be associated with leaf nodes. The associated device drivers are called leaf drivers.

The intermediate nodes in the tree are generally associated with buses (for example, SBus, SCSI, VME). These nodes are called nexus nodes and the drivers associated with them are called nexus drivers. Bus nexi are intended to encapsulate the architectural details associated with a particular element.

Currently, the Solaris 7 DDI/DKI supports only the writing of leaf drivers and one type of nexus driver, the SCSI host bus adapter driver.

The device tree structure creates a formal parent-child relationship between nodes. This parent-child relationship is the key to platform architecture independence.

When a leaf driver requires a service that is platform dependent (for example, a DMA mapping), the system transparently converts the request into a call to its parent to provide the service. The service providers are always nexus drivers; each nexus driver can in turn pass the request to its parent in order to provide the service. This approach enables leaf drivers to operate regardless of the platform architecture.

Device Driver Commands

The device driver commands are add_drv, rem_drv, modload, and modunload.

• add_drv(1M) - Informs the system that there is a newly installed device driver.

• rem_drv(1M) - Informs the system that the specified driver module is no longer valid.

• modload(1M) - Loads the specified loadable module into the running system.

• modunload(1M) - Unloads the specified loadable module from the running system.