gigaset: add kerneldoc comments (1cec9727) · Commits · 方亚芬 / raspberrypi_linux

drivers/isdn/gigaset/asyncdata.c

+18 −10

Original line number	Diff line number	Diff line
		@@ -334,7 +334,14 @@ static inline int iraw_loop(unsigned char c, unsigned char *src, int numbytes,
		return startbytes - numbytes;
		}

		/* process a block of data received from the device
		/**
		* gigaset_m10x_input() - process a block of data received from the device
		* @inbuf: received data and device descriptor structure.
		*
		* Called by hardware module {ser,usb}_gigaset with a block of received
		* bytes. Separates the bytes received over the serial data channel into
		* user data and command replies (locked/unlocked) according to the
		* current state of the interface.
		*/
		void gigaset_m10x_input(struct inbuf_t *inbuf)
		{
		@@ -543,16 +550,17 @@ static struct sk_buff iraw_encode(struct sk_buff skb, int head, int tail)
		return iraw_skb;
		}

		/* gigaset_send_skb
		* called by common.c to queue an skb for sending
		* and start transmission if necessary
		* parameters:
		* B Channel control structure
		* skb
		/**
		* gigaset_m10x_send_skb() - queue an skb for sending
		* @bcs: B channel descriptor structure.
		* @skb: data to send.
		*
		* Called by i4l.c to encode and queue an skb for sending, and start
		* transmission if necessary.
		*
		* Return value:
		* number of bytes accepted for sending
		* (skb->len if ok, 0 if out of buffer space)
		* or error code (< 0, eg. -EINVAL)
		* number of bytes accepted for sending (skb->len) if ok,
		* error code < 0 (eg. -ENOMEM) on error
		*/
		int gigaset_m10x_send_skb(struct bc_state bcs, struct sk_buff skb)
		{

drivers/isdn/gigaset/common.c

+104 −22

Original line number	Diff line number	Diff line
		@@ -38,6 +38,17 @@ MODULE_PARM_DESC(debug, "debug level");
		#define VALID_MINOR 0x01
		#define VALID_ID 0x02

		/**
		* gigaset_dbg_buffer() - dump data in ASCII and hex for debugging
		* @level: debugging level.
		* @msg: message prefix.
		* @len: number of bytes to dump.
		* @buf: data to dump.
		*
		* If the current debugging level includes one of the bits set in @level,
		* @len bytes starting at @buf are logged to dmesg at KERN_DEBUG prio,
		* prefixed by the text @msg.
		*/
		void gigaset_dbg_buffer(enum debuglevel level, const unsigned char *msg,
		size_t len, const unsigned char *buf)
		{
		@@ -280,6 +291,20 @@ static void clear_events(struct cardstate *cs)
		spin_unlock_irqrestore(&cs->ev_lock, flags);
		}

		/**
		* gigaset_add_event() - add event to device event queue
		* @cs: device descriptor structure.
		* @at_state: connection state structure.
		* @type: event type.
		* @ptr: pointer parameter for event.
		* @parameter: integer parameter for event.
		* @arg: pointer parameter for event.
		*
		* Allocate an event queue entry from the device's event queue, and set it up
		* with the parameters given.
		*
		* Return value: added event
		*/
		struct event_t gigaset_add_event(struct cardstate cs,
		struct at_state_t *at_state, int type,
		void ptr, int parameter, void arg)
		@@ -404,6 +429,15 @@ static void make_invalid(struct cardstate *cs, unsigned mask)
		spin_unlock_irqrestore(&drv->lock, flags);
		}

		/**
		* gigaset_freecs() - free all associated ressources of a device
		* @cs: device descriptor structure.
		*
		* Stops all tasklets and timers, unregisters the device from all
		* subsystems it was registered to, deallocates the device structure
		* @cs and all structures referenced from it.
		* Operations on the device should be stopped before calling this.
		*/
		void gigaset_freecs(struct cardstate *cs)
		{
		int i;
		@@ -512,7 +546,12 @@ static void gigaset_inbuf_init(struct inbuf_t inbuf, struct bc_state bcs,
		inbuf->inputstate = inputstate;
		}

		/* append received bytes to inbuf */
		/**
		* gigaset_fill_inbuf() - append received data to input buffer
		* @inbuf: buffer structure.
		* @src: received data.
		* @numbytes: number of bytes received.
		*/
		int gigaset_fill_inbuf(struct inbuf_t inbuf, const unsigned char src,
		unsigned numbytes)
		{
		@@ -612,20 +651,22 @@ static struct bc_state gigaset_initbcs(struct bc_state bcs,
		return NULL;
		}

		/* gigaset_initcs
		/**
		* gigaset_initcs() - initialize device structure
		* @drv: hardware driver the device belongs to
		* @channels: number of B channels supported by device
		* @onechannel: !=0 if B channel data and AT commands share one
		* communication channel (M10x),
		* ==0 if B channels have separate communication channels (base)
		* @ignoreframes: number of frames to ignore after setting up B channel
		* @cidmode: !=0: start in CallID mode
		* @modulename: name of driver module for LL registration
		*
		* Allocate and initialize cardstate structure for Gigaset driver
		* Calls hardware dependent gigaset_initcshw() function
		* Calls B channel initialization function gigaset_initbcs() for each B channel
		* parameters:
		* drv hardware driver the device belongs to
		* channels number of B channels supported by device
		* onechannel !=0: B channel data and AT commands share one
		* communication channel
		* ==0: B channels have separate communication channels
		* ignoreframes number of frames to ignore after setting up B channel
		* cidmode !=0: start in CallID mode
		* modulename name of driver module (used for I4L registration)
		* return value:
		*
		* Return value:
		* pointer to cardstate structure
		*/
		struct cardstate gigaset_initcs(struct gigaset_driver drv, int channels,
		@@ -843,6 +884,17 @@ static void cleanup_cs(struct cardstate *cs)
		}


		/**
		* gigaset_start() - start device operations
		* @cs: device descriptor structure.
		*
		* Prepares the device for use by setting up communication parameters,
		* scheduling an EV_START event to initiate device initialization, and
		* waiting for completion of the initialization.
		*
		* Return value:
		* 1 - success, 0 - error
		*/
		int gigaset_start(struct cardstate *cs)
		{
		unsigned long flags;
		@@ -885,9 +937,15 @@ error:
		}
		EXPORT_SYMBOL_GPL(gigaset_start);

		/* gigaset_shutdown
		* check if a device is associated to the cardstate structure and stop it
		* return value: 0 if ok, -1 if no device was associated
		/**
		* gigaset_shutdown() - shut down device operations
		* @cs: device descriptor structure.
		*
		* Deactivates the device by scheduling an EV_SHUTDOWN event and
		* waiting for completion of the shutdown.
		*
		* Return value:
		* 0 - success, -1 - error (no device associated)
		*/
		int gigaset_shutdown(struct cardstate *cs)
		{
		@@ -918,6 +976,13 @@ exit:
		}
		EXPORT_SYMBOL_GPL(gigaset_shutdown);

		/**
		* gigaset_stop() - stop device operations
		* @cs: device descriptor structure.
		*
		* Stops operations on the device by scheduling an EV_STOP event and
		* waiting for completion of the shutdown.
		*/
		void gigaset_stop(struct cardstate *cs)
		{
		mutex_lock(&cs->mutex);
		@@ -1026,6 +1091,14 @@ struct cardstate gigaset_get_cs_by_tty(struct tty_struct tty)
		return gigaset_get_cs_by_minor(tty->index + tty->driver->minor_start);
		}

		/**
		* gigaset_freedriver() - free all associated ressources of a driver
		* @drv: driver descriptor structure.
		*
		* Unregisters the driver from the system and deallocates the driver
		* structure @drv and all structures referenced from it.
		* All devices should be shut down before calling this.
		*/
		void gigaset_freedriver(struct gigaset_driver *drv)
		{
		unsigned long flags;
		@@ -1041,14 +1114,16 @@ void gigaset_freedriver(struct gigaset_driver *drv)
		}
		EXPORT_SYMBOL_GPL(gigaset_freedriver);

		/* gigaset_initdriver
		/**
		* gigaset_initdriver() - initialize driver structure
		* @minor: First minor number
		* @minors: Number of minors this driver can handle
		* @procname: Name of the driver
		* @devname: Name of the device files (prefix without minor number)
		*
		* Allocate and initialize gigaset_driver structure. Initialize interface.
		* parameters:
		* minor First minor number
		* minors Number of minors this driver can handle
		* procname Name of the driver
		* devname Name of the device files (prefix without minor number)
		* return value:
		*
		* Return value:
		* Pointer to the gigaset_driver structure on success, NULL on failure.
		*/
		struct gigaset_driver *gigaset_initdriver(unsigned minor, unsigned minors,
		@@ -1101,6 +1176,13 @@ error:
		}
		EXPORT_SYMBOL_GPL(gigaset_initdriver);

		/**
		* gigaset_blockdriver() - block driver
		* @drv: driver descriptor structure.
		*
		* Prevents the driver from attaching new devices, in preparation for
		* deregistration.
		*/
		void gigaset_blockdriver(struct gigaset_driver *drv)
		{
		drv->blocked = 1;

drivers/isdn/gigaset/ev-layer.c

+7 −2

Original line number	Diff line number	Diff line
		@@ -473,8 +473,13 @@ static int cid_of_response(char *s)
		//FIXME is ;<digit>+ at end of non-CID response really impossible?
		}

		/* This function will be called via task queue from the callback handler.
		* We received a modem response and have to handle it..
		/**
		* gigaset_handle_modem_response() - process received modem response
		* @cs: device descriptor structure.
		*
		* Called by asyncdata/isocdata if a block of data received from the
		* device must be processed as a modem command response. The data is
		* already in the cs structure.
		*/
		void gigaset_handle_modem_response(struct cardstate *cs)
		{

drivers/isdn/gigaset/i4l.c

+17 −0

Original line number	Diff line number	Diff line
		@@ -85,6 +85,14 @@ static int writebuf_from_LL(int driverID, int channel, int ack,
		return cs->ops->send_skb(bcs, skb);
		}

		/**
		* gigaset_skb_sent() - acknowledge sending an skb
		* @bcs: B channel descriptor structure.
		* @skb: sent data.
		*
		* Called by hardware module {bas,ser,usb}_gigaset when the data in a
		* skb has been successfully sent, for signalling completion to the LL.
		*/
		void gigaset_skb_sent(struct bc_state bcs, struct sk_buff skb)
		{
		unsigned len;
		@@ -461,6 +469,15 @@ int gigaset_isdn_setup_accept(struct at_state_t *at_state)
		return 0;
		}

		/**
		* gigaset_isdn_icall() - signal incoming call
		* @at_state: connection state structure.
		*
		* Called by main module to notify the LL that an incoming call has been
		* received. @at_state contains the parameters of the call.
		*
		* Return value: call disposition (ICALL_*)
		*/
		int gigaset_isdn_icall(struct at_state_t *at_state)
		{
		struct cardstate *cs = at_state->cs;

drivers/isdn/gigaset/interface.c

+9 −0

Original line number	Diff line number	Diff line
		@@ -616,6 +616,15 @@ void gigaset_if_free(struct cardstate *cs)
		tty_unregister_device(drv->tty, cs->minor_index);
		}

		/**
		* gigaset_if_receive() - pass a received block of data to the tty device
		* @cs: device descriptor structure.
		* @buffer: received data.
		* @len: number of bytes received.
		*
		* Called by asyncdata/isocdata if a block of data received from the
		* device must be sent to userspace through the ttyG* device.
		*/
		void gigaset_if_receive(struct cardstate *cs,
		unsigned char *buffer, size_t len)
		{