210 lines
7.2 KiB
Groff
210 lines
7.2 KiB
Groff
'\"! tbl | mmdoc
|
|
'\"macro stdmacro
|
|
.TH "Frame Scheduler" 3
|
|
.SH NAME
|
|
\f4frs_create_vmaster\f1 \- create a variable master frame scheduler object
|
|
.Op c p a
|
|
.SH SYNOPSIS
|
|
\f4#include <sys/frs.h>\f1
|
|
.PP
|
|
\f4frs_t\(** frs_create_vmaster (int \f2cpu\fP, int \f2n_minors\fP, int \f2n_slaves\fP, frs_intr_info_t \f2*intr_info\fP);\f1
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f4frs_create_vmaster\fP creates a variable frame scheduler object, allowing
|
|
variable length minor frames, and multiple interrupt sources. These
|
|
characteristics are defined by the interrupt information template passed
|
|
into \f2intr_info\fP.
|
|
.P
|
|
The master frame scheduler's cpu is specified using the \f2cpu\fP parameter,
|
|
while the number of slaves is specified using \f2n_slaves\fP.
|
|
.P
|
|
The number of minor frames, and therefore the number of entries in the
|
|
interrupt information template array, is specified using the \f2n_minors\fP
|
|
parameter.
|
|
.P
|
|
\f4Interrupt Information Templates\fP
|
|
.P
|
|
Variable frame schedulers may drive each minor frame with a different interrupt
|
|
source, as well as, define different durations for each minor frame. These
|
|
two characteristics may be used together or separately, and are defined using
|
|
an interrupt information template.
|
|
.P
|
|
An interrupt information template consists of an array of frs_intr_info_t data
|
|
structures. Each element in the array represents a minor frame. For example,
|
|
the first element in the array represents the interrupt information for the
|
|
first minor frame, and so on for \f2n_minors\fP frames.
|
|
.P
|
|
The frs_intr_info_t data structure contains two fields:
|
|
\f2intr_source\fP and \f2intr_qualifier\fP.
|
|
.P
|
|
The \f2intr_source\fP field defines the interrupt source, and may be one of
|
|
the following:
|
|
.PP
|
|
.TP 5
|
|
\f4FRS_INTRSOURCE_CCTIMER\fP
|
|
Use the synchronized clock timer with a period of \f2intr_qualifier\fP
|
|
microseconds.
|
|
.sp
|
|
If the synchronized clock timer is chosen as an interrupt source,
|
|
minor frames may be assigned different durations,
|
|
but different interrupt sources cannot be used to trigger them.
|
|
.TP
|
|
\f4FRS_INTRSOURCE_CPUTIMER\fP
|
|
Use the per-cpu timer with a period of \f2intr_qualifier\fP
|
|
microseconds.
|
|
.sp
|
|
If multiple interrupt sources are selected, the per-cpu timer cannot
|
|
be used as the interrupt source for the first minor frame.
|
|
.TP
|
|
\f4FRS_INTRSOURCE_DRIVER\fP
|
|
Use interrupts triggered by a kernel-level device driver, which is registered
|
|
with the frame scheduler. Each device driver registered with the FRS has a
|
|
unique registration number. When selecting device interrupts, the
|
|
target driver's registration number is specified
|
|
by \f2intr_qualifier\fP.
|
|
.sp
|
|
The kernel-level device driver and vertical retrace (FRS_INTRSOURCE_VSYNC)
|
|
interrupt sources cannot be used together.
|
|
.sp
|
|
If the FRS_INTRSOURCE_DRIVER interrupt source
|
|
is used, it must (at a minimum) trigger the first minor frame.
|
|
.TP
|
|
\f4FRS_INTRSOURCE_EXTINTR\fP
|
|
Use external interrupts (see ei(7)).
|
|
In this case the \f2intr_qualifier\fP should be set to zero.
|
|
.sp
|
|
For the frame scheduler to recognize an external interrupt, the interrupt
|
|
must be routed to the cpu of the master frame scheduler.
|
|
.TP
|
|
\f4FRS_INTRSOURCE_ULI\fP
|
|
Use user-level device driver interrupts (see uli(3)).
|
|
In this case the \f2intr_qualifier\fP should be set to zero.
|
|
.sp
|
|
For the frame scheduler to recognize a user-level interrupt, the interrupt
|
|
must be routed to the cpu of the master frame scheduler.
|
|
.TP
|
|
\f4FRS_INTRSOURCE_USER\fP
|
|
Use user-triggered pseudo-interrupts (see frs_userintr(3)).
|
|
In this case the \f2intr_qualifier\fP should be set to zero.
|
|
.TP
|
|
\f4FRS_INTRSOURCE_VSYNC\fP
|
|
Use the vertical retrace interrupt of graphics pipe number \f2intr_qualifier\fP.
|
|
.sp
|
|
The vertical retrace and the kernel-level device driver
|
|
(FRS_INTRSOURCE_DRIVER) interrupt sources cannot be used together.
|
|
.sp
|
|
If the FRS_INTRSOURCE_VSYNC interrupt source
|
|
is used, it must (at a minimum) trigger the first minor frame.
|
|
.P
|
|
The following example demonstrates how to define an interrupt information
|
|
template for a frame scheduler having minor frames of different durations:
|
|
.P
|
|
Assume the application requires four minor frames, where each
|
|
minor frame is triggered by the synchronized clock timer, and the duration
|
|
of each minor frame is as follows: 100ms, 150ms, 200ms and 250ms.
|
|
The interrupt information template may be defined as:
|
|
.RS 0.5i
|
|
.PP
|
|
frs_intr_info_t intr_info[4];
|
|
.PP
|
|
intr_info[0].intr_source = FRS_INTRSOURCE_CCTIMER;
|
|
intr_info[0].intr_qualifier = 100000;
|
|
.PP
|
|
intr_info[1].intr_source = FRS_INTRSOURCE_CCTIMER;
|
|
intr_info[1].intr_qualifier = 150000;
|
|
.PP
|
|
intr_info[2].intr_source = FRS_INTRSOURCE_CCTIMER;
|
|
intr_info[2].intr_qualifier = 200000;
|
|
.PP
|
|
intr_info[3].intr_source = FRS_INTRSOURCE_CCTIMER;
|
|
intr_info[3].intr_qualifier = 250000;
|
|
.RE
|
|
.PP
|
|
The following example demonstrates how to define an interrupt information
|
|
template for a frame scheduler using multiple interrupt sources:
|
|
.P
|
|
Assume the application requires two minor frames, where the first minor
|
|
frame is triggered by the vertical retrace interrupt and the second minor
|
|
frame is triggered by the CPU timer. Also assume the vertical retrace
|
|
interrupt is running at 60Hz (every 16.6ms). The following interrupt
|
|
information template defines the the CPU timer interrupt of the second
|
|
frame to fire 8.3ms after the vertical retrace interrupt:
|
|
.RS 0.5i
|
|
.PP
|
|
frs_intr_info_t intr_info[2];
|
|
.PP
|
|
intr_info[0].intr_source = FRS_INTRSOURCE_VSYNC;
|
|
intr_info[0].intr_qualifier = 0;
|
|
.PP
|
|
intr_info[1].intr_source = FRS_INTRSOURCE_CPUTIMER;
|
|
intr_info[1].intr_qualifier = 8300;
|
|
.RE
|
|
.P
|
|
Note that 8.3ms was chosen in this example, because it is known that the
|
|
timer interrupt will fire before the next major frame's vsync interrupt.
|
|
If 20ms was chosen for the timer instead, then a sequence error will occur
|
|
(interrupts arriving in an order other than what was defined) and an error
|
|
signal would be sent to the controller thread. See the
|
|
\f2REACT Real-Time Programmer's Guide\fP for information on sequence errors
|
|
and handling signals.
|
|
.P
|
|
Detailed programming examples are available, which cover the use
|
|
of the frame scheduler interfaces (including \f4frs_create_vmaster\fP),
|
|
and are located in the following directory: /usr/share/src/react/examples.
|
|
.P
|
|
\f4frs_create_vmaster\fP will fail if one or more of the following
|
|
conditions are true:
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
Invalid parameter
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
One or more of the selected interrupt sources is not supported on
|
|
the target platform
|
|
.TP 15
|
|
.SM
|
|
\%[EFAULT]
|
|
Invalid frame scheduler object or interrupt information template
|
|
.TP 15
|
|
.SM
|
|
\%[ENOSPC]
|
|
The system could not allocate an interrupt group
|
|
.TP 15
|
|
.SM
|
|
\%[ENOMEM]
|
|
The system could not allocate a frame scheduler object
|
|
.TP 15
|
|
.SM
|
|
\%[EEXIST]
|
|
A frame scheduler object already exists for the specified processor
|
|
.TP 15
|
|
.SM
|
|
\%[EPERM]
|
|
No permission to execute frame scheduler functions
|
|
.TP 15
|
|
.SM
|
|
\%[EPERM]
|
|
The calling pthread is not system scope
|
|
.TP 15
|
|
.SM
|
|
\%[ENODEV]
|
|
The REACT/Pro Frame Scheduler Subsystem has not been installed
|
|
.P
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion, a pointer to a Frame Scheduler object is
|
|
returned. Otherwise, NULL is returned and errno is set to indicate the
|
|
error.
|
|
.SH "SEE ALSO"
|
|
\f4frs_create_master\f1(3),
|
|
\f4frs_create_slave\f1(3),
|
|
\f4frs_destroy\f1(3),
|
|
\f4frs_start\f1(3),
|
|
\f4frs_enqueue\f1(3),
|
|
\f4frs_pthread_enqueue\f1(3),
|
|
\f4frs_setattr\f1(3)
|
|
.P
|
|
The REACT Real-Time Programmer's Guide (insight(1)) covers Frame Scheduler
|
|
principles and usage in detail.
|