sema(4) sema(4)
NAME
sema - format of multi-threaded kernel configuration file
SYNOPSIS
sema
DESCRIPTION
The sema file is included in the directory /etc/conf/cf.d. and is gen-
erated from a concatenation of individual files in the directory
/etc/conf/sema.d. It includes a one-line definition of multi-threaded
attributes of each device driver and configurable software module in
the system to be built. Multi-threaded means the capability to have
more than one CPU execute, in parallel, machine instructions common to
the scope of the device driver or module. If a driver or module is not
present in the sema file, then the following default attributes are
assumed. These attributes are vendor-specific, and other implementa-
tions may use different default attributes.
If the absent driver or module is STREAMS-based, then the system
assumes the driver or module is not multi-threaded, and the operating
system will acquire a per-driver or per-module compatibility semaphore
before executing any machine instructions within the scope of the
driver or module.
If the missing driver or module is not STREAMS-based, the system will
assume that the driver or module is multi-threaded.
Currently, sema is interpreted only for STREAMS drivers and modules.
Right now, it is required that non-STREAMS drivers and modules be
coded in a multi-threaded fashion, as the operating system makes no
guarantees that the machine instructions of a driver or module won't
be executed in parallel on multiple CPUs. In addition, STREAMS drivers
and modules containing device interrupt handlers must be multi-
threaded, as there is no way currently to configure the operating sys-
tem to direct interrupts to a specific CPU, or to acquire a compati-
bility semaphore before entering the driver's or module's interrupt
handler.
Each line in sema is an extension of the Master file component from a
Driver Software Package (DSP) either delivered with the base system or
installed later via idinstall.
Each line contains several whitespace-separated fields; they are
described below. Each field must be supplied with a value or a "-"
(dash).
1. Device name: This field is the internal name of the device or
module, and may be up to 8 characters long. The first character of
the name must be an alphabetic character; the others may be
letters, digits, or underscores. This field cannot have a "-" dash
specified.
Page 1 Reliant UNIX 5.44 Printed 11/98
sema(4) sema(4)
2. Compatibility semaphore name: This field is a string of characters
that identify the name of the compatibility semaphore that the
operating system kernel will acquire before entering the device
driver or module. Multiple sema files may use the same sema name,
giving the capability to share the same semaphore between drivers
that have common data structures. If this field is a "-" (dash),
and there isn't a conflict with the fourth field, this indicates no
compatibility semaphore is required. The fourth field, used only by
stream drivers and modules, may require a compat sema even if a
dash is specified (i.e. PLCOMPAT). In this case, a "-" (dash) may
indicate that the name will default to the first field: the inter-
nal device name.
3. Logical CPU number: This field contains a string of decimal digits
that indicate which logical CPU the device or module is bound to.
Logical CPU numbers begin with 0 and are numbered to NCPU - 1. The
constant NCPU can be found in /usr/include/sys/param.h. If this
field is a "-" (dash), this indicates that the device or module is
not bound. If the logical cpu is not online when the device driver
or module is executed, the operating system will map it the CPU
number to one that is on-line. If this field is not a "-", then the
second field - the compatibility semaphore name - must be a "-"; a
driver or module cannot be both bound and have a compatibility
semaphore.
4. Degree of parallelism: The field must be a "-" (dash) if the driver
or module is not STREAMS-based. Otherwise, this field contains a
string of characters that indicate the level of parallelism a
STREAMS driver or module executes in. There are five standard lev-
els of parallelism:
PLCOMPAT
Otherwise known as level 1, or compatibility mode, this level
specifies that the STREAMS driver or module is single-
threaded, and must be bound to a logical CPU or entered with a
compatibility semaphore held. Whether binding or a compatibil-
ity semaphore is used for single threading a driver or module,
depends on whether a "-" is present in field number 3. If nei-
ther field two nor field three is specified, then the default
action is to assign a compat sema.
If the compatibility mode semaphore is used to single-thread
the driver or module, then all entry points (except for inter-
rupt handlers), including the put procedures, service pro-
cedures, initialization, start, open, close, timeouts, buf-
calls, and extended message free routines are synchronized
with each other. In addition, since the compatibility sema-
phore is not re-entrant, none of the entry points are.
If CPU binding is used to single-thread the driver or module,
and all entry points (except for interrupt handlers) will be
executed and bound to a specific CPU. Thus the environment of
Page 2 Reliant UNIX 5.44 Printed 11/98
sema(4) sema(4)
driver or module (sans interrupts) precisely simulates that of
the single processor system, so protection via spls, or inter-
rupt priority levels remains the responsibility of the driver
or module.
There are several pros and cons when deciding to use binding
versus a compatibility semaphore. The semaphore approach per-
mits a driver or module to "float" to any available processor
on the system, so this approach allows automatic load distri-
bution. The binding approach loses on load distribution, but
by staying on one CPU, the per CPU caches of primary memory
are not invalidated as often as they be if the module ping-
ponged to the first available CPU. It is usually unwise to
bind a pushable STREAMS module to a CPU, because it cannot be
pushed onto a STREAMS driver that that is bound to a different
CPU.
PLCOORDALL
Otherwise known as level 2, this level takes the four pro-
cedural entry points - the read service procedure, the read
put procedure, the write service procedure, and the write pro-
cedure - and synchronizes all four with each other. Only one
the four procedures may be executing, and none of the pro-
cedures are re-entrant. There is no synchronization or serial-
ization with timeouts, bufcalls, extended message free rou-
tines, or interrupt handlers.
PLCOORDSRVPAIR
Otherwise known as level 3, this level takes the two service
procedure entry points - the read and write service procedures
- and synchronizes them with each other. Only one of the two
service procedures may be executing, and none of the two ser-
vice procedures are re-entrant. The read and put procedures
may run in parallel with each other and one of the service
procedures. The read and put procedures are also re-entrant.
There is no synchronization or serialization with timeouts,
bufcalls, extended message free routines, or interrupt
handlers.
PLCOORDSRVS
Otherwise known as level 4, this level takes each service pro-
cedure, and guarantees that they are not re-entrant. Unlike
the PLCOORDSRVPAIR level, the read and write service pro-
cedures can run in parallel. The read and put procedures may
run in parallel with each other and the service procedures.
The read and put procedures are also re-entrant. There is no
synchronization or serialization with timeouts, bufcalls,
extended message free routines, or interrupt handlers.
PLNOCOORD
Otherwise known as level 5, this level allows all four pro-
cedural entry points - the read service procedure, the read
Page 3 Reliant UNIX 5.44 Printed 11/98
sema(4) sema(4)
put procedure, the write service procedure, and the write put
procedure - to run in parallel with other. In addition, all
four procedures are re-entrant. There is no synchronization or
serialization with timeouts, bufcalls, extended message free
routines, or interrupt handlers.
It is possible specify a custom value for degree of parallelism in the
form a hexadecimal constant. The constant must begin with 0x and be
followed by four hexadecimal digits. Each digit specifies a coordina-
tion mask for a particular procedure. The first digit specifies the
mask for the write put procedure. The second digit specifies the mask
for the write service procedure. The third digit specifies the mask
for read put procedure. The fourth digit specifies the mask for the
read service procedure. Each hexadecimal digit mask specifies which of
the four procedures the considered procedure runs exclusive of. If the
high order first bit of the digit mask is set, then the procedure runs
exclusive of the write put procedure. If the second bit is set, then
the procedure runs exclusive of the write service procedure. If the
third bit is set, then the procedure runs exclusive of the read put
procedure. If the fourth bit is set, then the procedure runs exclusive
of the read service procedure. For example if the third hexadecimal
digit has a value of "c", then in binary this is "1100", and so the
read put procedure must run exclusive of the write put and write ser-
vice procedures. However, the read put procedure is re-entrant, and it
can run in parallel with the read service procedure. Note that in this
example, the digit masks for the write put and write service pro-
cedures are set to indicate that they run exclusive of the read put
procedure. To further illustrate, note that
PLCOORDALL is equivalent to 0xffff;
PLCOORDSRVPAIR is equivalent to 0x0505;
PLCOORDSRVS is equivalent to 0x0401; and
PLNOCOORD is equivalent to 0x0000.
Custom degrees of parallelism do not provide synchronization or seri-
alization with timeouts, bufcalls, extended message free routines, or
interrupt handlers.
If the STREAMS driver is a multiplexor, it is possible to specify dif-
ferent degrees of parallelism for both upper and lower halves. To do
this specify the degree for the upper half, followed by a "/" (slash)
followed by the degree for the lower half. Either or both of the
degrees may be standard or custom. However if either of the degrees is
PLCOMPAT, the other half's degree must be as well.
EXAMPLES
drv - - PLCOMPAT
Indicates that driver drv is single-threaded, and that the operating
system will achieve this by using a compatibility semaphore, which
defaults to the name drv.
Page 4 Reliant UNIX 5.44 Printed 11/98
sema(4) sema(4)
drvb - 5 PLCOMPAT
Indicates that driver drvb is single-threaded, and that the operating
system will achieve this by binding it to logical CPU 5.
drvc drvc - PLCOMPAT
drvd drvc - PLCOMPAT
Indicates that drivers drvc and drvd are each single-threaded, and
that the operating system will achieve this by using a compatibility
semaphore, called drvc. However, because both drivers use the same
semaphore, the two drivers will not be able to run in parallel with
each other.
drvx - - PLCOORDSRVS
Indicates that drvx is a multi-threaded STREAMS driver. Only one invo-
cation of a service procedure on a specific queue can be running.
mux - - PLCOORDALL/0x0240
Indicates that STREAMS driver mux is a multi-threaded multiplexor. The
top half coordinates all four procedures with each other. The lower
half ensures that the write service procedure runs exclusive of the
read put procedure and vice versa.
SEE ALSO
idinstall(1M), mdevice(4), sdevice(4).
Page 5 Reliant UNIX 5.44 Printed 11/98