LinCAN driver structured comments updated.

diff --git a/lincan/include/can_queue.h b/lincan/include/can_queue.h
index 8821dca02c488ea8fdc8d64af161f3879d8bd777..1392f3a665bd87ba42df06398e0d6f8b9af997bb 100644 (file)
--- a/lincan/include/can_queue.h
+++ b/lincan/include/can_queue.h
@@ -39,7 +39,7 @@
  * @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.
  * @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.

- * @slotnr:  number of allocated slots
+ * @slotsnr:  number of allocated slots

  *
  * This structure represents CAN FIFO queue. It is implemented as 
  * a single linked list of slots prepared for processing. The empty slots
  *
  * This structure represents CAN FIFO queue. It is implemented as 
  * a single linked list of slots prepared for processing. The empty slots


@@ -319,6 +319,8 @@ struct canque_edge_t {
  *     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.
  * @inlist: the list of outgoing edges input sides.
  *     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.
  * @inlist: the list of outgoing edges input sides.

+ * @outlist: the list of all incoming edges output sides. Each of there edges
+ *     is listed on one of @active or @idle lists.

  * @ends_lock: the lock synchronizing operations between threads accessing
  *     same ends structure.
  * @notify: pointer to notify procedure. The next state changes are notified.
  * @ends_lock: the lock synchronizing operations between threads accessing
  *     same ends structure.
  * @notify: pointer to notify procedure. The next state changes are notified.

diff --git a/lincan/include/can_sysdep.h b/lincan/include/can_sysdep.h
index 5b33971292dc6e9061582317fdea0f6e8146b989..0dd0e5546353e14b36d4b7a8066d926e322d3169 100644 (file)
--- a/lincan/include/can_sysdep.h
+++ b/lincan/include/can_sysdep.h
@@ -179,6 +179,8 @@
 #define can_set_rtl_file_private_data(fptr, p) do{ fptr->f_minor=(long)(p); } while(0)
 #define can_get_rtl_file_private_data(fptr) ((void*)((fptr)->f_minor))
 
 #define can_set_rtl_file_private_data(fptr, p) do{ fptr->f_minor=(long)(p); } while(0)
 #define can_get_rtl_file_private_data(fptr) ((void*)((fptr)->f_minor))
 

+extern can_spinlock_t can_irq_manipulation_lock;
+

 #endif /*CAN_WITH_RTL*/
 
 #endif /*_CAN_SYSDEP_H*/
 #endif /*CAN_WITH_RTL*/
 
 #endif /*_CAN_SYSDEP_H*/

diff --git a/lincan/include/main.h b/lincan/include/main.h
index b4a0b32a7eb29cf395e357d822fc1f9bb17a17fe..2fa81ced2d4dc640e6e9eaa363ad73dfc111fd5a 100644 (file)
--- a/lincan/include/main.h
+++ b/lincan/include/main.h
@@ -53,6 +53,8 @@ struct canhardware_t {
  * @chip: array of pointers to the chip structures
  * @hwspecops: pointer to board specific operations
  * @hosthardware_p: pointer to the root hardware structure
  * @chip: array of pointers to the chip structures
  * @hwspecops: pointer to board specific operations
  * @hosthardware_p: pointer to the root hardware structure

+ * @sysdevptr: union reserved for pointer to bus specific
+ *     device structure (case @pcidev is used for PCI devices)

  *
  * The structure represent configuration and state of associated board.
  * The driver infrastructure prepares this structure and calls
  *
  * The structure represent configuration and state of associated board.
  * The driver infrastructure prepares this structure and calls


@@ -129,6 +131,15 @@ struct candevice_t {
  * @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
  * @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

+ * @chip_lock: reserved for synchronization of the chip supporting routines
+ *     (not used in the current driver version)
+ * @worker_thread: chip worker thread ID (RT-Linux specific field)
+ * @pend_flags: holds information about pending interrupt and tx_wake() operations
+ *     (RT-Linux specific field). Masks values:
+ *     %MSGOBJ_TX_REQUEST .. some of the message objects requires tx_wake() call, 
+ *     %MSGOBJ_IRQ_REQUEST .. chip interrupt processing required
+ *     %MSGOBJ_WORKER_WAKE .. marks, that worker thread should be waked
+ *             for some of above reasons

  *
  * The fields @write_register and @read_register are copied from
  * corresponding fields from @hwspecops structure
  *
  * The fields @write_register and @read_register are copied from
  * corresponding fields from @hwspecops structure


@@ -190,6 +201,10 @@ struct chip_t {
  * @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.
  * @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.

+ * @obj_flags: message object specific flags. Masks values:
+ *     %MSGOBJ_TX_REQUEST .. the message object requests TX activation
+ *     %MSGOBJ_TX_LOCK .. some IRQ routine or callback on some CPU 
+ *             is running inside TX activation processing code

  */
 struct msgobj_t {
        unsigned long obj_base_addr;
  */
 struct msgobj_t {
        unsigned long obj_base_addr;

diff --git a/lincan/src/can_devrtl.c b/lincan/src/can_devrtl.c
index 812ea84a731be5de4952af924b4416ebb5f25f7e..37bbbf1c023fb54f4769669d04c97f9422475005 100644 (file)
--- a/lincan/src/can_devrtl.c
+++ b/lincan/src/can_devrtl.c
@@ -16,6 +16,8 @@
 
 #include <rtl_malloc.h>
 
 
 #include <rtl_malloc.h>
 

+can_spinlock_t can_irq_manipulation_lock;
+

 unsigned int can_rtl_isr( unsigned int irq_num, struct pt_regs *r )
 {
        struct chip_t *chip;
 unsigned int can_rtl_isr( unsigned int irq_num, struct pt_regs *r )
 {
        struct chip_t *chip;

diff --git a/lincan/src/can_quekern.c b/lincan/src/can_quekern.c
index 5089e5cbc2c8aec6cbc9ad95d51385c4afd65ff3..3eea5a36b4d462c14f9cf1d01e778e5fd9a5976b 100644 (file)
--- a/lincan/src/can_quekern.c
+++ b/lincan/src/can_quekern.c
@@ -176,6 +176,13 @@ void canque_edge_do_dead(struct canque_edge_t *edge, int dead_fl)
  * @qends: pointer to the callback side ends structure
  * @qedge: edge which invoked notification 
  * @what: notification type
  * @qends: pointer to the callback side ends structure
  * @qedge: edge which invoked notification 
  * @what: notification type

+ *
+ * The notification event is handled directly by call of this function except case,
+ * when called from RT-Linux context in mixed mode Linux/RT-Linux compilation.
+ * It is not possible to directly call Linux kernel synchronization primitives
+ * in such case. The notification request is postponed and signaled by @pending_inops flags
+ * by call canqueue_rtl2lin_check_and_pend() function. 
+ * The edge reference count is increased until until all pending notifications are processed.

  */
 void canqueue_notify_kern(struct canque_ends_t *qends, struct canque_edge_t *qedge, int what)
 {
  */
 void canqueue_notify_kern(struct canque_ends_t *qends, struct canque_edge_t *qedge, int what)
 {


@@ -376,7 +383,7 @@ struct canque_edge_t *canque_new_edge_kern(int slotsnr)
 
 #ifdef USE_SYNC_DISCONNECT_EDGE_KERN
 
 
 #ifdef USE_SYNC_DISCONNECT_EDGE_KERN
 

-/**
+/*not included in doc

  * canqueue_disconnect_edge_kern - disconnect edge from communicating entities with wait
  * @qends: ends structure belonging to calling communication object
  * @qedge: pointer to edge
  * canqueue_disconnect_edge_kern - disconnect edge from communicating entities with wait
  * @qends: ends structure belonging to calling communication object
  * @qedge: pointer to edge

diff --git a/lincan/src/can_quertl.c b/lincan/src/can_quertl.c
index dc59f8ebf958c1a23d428d703ed8b0347989c0aa..2ebc2654e052c51dcfe4260d1b1f00791607c043 100644 (file)
--- a/lincan/src/can_quertl.c
+++ b/lincan/src/can_quertl.c
@@ -421,6 +421,9 @@ int canqueue_ends_dispose_rtl(struct canque_ends_t *qends, int sync)
 
 
 
 
 
 

+/**
+ * canqueue_rtl_initialize - initialization of global RT-Linux specific features
+ */

 void canqueue_rtl_initialize(void)
 {
        INIT_LIST_HEAD(&canque_pending_edges_list);
 void canqueue_rtl_initialize(void)
 {
        INIT_LIST_HEAD(&canque_pending_edges_list);


@@ -430,6 +433,9 @@ void canqueue_rtl_initialize(void)
 }
 
 
 }
 
 

+/**
+ * canqueue_rtl_done - finalization of glopal RT-Linux specific features
+ */

 void canqueue_rtl_done(void)
 {
        rtl_free_soft_irq (canqueue_rtl_irq);
 void canqueue_rtl_done(void)
 {
        rtl_free_soft_irq (canqueue_rtl_irq);

diff --git a/lincan/src/devcommon.c b/lincan/src/devcommon.c
index c0b602886f49a8a64abf7552aae9ad73262732c2..e17a0618d7709a3ebc5c801077904c605fdab2d5 100644 (file)
--- a/lincan/src/devcommon.c
+++ b/lincan/src/devcommon.c
@@ -12,6 +12,17 @@
 #include "../include/main.h"
 #include "../include/devcommon.h"
 
 #include "../include/main.h"
 #include "../include/devcommon.h"
 

+/**
+ * canqueue_notify_chip - notification callback handler for CAN chips ends of queues
+ * @qends: pointer to the callback side ends structure
+ * @qedge: edge which invoked notification 
+ * @what: notification type
+ *
+ * This function has to deal with more possible cases. It can be called from
+ * the kernel or interrupt context for Linux only compilation of driver.
+ * The function can be called from kernel context or RT-Linux thread context
+ * for mixed mode Linux/RT-Linux compilation.
+ */

 void canqueue_notify_chip(struct canque_ends_t *qends, struct canque_edge_t *qedge, int what)
 {
        struct chip_t *chip=qends->endinfo.chipinfo.chip;
 void canqueue_notify_chip(struct canque_ends_t *qends, struct canque_edge_t *qedge, int what)
 {
        struct chip_t *chip=qends->endinfo.chipinfo.chip;


@@ -56,6 +67,12 @@ void canqueue_notify_chip(struct canque_ends_t *qends, struct canque_edge_t *qed
 }
 
 
 }
 
 

+/**
+ * canqueue_ends_init_chip - CAN chip specific ends initialization
+ * @qends: pointer to the ends structure
+ * @chip: pointer to the corresponding CAN chip structure
+ * @obj: pointer to the corresponding message object structure
+ */

 int canqueue_ends_init_chip(struct canque_ends_t *qends, struct chip_t *chip, struct msgobj_t *obj)
 {
        int ret;
 int canqueue_ends_init_chip(struct canque_ends_t *qends, struct chip_t *chip, struct msgobj_t *obj)
 {
        int ret;


@@ -75,6 +92,12 @@ int canqueue_ends_init_chip(struct canque_ends_t *qends, struct chip_t *chip, st
 }
 
 
 }
 
 

+/**
+ * canqueue_ends_done_chip - finalizing of the ends structure for CAN chips
+ * @qends: pointer to ends structure
+ *
+ * Return Value: Function should be designed such way to not fail.
+ */

 int canqueue_ends_done_chip(struct canque_ends_t *qends)
 {
        int delayed;
 int canqueue_ends_done_chip(struct canque_ends_t *qends)
 {
        int delayed;

diff --git a/lincan/src/finish.c b/lincan/src/finish.c
index 922b4d3608077fe03dfda6a78142707b7e2566b7..9016ae8b9b6c6cdc3ad9a9961446b7bc4766a40f 100644 (file)
--- a/lincan/src/finish.c
+++ b/lincan/src/finish.c
@@ -6,7 +6,10 @@
 #include "../include/setup.h"
 
 
 #include "../include/setup.h"
 
 

-
+/**
+ * msgobj_done - destroys one CAN message object
+ * @obj: pointer to CAN message object structure
+ */

 void msgobj_done(struct msgobj_t *obj)
 {
        int delayed=0;
 void msgobj_done(struct msgobj_t *obj)
 {
        int delayed=0;


@@ -44,6 +47,10 @@ void msgobj_done(struct msgobj_t *obj)
 }
 
 
 }
 
 

+/**
+ * canchip_done - destroys one CAN chip representation
+ * @chip: pointer to CAN chip structure
+ */

 void canchip_done(struct chip_t *chip)
 {
 
 void canchip_done(struct chip_t *chip)
 {
 


@@ -73,6 +80,10 @@ void canchip_done(struct chip_t *chip)
 
 }
 
 
 }
 

+/**
+ * candevice_done - destroys representation of one CAN device/board
+ * @candev: pointer to CAN device/board structure
+ */

 void candevice_done(struct candevice_t *candev)
 {
        int i;
 void candevice_done(struct candevice_t *candev)
 {
        int i;


@@ -93,6 +104,10 @@ void candevice_done(struct candevice_t *candev)
        candev->hwspecops=NULL;
 }
 
        candev->hwspecops=NULL;
 }
 

+/**
+ * candevice_done - destroys representation of all CAN devices/boards
+ * @canhw: pointer to the root of all CAN hardware representation
+ */

 void canhardware_done(struct canhardware_t *canhw)
 {
        int i;
 void canhardware_done(struct canhardware_t *canhw)
 {
        int i;

diff --git a/lincan/src/main.c b/lincan/src/main.c
index f4edb7964134061d6e2470983dbb5071e2deac93..02a8ef9f7880dcf0701a770c28ee2b8eb7393439 100644 (file)
--- a/lincan/src/main.c
+++ b/lincan/src/main.c
@@ -199,6 +199,7 @@ int init_module(void)
        }
 
        #ifdef CAN_WITH_RTL
        }
 
        #ifdef CAN_WITH_RTL

+       can_spin_lock_init(&can_irq_manipulation_lock);

        canqueue_rtl_initialize();
        res=rtl_register_rtldev(major,DEVICE_NAME,&can_fops_rtl);
        if (res<0) {
        canqueue_rtl_initialize();
        res=rtl_register_rtldev(major,DEVICE_NAME,&can_fops_rtl);
        if (res<0) {

diff --git a/lincan/src/setup.c b/lincan/src/setup.c
index 72ef1a9f2b2e51faf1ec284978a2dabb6d65cb31..75ca0ef5176b7d47ad7b574b6596428c384b9a71 100644 (file)
--- a/lincan/src/setup.c
+++ b/lincan/src/setup.c
@@ -24,6 +24,15 @@ int init_chip_struct(struct candevice_t *candev, int chipnr, int irq, long baudr
 int init_obj_struct(struct candevice_t *candev, struct chip_t *hostchip, int objnr);
 int init_chipspecops(struct candevice_t *candev, int chipnr);
 
 int init_obj_struct(struct candevice_t *candev, struct chip_t *hostchip, int objnr);
 int init_chipspecops(struct candevice_t *candev, int chipnr);
 

+/**
+ * can_checked_malloc - memory allocation with registering of requested blocks
+ * @size: size of the requested block
+ *
+ * The function is used in the driver initialization phase to catch possible memory
+ * leaks for future driver finalization or case, that driver initialization fail.
+ * 
+ * Return Value: pointer to the allocated memory or NULL in the case of fail
+ */

 void *can_checked_malloc(size_t size)
 {
        struct mem_addr *mem_new;
 void *can_checked_malloc(size_t size)
 {
        struct mem_addr *mem_new;


@@ -54,6 +63,10 @@ void *can_checked_malloc(size_t size)
        return address_p;
 }
 
        return address_p;
 }
 

+/**
+ * can_checked_free - free memory allocated by  can_checked_malloc()
+ * @address_p: pointer to the memory block
+ */

 int can_checked_free(void *address_p)
 {
        struct mem_addr **mem_pptr;
 int can_checked_free(void *address_p)
 {
        struct mem_addr **mem_pptr;


@@ -79,6 +92,12 @@ int can_checked_free(void *address_p)
 }
 
 
 }
 
 

+/**
+ * can_del_mem_list - check for stale memory allocations at driver finalization
+ *
+ * Checks, if there are still some memory blocks allocated and releases memory
+ * occupied by such blocks back to the system
+ */

 int can_del_mem_list(void)
 {
        struct mem_addr *mem;
 int can_del_mem_list(void)
 {
        struct mem_addr *mem;


@@ -102,6 +121,18 @@ int can_del_mem_list(void)
        return 0;
 }
 
        return 0;
 }
 

+/**
+ * can_request_io_region - request IO space region
+ * @start: the first IO port address
+ * @n: number of the consecutive IO port addresses
+ * @name: name/label for the requested region
+ *
+ * The function hides system specific implementation of the feature.
+ *
+ * Return Value: returns positive value (1) in the case, that region could
+ *     be reserved for the driver. Returns zero (0) if there is collision with
+ *     other driver or region cannot be taken for some other reason.
+ */

 int can_request_io_region(unsigned long start, unsigned long n, const char *name)
 {
     #if (LINUX_VERSION_CODE < KERNEL_VERSION(2,4,0))
 int can_request_io_region(unsigned long start, unsigned long n, const char *name)
 {
     #if (LINUX_VERSION_CODE < KERNEL_VERSION(2,4,0))


@@ -113,11 +144,28 @@ int can_request_io_region(unsigned long start, unsigned long n, const char *name
     #endif
 }
 
     #endif
 }
 

+/**
+ * can_release_io_region - release IO space region
+ * @start: the first IO port address
+ * @n: number of the consecutive IO port addresses
+ */

 void can_release_io_region(unsigned long start, unsigned long n)
 {
        release_region(start,n);
 }
 
 void can_release_io_region(unsigned long start, unsigned long n)
 {
        release_region(start,n);
 }
 

+/**
+ * can_request_mem_region - request memory space region
+ * @start: the first memory port physical address
+ * @n: number of the consecutive memory port addresses
+ * @name: name/label for the requested region
+ *
+ * The function hides system specific implementation of the feature.
+ *
+ * Return Value: returns positive value (1) in the case, that region could
+ *     be reserved for the driver. Returns zero (0) if there is collision with
+ *     other driver or region cannot be taken for some other reason.
+ */

 int can_request_mem_region(unsigned long start, unsigned long n, const char *name)
 {
     #if (LINUX_VERSION_CODE < KERNEL_VERSION(2,4,0))
 int can_request_mem_region(unsigned long start, unsigned long n, const char *name)
 {
     #if (LINUX_VERSION_CODE < KERNEL_VERSION(2,4,0))


@@ -127,6 +175,11 @@ int can_request_mem_region(unsigned long start, unsigned long n, const char *nam
     #endif
 }
 
     #endif
 }
 

+/**
+ * can_release_mem_region - release memory space region
+ * @start: the first memory port physical address
+ * @n: number of the consecutive memory port addresses
+ */

 void can_release_mem_region(unsigned long start, unsigned long n)
 {
     #if (LINUX_VERSION_CODE < KERNEL_VERSION(2,4,0))
 void can_release_mem_region(unsigned long start, unsigned long n)
 {
     #if (LINUX_VERSION_CODE < KERNEL_VERSION(2,4,0))


@@ -136,8 +189,17 @@ void can_release_mem_region(unsigned long start, unsigned long n)
     #endif
 }
 
     #endif
 }
 

-/* This function shifts all base address structures acording to address
-   translation between physical and virtual address mappings */
+/**
+ * can_base_addr_fixup - relocates board physical memory addresses to the CPU accessible ones
+ * @candev: pointer to the previously filled device/board, chips and message objects structures
+ * @new_base: @candev new base address
+ *
+ * This function adapts base addresses of all structures of one board
+ * to the new board base address.
+ * It is required for translation between physical and virtual address mappings.
+ * This function is prepared to simplify board specific xxx_request_io() function
+ * for memory mapped devices.
+ */

 int can_base_addr_fixup(struct candevice_t *candev, unsigned long new_base)
 {
        unsigned long offs;
 int can_base_addr_fixup(struct candevice_t *candev, unsigned long new_base)
 {
        unsigned long offs;


@@ -154,6 +216,13 @@ int can_base_addr_fixup(struct candevice_t *candev, unsigned long new_base)
 }
 
 
 }
 
 

+/**
+ * register_obj_struct - registers message object into global array
+ * @obj: the initialized message object being registered
+ * @minorbase: wanted minor number, if (-1) automatically selected
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int register_obj_struct(struct msgobj_t *obj, int minorbase)
 {
        static int next_minor=0;
 int register_obj_struct(struct msgobj_t *obj, int minorbase)
 {
        static int next_minor=0;


@@ -178,6 +247,13 @@ int register_obj_struct(struct msgobj_t *obj, int minorbase)
 }
 
 
 }
 
 

+/**
+ * register_chip_struct - registers chip into global array
+ * @chip: the initialized chip structure being registered
+ * @minorbase: wanted minor number base, if (-1) automatically selected
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int register_chip_struct(struct chip_t *chip, int minorbase)
 {
        static int next_chip_slot=0;
 int register_chip_struct(struct chip_t *chip, int minorbase)
 {
        static int next_chip_slot=0;


@@ -199,7 +275,14 @@ int register_chip_struct(struct chip_t *chip, int minorbase)
 }
 
 
 }
 
 

-/* The function init_hw_struct is used to initialize the hardware structure. */
+
+/**
+ * init_hw_struct - initializes driver hardware description structures
+ *
+ * The function init_hw_struct() is used to initialize the hardware structure.
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int init_hw_struct(void)
 {
        int i=0;
 int init_hw_struct(void)
 {
        int i=0;


@@ -220,8 +303,28 @@ int init_hw_struct(void)
        return 0;
 }
 
        return 0;
 }
 

-/* The function init_device_struct is used to initialize a single device 
- * structure.
+/**
+ * init_device_struct - initializes single CAN device/board
+ * @card: index into @hardware_p HW description
+ * @chan_param_idx_p: pointer to the index into arrays of the CAN channel parameters
+ * @irq_param_idx_p: pointer to the index into arrays of the per CAN channel IRQ parameters
+ *
+ * The function builds representation of the one board from parameters provided
+ * in the module parameters arrays: 
+ *     @hw[card] .. hardware type,
+ *     @io[card] .. base IO address,
+ *     @baudrate[chan_param_idx] .. per channel baudrate,
+ *     @minor[chan_param_idx] .. optional specification of requested channel minor base,
+ *     @irq[irq_param_idx] .. one or more board/chips IRQ parameters.
+ * The indexes are advanced after consumed parameters if the registration is successful.
+ *
+ * The hardware specific operations of the device/board are initialized by call to
+ * init_hwspecops() function. Then board data are initialized by board specific 
+ * init_hw_data() function. Then chips and objects representation is build by
+ * init_chip_struct() function. If all above steps are successful, chips and
+ * message objects are registered into global arrays. 
+ *
+ * Return Value: returns negative number in the case of fail

  */
 int init_device_struct(int card, int *chan_param_idx_p, int *irq_param_idx_p)
 {
  */
 int init_device_struct(int card, int *chan_param_idx_p, int *irq_param_idx_p)
 {


@@ -308,8 +411,19 @@ int init_device_struct(int card, int *chan_param_idx_p, int *irq_param_idx_p)
        
 }
 
        
 }
 

-/* The function init_chip_struct is used to initialize all chip_t structures
- * on one hardware board.
+/**
+ * init_chip_struct - initializes one CAN chip structure
+ * @candev: pointer to the corresponding CAN device/board
+ * @chipnr: index of the chip in the corresponding device/board structure
+ * @irq: chip IRQ number or (-1) if not appropriate
+ * @baudrate: baudrate in the units of 1Bd
+ *
+ * Chip structure is allocated and chip specific operations are filled by 
+ * call to board specific init_chip_data() function and generic
+ * init_chipspecops() function. The message objects are generated by 
+ * calls to init_obj_struct() function.
+ *
+ * Return Value: returns negative number in the case of fail

  */
 int init_chip_struct(struct candevice_t *candev, int chipnr, int irq, long baudrate)
 {
  */
 int init_chip_struct(struct candevice_t *candev, int chipnr, int irq, long baudrate)
 {


@@ -350,6 +464,17 @@ int init_chip_struct(struct candevice_t *candev, int chipnr, int irq, long baudr
 }
 
 
 }
 
 

+/**
+ * init_obj_struct - initializes one CAN message object structure
+ * @candev: pointer to the corresponding CAN device/board
+ * @hostchip: pointer to the chip containing this object
+ * @objnr: index of the builded object in the chip structure
+ *
+ * The function initializes message object structure and allocates and initializes
+ * CAN queue chip ends structure.
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int init_obj_struct(struct candevice_t *candev, struct chip_t *hostchip, int objnr)
 {
        struct canque_ends_t *qends;
 int init_obj_struct(struct candevice_t *candev, struct chip_t *hostchip, int objnr)
 {
        struct canque_ends_t *qends;


@@ -388,6 +513,17 @@ int init_obj_struct(struct candevice_t *candev, struct chip_t *hostchip, int obj
 }
 
 
 }
 
 

+/**
+ * init_hwspecops - finds and initializes board/device specific operations
+ * @candev: pointer to the corresponding CAN device/board
+ * @irqnum_p: optional pointer to the number of interrupts required by board
+ *
+ * The function searches board @hwname in the list of supported boards types.
+ * The board type specific board_register() function is used to initialize
+ * @hwspecops operations.
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int init_hwspecops(struct candevice_t *candev, int *irqnum_p)
 {
        const struct boardtype_t *brp;
 int init_hwspecops(struct candevice_t *candev, int *irqnum_p)
 {
        const struct boardtype_t *brp;


@@ -407,6 +543,17 @@ int init_hwspecops(struct candevice_t *candev, int *irqnum_p)
 }
 
 
 }
 
 

+/**
+ * init_chipspecops - fills chip specific operations for board for known chip types
+ * @candev: pointer to the corresponding CAN device/board
+ * @chipnr: index of the chip in the device/board structure
+ *
+ * The function fills chip specific operations for next known generic chip
+ * types "i82527", "sja1000", "sja1000p" (PeliCAN). Other non generic chip types
+ * operations has to be initialized in the board specific init_chip_data() function.
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int init_chipspecops(struct candevice_t *candev, int chipnr)
 {
        if (!strcmp(candev->chip[chipnr]->chip_type,"i82527")) {
 int init_chipspecops(struct candevice_t *candev, int chipnr)
 {
        if (!strcmp(candev->chip[chipnr]->chip_type,"i82527")) {


@@ -427,6 +574,12 @@ int init_chipspecops(struct candevice_t *candev, int chipnr)
 
 #ifndef CAN_WITH_RTL
 
 
 #ifndef CAN_WITH_RTL
 

+/**
+ * can_chip_setup_irq - attaches chip to the system interrupt processing
+ * @chip: pointer to CAN chip structure
+ *
+ * Return Value: returns negative number in the case of fail
+ */

 int can_chip_setup_irq(struct chip_t *chip)
 {
        if(chip==NULL)
 int can_chip_setup_irq(struct chip_t *chip)
 {
        if(chip==NULL)


@@ -444,6 +597,10 @@ int can_chip_setup_irq(struct chip_t *chip)
 }
 
 
 }
 
 

+/**
+ * can_chip_free_irq - unregisters chip interrupt handler from the system
+ * @chip: pointer to CAN chip structure
+ */

 void can_chip_free_irq(struct chip_t *chip)
 {
        if((chip->flags & CHIP_IRQ_SETUP) && (chip->chip_irq>=0)) {
 void can_chip_free_irq(struct chip_t *chip)
 {
        if((chip->flags & CHIP_IRQ_SETUP) && (chip->chip_irq>=0)) {