msgq.h

USb in User space, a kernel module that use usb layer

/*
 * msgq.h
 *
 * Author : Lionetti Salvatore <[e-mail]>
 * License: GPL
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 */
/* dataQ_T object is use to simply hold msg (variable length data) or stream of bytes.
 * 
 * msg is an entity created 'atomically' (like UDP) by user write().
 * 
 * PACKET mode for WRITE:
 * We write 1 msg, only if have enough space.
 *
 * PACKET mode for READ:
 * We read 1 msg@time, if user call with len<msgLen, we return 0.
 *
 * Possible scenario:
 *	Read	Write
 *	==============
 * 	STREAM	STREAM
 * 	STREAM	PACKET
 * 	PACKET	PACKET
 * 	
 * 	PACKET	STREAM	is !possible: only write can define a msg.
 * 	
 * So, for example usb subsystem, can store msg in this struct
 * letting user know len of single msg, that can be useful. 
 * However we let user read in a 'stream way' so spar[] is provided in struct.
 *
 * PACKET/STREAM mode could be changed@runtime, either for read(), write(), es:
 * 	WriteMsg(a) 	WriteStream(b) WriteStream(c) WriteStream(d) WriteMsg(e)
 *
 * 	will produce:
 *	-------------------------------------------------------------------------
 * 	| len | a  	| len | 	b 	c 	d	| len | e 	| 
 * 	-------------------------------------------------------------------------
 * 
 * Defaul is STREAM for READ,
 * 	     PACKET for WRITE (so if !enough space available, no partial data will result).
 * As internal index we choice int in order to easily move between buffers.
 *
 * TODO: 1) msg metadata separated by char* data so destination can also be fileDescriptor,...
 * 	 2) extend read() extending enum dataQ_dataOrgT and using complete() function.
 * 	 3) changing@runtime PACKET, STREAM.*/

enum dataQ_dataOrgT {STREAM, PACKET};
/* enum {ZEROCOPY, FULLCOPY} dataQ_dataGetT; !needed because interface was different.
 * 					     Caller must change code.*/
enum AddrSpaceT {KERN, USER};
struct dataQ_T {
	enum dataQ_dataOrgT dataOrgWrite;
	enum dataQ_dataOrgT dataOrgRead[5];
	int spar[5];	/* To write also in stream way.*/
	int curr[5]; 	/* max 5 readers,*/
	int curw;	/* 1 writer.*/

	char* data;
	int len;
	
	/* statistical info.*/
	int lostR;
	int lostW;

	/* Customer info, just to simplify code.
	 * This object never touch such a value.*/
	void* context;

	/* To avoid extra coping.*/
	enum AddrSpaceT rdSrc, rdDst;
	enum AddrSpaceT wrSrc, wrDst;

};

void initQ(struct dataQ_T *q, char *buf, int len);
void copyQ(struct dataQ_T *q, struct dataQ_T *q2copy);
int spaceQ(struct dataQ_T *q);
void reseQ(struct dataQ_T *q);
/*
 * writeQ(): return number of bytes delivered.
 * 	>0 some bytes written,
 * 	0  no bytes written
 * 	<0 some error occur.
 *
 * PACKET mode: write exactly len bytes or nothing.
 * STREAM mode: write as many bytes we can.
 */
int writeQ(struct dataQ_T *q, char *buf, int len);
int availQ(struct dataQ_T* q, int whoR);
/* 
 * readQ(): return number of bytes readed.
 *
 * PACKET mode: read a msg | return 0 (-EAGAIN?);
 * STREAM mode: read as many bytes we can
 * read at most len bytes.
 * Do a copy.
 *
 * return error only if some assertion fail.
 */
int readQ(struct dataQ_T *q, int whoR, char *buf, int len);
/* 
 * read at most len bytes.
 * Only return pointer.
 */
int readQ_0C(struct dataQ_T *q, int whoR, char **buf, int len);
/* !yet used.*/
int dumpQ(struct dataQ_T *q, char* buf, int len);
void testQ(void);