X-Git-Url: http://rtime.felk.cvut.cz/gitweb/lincan.git/blobdiff_plain/d8365e7fd56ca15c05502848338017013e628a9d..2827b727d2910a3b48f9de7d67b3a67f59e256c7:/lincan/src/setup.c

diff --git a/lincan/src/setup.c b/lincan/src/setup.c
index 72ef1a9..6a59e2f 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)
 {
@@ -329,6 +443,7 @@ int init_chip_struct(struct candevice_t *candev, int chipnr, int irq, long baudr
 	chip->chipspecops=can_checked_malloc(sizeof(struct chipspecops_t));
 	if (chip->chipspecops==NULL)
 		return -ENOMEM;
+	memset(chip->chipspecops,0,sizeof(struct chipspecops_t));
 
 	chip->chip_idx=chipnr;
 	chip->hostdevice=candev;
@@ -350,6 +465,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 +514,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 +544,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 +575,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 +598,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)) {