'\"! tbl | mmdoc
'\"macro stdmacro
.TH "Frame Scheduler" 3
.SH NAME
\f4frs_create\f1, \f4frs_create_master\f1, \f4frs_create_slave\f1 \- create a frame scheduler object
.Op c p a
.SH SYNOPSIS
\f4#include <sys/frs.h>\f1
.PP
\f4frs_t\(** frs_create (int \f2cpu\fP, int \f2intr_source\fP, int \f2intr_qualifier\fP, int \f2n_minors\fP, pid_t \f2sync_master_pid\fP, int \f2n_slaves\fP);\f1
.PP
\f4frs_t\(** frs_create_master (int \f2cpu\fP, int \f2intr_source\fP, int \f2intr_qualifier\fP, int \f2n_minors\fP, int \f2n_slaves\fP);\f1
.PP
\f4frs_t\(** frs_create_slave (int \f2cpu\fP, frs_t\(** \f2sync_master_frs\fP);\f1
.fi
.SH DESCRIPTION
\f4frs_create\fP creates a frame scheduler object attached to processor
\f2cpu\fP driven by the one of six real-time interrupt source types.
.P
The interrupt source is specified by \f2intr_source\fP 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.
.TP
\f4FRS_INTRSOURCE_CPUTIMER\fP
Use the per-cpu timer with a period of \f2intr_qualifier\fP
microseconds.
.TP
\f4FRS_INTRSOURCE_DRIVER\fP
Use interrupts triggered by an FRS registered device driver.
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.
.TP
\f4FRS_INTRSOURCE_EXTINTR\fP
Use external interrupts. 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.
.P
The number of minor frames per major frame is specified by \f2n_minors\fP.
.P
If the frame scheduler being created is a synchronization master, parameter
\f2sync_master_pid\fP should be set to \f4FRS_SYNC_MASTER\fP and \f2n_slaves\fP
should be used to specify the number slaves.
.P
If the frame scheduler
is a slave, \f2sync_master_pid\fP should be set to the pid of the process
that created the sync-master frame scheduler, and \f2n_slaves\fP set to 0.
.P
\f4frs_create_master\fP is a simplified version of \f4frame_create\fP,
where a new frame scheduler object is created, and the calling thread or
process is automatically configured as the master controller.
.P
\f4frs_create_slave\fP is a simplified version of \f4frame_create\fP,
where a new frame scheduler object is created from the specified
\f2sync_master_frs\fP, and the calling thread or process is automatically
configured as a slave controller.
.P
Pthread applications cannot use \f4frs_create\fP to create a slave
frame scheduler object. It is recommended that pthread applications
use either \f4frs_create_master\fP or \f4frs_create_slave\fP for creating
frame scheduler objects.
.P
Pthreads calling frame scheduler creation routines must be system scope.
.P
The frame scheduler creation routines will fail if one or more of the following
conditions are true:
.TP 15
.SM
\%[EINVAL]
Invalid parameter
.TP 15
.SM
\%[EINVAL]
The selected interrupt source is not supported on the target platform 
.TP 15
.SM
\%[EFAULT]
Invalid frame scheduler object
.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
.TP 15
.SM
\%[ESRCH]
The controller thread or process of the specified frame scheduler
object does not exist
.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_vmaster\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.
.P
Frame scheduler programming examples (if installed) can be found in the
following directory: /usr/share/src/react/examples.