<P align=3Dcenter><A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digita=
l_UNIX_Bookshelf.html"><IMG=20
alt=3D"[Return to Library]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/BOOKSHELF.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/TOC.html"><IMG=20
alt=3D[Contents]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/TOC.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#DesSimple"><IMG=20
alt=3D"[Previous Chapter]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/REW.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#identstand_devdrv"><IMG=20
alt=3D"[Previous Section]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/PREV.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#ChooseWrtngComments"><IMG=20
alt=3D"[Next Section]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/NEXT.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut6.html"><IMG=20
alt=3D"[Next Chapter]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/FF.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/INDEX.html"><IMG=20
alt=3D[Index]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/INDEX.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.h=
tml"><IMG=20
alt=3D[Help]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/HELP.GIF"=20
border=3D0></A>=20
<P>
<HR>

<P>
<H3>2.1.2.1&nbsp;&nbsp;&nbsp;&nbsp;Specifying a Naming Scheme </H3>
<P><A name=3Dnx_id_41></A>The <TT>/dev/none</TT> driver uses the name=20
<TT>none</TT> as the prefix for device driver interface names. Device =
driver=20
interfaces written for Digital UNIX can use the following naming =
conventions:=20
<UL>
  <P>
  <LI>A prefix that represents the name of some device. In this example, =
the=20
  device is called <TT>none</TT>; therefore, each driver interface =
begins with=20
  that prefix.=20
  <P></P>
  <LI>The name of the interface, for example, <TT>open</TT> and =
<TT>close</TT>.=20
  Thus, the example driver has interface names such as <TT>noneopen</TT> =
and=20
  <TT>noneclose</TT>. </LI></UL>
<P>
<P>The <TT>/dev/none</TT> driver uses the name <TT>none</TT> as the =
prefix for=20
data structures internal to the device driver. These structures include =
a data=20
structure (often referred to as a <TT>softc</TT> structure) to store=20
driver-specific information. <A name=3Dnx_id_42></A>
<P>When using the CSR I/O access interfaces to read from and write to a =
device's=20
CSR addresses, you create device register offset names. You can also use =
the=20
prefix to create names for each of the device register offsets. Because =
the=20
<TT>/dev/none</TT> driver uses the CSR I/O access interfaces, it uses =
the name=20
<TT>none</TT> as the prefix to the device register offset name.=20
<P>The <TT>/dev/none</TT> driver uses the prefix <TT>DN</TT> for device =
driver=20
constant names. The prefix matches the first two characters in the =
driver name,=20
<TT>/dev/none</TT> (the letters D and N). These constants can represent =
values=20
or macros. For example, the constant <TT>DN_SIZE</TT> might represent =
the size=20
of the device register area.=20
<P>The previously described naming schemes are recommendations, not=20
requirements. The one naming requirement you must follow concerns the =
name of=20
the <TT>configure</TT> interface, which for the <TT>/dev/none</TT> =
driver is=20
<TT>none_configure</TT>. <A name=3Dnx_id_43></A><A =
name=3Dnx_id_44></A>This=20
interface is the configuration entry point called as a result of =
configuration=20
(both static and dynamic) requests. For the <TT>configure</TT> =
interface, the=20
underscore character (_) must follow the driver's name. This underscore=20
character in the name is a requirement of the configuration process for =
drivers=20
and is the Digital UNIX convention.=20
<P>Before choosing a naming scheme, you have to make sure that these =
names do=20
not conflict with other driver interface and structure names. To help =
you=20
determine what names are currently used by the system, run the =
<TT>nm</TT>=20
command on the kernel image file. This image file is usually called=20
<TT>/vmunix</TT>. (Note that you should not run the <TT>nm</TT> command =
on the=20
boot-link <TT>/sysconfigtab</TT> kernel image file.) If you follow the =
device=20
driver (kernel) kits delivery process described in <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut17.html#DevDriverKitDelivery">Chapter=20
12</A>, you should be particularly careful about choosing a naming =
scheme,=20
ensuring that it does not conflict with that of other third-party driver =

vendors. <A name=3Dnx_id_45></A><A name=3Dnx_id_46></A>
<P>Third-party driver writers may need to specify controller and device=20
information in calls to the <TT>create_controller_struct</TT> and=20
<TT>create_device_struct</TT> interfaces. <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut10.html#UsingCreRtnstoRegContrlDevInfo">Section=20
6.6.4.3</A> shows how to call these interfaces to create the =
<TT>controller</TT>=20
and <TT>device</TT> structures associated with your device drivers. If =
you are=20
supporting Digital devices, you specify valid device definition keywords =

