strsubr.h revision 9acbbeaf2a1ffe5c14b244867d427714fab43c5c
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/* Copyright (c) 1984, 1986, 1987, 1988, 1989 AT&T */
/* All Rights Reserved */
/*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _SYS_STRSUBR_H
#define _SYS_STRSUBR_H
#pragma ident "%Z%%M% %I% %E% SMI" /* SVr4.0 1.17 */
/*
* WARNING:
* Everything in this file is private, belonging to the
* STREAMS subsystem. The only guarantee made about the
* contents of this file is that if you include it, your
* code will not port to the next release.
*/
#ifdef __cplusplus
extern "C" {
#endif
/*
* In general, the STREAMS locks are disjoint; they are only held
* locally, and not simultaneously by a thread. However, module
* code, including at the stream head, requires some locks to be
* acquired in order for its safety.
* 1. Stream level claim. This prevents the value of q_next
* from changing while module code is executing.
* 2. Queue level claim. This prevents the value of q_ptr
* from changing while put or service code is executing.
* In addition, it provides for queue single-threading
* for QPAIR and PERQ MT-safe modules.
* 3. Stream head lock. May be held by the stream head module
* Note: that the only types of twisted stream supported are
* the pipe and transports which have read and write service
* procedures on both sides of the twist.
* 4. Queue lock. May be acquired by utility routines on
* behalf of a module.
*/
/*
* In general, sd_lock protects the consistency of the stdata
* structure. Additionally, it is used with sd_monitor
* the following fields:
* sd_iocblk
* sd_flag
* sd_copyflag
* sd_iocid
* sd_iocwait
* sd_sidp
* sd_pgidp
* sd_wroff
* sd_tail
* sd_rerror
* sd_werror
* sd_pushcnt
* sd_sigflags
* sd_siglist
* sd_pollist
* sd_mark
* sd_closetime
* sd_wakeq
* sd_uiordq
* sd_uiowrq
* sd_maxblk
*
* The following fields are modified only by the allocator, which
* has exclusive access to them at that time:
* sd_wrq
* sd_strtab
*
* The following field is protected by the overlying file system
* code, guaranteeing single-threading of opens:
* sd_vnode
*
* Stream-level locks should be acquired before any queue-level locks
* are acquired.
*
* The stream head write queue lock(sd_wrq) is used to protect the
* fields qn_maxpsz and qn_minpsz because freezestr() which is
* necessary for strqset() only gets the queue lock.
*/
/*
* Function types for the parameterized stream head.
* The msgfunc_t takes the parameters:
* msgfunc(vnode_t *vp, mblk_t *mp, strwakeup_t *wakeups,
* strsigset_t *firstmsgsigs, strsigset_t *allmsgsigs,
* strpollset_t *pollwakeups);
* It returns an optional message to be processed by the stream head.
*
* The parameters for errfunc_t are:
* errfunc(vnode *vp, int ispeek, int *clearerr);
* It returns an errno and zero if there was no pending error.
*/
typedef uint_t strwakeup_t;
typedef uint_t strsigset_t;
typedef short strpollset_t;
typedef uintptr_t callbparams_id_t;
/*
* Per stream sd_lock in putnext may be replaced by per cpu stream_putlocks
* each living in a separate cache line. putnext/canputnext grabs only one of
* stream_putlocks while strlock() (called on behalf of insertq()/removeq())
* acquires all stream_putlocks. Normally stream_putlocks are only employed
* for highly contended streams that have SQ_CIPUT queues in the critical path
*
* stream_putlocks are dynamically assigned to stdata structure through
* sd_ciputctrl pointer possibly when a stream is already in use. Since
* strlock() uses stream_putlocks only under sd_lock acquiring sd_lock when
* assigning stream_putlocks to the stream ensures synchronization with
* strlock().
*
* For lock ordering purposes stream_putlocks are treated as the extension of
* sd_lock and are always grabbed right after grabbing sd_lock and released
* right before releasing sd_lock except putnext/canputnext where only one of
* stream_putlocks locks is used and where it is the first lock to grab.
*/
typedef struct ciputctrl_str {
union _ciput_un {
struct _ciput_str {
} ciput_str;
} ciput_un;
} ciputctrl_t;
/*
* Header for a stream: interface to rest of system.
*/
typedef struct stdata {
/* compatibility */
int sd_rerror; /* error to return on read ops */
int sd_werror; /* error to return on write ops */
int sd_pushcnt; /* number of pushes done on stream */
int sd_sigflags; /* logical OR of all siglist events */
/* the stream head so we don't have */
/* to ask the module below the stream */
/* head to get this information. */
int sd_refcnt; /* number of claimstr */
char sd_struiodnak; /* defer NAK of M_IOCTL by rput() */
/*
* support for low contention concurrent putnext.
*/
int sd_anchor; /* position of anchor in stream */
/*
* Service scheduling at the stream head.
*/
void *sd_servid; /* Service ID for bckgrnd schedule */
short sd_nqueues; /* Number of queues in the list */
} stdata_t;
/*
* stdata servicing flags.
*/
#define STRS_WILLSERVICE 0x01
#define STRS_SCHEDULED 0x02
/*
* stdata flag field defines
*/
/* NDELAY reads and writes */
/* 0x00020000 unused */
/* 0x00040000 unused */
/* 0x00100000 unused */
/* 0x00200000 unused */
/*
* Copy-related flags (sd_copyflag), set by SO_COPYOPT.
*/
/* pages instead of bcopy */
/*
* Options and flags for strrput (sd_rput_opt)
*/
/*
*/
/*
* Options and flags for strread (sd_read_opt)
*/
/* retain data blocks */
/*
* Flags parameter for strsetrputhooks() and strsetwputhooks().
* These flags define the interface for setting the above internal
* flags in sd_rput_opt and sd_wput_opt.
*/
/*
* Each queue points to a sync queue (the inner perimeter) which keeps
* track of the number of threads that are inside a given queue (sq_count)
* and also is used to implement the asynchronous putnext
* (by queuing messages if the queue can not be entered.)
*
* b_queue recording the queue and b_prev recording the function to
* be called (either the put procedure or a qwriter callback function.)
*
* The sq_count counter tracks the number of threads that are
* executing inside the perimeter or (in the case of outer perimeters)
* have some work queued for them relating to the perimeter. The sq_rmqcount
* counter tracks the subset which are in removeq() (usually invoked from
* qprocsoff(9F)).
*
* In addition a module writer can declare that the module has an outer
* perimeter (by setting D_MTOUTPERIM) in which case all inner perimeter
* syncq's for the module point (through sq_outer) to an outer perimeter
* syncq. The outer perimeter consists of the doubly linked list (sq_onext and
* sq_oprev) linking all the inner perimeter syncq's with out outer perimeter
* syncq. This is used to implement qwriter(OUTER) (an asynchronous way of
* getting exclusive access at the outer perimeter) and outer_enter/exit
* which are used by the framework to acquire exclusive access to the outer
* perimeter during open and close of modules that have set D_MTOUTPERIM.
*
* In the inner perimeter case sq_save is available for use by machine
* the inner perimeter syncqs and to queue become_writer requests on the
* outer perimeter syncqs.
*
* Note: machine dependent optimized versions of putnext may depend
* on the order of sq_flags and sq_count (so that they can e.g.
* read these two fields in a single load instruction.)
*
* sq_putlocks/sq_putcounts each living in a separate cache line. Obviously
* of sq_putlocks and update only 1 of sq_putcounts. strlock() and many
* SQLOCK) and figure out the count value as the sum of sq_count and all of
* sq_putcounts. The idea is to make critical fast path -- putnext -- much
* faster at the expense of much less often used slower path like
* there's no need to grab multiple sq_putlocks and look at sq_putcounts. See
* strsubr.c for more comments.
*
* Note regular SQLOCK and sq_count are still used in many routines
* (e.g. entersq(), rwnext()) in the same way as before sq_putlocks were
* introduced.
*
* To understand when all sq_putlocks need to be held and all sq_putcounts
* need to be added up one needs to look closely at putnext code. Basically if
* a routine like e.g. wait_syncq() needs to be sure that perimeter is empty
* all sq_putlocks/sq_putcounts need to be held/added up. On the other hand
* there's no need to hold all sq_putlocks and count all sq_putcounts in
* routines like leavesq()/dropsq() and etc. since the are usually exit
* counterparts of entersq/outer_enter() and etc. which have already either
* prevented put entry poins from executing or did not care about put
* entrypoints. entersq() doesn't need to care about sq_putlocks/sq_putcounts
* if the entry point has a shared access since put has the highest degree of
* concurrency and such entersq() does not intend to block out put
* entrypoints.
*
* Before sq_putcounts were introduced the standard way to wait for perimeter
* to become empty was:
*
* mutex_enter(SQLOCK(sq));
* while (sq->sq_count > 0) {
* sq->sq_flags |= SQ_WANTWAKEUP;
* cv_wait(&sq->sq_wait, SQLOCK(sq));
* }
* mutex_exit(SQLOCK(sq));
*
* The new way is:
*
* mutex_enter(SQLOCK(sq));
* count = sq->sq_count;
* SQ_PUTLOCKS_ENTER(sq);
* SUM_SQ_PUTCOUNTS(sq, count);
* while (count != 0) {
* sq->sq_flags |= SQ_WANTWAKEUP;
* SQ_PUTLOCKS_EXIT(sq);
* cv_wait(&sq->sq_wait, SQLOCK(sq));
* count = sq->sq_count;
* SQ_PUTLOCKS_ENTER(sq);
* SUM_SQ_PUTCOUNTS(sq, count);
* }
* SQ_PUTLOCKS_EXIT(sq);
* mutex_exit(SQLOCK(sq));
*
* Note that SQ_WANTWAKEUP is set before dropping SQ_PUTLOCKS. This makes sure
* putnext won't skip a wakeup.
*
* sq_putlocks are treated as the extension of SQLOCK for lock ordering
* purposes and are always grabbed right after grabbing SQLOCK and released
* right before releasing SQLOCK. This also allows dynamic creation of
* sq_putlocks while holding SQLOCK (by making sq_ciputctrl non null even when
* the stream is already in use). Only in putnext one of sq_putlocks
* is grabbed instead of SQLOCK. putnext return path remembers what counter it
* incremented and decrements the right counter on its way out.
*/
struct syncq {
/*
* Distributed syncq scheduling
* The list of queue's is handled by sq_head and
* sq_tail fields.
*
* The list of events is handled by the sq_evhead and sq_evtail
* fields.
*/
/*
* Concurrency and condition variables
*/
/* inner perimeter */
/*
* Handling synchronous callbacks such as qtimeout and qbufcall
*/
/*
* Links forming an outer perimeter from one outer syncq and
* a set of inner sync queues.
*/
/*
* support for low contention concurrent putnext.
*/
/*
* Counter for the number of threads wanting to become exclusive.
*/
/*
* These two fields are used for scheduling a syncq for
* background processing. The sq_svcflag is protected by
* SQLOCK lock.
*/
void * sq_servid;
/*
* Maximum priority of the queues on this syncq.
*/
};
/*
* sync queue scheduling flags (for sq_svcflags).
*/
/*
*/
#define SQ_FASTPUT 0x8000
#define SQ_FASTMASK 0x7FFF
/*
* sync queue state flags
*/
/* perimeter */
#define SQ_FLAGMASK 0x00FF
/*
* Test a queue to see if inner perimeter is exclusive.
*/
/*
* If any of these flags are set it is not possible for a thread to
* enter a put or service procedure. Instead it must either block
* or put the message on the syncq.
*/
/*
* If any of these flags are set it not possible to drain the syncq
*/
/*
* Flags to trigger syncq tail processing.
*/
/*
* Syncq types (stored in sq_type)
* The SQ_TYPES_IN_FLAGS (ciput) are also stored in sq_flags
* for performance reasons. Thus these type values have to be in the low
* 16 bits and not conflict with the sq_flags values above.
*
* Notes:
* - putnext() and put() assume that the put procedures have the highest
* degree of concurrency. Thus if any of the SQ_CI* are set then SQ_CIPUT
* has to be set. This restriction can be lifted by adding code to putnext
* and put that check that sq_count == 0 like entersq does.
* - putnext() and put() does currently not handle !SQ_COPUT
* - In order to implement !SQ_COCB outer_enter has to be fixed so that
* the callback can be cancelled while cv_waiting in outer_enter.
* - If SQ_CISVC needs to be implemented, qprocsoff() needs to wait
* for the currently running services to stop (wait for QINSERVICE
* to go off). disable_svc called from qprcosoff disables only
* services that will be run in future.
*
* All the SQ_CO flags are set when there is no outer perimeter.
*/
/* Types also kept in sq_flags for performance */
#define SQ_TYPES_IN_FLAGS (SQ_CIPUT)
/*
* Flag combinations passed to entersq and leavesq to specify the type
* of entry point.
*/
/*
* Other syncq types which are not copied into flags.
*/
/*
* Asynchronous callback qun*** flag.
* The mechanism these flags are used in is one where callbacks enter
* the perimeter thanks to framework support. To use this mechanism
* the q* and qun* flavors of the callback routines must be used.
* e.g. qtimeout and quntimeout. The synchronization provided by the flags
* avoids deadlocks between blocking qun* routines and the perimeter
* lock.
*/
/*
* Cancel callback mask.
* The mask expands as the number of cancelable callback types grows
* Note - separate callback flag because different callbacks have
* overlapping id space.
*/
typedef struct callbparams {
void (*cbp_func)(void *);
void *cbp_arg;
struct callbparams *cbp_next;
typedef struct strbufcall {
void (*bc_func)(void *);
void *bc_arg;
struct strbufcall *bc_next;
} strbufcall_t;
/*
* on request. The valid S_* events are defined in stropts.h.
*/
typedef struct strsig {
int ss_events; /* S_* events */
} strsig_t;
/*
* bufcall list
*/
struct bclist {
};
/*
* Structure used to track mux links and unlinks.
*/
struct mux_node {
};
/*
* Flags for mux_nodes.
*/
#define VISITED 1
/*
* Edge structure - a list of these is hung off the
* mux_node to represent the outgoing edges.
*/
struct mux_edge {
int me_muxid; /* id of link */
};
/*
* Queue info
*
* The syncq is included here to reduce memory fragmentation
* for kernel memory allocators that only allocate in sizes that are
* powers of two. If the kernel memory allocator changes this should
* be revisited.
*/
typedef struct queinfo {
} queinfo_t;
/*
* Multiplexed streams info
*/
typedef struct linkinfo {
} linkinfo_t;
/*
* List of syncq's used by freeezestr/unfreezestr
*/
typedef struct syncql {
} syncql_t;
typedef struct sqlist {
} sqlist_t;
typedef struct perdm {
} perdm_t;
/*
* fmodsw_impl_t is used within the kernel. fmodsw is used by
*/
typedef struct fmodsw_impl fmodsw_impl_t;
struct fmodsw_impl {
};
typedef enum {
FMODSW_HOLD = 0x00000001,
FMODSW_LOAD = 0x00000002
typedef struct cdevsw_impl {
/*
* Enumeration of the types of access that can be requested for a
* controlling terminal under job control.
*/
enum jcaccess {
JCREAD, /* read data on a ctty */
JCWRITE, /* write data to a ctty */
JCSETP, /* set ctty parameters */
JCGETP /* get ctty parameters */
};
/*
* Finding related queues
*/
/*
* Locking macros
*/
#define STREAM_PUTLOCKS_ENTER(stp) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
#define STREAM_PUTLOCKS_EXIT(stp) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
#define SQ_PUTLOCKS_ENTER(sq) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
#define SQ_PUTLOCKS_EXIT(sq) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
#define SQ_PUTCOUNT_SETFAST(sq) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
#define SQ_PUTCOUNT_CLRFAST(sq) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
#ifdef DEBUG
#define SQ_PUTLOCKS_HELD(sq) { \
int i; \
for (i = 0; i <= nlocks; i++) { \
} \
} \
}
int i; \
for (i = 0; i <= ncounts; i++) { \
count += \
SQ_FASTMASK); \
} \
} \
}
int i; \
for (i = 0; i <= (nciput); i++) { \
SQ_FASTMASK); \
} \
}
#else /* DEBUG */
#define SQ_PUTLOCKS_HELD(sq)
#endif /* DEBUG */
int i; \
for (i = 0; i <= ncounts; i++) { \
SQ_FASTMASK); \
} \
} \
}
/*
* syncq message manipulation macros.
*/
/*
* Put a message on the queue syncq.
* Assumes QLOCK held.
*/
{ \
qp->q_syncqmsgs++; \
} else { \
} \
}
/*
* Miscellaneous parameters and flags.
*/
/*
* Default timeout in milliseconds for ioctls and close
*/
#define STRTIMOUT 15000
/*
* Flag values for stream io
*/
/*
* These flags need to be unique for stream io name space
* and copy modes name space. These flags allow strwaitq
* and strdoioctl to proceed as if signals or errors on the stream
* head have not occurred; i.e. they will be detected by some other
* means.
* STR_NOSIG does not allow signals to interrupt the call
* STR_NOERROR does not allow stream head read, write or hup errors to
* affect the call. When used with strdoioctl(), if a previous ioctl
* is pending and times out, STR_NOERROR will cause strdoioctl() to not
* return ETIME. If, however, the requested ioctl times out, ETIME
* will be returned (use ic_timout instead)
* STR_PEEK is used to inform strwaitq that the reader is peeking at data
* and that a non-persistent error should not be cleared.
* STR_DELAYERR is used to inform strwaitq that it should not check errors
* after being awoken since, in addition to an error, there might also be
* data queued on the stream head read queue.
*/
/*
* Copy modes for tty and I_STR ioctls
*/
/*
* Mux defines.
*/
/*
* Definitions of Streams macros and function interfaces.
*/
/*
* Obsolete queue scheduling macros. They are not used anymore, but still kept
* here for 3-d party modules and drivers who might still use them.
*/
#define setqsched()
#define qready() 1
#ifdef _KERNEL
#define runqueues()
#define queuerun()
#endif
/* compatibility module for style 2 drivers with DR race condition */
#define DRMODNAME "drcompat"
/*
* Macros dealing with mux_nodes.
*/
((X)->mn_originp = NULL)
/*
* Twisted stream macros
*/
mutex_enter(&((X)->sd_lock)); \
} else { \
mutex_enter(&((X)->sd_lock)); \
}
#ifdef _KERNEL
extern void strinit(void);
cred_t *, int *);
extern void mux_rmvedge(stdata_t *, int);
uint32_t *);
int *, int, rval_t *);
extern int strstartplumb(struct stdata *, int, int);
extern void strendplumb(struct stdata *);
struct pollhead **);
extern void str_cn_clean(); /* XXX hook for consoles signal cleanup */
extern int getiocseqno(void);
extern int strwaitbuf(size_t, int);
extern int strcopyout(void *, void *, size_t, int);
extern void disable_svc(queue_t *);
extern void remove_runlist(queue_t *);
extern void qenable_locked(queue_t *);
extern void strunblock(queue_t *);
extern void releasestr(queue_t *);
extern void drain_syncq(syncq_t *);
extern void wait_sq_svc(syncq_t *);
extern void outer_exit(syncq_t *);
void *, int);
extern void qcallbwrapper(void *);
extern void stream_willservice(stdata_t *);
extern void stream_runservice(stdata_t *);
extern void strpollwakeup(vnode_t *, short);
extern int putnextctl_wait(queue_t *, int);
unsigned char, int, int);
extern void strflushrq(vnode_t *, int);
extern int strwaitmark(vnode_t *);
struct multidata_s;
struct pdesc_s;
struct pdesc_s *);
extern int fmodsw_register(const char *, struct streamtab *, int);
extern int fmodsw_unregister(const char *);
extern void fmodsw_rele(fmodsw_impl_t *);
extern void freemsgchain(mblk_t *);
/*
* shared or externally configured data structures
*/
extern int nstrpush; /* maximum number of pushes allowed */
/*
* Bufcalls related variables.
*/
extern struct kmem_cache *ciputctrl_cache;
extern int n_ciputctrl;
extern int max_n_ciputctrl;
extern int min_n_ciputctrl;
extern cdevsw_impl_t *devimpl;
#endif /* _KERNEL */
/*
* intended for the STREAMS framework.
*
* Finding related queues
*/
/*
*/
/*
* The following hardware checksum related macros are private
* interfaces that are subject to change without notice.
*/
#ifdef _KERNEL
#endif /* _KERNEL */
#ifdef __cplusplus
}
#endif
#endif /* _SYS_STRSUBR_H */