building dd.htm

What is this ``device driver stuff anyway? Here s a very short introduction to the concept.

<p>
<tt>Device_Char_Minor = [0-10],[21-30]</tt>
</p><p>
To specify more than one range of device minor numbers, enclose the first
range within brackets ([]) and separate the range with a dash (-).
Follow the first range with a comma (,).
Specify the second range in the same manner as the first and omit the
comma (unless there are additional ranges).
</p><p>
The values you specify for block devices are the same except that you use
the
<tt>Device_Block_Minor</tt>
field instead of
<tt>Device_Char_Minor</tt>.
</p></li></ul><p>
<a href="#co_id_96_rtn_4">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_96_5"></a>
Shows that the driver writer at EasyDriver Incorporated assigns the value
<tt>none</tt>
to the
<tt>Device_Char_Files</tt>
field.
This field identifies the device special file name associated with the
minor number for the character device
controlled by the
<tt>/dev/none</tt>
driver.
Use a single value as the device special file name associated with the
device minor number for the character device controlled by your driver product;
or, specify the device special file name as follows:
<ul>
<p></p><li>
One device special file name, for example:
<p>
<tt>Device_Char_Files = rrz1</tt>
</p><p>
To specify a single file name, simply specify the name.
</p><p></p></li><li>
More than one device special file name, for example:
<p>
<tt>Device_Char_Files = rrz1,rrz2,rrz3</tt>
</p><p>
To specify more than one file name, specify the names
separated by commas.
</p><p></p></li><li>
A range of device special file names, for example:
<p>
<tt>Device_Char_Files = rrz1[1-10]</tt>
</p><p>
To specify a range of file names, enclose the range within
brackets ([]) and separate the beginning and ending names with
a dash (-).
The following rules apply to letters specified in a range:
</p><ul>
<p></p><li>
Both letters must be either lowercase or uppercase.
Thus,
<tt>[a-h]</tt>
or
<tt>[A-H]</tt>
are valid range specifications while
<tt>[A-h]</tt>
and
<tt>[a-H]</tt>
are invalid.
<p></p></li><li>
Only one letter is allowed in the range specification, as in the
example.
Thus,
<tt>[aa-hh]</tt>
is not a valid range specification.
<p></p></li><li>
The ending letter must be greater than the beginning letter.
Thus,
<tt>[z-a]</tt>
is not a valid range specification.
</li></ul><p>
</p><p></p></li><li>
More than one range of device special file names, for example:
<p>
<tt>Device_Char_Files = rrz1[a-h],rrz2[i-t]</tt>
</p><p>
To specify more than one range of file names, enclose the first
range within brackets ([]) and separate the range with a dash (-).
Follow the first range with a comma (,).
Specify the second range in the same manner as the first and omit the
comma (unless there are additional ranges).
</p><p>
The values you specify for block devices are the same except that you use
the
<tt>Device_Block_Files</tt>
field instead of
<tt>Device_Char_Files</tt>.
In addition, you specify the device name as a block device, for example
<tt>rz0</tt>
and
<tt>rz1</tt>
instead of
<tt>rrz0</tt>
and
<tt>rrz1</tt>.
</p><p>
The
<tt>Device_Char_Files</tt>
field must be paired with corresponding minor numbers specified in the
<tt>Device_Char_Minor</tt>
field.
(For block devices, the
<tt>Device_Block_Files</tt>
field must be paired with corresponding minor numbers specified in the
<tt>Device_Block_Minor</tt>
field.)
The ranges for each must represent an equal number of file-to-minor
number associations.
The following example shows a correct match:
</p><p>
<tt>Device_Char_Files = rrz0[a-h]</tt>
</p><p>
<tt>Device_Char_Minor = [0-7]</tt>
</p><p>
The following shows an invalid match:
</p><p>
<tt>Device_Char_Files = rrz0[a-c]</tt>
</p><p>
<tt>Device_Char_Minor = [0-7]</tt>
</p><p>
The following shows a match that uses more than one range.
Note that the gap in the minor numbers is valid.
</p><p>
<tt>Device_Char_Files = rrz0[a-h],rrz1[a-h],rrz2[a-h],rrt5[a-h]</tt>
</p><p>
<tt>Device_Char_Minor = [0-7],[8-15],[16-23],[40-47]</tt>
</p><p>
The number of files must equal the number of minor numbers, just as in a
single range specification.
In addition, the maximum number of devices is 512.
Thus, the following range specifications are invalid:
</p><p>
<tt>Device_Char_Files = rrz0[0-300],rrz1[301-600]</tt>
</p><p>
<tt>Device_Char_Minor = [0-300],[301-600]</tt>
</p><p>
If you violate any of the previously discussed rules, none of the device
special files will be created.
</p></li></ul><p>
<a href="#co_id_96_rtn_5">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_96_6"></a>
Shows that the driver writer at EasyDriver Incorporated assigns the value
<tt>root</tt>
to the
<tt>Device_User</tt>
field.
This field identifies the user that owns the device special files
associated with the
<tt>/dev/none</tt>
driver.
<p>
Use the value
<tt>root</tt>
as the user name or specify something else for your driver product.
<a href="#co_id_96_rtn_6">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_96_7"></a>
Shows that the driver writer at EasyDriver Incorporated assigns the value
zero (0) to the
<tt>Device_Group</tt>
field.
This field identifies the group that owns the device special files
associated with the
<tt>/dev/none</tt>
driver.
<p>
Use the value zero (0)
as the group user or specify something else for your driver product.
<a href="#co_id_96_rtn_7">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_96_8"></a>
Shows that the driver writer at EasyDriver Incorporated assigns the value
<tt>666</tt>
to the
<tt>Device_Mode</tt>
field.
This field identifies the protection mode for the device special files
associated with the
<tt>/dev/none</tt>
driver.
<p>
Use the value
<tt>666</tt>
as the protection mode or specify another octal number for your driver product.
<a href="#co_id_96_rtn_8">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_96_9"></a>
Shows that the driver writer at EasyDriver Incorporated assigns the value
<tt>Same</tt>
to the
<tt>Device_Major_Req</tt>
field.
This field specifies requirements that relate to major number
assignment.
<p>
Use the value
<tt>Same</tt>
for your driver product.
<a href="#co_id_96_rtn_9">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_96_10"></a>
The option data for a bus contains bus-specific information.
For example, the option data associated with the TURBOchannel bus
includes the module name and the driver name.
The option data for the EISA bus includes the board ID and the driver
name.
The driver writer at EasyDriver Incorporated assigns the option data associated
with the TURBOchannel bus.
For example purposes, the
<tt>/dev/none</tt>
driver operates on the TURBOchannel bus.
Assign the option data associated with the bus your driver operates on,
using the following fields:
<tt>EISA_Option</tt>,
<tt>ISA_Option</tt>,
<tt>PCI_Option</tt>,
or
<tt>TC_Option</tt>.
If your driver operates on multiple buses, then you would specify the
appropriate keywords.
For example, if your driver operates on the EISA, ISA, and PCI buses you
would specify the
<tt>EISA_Option</tt>,
<tt>ISA_Option</tt>,
and
<tt>PCI_Option</tt>
keywords.
<p>
See the bus-specific books for descriptions of the values associated
with these option data fields.
</p><p>
Drivers operating on the VMEbus use the
<tt>VBA_Option</tt>
keyword.
</p><p>
One characteristic to note for the
<tt>TC_Option</tt>
field is that the information must be specified on one line
(that is, there should be no carriage returns separating the
information).
For complete explanations of the information associated with the
<tt>TC_Option</tt>
keyword, 
see
<cite>Writing TURBOchannel Device Drivers</cite>.
<a href="#co_id_96_rtn_10">[Return to example]</a>
</p></li></ol><p>
</p><p>
If your device driver calls the
<tt>contig_malloc</tt>
interface to allocate physically contiguous memory and you have
implemented the driver to be dynamically configured into the kernel,
you need to specify the
<tt>CMA_Option</tt>
field in your
<tt>sysconfigtab</tt>
file fragment. 
The
<tt>contig_malloc</tt>
interface cooperates with the
<tt>cma_dd</tt>
subsystem to ensure that a dynamically configured driver's request
for physically contiguous memory is granted.
The call to
<tt>contig_malloc</tt>
is the same for statically or dynamically configured drivers.
However, in the case of dynamically configured drivers, it is the
<tt>cma_dd</tt>
subsystem that causes the physically contiguous memory to be allocated.
The reason for this is that the
<tt>contig_malloc</tt>
interface does not work when the system reaches single-user mode.
</p><p>
The
<tt>CMA_Option</tt>
field provides the information that the Digital-provided
<tt>cma_dd</tt>
subsystem needs.
The
<tt>cma_dd</tt>
subsystem allocates physically contiguous memory on behalf of
a device driver that is dynamically configured into the kernel.
</p><p>
Each
<tt>CMA_Option</tt>
entry causes the
<tt>cma_dd</tt>
subsystem to generate (by calling the
<tt>contig_malloc</tt>
interface)
a contiguous block of memory.
The
<tt>cma_dd</tt>
subsystem reserves this memory in a saved memory pool.
When specifying information with the
<tt>CMA_Option</tt>
field, you use five parameters that map to the five arguments associated
with
<tt>contig_malloc</tt>.
You must make sure that the values passed to the call to
<tt>contig_malloc</tt>
match the values specified with the paramaters
associated with the
<tt>CMA_Option</tt>
field.
</p><p>
A device driver later calls the
<tt>contig_free</tt>
interface to release the physically contiguous memory and cause the
<tt>cma_dd</tt>
subsystem to return the memory resource to the save memory pool.
This memory resource is then available for reallocation by a dynamically
configured driver upon subsequent reload requests.
</p><p>
The following
<tt>sysconfigtab</tt>
file fragment shows how to specify the
<tt>CMA_Option</tt>
for a
<tt>/dev/xx</tt>
driver.
</p><p>
</p><pre>xx:
<br>.<br>.<br>.<br>
CMA_Option = Size - 0x10000, Alignment - 0x10000, Addrlimit - 0,
             Type - 0x1f, Flag - 1 <a name="co_id_97_rtn_1"></a><a href="#co_id_97_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
</pre>
<p>
</p><ol>
<p></p><li>
<a name="co_id_97_1"></a>
You specify the
<tt>CMA_Option</tt>
field.
One characteristic to note for the
<tt>CMA_Option</tt>
field is that the information must be specified on one line
(that is, there should be no carriage returns separating the
information).
The following list describes the five parameters:
<ul>
<p></p><li>
<tt>Size</tt>
<p>
This parameter maps to the
<tt><var>size</var></tt>
argument of the
<tt>contig_malloc</tt>
interface.
The parameter specifies
the size of the memory (in bytes) to allocate.
</p><p>
In the example, the size is
<tt>0x10000</tt>.
</p><p></p></li><li>
<tt>Alignment</tt>
<p>
This parameter maps to the
<tt><var>alignment</var></tt>
argument of the
<tt>contig_malloc</tt>
interface.
The parameter specifies
the alignment of the memory to be allocated.
For example, for a 256-byte alignment you should pass the value 256.
A zero (0) value means there is no alignment requirement.
</p><p>
In the example, the alignment is
<tt>0x10000</tt>.
</p><p></p></li><li>
<tt>Addrlimit</tt>