asssociated with these devices. These keywords represent the controllers =
and=20
devices that Digital supports. See the <CITE>System =
Administration</CITE> guide=20
(specifically, the section that discusses how to build the kernel to add =
support=20
for a new device) for information on how to obtain the device definition =

keywords asssociated with Digital-supported devices.=20
<P>If you are supporting non-Digital devices, you can select any string =
other=20
than those already chosen by Digital to represent the device. However, =
without=20
an exclusive naming scheme, your choices could conflict with those of =
other=20
third-party driver vendors. To avoid these conflicts, you can select a =
string=20
that includes the vendor and product names and, possibly, the version =
and=20
release numbers. This type of naming scheme minimizes the potential for =
name=20
conflicts. For example, the driver writers at EasyDriver Incorporated =
might=20
specify <TT>edgd</TT> for an internally developed device. <A=20
name=3DChooseWrtngComments></A>
<P>
<HR>

<P align=3Dcenter><A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digita=
l_UNIX_Bookshelf.html"><IMG=20
alt=3D"[Return to Library]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/BOOKSHELF.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/TOC.html"><IMG=20
alt=3D[Contents]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/TOC.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#DesSimple"><IMG=20
alt=3D"[Previous Chapter]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/REW.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#SpecNamingScheme"><IMG=20
alt=3D"[Previous Section]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/PREV.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#specchar_ofdev"><IMG=20
alt=3D"[Next Section]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/NEXT.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut6.html"><IMG=20
alt=3D"[Next Chapter]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/FF.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/INDEX.html"><IMG=20
alt=3D[Index]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/INDEX.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.h=
tml"><IMG=20
alt=3D[Help]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/HELP.GIF"=20
border=3D0></A>=20
<P>
<HR>

<P>
<H3>2.1.2.2&nbsp;&nbsp;&nbsp;&nbsp;Choosing an Approach for Writing =
Comments and=20
Documentation </H3>
<P><A name=3Dnx_id_47></A>The <TT>/dev/none</TT> driver takes two =
approaches to=20
supplying comments in the driver code examples used in the book. In the =
first=20
approach, the <TT>/dev/none</TT> driver contains no inline comments. =
Instead,=20
the following convention is used:=20
<P><PRE>int unit =3D minor(dev); <A name=3Dco_id_2_rtn_1></A><A =
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#co_id_2_1"><STRONG>[1]</STRONG></A>
</PRE>
<P>
<OL>
  <P>
  <LI><A name=3Dco_id_2_1></A><A name=3Dnx_id_48></A>A number appears =
after a line=20
  of code in the <TT>/dev/none</TT> device driver example. Following the =

  example, a corresponding number appears that contains an explanation =
of the=20
  associated line or lines. The device driver examples contained in Part =
3 use=20
  the first approach to make the source code easier to read. <A=20
  =
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#co_id_2_rtn_1">[Return=20
  to example]</A> </LI></OL>
<P>In the second approach, the <TT>/dev/none</TT> device driver supplies =

appropriate inline comments. The source code listing in <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut28.html#DevDrvSrcList">Appendix=20
B</A> uses the second approach.=20
<P>In addition to providing background information and detailed =
explanations of=20
the <TT>/dev/none</TT> driver, this book also offers information on =
device=20
driver concepts, kernel interfaces, data structures, and so forth. Your =
approach=20
to writing device driver documentation may be different. <A=20
name=3Dspecchar_ofdev></A>
<P>
<HR>

<P align=3Dcenter><A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digita=
l_UNIX_Bookshelf.html"><IMG=20
alt=3D"[Return to Library]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/BOOKSHELF.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/TOC.html"><IMG=20
alt=3D[Contents]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/TOC.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#DesSimple"><IMG=20
alt=3D"[Previous Chapter]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/REW.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#ChooseWrtngComments"><IMG=20
alt=3D"[Previous Section]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/PREV.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut5.html#SpecWhetDevCapBlockIO"><IMG=20
alt=3D"[Next Section]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/NEXT.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut6.html"><IMG=20
alt=3D"[Next Chapter]"=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/FF.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/INDEX.html"><IMG=20
alt=3D[Index]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/INDEX.GIF"=20
border=3D0></A> <A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.h=
tml"><IMG=20
alt=3D[Help]=20
src=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBV=
D-TE_html/HELP.GIF"=20
border=3D0></A>=20
<P>
<HR>

<P>
<H3>2.1.3&nbsp;&nbsp;&nbsp;&nbsp;Specifying Characteristics of the =
Device </H3>
<P><A=20
href=3D"http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUB=
VD-TE_html/drivertut29.html#devcharac_wkshtfordevnone">Figure=20