Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
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	multi-
       ple processors. More often, however, software is	ported	between	 envi-
       ronments	 that  share  an  operating system, processor, and source lan-
       guage. 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 existing 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-specific interac-
	    tions 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	inter-
	    face 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 supported
	    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 sup-
	    ported by Solaris.

	 o  Solaris  x86  specific  DDI	- These	interfaces are specific	to the
	    x86	processor, and may not be available on other  processors  sup-
	    ported 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
		support	routines.

       9P	Driver Properties - contains reference pages for driver	 prop-
		erties.

       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)

List OF	FUNCTIONS
       Name		       Description

       _fini(9E)	       loadable	module configuration entry points

       _info(9E)	       See _fini(9E)

       _init(9E)	       See _fini(9E)

       aread(9E)	       asynchronous read from a	device

       attach(9E)	       Attach a	device to the system, or resume	it

       awrite(9E)	       asynchronous write to a device

       chpoll(9E)	       poll  entry  point  for a non-STREAMS character
			       driver

       close(9E)	       relinquish access to a device

       csx_event_handler(9E)   PC Card driver event handler

       detach(9E)	       detach or suspend a device

       devmap(9E)	       validate	and translate virtual mapping for mem-
			       ory mapped device

       devmap_access(9E)       device mapping access entry point

       devmap_contextmgt(9E)   driver callback function	for context management

       devmap_dup(9E)	       device mapping duplication entry	point

       devmap_map(9E)	       device mapping create entry point

       devmap_unmap(9E)	       device mapping unmap entry point

       dump(9E)		       dump memory to device during system failure

       getinfo(9E)	       get device driver information

       gld(9E)		       Generic LAN Driver entry	points

       gldm_get_stats(9E)      See gld(9E)

       gldm_intr(9E)	       See gld(9E)

       gldm_ioctl(9E)	       See gld(9E)

       gldm_reset(9E)	       See gld(9E)

       gldm_send(9E)	       See gld(9E)

       gldm_set_mac_addr(9E)   See gld(9E)

       gldm_set_multicast(9E)  See gld(9E)

       gldm_set_promiscuous(9E)See gld(9E)

       gldm_start(9E)	       See gld(9E)

       gldm_stop(9E)	       See gld(9E)

       identify(9E)	       determine if a  driver  is  associated  with  a
			       device

       ioctl(9E)	       control a character device

       ks_snapshot(9E)	       take a snapshot of kstat	data

       ks_update(9E)	       dynamically update kstats

       mmap(9E)		       check virtual mapping for memory	mapped device

       open(9E)		       gain access to a	device

       power(9E)	       power a device attached to the system

       print(9E)	       display a driver	message	on system console

       probe(9E)	       determine  if  a	non-self-identifying device is
			       present

       prop_op(9E)	       report driver property information

       put(9E)		       receive messages	from the preceding queue

       read(9E)		       read data from a	device

       segmap(9E)	       map device memory into user space

       srv(9E)		       service queued messages

       strategy(9E)	       perform block I/O

       tran_abort(9E)	       abort a SCSI command

       tran_bus_reset(9e)      reset a SCSI bus

       tran_destroy_pkt(9E)    See tran_init_pkt(9E)

       tran_dmafree(9E)	       SCSI HBA	DMA deallocation entry point

       tran_getcap(9E)	       get/set SCSI transport capability

       tran_init_pkt(9E)       SCSI HBA	packet preparation and deallocation

       tran_quiesce(9e)	       quiesce and unquiesce a SCSI bus

       tran_reset(9E)	       reset a SCSI bus	or target

       tran_reset_notify(9E)   request to notify SCSI target of	bus reset

       tran_setcap(9E)	       See tran_getcap(9E)

       tran_start(9E)	       request to transport a SCSI command

       tran_sync_pkt(9E)       SCSI HBA	memory synchronization entry point

       tran_tgt_free(9E)       request to  free	 HBA  resources	 allocated  on
			       behalf of a target

       tran_tgt_init(9E)       request	to  initialize HBA resources on	behalf
			       of a particular target

       tran_tgt_probe(9E)      request to probe	SCSI bus for a particular tar-
			       get

       tran_unquiesce(9e)      See tran_quiesce(9e)

       write(9E)	       write data to a device

SunOS 5.10			  21 Dec 2004			     Intro(9E)

NAME | DESCRIPTION | SEE ALSO | List OF FUNCTIONS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=intro&sektion=9&manpath=SunOS+5.10>

home | help