eti_request(3C)                                   eti_request(3C)



NAME
     eti_map, eti_request, eti_unmap, eti_request_macro - edge
     triggered interrupt controls

SYNOPSIS
     #include <sys/types.h>
     #include <ml/pin.h>

     caddr_t eti_map (pin, addr)
     int pin;
     caddr_t addr;

     int eti_unmap (addr)
     caddr_t addr;

     void eti_request (func, addr)
     u_int func;
     caddr_t addr;

     #include <sys/types.h>
     #include <ml/pin.h>
     #include <sys/eti.h>

     eti_request_macro (func, addr)
     u_int func;
     caddr_t addr;


DESCRIPTION
     Edge triggered interrupts (eti), may be individually armed,
     disarmed, enabled, disabled and requested, without affecting
     any other interrupts in the system.

     These library routines give a user level process control
     over a particular edge triggered interrupt.  This is accom-
     plished by binding the physical address of a specified edge
     triggered interrupt into the address space of the process
     and then writing directly to this virtual address.

     The library routine that should be called first, eti_map(),
     will map the specified edge triggered interrupt into the
     process's address space.  This routine will then return the
     process's virtual address of the eti.  The pin parameter is
     an edge triggered interrupt pin number, and the addr parame-
     ter is a virtual address where the caller wishes the shared
     memory region to be attached.  If addr is zero, the system
     will pick the virtual address.  If addr is not zero, then
     eti_map() will attempt to attach the shared memory region at
     the specified address, automatically rounding the addr value
     to a SHMLBA boundary.

     The valid values for pin depend upon the system:



Page 1                        CX/UX Programmer's Reference Manual

eti_request(3C)                                   eti_request(3C)



          On Series 4000 HN4400 systems, pin may be 0 through 3.

          On Series 4000 HN4800 systems, pin may be 0 through 16.

          On Series 5000 HN5800 systems, pin may be 0 through 16.

     Once the eti_map() routine has been called, a second library
     routine, eti_request(), will perform the specified
     operation(s) on the specified virtual address. The function
     parameter is a pin function as defined in <ml/pin.h> and may
     be PIN_ARM, PIN_DISARM, PIN_ENABLE, PIN_DISABLE or
     PIN_REQUEST.  The addr parameter contains the virtual
     address of the pin.  This value should be the value that was
     returned from the previous eti_map() call.  No value is
     returned from this routine.

     A macro version of the eti_request() library routine,
     eti_request_macro(), will be provided in <sys/eti.h>.  The
     parameters to eti_request_macro() are the same as for the
     eti_request() library routine.  The eti_request_macro() is
     provided as a faster method for issuing a control function
     to an eti.  This macro is only available to C language pro-
     grams and is not available to Fortran or Ada programs.

     The eti_unmap() routine is provided to detach the shared
     memory region from the process.  The addr parameter is the
     virtual address returned from the previous eti_map() routine
     call.  (The eti shared memory region will be automatically
     detached when a process terminates, or issues one of the
     exec(2) system service calls.)

RESTRICTIONS
     A process must be super user, or must have the ACC_SHMBIND
     access vector bit set (if access vectors are configured) in
     order to use the spl_map() routine.

     These routines will NOT support the external VMIVME-5010 ETI
     VME board.  Only internal edge triggered interrupts will be
     supported.  Customers wishing to control etis on this board
     must use the kernel eti driver (see eti(7)), or use the new
     spl library support (see spl(3C)).

RETURN VALUE
     For eti_map() routine calls, upon successful completion, the
     virtual address of the edge triggered interrupt is returned.
     For eti_unmap() routine calls, upon successful completion, a
     value of zero is returned. Otherwise, for both of these
     calls, a value of -1 is returned and errno is set to indi-
     cate the error.

     The eti_request() routine returns no status information.




Page 2                        CX/UX Programmer's Reference Manual

eti_request(3C)                                   eti_request(3C)



ERRORS
     If any of the following conditions is detected, eti_map()
     will return -1 and set errno to the following value:

     [EINVAL]       The pin parameter was not valid.

     [EACCES]       The caller is not super-user, or does not
                    have the ACC_SHMBIND access vector bit set
                    (if access vectors are configured).

     [EINVAL]       The addr parameter is not a valid shared
                    memory segment value.

     [EMFILE]       The number of shared memory segments attached
                    to the calling process would exceed the
                    system-imposed limit.

     [ENOSPC]       The eti shared memory identifier is to be
                    created for the process, but the system-
                    imposed limit on the maximum number of
                    allowed system-wide shared memory identifiers
                    would be exceeded.

     If the any of the following conditions is detected,
     eti_unmap() will return -1 and set errno to the following
     value:

     [EINVAL]       The specified addr parameter was not a valid
                    segment start address of the eti shared
                    memory segment.

SEE ALSO
     iconnect(2), spl(3C), eti(7)






















Page 3                        CX/UX Programmer's Reference Manual