From dd8f5100e766813dca62a82c6b99ebf3648f2448 Mon Sep 17 00:00:00 2001 From: ppisa Date: Sun, 8 Feb 2004 14:56:15 +0000 Subject: [PATCH] LinCAN driver structured comments updated. --- lincan/include/can_queue.h | 4 +- lincan/include/can_sysdep.h | 2 + lincan/include/main.h | 15 ++++ lincan/src/can_devrtl.c | 2 + lincan/src/can_quekern.c | 9 +- lincan/src/can_quertl.c | 6 ++ lincan/src/devcommon.c | 23 +++++ lincan/src/finish.c | 17 +++- lincan/src/main.c | 1 + lincan/src/setup.c | 171 ++++++++++++++++++++++++++++++++++-- 10 files changed, 240 insertions(+), 10 deletions(-) diff --git a/lincan/include/can_queue.h b/lincan/include/can_queue.h index 8821dca..1392f3a 100644 --- 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. - * @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 @@ -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. + * @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. diff --git a/lincan/include/can_sysdep.h b/lincan/include/can_sysdep.h index 5b33971..0dd0e55 100644 --- 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)) +extern can_spinlock_t can_irq_manipulation_lock; + #endif /*CAN_WITH_RTL*/ #endif /*_CAN_SYSDEP_H*/ diff --git a/lincan/include/main.h b/lincan/include/main.h index b4a0b32..2fa81ce 100644 --- 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 + * @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 @@ -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 + * @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 @@ -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_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; diff --git a/lincan/src/can_devrtl.c b/lincan/src/can_devrtl.c index 812ea84..37bbbf1 100644 --- a/lincan/src/can_devrtl.c +++ b/lincan/src/can_devrtl.c @@ -16,6 +16,8 @@ #include +can_spinlock_t can_irq_manipulation_lock; + 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 5089e5c..3eea5a3 100644 --- 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 + * + * 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) { @@ -376,7 +383,7 @@ struct canque_edge_t *canque_new_edge_kern(int slotsnr) #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 diff --git a/lincan/src/can_quertl.c b/lincan/src/can_quertl.c index dc59f8e..2ebc265 100644 --- 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); @@ -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); diff --git a/lincan/src/devcommon.c b/lincan/src/devcommon.c index c0b6028..e17a061 100644 --- a/lincan/src/devcommon.c +++ b/lincan/src/devcommon.c @@ -12,6 +12,17 @@ #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; @@ -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; @@ -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; diff --git a/lincan/src/finish.c b/lincan/src/finish.c index 922b4d3..9016ae8 100644 --- a/lincan/src/finish.c +++ b/lincan/src/finish.c @@ -6,7 +6,10 @@ #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; @@ -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) { @@ -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; @@ -93,6 +104,10 @@ void candevice_done(struct candevice_t *candev) 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; diff --git a/lincan/src/main.c b/lincan/src/main.c index f4edb79..02a8ef9 100644 --- a/lincan/src/main.c +++ b/lincan/src/main.c @@ -199,6 +199,7 @@ int init_module(void) } #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) { diff --git a/lincan/src/setup.c b/lincan/src/setup.c index 72ef1a9..75ca0ef 100644 --- 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); +/** + * 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; @@ -54,6 +63,10 @@ void *can_checked_malloc(size_t size) 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; @@ -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; @@ -102,6 +121,18 @@ int can_del_mem_list(void) 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)) @@ -113,11 +144,28 @@ int can_request_io_region(unsigned long start, unsigned long n, const char *name #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); } +/** + * 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)) @@ -127,6 +175,11 @@ int can_request_mem_region(unsigned long start, unsigned long n, const char *nam #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)) @@ -136,8 +189,17 @@ void can_release_mem_region(unsigned long start, unsigned long n) #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; @@ -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; @@ -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; @@ -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; @@ -220,8 +303,28 @@ int init_hw_struct(void) 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) { @@ -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) { @@ -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; @@ -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; @@ -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")) { @@ -427,6 +574,12 @@ int init_chipspecops(struct candevice_t *candev, int chipnr) #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) @@ -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)) { -- 2.39.2