Intro man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

INTRO(9E)							     INTRO(9E)

NAME
       Intro, intro - overview of device driver interfaces and introduction to
       driver entry points

DESCRIPTION
       This page provides an overview of device driver interfaces and  all  of
       the Section 9 man pages (9E, 9F, 9P, and 9S). This overview is followed
       by an introduction to Section 9E, the driver entry-point routines.

   Overview of Device Driver Interfaces
       Section 9 provides reference information needed to write device drivers
       for the Solaris operating environment. It describes the interfaces pro‐
       vided by the Device Driver Interface and	 the  Driver-Kernel  Interface
       (DDI/DKI).

   Porting
       Software	 is usually considered portable if it can be adapted to run in
       a different environment more cheaply than it can be rewritten. The  new
       environment  may	 include  a different processor, operating system, and
       even the language in which the program is written, if a language trans‐
       lator is available. Likewise the new environment might include multiple
       processors. More often, however, software is  ported  between  environ‐
       ments  that  share an operating system, processor, and source language.
       The source code is modified to accommodate the differences in compilers
       or processors or releases of the operating system.

       In  the past, device drivers did not port easily for one or more of the
       following reasons:

	   o	  To enhance functionality, members had been added  to	kernel
		  data	structures accessed by drivers, or the sizes of exist‐
		  ing members had been redefined.

	   o	  The  calling	or  return  syntax  of	kernel	functions  had
		  changed.

	   o	  Driver  developers  did  not	use  existing kernel functions
		  where available, or relied on undocumented side effects that
		  were not maintained in the next release.

	   o	  Architecture-specific code had been scattered throughout the
		  driver when it could have been isolated.

       Operating systems are periodically reissued to customers as  a  way  to
       improve	performance,  fix bugs, and add new features. This is probably
       the most common	threat	to  compatibility  encountered	by  developers
       responsible for maintaining software. Another common problem is upgrad‐
       ing hardware. As new  hardware  is  developed,  customers  occasionally
       decide to upgrade to faster, more capable computers of the same family.
       Although they  may  run	the  same  operating  system  as  those	 being
       replaced,  architecture-specific	 code  may  prevent  the software from
       porting.

   Scope of Interfaces
       Although application programs have all of  the  porting	problems  men‐
       tioned, developers attempting to port device drivers have special chal‐
       lenges. Before describing the DDI/DKI, it is  necessary	to  understand
       the position of device drivers in operating systems.

       Device  drivers are kernel modules that control data transferred to and
       received from peripheral devices but are developed  independently  from
       the  rest  of  the kernel. If the goal of achieving complete freedom in
       modifying the kernel is to be reconciled with the goal of  binary  com‐
       patibility  with	 existing drivers, the interaction between drivers and
       the kernel must be rigorously  regulated.  This	driver/kernel  service
       interface is the most important of the three distinguishable interfaces
       for a driver, summarized as follows:

	   o	  Driver-Kernel. I/O System calls result in  calls  to	driver
		  entry	 point	routines.   These make up the kernel-to-driver
		  part of the service  interface,  described  in  Section  9E.
		  Drivers  may	call any of the functions described in Section
		  9F.  These are the driver-to-kernel part of the interface.

	   o	  Driver-Hardware. All drivers (except software drivers)  must
		  include  code	 for  interrupt handling, and may also perform
		  direct memory access (DMA). These  and  other	 hardware-spe‐
		  cific interactions make up the driver/hardware interface.

	   o	  Driver-Boot/Configuration  Software. The interaction between
		  the driver and the boot and configuration  software  is  the
		  third interface affecting drivers.

   Scope of the DDI/DKI
       The primary goal of the DDI/DKI is to facilitate both source and binary
       portability across successive releases of the operating	systems	 on  a
       particular  machine. In addition, it promotes source portability across
       implementations of UNIX on different  machines,	and  applies  only  to
       implementations	based  on  System V Release 4. The DDI/DKI consists of
       several sections:

	   o	  DDI/DKI Architecture Independent - These interfaces are sup‐
		  ported on all implementations of System V Release 4.

	   o	  DKI-only  - These interfaces are part of System V Release 4,
		  and may not be supported in future  releases	of  System  V.
		  There	 are only two interfaces in this class, segmap(9E) and
		  hat_getkpfnum(9F)

	   o	  Solaris DDI - These interfaces specific to Solaris.

	   o	  Solaris SPARC specific DDI - These interfaces	 are  specific
		  to  the  SPARC  processor, and may not be available on other
		  processors supported by Solaris.

	   o	  Solaris x86 specific DDI - These interfaces are specific  to
		  the x86 processor, and may not be available on other proces‐
		  sors supported by Solaris.

       To achieve the goal of source and binary compatibility, the  functions,
       routines,  and structures specified in the DDI/DKI must be used accord‐
       ing to these rules.

	   o	  Drivers cannot access system state structures (for  example,
		  u and sysinfo) directly.

	   o	  For  structures  external to the driver that may be accessed
		  directly, only the utility functions provided in Section  9F
		  should  be  used.  More generally, these functions should be
		  used wherever possible.

	   o	  The headers <sys/ddi.h> and <sys/sunddi.h> must be the  last
		  header files included by the driver.

   Audience
       Section	9  is for software engineers responsible for creating, modify‐
       ing, or maintaining drivers that	 run  on  this	operating  system  and
       beyond.	It  assumes  that the reader is familiar with system internals
       and the C programming language.

   PCMCIA Standard
       The PC Card 95 Standard is listed under the SEE ALSO  heading  in  some
       Section	9  reference  pages. This refers to documentation published by
       the Personal Computer Memory Card  International	 Association  (PCMCIA)
       and the Japan Electronic Industry Development Association (JEIDA).

   How to Use Section 9
       Section 9 is divided into the following subsections:

       9E
	      Driver  Entry  Points  - contains reference pages for all driver
	      entry point routines.

       9F
	      Kernel Functions - contains reference pages for all driver  sup‐
	      port routines.

       9P
	      Driver  Properties - contains reference pages for driver proper‐
	      ties.

       9S
	      Data Structures - contains reference  pages  for	driver-related
	      structures.

   Compatibility Note
       Sun Microsystem's implementation of the DDI/DKI was designed to provide
       binary compatibility for third-party device  drivers  across  currently
       supported  hardware  platforms  across  minor releases of the operating
       system. However, unforeseen technical issues may force changes  to  the
       binary  interface of the DDI/DKI. We cannot therefore promise or in any
       way assure that DDI/DKI-compliant device drivers will continue to oper‐
       ate correctly on future releases.

   Introduction to Section 9E
       Section	9E  describes the entry-point routines a developer can include
       in a device driver. These are called entry-point because	 they  provide
       the  calling  and return syntax from the kernel into the driver. Entry-
       points are called, for instance, in response to system calls, when  the
       driver is loaded, or in response to STREAMS events.

       Kernel functions usable by the driver are described in section 9F.

       In this section, reference pages contain the following headings:

	   o	  NAME describes the routine's purpose.

	   o	  SYNOPSIS summarizes the routine's calling and return syntax.

	   o	  INTERFACE  LEVEL describes any architecture dependencies. It
		  also indicates  whether  the	use  of	 the  entry  point  is
		  required, optional, or discouraged.

	   o	  ARGUMENTS describes each of the routine's arguments.

	   o	  DESCRIPTION provides general information about the routine.

	   o	  RETURN VALUES describes each of the routine's return values.

	   o	  SEE ALSO gives sources for further information.

   Overview of Driver Entry-Point Routines and Naming Conventions
       By  convention,	a  prefix string is added to the driver routine names.
       For a driver with the prefix prefix, the driver code may	 contain  rou‐
       tines  named  prefixopen,  prefixclose, prefixread, prefixwrite, and so
       forth. All global variables associated with the driver should also  use
       the same prefix.

       All routines and data should be declared as static.

       Every  driver  MUST  include  <sys/ddi.h>  and  <sys/sunddi.h>, in that
       order, and after all other include files.

       The  following  table  summarizes  the  STREAMS	driver	entry	points
       described in this section.

       Routine	  Type
       ──────────────────
       put	 DDI/DKI
       srv	 DDI/DKI

       The  following  table  summarizes  the driver entry points described in
       this section.

	    Routine	      Type
       ────────────────────────────────
       _fini		   Solaris DDI
       _info		   Solaris DDI
       _init		   Solaris DDI
       aread		   Solaris DDI
       attach		   Solaris DDI
       awrite		   Solaris DDI
       chpoll		   DDI/DKI
       close		   DDI/DKI
       detach		   Solaris DDI
       devmap		   Solaris DDI
       devmap_access	   Solaris DDI
       devmap_contextmgt   Solaris DDI
       devmap_dup	   Solaris DDI
       devmap_map	   Solaris DDI
       devmap_unmap	   Solaris DDI
       dump		   Solaris DDI
       getinfo		   Solaris DDI
       identify		   Solaris DDI
       ioctl		   DDI/DKI
       ks_update	   Solaris DDI
       mapdev_access	   Solaris DDI
       mapdev_dup	   Solaris DDI
       mapdev_free	   Solaris DDI
       mmap		   DKI only

       open		   DDI/DKI
       power		   Solaris DDI
       print		   DDI/DKI
       probe		   Solaris DDI
       prop_op		   Solaris DDI
       read		   DDI/DKI
       segmap		   DKI only
       strategy		   DDI/DKI
       tran_abort	   Solaris DDI
       tran_destroy_pkt	   Solaris DDI
       tran_dmafree	   Solaris DDI
       tran_getcap	   Solaris DDI
       tran_init_pkt	   Solaris DDI
       tran_reset	   Solaris DDI
       tran_reset_notify   Solaris DDI
       tran_setcap	   Solaris DDI
       tran_start	   Solaris DDI
       tran_sync_pkt	   Solaris DDI
       tran_tgt_free	   Solaris DDI
       tran_tgt_init	   Solaris DDI
       tran_tgt_probe	   Solaris DDI
       write		   DDI/DKI

       The following table lists the error codes returned by a driver  routine
       when  it encounters an error. The error values are listed in alphabetic
       order  and  are	defined	 in  sys/errno.h.  In  the  driver   open(9E),
       close(9E),  ioctl(9E),  read(9E),  and  write(9E)  routines, errors are
       passed back to the user by calling bioerror(9F) to set b_flags  to  the
       proper  error  code.  In	 the  driver  strategy(9E) routine, errors are
       passed back to the user by setting the b_error member  of  the  buf(9S)
       structure  to the error code. For STREAMS ioctl routines, errors should
       be sent upstream in an M_IOCNAK message. For STREAMS read() and write()
       routines,  errors  should  be  sent upstream in an M_ERROR message. The
       driver print routine should not return an error code because the	 func‐
       tion  that  it  calls,  cmn_err(9F),  is	 declared as void (no error is
       returned).

       Error Value	 Error Description
       ─────────────────────────────────────────
       EAGAIN	     Kernel resources, such  as
		     the buf structure or cache
		     memory, are not  available
		     at	 this  time (device may
		     be	 busy,	or  the	 system
		     resource	is  not	 avail‐
		     able).  This  is  used  in
		     open,  ioctl, read, write,
		     and strategy.
       ─────────────────────────────────────────
       EFAULT	     An	 invalid  address   has
		     been  passed  as  an argu‐
		     ment;  memory   addressing
		     error.  This  is  used  in
		     open, close, ioctl,  read,
		     write, and strategy.
       ─────────────────────────────────────────
       EINTR	     Sleep  interrupted by sig‐
		     nal. This is used in open,
		     close, ioctl, read, write,
		     and strategy.
       ─────────────────────────────────────────

       EINVAL	     An	 invalid  argument  was
		     passed   to  the  routine.
		     This  is  used  in	  open,
		     ioctl,  read,  write,  and
		     strategy.
       ─────────────────────────────────────────
       EIO	     A device  error  occurred;
		     an	  error	 condition  was
		     detected in a device  sta‐
		     tus   register   (the  I/O
		     request was valid, but  an
		     error   occurred	on  the
		     device). This is  used  in
		     open,  close, ioctl, read,
		     write, and strategy.
       ─────────────────────────────────────────
       ENXIO	     An	 attempt  was  made  to
		     access  a device or subde‐
		     vice that does  not  exist
		     (one  that	 is not config‐
		     ured); an attempt was made
		     to	 perform an invalid I/O
		     operation;	 an   incorrect
		     minor  number  was	 speci‐
		     fied.  This  is  used   in
		     open,  close, ioctl, read,
		     write, and strategy.
       ─────────────────────────────────────────
       EPERM	     A	process	 attempting  an
		     operation	 did  not  have
		     required permission.  This
		     is	 used  in  open, ioctl,
		     read, write, and strategy.
       ─────────────────────────────────────────
       EROFS	     An	 attempt  was  made  to
		     open  for	writing a read-
		     only device. This is  used
		     in open.

       The  table  below  cross references error values to the driver routines
       from which the error values can be returned.

       ┌───────┬────────┬────────┬──────────────────────────┐
       │ open  │ close	│ ioctl	 │ read, write and strategy │
       ├───────┼────────┼────────┼──────────────────────────┤
       │EAGAIN │ EFAULT │ EAGAIN │ EAGAIN		    │
       │EFAULT │ EINTR	│ EFAULT │ EFAULT		    │
       │EINTR  │ EIO	│ EINTR	 │ EINTR		    │
       │EINVAL │ ENXIO	│ EINVAL │ EINVAL		    │
       │EIO    │	│ EIO	 │ EIO			    │
       │ENXIO  │	│ ENXIO	 │ ENXIO		    │
       │EPERM  │	│ EPERM	 │			    │
       │EROFS  │	│	 │			    │
       └───────┴────────┴────────┴──────────────────────────┘

SEE ALSO
       Intro(9F), Intro(9S)

				 May 15, 2001			     INTRO(9E)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net