Design for the 'configuration through a device file' task

This text deals with configuring syscalltrack through a device
file. 

To configure (add/delete/enable/disable rules) the client (user space
configuration utility) opens the device file, and writes to it a request
packet[1]. The server (kernel module) takes appropriate action and
prepares a response packet[2]. The client then reads the response
packet and closes the device file. 

___protocol description___

client: 
	open the device file for read/write
server: 
	mark that the device file is open for write -  fail all other
	     open requests. 
	clear internal 'request buffer' and 'response packet'. 
client:
	write the request packet to the device file.
server:
	copy the request packet to the request buffer. if the client
	issues multiple 'write' calls, write them one after another on
	the buffer. if the client is about to overflow the buffer,
	return ENOSPC. once the entire packet is written:
		check that the packet is valid
		if it is, take appropriate action
	prepare a response packet
client:
	read the 'response packet' from the device file
	close the device file

It should be noted that the request/response packets have exactly the
same structure. 

___request packet contents___

The exact definitions and constants can be found in
sct_rules_module/module_interface.h

/* the requests exchanged between userspace and kernelspace have this */ 
/* format. note - the data field is actually *inline* in the request, */
/* so when reading it from the device file, you can't use this structure */ 
/* "as is" to read from the device, although that's a bad idea anyway */ 
/* (think field ordering and padding */
typedef struct dev_request_type {
	/* prefix */ 
	unsigned int size;    /* packet size */
	unsigned int id;      /* packet id */ 
	unsigned int cmd;     /* packet command, possibly or'd with REPLY */ 

	/* data */ 
	int result;           /* operation result - one of the error code above */ 
	unsigned int data_sz; /* data size */ 
	unsigned char* data;  /* pointer to data */ 
	
	/* sufix */ 
	int magic;            /* magic people, voodoo people*/ 
} dev_req_t; 

each request packet contains these fields, in this order:

[1] SIZE:	unsigned int
[2] ID		unsigned int
[3] CMD:	unsigned int
[4] RESULT:	int
[5] DATA_SZ:	unsigned int
[6] DATA:	unsigned char array of length DATA_SZ
[7] MAGIC:	int

[1] PACKET_SIZE:	

The total size of this packet, in bytes. This should include the size
of the data field. see update_size() in sct_ctrl_lib for the actual
calculation. 

[2] PACKET_ID:
    
The id of this packet - client is free to choose whatever id it
wants. The kernel should reply with the *same* ID. 

[3] CMD

This field identifies this request as one of the following:

#define	CTL_TRACKER_ADD_RULE		        1
#define	CTL_TRACKER_DEL_RULE		        2
#define	CTL_TRACKER_ENABLE_RULE		        3
#define	CTL_TRACKER_DISABLE_RULE	        4
#define	CTL_TRACKER_DEL_ALL_RULES_FOR_SYSCALL	5
#define CTL_TRACKER_DEL_ALL_MODULE_RULES        6
#define CTL_TRACKER_PRINT_ALL_RULES             7
#define CTL_TRACKER_CMD_GET_ALL_RULES           8              
#define CTL_TRACKER_CMD_GET_ALL_RULE_COUNT      9

When this packet is a response to a former request, this field will be
bitwise OR'd with the constant REPLY. 

[4] RESULT: 

When this packet is a request, this field should be 0. When it's a
reply, this field is set to one of the following values:

#define	CTL_TRACKER_SUCCESS			0

the operation was succesfull. 

#define CTL_TRACKER_EINVAL			1

the 'request packet' is invalid

#define	CTL_TRACKER_ENOMEM			2

the kernel could not allocate memory 

#define	CTL_TRACKER_EINTR			3

performing the request was interrupted - the client should
try again. 

#define CTL_TRACKER_ENOSYS			4

no such syscall (invalid syscall_id parameter)

#define CTL_TRACKER_ESYSUNSUP			5

this syscall is not supported at the moment

#define CTL_TRACKER_ENOENT			6

no such tracking rule

#define CTL_TRACKR_EBADTRACKINGRULE		7

the tracking rule could not be deserialized

[5] DATA_SZ:

For packets which have a DATA field, this field should be the length
(in bytes!) of the data field. For packets with no data field, this
field MUST be 0. 

[6] DATA:

For packets which have data, this field contained the data. Packets
such as there are the 'add rule' request, and the 'get rule count' and
'get rules' responses. 

[7] COOKIE:

This field must be set to the constant DEV_FILE_MAGIC_COOKIE. 

-- 
$Id: sct_device_control_file_design.txt,v 1.6 2002/06/25 20:31:51 mulix Exp $