gigaset: add kerneldoc comments (1cec9727) · Commits · e / devices / android_kernel_oneplus_sm8150

drivers/isdn/gigaset/asyncdata.c

+18 −10

Original line number	Original line	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;		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)		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;		return iraw_skb;
	}		}

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

drivers/isdn/gigaset/common.c

+104 −22

Original line number	Original line	Diff line number	Diff line
	@@ -38,6 +38,17 @@ MODULE_PARM_DESC(debug, "debug level");
	#define VALID_MINOR 0x01		#define VALID_MINOR 0x01
	#define VALID_ID 0x02		#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,		void gigaset_dbg_buffer(enum debuglevel level, const unsigned char *msg,
	size_t len, const unsigned char *buf)		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);		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 event_t gigaset_add_event(struct cardstate cs,
	struct at_state_t *at_state, int type,		struct at_state_t *at_state, int type,
	void ptr, int parameter, void arg)		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);		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)		void gigaset_freecs(struct cardstate *cs)
	{		{
	int i;		int i;
	@@ -512,7 +546,12 @@ static void gigaset_inbuf_init(struct inbuf_t inbuf, struct bc_state bcs,
	inbuf->inputstate = inputstate;		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,		int gigaset_fill_inbuf(struct inbuf_t inbuf, const unsigned char src,
	unsigned numbytes)		unsigned numbytes)
	{		{
	@@ -612,20 +651,22 @@ static struct bc_state gigaset_initbcs(struct bc_state bcs,
	return NULL;		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		* Allocate and initialize cardstate structure for Gigaset driver
	* Calls hardware dependent gigaset_initcshw() function		* Calls hardware dependent gigaset_initcshw() function
	* Calls B channel initialization function gigaset_initbcs() for each B channel		* Calls B channel initialization function gigaset_initbcs() for each B channel
	* parameters:		*
	* drv hardware driver the device belongs to		* Return value:
	* 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:
	* pointer to cardstate structure		* pointer to cardstate structure
	*/		*/
	struct cardstate gigaset_initcs(struct gigaset_driver drv, int channels,		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)		int gigaset_start(struct cardstate *cs)
	{		{
	unsigned long flags;		unsigned long flags;
	@@ -885,9 +937,15 @@ int gigaset_start(struct cardstate *cs)
	}		}
	EXPORT_SYMBOL_GPL(gigaset_start);		EXPORT_SYMBOL_GPL(gigaset_start);

	/* gigaset_shutdown		/**
	* check if a device is associated to the cardstate structure and stop it		* gigaset_shutdown() - shut down device operations
	* return value: 0 if ok, -1 if no device was associated		* @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)		int gigaset_shutdown(struct cardstate *cs)
	{		{
	@@ -918,6 +976,13 @@ int gigaset_shutdown(struct cardstate *cs)
	}		}
	EXPORT_SYMBOL_GPL(gigaset_shutdown);		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)		void gigaset_stop(struct cardstate *cs)
	{		{
	mutex_lock(&cs->mutex);		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);		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)		void gigaset_freedriver(struct gigaset_driver *drv)
	{		{
	unsigned long flags;		unsigned long flags;
	@@ -1041,14 +1114,16 @@ void gigaset_freedriver(struct gigaset_driver *drv)
	}		}
	EXPORT_SYMBOL_GPL(gigaset_freedriver);		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.		* Allocate and initialize gigaset_driver structure. Initialize interface.
	* parameters:		*
	* minor First minor number		* Return value:
	* 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:
	* Pointer to the gigaset_driver structure on success, NULL on failure.		* Pointer to the gigaset_driver structure on success, NULL on failure.
	*/		*/
	struct gigaset_driver *gigaset_initdriver(unsigned minor, unsigned minors,		struct gigaset_driver *gigaset_initdriver(unsigned minor, unsigned minors,
	@@ -1101,6 +1176,13 @@ struct gigaset_driver *gigaset_initdriver(unsigned minor, unsigned minors,
	}		}
	EXPORT_SYMBOL_GPL(gigaset_initdriver);		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)		void gigaset_blockdriver(struct gigaset_driver *drv)
	{		{
	drv->blocked = 1;		drv->blocked = 1;

drivers/isdn/gigaset/ev-layer.c

+7 −2

Original line number	Original line	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?		//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)		void gigaset_handle_modem_response(struct cardstate *cs)
	{		{

drivers/isdn/gigaset/i4l.c

+17 −0

Original line number	Original line	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);		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)		void gigaset_skb_sent(struct bc_state bcs, struct sk_buff skb)
	{		{
	unsigned len;		unsigned len;
	@@ -461,6 +469,15 @@ int gigaset_isdn_setup_accept(struct at_state_t *at_state)
	return 0;		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)		int gigaset_isdn_icall(struct at_state_t *at_state)
	{		{
	struct cardstate *cs = at_state->cs;		struct cardstate *cs = at_state->cs;

drivers/isdn/gigaset/interface.c

+9 −0

Original line number	Original line	Diff line number	Diff line
	@@ -616,6 +616,15 @@ void gigaset_if_free(struct cardstate *cs)
	tty_unregister_device(drv->tty, cs->minor_index);		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,		void gigaset_if_receive(struct cardstate *cs,
	unsigned char *buffer, size_t len)		unsigned char *buffer, size_t len)
	{		{