From: ppisa <ppisa>
Date: Mon, 1 Sep 2003 01:16:16 +0000 (+0000)
Subject: LinCAN driver major structured comments and documentation update
X-Git-Tag: CLT_COMM_CAN_pre_canmsg_change~24
X-Git-Url: http://rtime.felk.cvut.cz/gitweb/lincan.git/commitdiff_plain/3129fcd8094edcb910b708463fdf1a234f11fb55

LinCAN driver major structured comments and documentation update
---

diff --git a/lincan/include/can.h b/lincan/include/can.h
index e310732..344dcf6 100644
--- a/lincan/include/can.h
+++ b/lincan/include/can.h
@@ -10,6 +10,19 @@
 
 #define CAN_MSG_LENGTH 8
 
+/**
+ * struct canmsg_t - structure representing CAN message
+ * @flags:  message flags, %MSG_RTR .. message is Remote Transmission Request,
+ *	%MSG_EXT .. message with extended ID, %MSG_OVR indication of queue
+ *	overflow condition
+ * @cob:    communication object number (not used)
+ * @id:     ID of CAN message
+ * @timestamp: not used
+ * @length: length of used data
+ * @data:   data bytes buffer
+ *
+ * Header: can.h
+ */
 struct canmsg_t {
 	short		flags;
 	int		cob;
diff --git a/lincan/include/can_queue.h b/lincan/include/can_queue.h
index bf092cd..51f1d9b 100644
--- a/lincan/include/can_queue.h
+++ b/lincan/include/can_queue.h
@@ -29,7 +29,7 @@
 /**
  * struct canque_slot_t - one CAN message slot in the CAN FIFO queue 
  * @next: pointer to the next/younger slot
- * @mrs_do_inp: space for flags and optional command describing action
+ * @slot_flags: space for flags and optional command describing action
  *	associated with slot data
  * @msg: space for one CAN message
  *
@@ -57,7 +57,7 @@
  * @head: pointer to the FIFO head, oldest slot
  * @tail: pointer to the location, where pointer to newly inserted slot
  *	should be added
- * @tail: pointer to the location, where pointer to newly inserted slot
+ * @flist: pointer to list of the free slots associated with queue
  * @entry: pointer to the memory allocated for the list slots.
  * @fifo_lock: the lock to ensure atomicity of slot manipulation operations.
  *
@@ -278,7 +278,7 @@ struct msgobj_t;
 struct chip_t;
 
 /**
- * canque_edge_t - CAN message delivery subsystem graph edge
+ * struct canque_edge_t - CAN message delivery subsystem graph edge
  * @fifo: place where primitive @struct canque_fifo_t FIFO is located.
  * @filtid: the possible CAN message identifiers filter.
  * @filtmask: the filter mask, the comparison considers only
@@ -292,6 +292,10 @@ struct chip_t;
  * @edge_used: the atomic usage counter, mainly used for safe destruction of the edge.
  * @edge_prio: the assigned queue priority from the range 0 to %CANQUEUE_PRIO_NR-1
  * @edge_num: edge sequential number intended for debugging purposes only
+ *
+ * This structure represents one direction connection from messages source 
+ * (@inends) to message consumer (@outends) fifo ends hub. The edge contains
+ * &struct canque_fifo_t for message fifo implementation.
  */
 struct canque_edge_t {
 	struct canque_fifo_t fifo;
@@ -307,7 +311,7 @@ struct canque_edge_t {
 };
 
 /**
- * canque_edge_t - CAN message delivery subsystem graph vertex (FIFO ends)
+ * struct canque_ends_t - CAN message delivery subsystem graph vertex (FIFO ends)
  * @active: the array of the lists of active edges directed to the ends structure
  *	with ready messages. The array is indexed by the edges priorities. 
  * @idle: the list of the edges directed to the ends structure with empty FIFOs.
@@ -320,9 +324,17 @@ struct canque_edge_t {
  *	%CANQUEUE_NOTIFY_PROC  (in->out call) - empty state negated => out side is requested to process slots.
  *	%CANQUEUE_NOTIFY_NOUSR (both) - notify, that the last user has released the edge usage
  *		called with some lock to prevent edge disappear.
+ *	%CANQUEUE_NOTIFY_DEAD  (both) - edge is in progress of deletion.
+ *	%CANQUEUE_NOTIFY_ATACH (both) - new edge has been attached to end.
+ *	%CANQUEUE_NOTIFY_FILTCH (out->in call) - edge filter rules changed
+ *	%CANQUEUE_NOTIFY_ERROR  (out->in call) - error in messages processing.
  * @context: space to store ends user specific information
  * @endinfo: space to store some other ends usage specific informations
  *	mainly for waking-up by the notify calls.
+ *
+ * Structure represents place to connect edges to for CAN communication entity.
+ * The zero, one or more incoming and outgoing edges can be connected to
+ * this structure.
  */
 struct canque_ends_t {
 	struct list_head active[CANQUEUE_PRIO_NR];
@@ -357,6 +369,11 @@ struct canque_ends_t {
 #define CANQUEUE_NOTIFY_ERRTX_SEND 0x11002 /* tx send error */
 #define CANQUEUE_NOTIFY_ERRTX_BUS  0x11003 /* tx bus error */
 
+/**
+ * canque_notify_inends - request to send notification to the input ends
+ * @qedge: pointer to the edge structure
+ * @what: notification type
+ */
 static inline
 void canque_notify_inends(struct canque_edge_t *qedge, int what)
 {
@@ -365,6 +382,11 @@ void canque_notify_inends(struct canque_edge_t *qedge, int what)
 			qedge->inends->notify(qedge->inends,qedge,what);
 }
 
+/**
+ * canque_notify_outends - request to send notification to the output ends
+ * @qedge: pointer to the edge structure
+ * @what: notification type
+ */
 static inline
 void canque_notify_outends(struct canque_edge_t *qedge, int what)
 {
@@ -373,6 +395,11 @@ void canque_notify_outends(struct canque_edge_t *qedge, int what)
 			qedge->outends->notify(qedge->outends,qedge,what);
 }
 
+/**
+ * canque_notify_bothends - request to send notification to the both ends
+ * @qedge: pointer to the edge structure
+ * @what: notification type
+ */
 static inline
 void canque_notify_bothends(struct canque_edge_t *qedge, int what)
 {
@@ -380,6 +407,14 @@ void canque_notify_bothends(struct canque_edge_t *qedge, int what)
 	canque_notify_outends(qedge, what);
 }
 
+/**
+ * canque_activate_edge - mark output end of the edge as active
+ * @qedge: pointer to the edge structure
+ * @inends: input side of the edge
+ *
+ * Function call moves output side of the edge from idle onto active edges
+ * list.
+ */
 static inline
 void canque_activate_edge(struct canque_ends_t *inends, struct canque_edge_t *qedge)
 {
diff --git a/lincan/include/main.h b/lincan/include/main.h
index c6a0741..17e8f55 100644
--- a/lincan/include/main.h
+++ b/lincan/include/main.h
@@ -43,6 +43,13 @@
    #define IRQ_RETVAL(x)
 #endif /* <=2.5.67 */
 
+/**
+ * struct canhardware_t - structure representing pointers to all CAN boards
+ * @nr_boards: number of present boards
+ * @rtr_queue: RTR - remote transmission request queue (expect some changes there)
+ * @rtr_lock: locking for RTR queue
+ * @candevice: array of pointers to CAN devices/boards
+ */
 struct canhardware_t {
 	int nr_boards;
 	struct rtr_id *rtr_queue;
@@ -50,6 +57,36 @@ struct canhardware_t {
 	struct candevice_t *candevice[MAX_HW_CARDS];
 };
 
+/**
+ * struct candevice_t - CAN device/board structure
+ * @hwname: text string with board type
+ * @candev_idx: board index in canhardware_t.candevice[]
+ * @io_addr: IO/physical MEM address
+ * @res_addr: optional reset register port
+ * @dev_base_addr: CPU translated IO/virtual MEM address
+ * @flags: board flags: %PROGRAMMABLE_IRQ .. interrupt number
+ *	can be programmed into board
+ * @nr_all_chips: number of chips present on the board
+ * @nr_82527_chips: number of Intel 8257 chips 
+ * @nr_sja1000_chips: number of Philips SJA100 chips
+ * @chip: array of pointers to the chip structures
+ * @hwspecops: pointer to board specific operations
+ * @hosthardware_p: pointer to the root hardware structure
+ *
+ * The structure represent configuration and state of associated board.
+ * The driver infrastructure prepares this structure and calls
+ * board type specific board_register() function. The board support provided
+ * register function fills right function pointers in @hwspecops structure.
+ * Then driver setup calls functions init_hw_data(), init_chip_data(),
+ * init_chip_data(), init_obj_data() and program_irq(). Function init_hw_data()
+ * and init_chip_data() have to specify number and types of connected chips
+ * or objects respectively.
+ * The use of @nr_all_chips is preferred over use of fields @nr_82527_chips
+ * and @nr_sja1000_chips in the board non-specific functions.
+ * The @io_addr and @dev_base_addr is filled from module parameters
+ * to the same value. The request_io function can fix-up @dev_base_addr
+ * field if virtual address is different than bus address.
+ */
 struct candevice_t {
 	char *hwname;			/* text board type */
 	int candev_idx;			/* board index in canhardware_t.candevice[] */
@@ -57,10 +94,6 @@ struct candevice_t {
 	unsigned long res_addr;		/* optional seset register port */
 	unsigned long dev_base_addr;	/* CPU translated IO/virtual MEM address */
 	unsigned int flags;
-
-	/* Hardware chip configuration. In case of multiple chips *chip
-	 * is the first in an array of chip_t structures.
-	 */
 	int nr_all_chips;
 	int nr_82527_chips;
 	int nr_sja1000_chips;
@@ -71,48 +104,65 @@ struct candevice_t {
 	struct canhardware_t *hosthardware_p;
 };
 
+/**
+ * struct chip_t - CAN chip state and type information
+ * @chip_type: text string describing chip type
+ * @chip_idx: index of the chip in candevice_t.chip[] array
+ * @chip_irq: chip interrupt number if any
+ * @chip_base_addr: chip base address in the CPU IO or virtual memory space
+ * @flags: chip flags: %CHIP_CONFIGURED .. chip is configured,
+ *	%CHIP_SEGMENTED .. access to the chip is segmented (mainly for i82527 chips)
+ * @clock: chip base clock frequency in Hz
+ * @write_register: write chip register function copy -
+ * @read_register: read chip register function copy
+ * @sja_cdr_reg: SJA specific register -
+ *	holds hardware specific options for the Clock Divider
+ *	register. Options defined in the sja1000.h file:
+ *	%CDR_CLKOUT_MASK, %CDR_CLK_OFF, %CDR_RXINPEN, %CDR_CBP, %CDR_PELICAN
+ * @sja_ocr_reg: SJA specific register -
+ *	hold hardware specific options for the Output Control
+ *	register. Options defined in the sja1000.h file:
+ *	%OCR_MODE_BIPHASE, %OCR_MODE_TEST, %OCR_MODE_NORMAL, %OCR_MODE_CLOCK,
+ *	%OCR_TX0_LH, %OCR_TX1_ZZ.
+ * @int_cpu_reg: Intel specific register -
+ *	holds hardware specific options for the CPU Interface
+ *	register. Options defined in the i82527.h file:
+ *	%iCPU_CEN, %iCPU_MUX, %iCPU_SLP, %iCPU_PWD, %iCPU_DMC, %iCPU_DSC, %iCPU_RST.
+ * @int_clk_reg: Intel specific register -
+ *	holds hardware specific options for the Clock Out
+ *	register. Options defined in the i82527.h file:
+ *	%iCLK_CD0, %iCLK_CD1, %iCLK_CD2, %iCLK_CD3, %iCLK_SL0, %iCLK_SL1.
+ * @int_bus_reg: Intel specific register -
+ *	holds hardware specific options for the Bus Configuration
+ *	register. Options defined in the i82527.h file:
+ *	%iBUS_DR0, %iBUS_DR1, %iBUS_DT1, %iBUS_POL, %iBUS_CBY.
+ * @msgobj: array of pointers to individual communication objects
+ * @chipspecops: pointer to the set of chip specific object filled by init_chip_data() function
+ * @hostdevice: pointer to chip hosting board
+ * @max_objects: maximal number of communication objects connected to this chip
+ *
+ * The fields @write_register and @read_register are copied from
+ * corresponding fields from @hwspecops structure
+ * (chip->hostdevice->hwspecops->write_register and 
+ * chip->hostdevice->hwspecops->read_register)
+ * to speedup can_write_reg() and can_read_reg() functions.
+ */
 struct chip_t {
 	char *chip_type;
 	int chip_idx;	/* chip index in candevice_t.chip[] */
 	int chip_irq;
 	unsigned long chip_base_addr;
 	unsigned int flags;
-	int clock; // Chip clock in Hz
+	int clock; /* Chip clock in Hz */
 
-	/* This is copy of the chip->hostdevice->hwspecops->read_register
-	 * and the chip->hostdevice->hwspecops->write_register.
-	 * The pointers were added for performance reasons, and are initialized
-	 * by init_chip_struct() from values given by hardware specific init_hwspecops().
-	 */
 	void (*write_register)(unsigned char data,unsigned long address);
 	unsigned (*read_register)(unsigned long address);
 
-	/* sja_cdr_reg holds hardware specific options for the Clock Divider
-	 * register. Options defined in the sja1000.h file:
-	 * CDR_CLKOUT_MASK, CDR_CLK_OFF, CDR_RXINPEN, CDR_CBP, CDR_PELICAN
-	 *
-	 * sja_ocr_reg holds hardware specific options for the Output Control
-	 * register. Options defined in the sja1000.h file:
-	 * OCR_MODE_BIPHASE, OCR_MODE_TEST, OCR_MODE_NORMAL, OCR_MODE_CLOCK,
-	 * OCR_TX0_LH, OCR_TX1_ZZ.
-	 *
-	 * int_clk_reg holds hardware specific options for the Clock Out
-	 * register. Options defined in the i82527.h file:
-	 * iCLK_CD0, iCLK_CD1, iCLK_CD2, iCLK_CD3, iCLK_SL0, iCLK_SL1.
-	 *
-	 * int_bus_reg holds hardware specific options for the Bus Configuration
-	 * register. Options defined in the i82527.h file:
-	 * iBUS_DR0, iBUS_DR1, iBUS_DT1, iBUS_POL, iBUS_CBY.
-	 *
-	 * int_cpu_reg holds hardware specific options for the CPU Interface
-	 * register. Options defined in the i82527.h file:
-	 * iCPU_CEN, iCPU_MUX, iCPU_SLP, iCPU_PWD, iCPU_DMC, iCPU_DSC, iCPU_RST.
-	 */
-	unsigned short sja_cdr_reg; // sja1000 only!
-	unsigned short sja_ocr_reg; // sja1000 only!
-	unsigned short int_cpu_reg; // intel 82527 only!
-	unsigned short int_clk_reg; // intel 82527 only!
-	unsigned short int_bus_reg; // intel 82527 only!
+	unsigned short sja_cdr_reg; /* sja1000 only! */
+	unsigned short sja_ocr_reg; /* sja1000 only! */
+	unsigned short int_cpu_reg; /* intel 82527 only! */
+	unsigned short int_clk_reg; /* intel 82527 only! */
+	unsigned short int_bus_reg; /* intel 82527 only! */
 
 	struct msgobj_t *msgobj[MAX_MSGOBJS];
 
@@ -123,6 +173,25 @@ struct chip_t {
 	int max_objects;	/* 1 for sja1000, 15 for */
 };
 
+/**
+ * struct msgobj_t - structure holding communication object state
+ * @obj_base_addr: 
+ * @minor: associated device minor number
+ * @object: object number in chip_t structure +1
+ * @flags: message object flags
+ * @ret: field holding status of the last Tx operation
+ * @qends: pointer to message object corresponding ends structure
+ * @tx_qedge: edge corresponding to transmitted message
+ * @tx_slot: slot holding transmitted message, slot is taken from
+ *	canque_test_outslot() call and is freed by canque_free_outslot()
+ *	or rescheduled canque_again_outslot()
+ * @rx_msg: temporary storage to hold received messages before
+ *	calling to canque_filter_msg2edges()
+ * @hostchip: pointer to the &chip_t structure this object belongs to
+ * @obj_used: counter of users (associated file structures for Linux
+ *	userspace clients) of this object
+ * @obj_users: list of user structures of type &canuser_t.
+ */
 struct msgobj_t {
 	unsigned long obj_base_addr;
 	unsigned int minor;	/* associated device minor number  */
@@ -143,6 +212,16 @@ struct msgobj_t {
 
 #define CAN_USER_MAGIC 0x05402033
 
+/**
+ * struct canuser_t - structure holding CAN user/client state
+ * @peers: for connection into list of object users
+ * @qends: pointer to the ends structure corresponding for this user
+ * @file: pointer to open device file state structure
+ * @msgobj: communication object the user is connected to
+ * @rx_edge0: default receive queue for filter IOCTL
+ * @magic: magic number to check consistency when pointer is retrieved
+ *	from file private field
+ */
 struct canuser_t {
 	struct list_head peers;
 	struct canque_ends_t *qends;
@@ -152,6 +231,25 @@ struct canuser_t {
 	int magic;
 };
 
+/**
+ * struct hwspecops_t - hardware/board specific operations
+ * @request_io: reserve io or memory range for can board
+ * @release_io: free reserved io memory range
+ * @reset: hardware reset routine
+ * @init_hw_data: called to initialize &candevice_t structure, mainly 
+ *	@res_add, @nr_all_chips, @nr_82527_chips, @nr_sja1000_chips
+ *	and @flags fields
+ * @init_chip_data: called initialize each &chip_t structure, mainly
+ *	@chip_type, @chip_base_addr, @clock and chip specific registers.
+ *	It is responsible to setup &chip_t->@chipspecops functions
+ *	for non-standard chip types (type other than "i82527", "sja1000" or "sja1000p")
+ * @init_obj_data: called initialize each &msgobj_t structure,
+ *	mainly @obj_base_addr field.
+ * @program_irq: program interrupt generation hardware of the board
+ *	if flag %PROGRAMMABLE_IRQ is present for specified device/board 
+ * @write_register: low level write register routine
+ * @read_register: low level read register routine
+ */
 struct hwspecops_t {
 	int (*request_io)(struct candevice_t *candev);
 	int (*release_io)(struct candevice_t *candev);
@@ -164,6 +262,28 @@ struct hwspecops_t {
 	unsigned (*read_register)(unsigned long address);
 };
 
+/**
+ * struct chipspecops_t - can controller chip specific operations
+ * @chip_config: CAN chip configuration
+ * @baud_rate: set communication parameters
+ * @standard_mask: setup of mask for message filtering
+ * @extended_mask: setup of extended mask for message filtering
+ * @message15_mask: set mask of i82527 message object 15
+ * @clear_objects: clears state of all message object residing in chip
+ * @config_irqs: tunes chip hardware interrupt delivery
+ * @pre_read_config: prepares message object for message reception
+ * @pre_write_config: prepares message object for message transmission
+ * @send_msg: initiate message transmission
+ * @remote_request: configures message object and asks for RTR message
+ * @check_tx_stat: checks state of transmission engine
+ * @wakeup_tx: wakeup TX processing
+ * @enable_configuration: enable chip configuration mode
+ * @disable_configuration: disable chip configuration mode
+ * @set_btregs: configures bitrate registers
+ * @start_chip: starts chip message processing
+ * @stop_chip: stops chip message processing
+ * @irq_handler: interrupt service routine
+ */
 struct chipspecops_t {
 	int (*chip_config)(struct chip_t *chip);
 	int (*baud_rate)(struct chip_t *chip, int rate, int clock, int sjw,
@@ -202,11 +322,7 @@ struct mem_addr {
 struct rtr_id {
 	unsigned long id;
 	struct canmsg_t *rtr_message;
-#if (LINUX_VERSION_CODE <= KERNEL_VERSION(2,3,0))
-	struct wait_queue *rtr_wq;
-#else
-	struct __wait_queue_head rtr_wq;
-#endif
+	wait_queue_head_t rtr_wq;
 	struct rtr_id *next;
 };
 
diff --git a/lincan/src/aim104.c b/lincan/src/aim104.c
index da8afc0..564809f 100644
--- a/lincan/src/aim104.c
+++ b/lincan/src/aim104.c
@@ -26,9 +26,9 @@
 #define IO_RANGE 0x20
 
 /**
- * template_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * template_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function template_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -51,8 +51,8 @@ int aim104_request_io(struct candevice_t *candev)
 }
 
 /**
- * template_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * template_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function template_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -71,7 +71,7 @@ int aim104_release_io(struct candevice_t *candev)
 
 /**
  * template_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -110,8 +110,8 @@ int aim104_reset(struct candevice_t *candev)
 #define NR_SJA1000 1
 
 /**
- * template_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * template_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -137,7 +137,7 @@ int aim104_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "sja1000"
 /**
  * template_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function template_init_chip_data() is used to initialize the hardware
@@ -178,7 +178,7 @@ int aim104_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * template_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function template_init_obj_data() is used to initialize the hardware
@@ -203,7 +203,7 @@ int aim104_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * template_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/bfadcan.c b/lincan/src/bfadcan.c
index 3e145f6..8eeaf3d 100644
--- a/lincan/src/bfadcan.c
+++ b/lincan/src/bfadcan.c
@@ -60,9 +60,9 @@ void bfadcan_write_register(unsigned char data, unsigned long address);
 
 
 /**
- * bfadcan_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * bfadcan_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function bfadcan_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -85,8 +85,8 @@ int bfadcan_request_io(struct candevice_t *candev)
 }
 
 /**
- * bfadcan_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * bfadcan_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function bfadcan_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -105,7 +105,7 @@ int bfadcan_release_io(struct candevice_t *candev)
 
 /**
  * bfadcan_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function bfadcan_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -149,8 +149,8 @@ int bfadcan_reset(struct candevice_t *candev)
 #define NR_SJA1000 1
 
 /**
- * bfadcan_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * bfadcan_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function bfadcan_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -176,7 +176,7 @@ int bfadcan_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "sja1000p"
 /**
  * bfadcan_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function bfadcan_init_chip_data() is used to initialize the hardware
@@ -232,7 +232,7 @@ int bfadcan_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * bfadcan_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function bfadcan_init_obj_data() is used to initialize the hardware
@@ -257,7 +257,7 @@ int bfadcan_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * bfadcan_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function bfadcan_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/can_queue.c b/lincan/src/can_queue.c
index 83b0839..62d8e19 100644
--- a/lincan/src/can_queue.c
+++ b/lincan/src/can_queue.c
@@ -105,6 +105,18 @@ int canque_fifo_done(struct canque_fifo_t *fifo)
  list_entry(ptr, type, member)
 */
 
+/**
+ * canque_get_inslot - finds one outgoing edge and allocates slot from it
+ * @qends: ends structure belonging to calling communication object
+ * @qedgep: place to store pointer to found edge
+ * @slotp: place to store pointer to  allocated slot
+ * @cmd: command type for slot
+ *
+ * Function looks for the first non-blocked outgoing edge in @qends structure
+ * and tries to allocate slot from it.
+ * Return Value: If there is no usable edge or there is no free slot in edge
+ *	negative value is returned.
+ */
 int canque_get_inslot(struct canque_ends_t *qends,
 	struct canque_edge_t **qedgep, struct canque_slot_t **slotp, int cmd)
 {
@@ -136,6 +148,23 @@ int canque_get_inslot(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_get_inslot4id - finds best outgoing edge and slot for given ID
+ * @qends: ends structure belonging to calling communication object
+ * @qedgep: place to store pointer to found edge
+ * @slotp: place to store pointer to  allocated slot
+ * @cmd: command type for slot
+ * @id: communication ID of message to send into edge
+ * @prio: optional priority of message
+ *
+ * Function looks for the non-blocked outgoing edge accepting messages
+ * with given ID. If edge is found, slot is allocated from that edge.
+ * The edges with non-zero mask are preferred over edges open to all messages.
+ * If more edges with mask accepts given message ID, the edge with
+ * highest priority below or equal to required priority is selected.
+ * Return Value: If there is no usable edge or there is no free slot in edge
+ *	negative value is returned.
+ */
 int canque_get_inslot4id(struct canque_ends_t *qends,
 	struct canque_edge_t **qedgep, struct canque_slot_t **slotp,
 	int cmd, unsigned long id, int prio)
@@ -189,6 +218,17 @@ int canque_get_inslot4id(struct canque_ends_t *qends,
 }
 
 
+/**
+ * canque_put_inslot - schedules filled slot for processing
+ * @qends: ends structure belonging to calling communication object
+ * @qedge: edge slot belong to
+ * @slot: pointer to the prepared slot
+ *
+ * Puts slot previously acquired by canque_get_inslot() or canque_get_inslot4id()
+ * function call into FIFO queue and activates edge processing if needed.
+ * Return Value: Positive value informs, that activation of output end
+ *	has been necessary
+ */
 int canque_put_inslot(struct canque_ends_t *qends,
 	struct canque_edge_t *qedge, struct canque_slot_t *slot)
 {
@@ -207,6 +247,16 @@ int canque_put_inslot(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_abort_inslot - aborts preparation of the message in the slot
+ * @qends: ends structure belonging to calling communication object
+ * @qedge: edge slot belong to
+ * @slot: pointer to the previously allocated slot
+ *
+ * Frees slot previously acquired by canque_get_inslot() or canque_get_inslot4id()
+ * function call. Used when message copying into slot fails.
+ * Return Value: Positive value informs, that queue full state has been negated.
+ */
 int canque_abort_inslot(struct canque_ends_t *qends,
 	struct canque_edge_t *qedge, struct canque_slot_t *slot)
 {
@@ -224,6 +274,15 @@ int canque_abort_inslot(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_filter_msg2edges - sends message into all edges which accept its ID
+ * @qends: ends structure belonging to calling communication object
+ * @msg: pointer to CAN message
+ *
+ * Sends message to all outgoing edges connected to the given ends, which accepts
+ * message communication ID.
+ * Return Value: Returns number of edges message has been send to
+ */
 int canque_filter_msg2edges(struct canque_ends_t *qends, struct canmsg_t *msg)
 {
 	int destnr=0;
@@ -264,6 +323,18 @@ int canque_filter_msg2edges(struct canque_ends_t *qends, struct canmsg_t *msg)
 	return destnr;
 }
 
+/**
+ * canque_test_outslot - test and retrieve ready slot for given ends
+ * @qends: ends structure belonging to calling communication object
+ * @qedgep: place to store pointer to found edge
+ * @slotp: place to store pointer to received slot
+ *
+ * Function takes highest priority active incoming edge and retrieves
+ * oldest ready slot from it.
+ * Return Value: Negative value informs, that there is no ready output
+ *	slot for given ends. Positive value is equal to the command
+ *	slot has been allocated by the input side.
+ */
 int canque_test_outslot(struct canque_ends_t *qends,
 	struct canque_edge_t **qedgep, struct canque_slot_t **slotp)
 {
@@ -288,6 +359,17 @@ int canque_test_outslot(struct canque_ends_t *qends,
 	return -1;
 }
 
+/**
+ * canque_free_outslot - frees processed output slot
+ * @qends: ends structure belonging to calling communication object
+ * @qedge: edge slot belong to
+ * @slot: pointer to the processed slot
+ *
+ * Function releases processed slot previously acquired by canque_test_outslot()
+ * function call.
+ * Return Value: Return value informs if input side has been notified
+ *	to know about change of edge state
+ */
 int canque_free_outslot(struct canque_ends_t *qends,
 	struct canque_edge_t *qedge, struct canque_slot_t *slot)
 {
@@ -321,17 +403,22 @@ int canque_free_outslot(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_again_outslot - reschedule output slot to process it again later
+ * @qends: ends structure belonging to calling communication object
+ * @qedge: edge slot belong to
+ * @slot: pointer to the slot for re-processing
+ *
+ * Function reschedules slot previously acquired by canque_test_outslot()
+ * function call for second time processing.
+ * Return Value: Function cannot fail.
+ */
 int canque_again_outslot(struct canque_ends_t *qends,
 	struct canque_edge_t *qedge, struct canque_slot_t *slot)
 {
 	int ret;
 	unsigned long flags;
 	ret=canque_fifo_again_outslot(&qedge->fifo, slot);
-	if(ret&CAN_FIFOF_EMPTY){
-	  	canque_notify_inends(qedge,CANQUEUE_NOTIFY_EMPTY);
-	}
-	if(ret&CAN_FIFOF_FULL)
-	  	canque_notify_inends(qedge,CANQUEUE_NOTIFY_SPACE);
 	spin_lock_irqsave(&qends->ends_lock, flags);
 	if(atomic_dec_and_test(&qedge->edge_used))
   		canque_notify_bothends(qedge,CANQUEUE_NOTIFY_NOUSR);
@@ -340,6 +427,14 @@ int canque_again_outslot(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_set_filt - sets filter for specified edge
+ * @qedge: pointer to the edge
+ * @filtid: ID to set for the edge
+ * @filtmask: mask used for ID match check
+ *
+ * Return Value: Negative value is returned if edge is in the process of delete.
+ */
 int canque_set_filt(struct canque_edge_t *qedge,
 	unsigned long filtid, unsigned long filtmask)
 {
@@ -367,6 +462,16 @@ int canque_set_filt(struct canque_edge_t *qedge,
 	return ret;
 }
 
+/**
+ * canque_flush - fluesh all ready slots in the edge
+ * @qedge: pointer to the edge
+ *
+ * Tries to flush all allocated slots from the edge, but there could
+ * exist some slots associated to edge which are processed by input
+ * or output side and cannot be flushed at this moment.
+ * Return Value: The nonzero value indicates, that queue has not been
+ *	empty before the function call.
+ */
 int canque_flush(struct canque_edge_t *qedge)
 {
 	int ret;
@@ -392,6 +497,12 @@ int canque_flush(struct canque_edge_t *qedge)
 	return ret;
 }
 
+/**
+ * canqueue_ends_init_gen - subsystem independent routine to initialize ends state
+ * @qends: pointer to the ends structure
+ *
+ * Return Value: Cannot fail.
+ */
 int canqueue_ends_init_gen(struct canque_ends_t *qends)
 {
 	int i;
@@ -405,6 +516,12 @@ int canqueue_ends_init_gen(struct canque_ends_t *qends)
 }
 
 
+/**
+ * canqueue_notify_kern - notification callback handler for Linux userspace clients
+ * @qends: pointer to the callback side ends structure
+ * @qedge: edge which invoked notification 
+ * @what: notification type
+ */
 void canqueue_notify_kern(struct canque_ends_t *qends, struct canque_edge_t *qedge, int what)
 {
 	DEBUGQUE("canqueue_notify_kern for edge %d and event %d\n",qedge->edge_num,what);
@@ -433,6 +550,10 @@ void canqueue_notify_kern(struct canque_ends_t *qends, struct canque_edge_t *qed
 	}
 }
 
+/**
+ * canqueue_ends_init_kern - Linux userspace clients specific ends initialization
+ * @qends: pointer to the callback side ends structure
+ */
 int canqueue_ends_init_kern(struct canque_ends_t *qends)
 {
 	canqueue_ends_init_gen(qends);
@@ -446,6 +567,19 @@ int canqueue_ends_init_kern(struct canque_ends_t *qends)
 }
 
 
+/**
+ * canque_get_inslot4id_wait_kern - find or wait for best outgoing edge and slot for given ID
+ * @qends: ends structure belonging to calling communication object
+ * @qedgep: place to store pointer to found edge
+ * @slotp: place to store pointer to  allocated slot
+ * @cmd: command type for slot
+ * @id: communication ID of message to send into edge
+ * @prio: optional priority of message
+ *
+ * Same as canque_get_inslot4id(), except, that it waits for free slot
+ * in case, that queue is full. Function is specific for Linux userspace clients.
+ * Return Value: If there is no usable edge negative value is returned.
+ */
 int canque_get_inslot4id_wait_kern(struct canque_ends_t *qends,
 	struct canque_edge_t **qedgep, struct canque_slot_t **slotp,
 	int cmd, unsigned long id, int prio)
@@ -457,6 +591,18 @@ int canque_get_inslot4id_wait_kern(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_get_outslot_wait_kern - receive or wait for ready slot for given ends
+ * @qends: ends structure belonging to calling communication object
+ * @qedgep: place to store pointer to found edge
+ * @slotp: place to store pointer to received slot
+ *
+ * The same as canque_test_outslot(), except it waits in the case, that there is
+ * no ready slot for given ends. Function is specific for Linux userspace clients.
+ * Return Value: Negative value informs, that there is no ready output
+ *	slot for given ends. Positive value is equal to the command
+ *	slot has been allocated by the input side.
+ */
 int canque_get_outslot_wait_kern(struct canque_ends_t *qends,
 	struct canque_edge_t **qedgep, struct canque_slot_t **slotp)
 {
@@ -467,16 +613,32 @@ int canque_get_outslot_wait_kern(struct canque_ends_t *qends,
 	return ret;
 }
 
+/**
+ * canque_sync_wait_kern - wait for all slots processing
+ * @qends: ends structure belonging to calling communication object
+ * @qedge: pointer to edge
+ *
+ * Functions waits for ends transition into empty state.
+ * Return Value: Positive value indicates, that edge empty state has been reached.
+ *	Negative or zero value informs about interrupted wait or other problem.
+ */
 int canque_sync_wait_kern(struct canque_ends_t *qends, struct canque_edge_t *qedge)
 {
 	int ret=-1;
 	DEBUGQUE("canque_sync_wait_kern\n");
 	wait_event_interruptible((qends->endinfo.fileinfo.emptyq), 
-		(ret=canque_fifo_test_fl(&qedge->fifo,EMPTY)));
+		(ret=canque_fifo_test_fl(&qedge->fifo,EMPTY)?1:0));
 	return ret;
 }
 
 
+/**
+ * canque_new_edge_kern - allocate new edge structure in the Linux kernel context
+ * @slotsnr: required number of slots in the newly allocated edge structure
+ *
+ * Return Value: Returns pointer to allocated slot structure or %NULL if
+ *	there is not enough memory to process operation.
+ */
 struct canque_edge_t *canque_new_edge_kern(int slotsnr)
 {
 	struct canque_edge_t *qedge;
@@ -503,6 +665,14 @@ struct canque_edge_t *canque_new_edge_kern(int slotsnr)
 	return qedge;
 }
 
+/**
+ * canqueue_connect_edge - connect edge between two communication entities
+ * @qedge: pointer to edge
+ * @inends: pointer to ends the input of the edge should be connected to
+ * @outends: pointer to ends the output of the edge should be connected to
+ *
+ * Return Value: Negative value informs about failed operation.
+ */
 int canqueue_connect_edge(struct canque_edge_t *qedge, struct canque_ends_t *inends, struct canque_ends_t *outends)
 {
 	unsigned long flags;
@@ -528,6 +698,13 @@ int canqueue_connect_edge(struct canque_edge_t *qedge, struct canque_ends_t *ine
 	return 0;
 }
 
+/**
+ * canqueue_disconnect_edge - disconnect edge from communicating entities
+ * @qedge: pointer to edge
+ *
+ * Return Value: Negative value means, that edge is used and cannot
+ *	be disconnected. Operation has to be delayed.
+ */
 int canqueue_disconnect_edge(struct canque_edge_t *qedge)
 {
 	int ret;
@@ -557,6 +734,16 @@ int canqueue_disconnect_edge(struct canque_edge_t *qedge)
 	return ret;
 }
 
+/**
+ * canqueue_disconnect_edge_kern - disconnect edge from communicating entities with wait
+ * @qends: ends structure belonging to calling communication object
+ * @qedge: pointer to edge
+ *
+ * Same as canqueue_disconnect_edge(), but tries to wait for state with zero
+ * use counter.
+ * Return Value: Negative value means, that edge is used and cannot
+ *	be disconnected yet. Operation has to be delayed.
+ */
 int canqueue_disconnect_edge_kern(struct canque_ends_t *qends, struct canque_edge_t *qedge)
 {
 	canque_fifo_set_fl(&qedge->fifo,BLOCK);
@@ -620,6 +807,14 @@ void canqueue_block_list(struct canque_ends_t *qends, struct list_head *list)
 }
 
 
+/**
+ * canqueue_ends_done_kern - finalizing of the ends structure for Linux kernel clients
+ * @qends: pointer to ends structure
+ * @sync: flag indicating, that user wants to wait for processing of all remaining
+ *	messages
+ *
+ * Return Value: Function should be designed such way to not fail.
+ */
 int canqueue_ends_done_kern(struct canque_ends_t *qends, int sync)
 {
 	unsigned long flags;
diff --git a/lincan/src/cc_can104.c b/lincan/src/cc_can104.c
index 521bec7..e0f47fe 100644
--- a/lincan/src/cc_can104.c
+++ b/lincan/src/cc_can104.c
@@ -27,9 +27,9 @@
 #define IO_RANGE 0x80
 
 /**
- * template_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * template_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function template_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -52,8 +52,8 @@ int cc104_request_io(struct candevice_t *candev)
 }
 
 /**
- * template_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * template_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function template_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -72,7 +72,7 @@ int cc104_release_io(struct candevice_t *candev)
 
 /**
  * template_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -90,8 +90,8 @@ int cc104_reset(struct candevice_t *candev)
 #define NR_SJA1000 1
 
 /**
- * template_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * template_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -117,7 +117,7 @@ int cc104_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "sja1000"
 /**
  * template_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function template_init_chip_data() is used to initialize the hardware
@@ -159,7 +159,7 @@ int cc104_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * template_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function template_init_obj_data() is used to initialize the hardware
@@ -184,7 +184,7 @@ int cc104_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * template_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/m437.c b/lincan/src/m437.c
index c2073ed..b5349b8 100644
--- a/lincan/src/m437.c
+++ b/lincan/src/m437.c
@@ -44,9 +44,9 @@
 static long base = 0L; 
 
 /**
- * m437_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * m437_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function m437_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -76,8 +76,8 @@ int m437_request_io(struct candevice_t *candev)
 }
 
 /**
- * m437_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * m437_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function m437_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -124,7 +124,7 @@ int m437_release_io(struct candevice_t *candev)
 
 /**
  * m437_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function m437_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -142,8 +142,8 @@ int m437_reset(struct candevice_t *candev)
 #define NR_SJA1000 0
 
 /**
- * m437_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * m437_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function m437_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -171,7 +171,7 @@ int m437_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "i82527"
 /**
  * m437_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function m437_init_chip_data() is used to initialize the hardware
@@ -216,7 +216,7 @@ int m437_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * m437_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function m437_init_obj_data() is used to initialize the hardware
@@ -241,7 +241,7 @@ int m437_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * m437_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function m437_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/pc_i03.c b/lincan/src/pc_i03.c
index 0490fe6..daec69c 100644
--- a/lincan/src/pc_i03.c
+++ b/lincan/src/pc_i03.c
@@ -32,9 +32,9 @@ unsigned int pci03_base_addr;
 #define IO_RANGE 0x200	// The pc-i03 uses an additional 0x100 bytes reset space
 
 /**
- * pci03_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * pci03_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function pci03_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -57,8 +57,8 @@ int pci03_request_io(struct candevice_t *candev)
 }
 
 /**
- * pci03_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * pci03_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function pci03_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -77,7 +77,7 @@ int pci03_release_io(struct candevice_t *candev)
 
 /**
  * pci03_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function pci03_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -119,8 +119,8 @@ int pci03_reset(struct candevice_t *candev)
 #define NR_SJA1000 1
 
 /**
- * pci03_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * pci03_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function pci03_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -144,7 +144,7 @@ int pci03_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "sja1000"
 /**
  * pci03_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function pci03_init_chip_data() is used to initialize the hardware
@@ -186,7 +186,7 @@ int pci03_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * pci03_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function pci03_init_obj_data() is used to initialize the hardware
@@ -211,7 +211,7 @@ int pci03_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * pci03_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function pci03_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/pcccan.c b/lincan/src/pcccan.c
index 290a44a..0ca6f28 100644
--- a/lincan/src/pcccan.c
+++ b/lincan/src/pcccan.c
@@ -48,9 +48,9 @@ unsigned long pcccan_base=0x0;
 #define IO_RANGE 0x8
 
 /**
- * pcccan_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * pcccan_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function pcccan_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -73,8 +73,8 @@ int pcccan_request_io(struct candevice_t *candev)
 }
 
 /**
- * pcccan_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * pcccan_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function pcccan_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -93,7 +93,7 @@ int pcccan_release_io(struct candevice_t *candev)
 
 /**
  * pcccan_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function pcccan_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -133,8 +133,8 @@ int pcccan_reset(struct candevice_t *candev)
 #define NR_SJA1000 0
 
 /**
- * pcccan_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * pcccan_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function pcccan_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -160,7 +160,7 @@ int pcccan_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "i82527"
 /**
  * pcccan_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function pcccan_init_chip_data() is used to initialize the hardware
@@ -208,7 +208,7 @@ int pcccan_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * pcccan_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function pcccan_init_obj_data() is used to initialize the hardware
@@ -233,7 +233,7 @@ int pcccan_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * pcccan_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function pcccan_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/pcm3680.c b/lincan/src/pcm3680.c
index a1ccf4a..22330cb 100644
--- a/lincan/src/pcm3680.c
+++ b/lincan/src/pcm3680.c
@@ -27,9 +27,9 @@
 #define IO_RANGE 0x400
 
 /**
- * template_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * template_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function template_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -59,8 +59,8 @@ int pcm3680_request_io(struct candevice_t *candev)
 }
 
 /**
- * template_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * template_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function template_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -79,7 +79,7 @@ int pcm3680_release_io(struct candevice_t *candev)
 
 /**
  * template_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -121,8 +121,8 @@ int pcm3680_reset(struct candevice_t *candev)
 #define NR_SJA1000 2
 
 /**
- * template_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * template_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -148,7 +148,7 @@ int pcm3680_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "sja1000p"
 /**
  * template_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function template_init_chip_data() is used to initialize the hardware
@@ -192,7 +192,7 @@ int pcm3680_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * template_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function template_init_obj_data() is used to initialize the hardware
@@ -217,7 +217,7 @@ int pcm3680_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * template_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/pikronisa.c b/lincan/src/pikronisa.c
index 703adad..a0a6d07 100644
--- a/lincan/src/pikronisa.c
+++ b/lincan/src/pikronisa.c
@@ -27,9 +27,9 @@
 #define IO_RANGE 0x100
 
 /**
- * pikronisa_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * pikronisa_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function pikronisa_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -60,8 +60,8 @@ int pikronisa_request_io(struct candevice_t *candev)
 }
 
 /**
- * pikronisa_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * pikronisa_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function pikronisa_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -82,7 +82,7 @@ int pikronisa_release_io(struct candevice_t *candev)
 
 /**
  * pikronisa_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function pikronisa_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -125,8 +125,8 @@ int pikronisa_reset(struct candevice_t *candev)
 #define NR_SJA1000 1
 
 /**
- * pikronisa_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * pikronisa_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * The function pikronisa_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -154,7 +154,7 @@ int pikronisa_init_hw_data(struct candevice_t *candev)
 
 /**
  * pikronisa_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function pikronisa_init_chip_data() is used to initialize the hardware
@@ -199,7 +199,7 @@ int pikronisa_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * pikronisa_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function pikronisa_init_obj_data() is used to initialize the hardware
@@ -223,7 +223,7 @@ int pikronisa_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * pikronisa_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function pikronisa_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/read.c b/lincan/src/read.c
index 64b2415..92fcb68 100644
--- a/lincan/src/read.c
+++ b/lincan/src/read.c
@@ -98,11 +98,7 @@ inline ssize_t can_rtr_read(struct chip_t *chip, struct msgobj_t *obj,
 		new_rtr_entry=(struct rtr_id *)kmalloc(sizeof(struct rtr_id),GFP_ATOMIC);
 		rtr_current->next=new_rtr_entry;
 	}
-#if (LINUX_VERSION_CODE <= KERNEL_VERSION(2,3,0))
-	init_waitqueue(&new_rtr_entry->rtr_wq);
-#else
 	init_waitqueue_head(&new_rtr_entry->rtr_wq);
-#endif
 	new_rtr_entry->id = read_msg.id;
 	new_rtr_entry->rtr_message = &read_msg;
 	new_rtr_entry->next=NULL;
diff --git a/lincan/src/sja1000p.c b/lincan/src/sja1000p.c
index 19e2e57..ef587dd 100644
--- a/lincan/src/sja1000p.c
+++ b/lincan/src/sja1000p.c
@@ -18,6 +18,10 @@
 #include "../include/main.h"
 #include "../include/sja1000p.h"
 
+/**
+ * sja1000p_enable_configuration - enable chip configuration mode
+ * @chip: pointer to chip state structure
+ */
 int sja1000p_enable_configuration(struct chip_t *chip)
 {
 	int i=0;
@@ -44,6 +48,10 @@ int sja1000p_enable_configuration(struct chip_t *chip)
 	return 0;
 }
 
+/**
+ * sja1000p_disable_configuration - disable chip configuration mode
+ * @chip: pointer to chip state structure
+ */
 int sja1000p_disable_configuration(struct chip_t *chip)
 {
 	int i=0;
@@ -426,7 +434,7 @@ int sja1000p_set_btregs(struct chip_t *chip, unsigned short btr0,
 }
 
 /**
- * sja1000p_stop_chip: -  starts chip message processing
+ * sja1000p_start_chip: -  starts chip message processing
  * @chip: pointer to chip state structure
  *
  * Return Value: negative value reports error.
diff --git a/lincan/src/template.c b/lincan/src/template.c
index 3075ad5..6a82757 100644
--- a/lincan/src/template.c
+++ b/lincan/src/template.c
@@ -32,9 +32,9 @@
 #define IO_RANGE 0x100
 
 /**
- * template_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * template_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * The function template_request_io() is used to reserve the io-memory. If your
  * hardware uses a dedicated memory range as hardware control registers you
@@ -57,8 +57,8 @@ int template_request_io(struct candevice_t *candev)
 }
 
 /**
- * template_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * template_release_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * The function template_release_io() is used to free reserved io-memory.
  * In case you have reserved more io memory, don't forget to free it here.
@@ -77,7 +77,7 @@ int template_release_io(struct candevice_t *candev)
 
 /**
  * template_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_reset() is used to give a hardware reset. This is 
  * rather hardware specific so I haven't included example code. Don't forget to 
@@ -96,7 +96,7 @@ int template_reset(struct candevice_t *candev)
 
 /**
  * template_init_hw_data - Initialize hardware cards
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_init_hw_data() is used to initialize the hardware
  * structure containing information about the installed CAN-board.
@@ -122,7 +122,7 @@ int template_init_hw_data(struct candevice_t *candev)
 #define CHIP_TYPE "i82527"
 /**
  * template_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * The function template_init_chip_data() is used to initialize the hardware
@@ -169,7 +169,7 @@ int template_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * template_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * The function template_init_obj_data() is used to initialize the hardware
@@ -194,7 +194,7 @@ int template_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * template_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * The function template_program_irq() is used for hardware that uses 
  * programmable interrupts. If your hardware doesn't use programmable interrupts
diff --git a/lincan/src/virtual.c b/lincan/src/virtual.c
index 5b39ecf..42c0f57 100644
--- a/lincan/src/virtual.c
+++ b/lincan/src/virtual.c
@@ -307,9 +307,9 @@ int virtual_wakeup_tx(struct chip_t *chip, struct msgobj_t *obj)
 /* * * Virtual Board Functionality * * */
 
 /**
- * virtual_request_io: - reserve io memory
- * @io_addr: The reserved memory starts at @io_addr, wich is the module 
- * parameter @io.
+ * virtual_request_io: - reserve io or memory range for can board
+ * @candev: pointer to candevice/board which asks for io. Field @io_addr
+ *	of @candev is used in most cases to define start of the range
  *
  * Return Value: The function returns zero on success or %-ENODEV on failure
  * File: src/virtual.c
@@ -320,8 +320,8 @@ int virtual_request_io(struct candevice_t *candev)
 }
 
 /**
- * virtual_release_io - free reserved io-memory
- * @io_addr: Start of the memory range to be released.
+ * virtual_elease_io - free reserved io memory range
+ * @candev: pointer to candevice/board which releases io
  *
  * Return Value: The function always returns zero
  * File: src/virtual.c
@@ -333,7 +333,7 @@ int virtual_release_io(struct candevice_t *candev)
 
 /**
  * virtual_reset - hardware reset routine
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * Return Value: The function returns zero on success or %-ENODEV on failure
  * File: src/virtual.c
@@ -344,8 +344,8 @@ int virtual_reset(struct candevice_t *candev)
 }
 
 /**
- * virtual_init_hw_data - Initialze hardware cards
- * @card: Number of the hardware card.
+ * virtual_init_hw_data - Initialize hardware cards
+ * @candev: Pointer to candevice/board structure
  *
  * Return Value: The function always returns zero
  * File: src/virtual.c
@@ -365,7 +365,7 @@ int virtual_init_hw_data(struct candevice_t *candev)
 
 /**
  * virtual_init_chip_data - Initialize chips
- * @card: Number of the hardware card
+ * @candev: Pointer to candevice/board structure
  * @chipnr: Number of the CAN chip on the hardware card
  *
  * Return Value: The function always returns zero
@@ -407,7 +407,7 @@ int virtual_init_chip_data(struct candevice_t *candev, int chipnr)
 
 /**
  * virtual_init_obj_data - Initialize message buffers
- * @chipnr: Number of the CAN chip
+ * @chip: Pointer to chip specific structure
  * @objnr: Number of the message buffer
  *
  * Return Value: The function always returns zero
@@ -422,7 +422,7 @@ int virtual_init_obj_data(struct chip_t *chip, int objnr)
 
 /**
  * virtual_program_irq - program interrupts
- * @card: Number of the hardware card.
+ * @candev: Pointer to candevice/board structure
  *
  * Return value: The function returns zero on success or %-ENODEV on failure
  * File: src/virtual.c