Intro man page on OpenIndiana

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

Intro(9E)		      Driver Entry Points		     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
			   available).	This  is  used	in  open,
			   ioctl, read, write, and strategy.
       ───────────────────────────────────────────────────────────
       EFAULT		   An  invalid address has been passed as
			   an argument; memory addressing  error.
			   This	 is  used  in open, close, ioctl,
			   read, write, and strategy.
       ───────────────────────────────────────────────────────────
       EINTR		   Sleep interrupted by signal.	 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 con‐
			   dition was detected in a device status
			   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 subdevice that does not exist  (one
			   that	 is  not  configured); an attempt
			   was made to	perform	 an  invalid  I/O
			   operation;  an  incorrect minor number
			   was specified. This is used	in  open,
			   close,  ioctl, read, write, and strat‐
			   egy.
       ───────────────────────────────────────────────────────────
       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 writ‐
			   ing 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)

SunOS 5.11			  15 May 2001			     Intro(9E)
[top]

List of man pages available for OpenIndiana

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