spi: spi cleanups

- Rearranged multi-line comment style. - Add tabs. - Add spaces. Signed-off-by: Jagannadha Sutradharudu Teki <jaganna@xilinx.com>

spi: spi cleanups
- Rearranged multi-line comment style. - Add tabs. - Add spaces. Signed-off-by: Jagannadha Sutradharudu Teki <jaganna@xilinx.com>
Jagannadha Sutradharudu Teki
1 parent a5e8199a13
Showing 1 changed file with 44 additions and 43 deletions Side-by-side Diff
include/spi.h
@@ -29,10 +29,11 @@
 #define SPI_XFER_END	0x02			/* Deassert CS after transfer */
  
 /* Header byte that marks the start of the message */
-#define SPI_PREAMBLE_END_BYTE	0xec
+#define SPI_PREAMBLE_END_BYTE		0xec
  
-/*-----------------------------------------------------------------------
- * Representation of a SPI slave, i.e. what we're communicating with.
+/**
+ * struct spi_slave: Representation of a SPI slave,
+ *		      i.e. what we're communicating with.
  *
  * Drivers are expected to extend this with controller-specific data.
  *
  
@@ -42,12 +43,12 @@
  *		be written at once, excluding command bytes.
  */
 struct spi_slave {
-	unsigned int	bus;
-	unsigned int	cs;
+	unsigned int bus;
+	unsigned int cs;
 	unsigned int max_write_size;
 };
  
-/*-----------------------------------------------------------------------
+/**
  * Initialization, must be called once on start up.
  *
  * TODO: I don't think we really need this.
@@ -60,10 +61,10 @@
  * Allocate and zero all fields in the spi slave, and set the bus/chip
  * select. Use the helper macro spi_alloc_slave() to call this.
  *
- * @offset: Offset of struct spi_slave within slave structure
- * @size: Size of slave structure
- * @bus: Bus ID of the slave chip.
- * @cs: Chip select ID of the slave chip on the specified bus.
+ * @offset:	Offset of struct spi_slave within slave structure.
+ * @size:	Size of slave structure.
+ * @bus:	Bus ID of the slave chip.
+ * @cs:		Chip select ID of the slave chip on the specified bus.
  */
 void *spi_do_alloc_slave(int offset, int size, unsigned int bus,
 			 unsigned int cs);
@@ -74,10 +75,10 @@
  * Allocate and zero all fields in the spi slave, and set the bus/chip
  * select.
  *
- * @_struct: Name of structure to allocate (e.g. struct tegra_spi). This
- *	structure must contain a member 'struct spi_slave *slave'.
- * @bus: Bus ID of the slave chip.
- * @cs: Chip select ID of the slave chip on the specified bus.
+ * @_struct:	Name of structure to allocate (e.g. struct tegra_spi).
+ *		This structure must contain a member 'struct spi_slave *slave'.
+ * @bus:	Bus ID of the slave chip.
+ * @cs:		Chip select ID of the slave chip on the specified bus.
  */
 #define spi_alloc_slave(_struct, bus, cs) \
 	spi_do_alloc_slave(offsetof(_struct, slave), \
  
@@ -89,13 +90,13 @@
  * Allocate and zero all fields in the spi slave, and set the bus/chip
  * select.
  *
- * @bus: Bus ID of the slave chip.
- * @cs: Chip select ID of the slave chip on the specified bus.
+ * @bus:	Bus ID of the slave chip.
+ * @cs:		Chip select ID of the slave chip on the specified bus.
  */
 #define spi_alloc_slave_base(bus, cs) \
 	spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs)
  
-/*-----------------------------------------------------------------------
+/**
  * Set up communications parameters for a SPI slave.
  *
  * This must be called once for each slave. Note that this function
@@ -103,10 +104,10 @@
  * contents of spi_slave so that the hardware can be easily
  * initialized later.
  *
- *   bus:     Bus ID of the slave chip.
- *   cs:      Chip select ID of the slave chip on the specified bus.
- *   max_hz:  Maximum SCK rate in Hz.
- *   mode:    Clock polarity, clock phase and other parameters.
+ * @bus:	Bus ID of the slave chip.
+ * @cs:		Chip select ID of the slave chip on the specified bus.
+ * @max_hz:	Maximum SCK rate in Hz.
+ * @mode:	Clock polarity, clock phase and other parameters.
  *
  * Returns: A spi_slave reference that can be used in subsequent SPI
  * calls, or NULL if one or more of the parameters are not supported.
  
  
@@ -114,14 +115,14 @@
 struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
 		unsigned int max_hz, unsigned int mode);
  
-/*-----------------------------------------------------------------------
+/**
  * Free any memory associated with a SPI slave.
  *
- *   slave:	The SPI slave
+ * @slave:	The SPI slave
  */
 void spi_free_slave(struct spi_slave *slave);
  
-/*-----------------------------------------------------------------------
+/**
  * Claim the bus and prepare it for communication with a given slave.
  *
  * This must be called before doing any transfers with a SPI slave. It
  
  
  
@@ -130,25 +131,25 @@
  * allowed to claim the same bus for several slaves without releasing
  * the bus in between.
  *
- *   slave:	The SPI slave
+ * @slave:	The SPI slave
  *
  * Returns: 0 if the bus was claimed successfully, or a negative value
  * if it wasn't.
  */
 int spi_claim_bus(struct spi_slave *slave);
  
-/*-----------------------------------------------------------------------
+/**
  * Release the SPI bus
  *
  * This must be called once for every call to spi_claim_bus() after
  * all transfers have finished. It may disable any SPI hardware as
  * appropriate.
  *
- *   slave:	The SPI slave
+ * @slave:	The SPI slave
  */
 void spi_release_bus(struct spi_slave *slave);
  
-/*-----------------------------------------------------------------------
+/**
  * SPI transfer
  *
  * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
  
  
  
@@ -161,19 +162,19 @@
  * temporary variables, this is OK).
  *
  * spi_xfer() interface:
- *   slave:	The SPI slave which will be sending/receiving the data.
- *   bitlen:	How many bits to write and read.
- *   dout:	Pointer to a string of bits to send out.  The bits are
+ * @slave:	The SPI slave which will be sending/receiving the data.
+ * @bitlen:	How many bits to write and read.
+ * @dout:	Pointer to a string of bits to send out.  The bits are
  *		held in a byte array and are sent MSB first.
- *   din:	Pointer to a string of bits that will be filled in.
- *   flags:	A bitwise combination of SPI_XFER_* flags.
+ * @din:	Pointer to a string of bits that will be filled in.
+ * @flags:	A bitwise combination of SPI_XFER_* flags.
  *
- *   Returns: 0 on success, not 0 on failure
+ * Returns: 0 on success, not 0 on failure
  */
 int  spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout,
 		void *din, unsigned long flags);
  
-/*-----------------------------------------------------------------------
+/**
  * Determine if a SPI chipselect is valid.
  * This function is provided by the board if the low-level SPI driver
  * needs it to determine if a given chipselect is actually valid.
@@ -183,7 +184,7 @@
  */
 int  spi_cs_is_valid(unsigned int bus, unsigned int cs);
  
-/*-----------------------------------------------------------------------
+/**
  * Activate a SPI chipselect.
  * This function is provided by the board code when using a driver
  * that can't control its chipselects automatically (e.g.
@@ -192,7 +193,7 @@
  */
 void spi_cs_activate(struct spi_slave *slave);
  
-/*-----------------------------------------------------------------------
+/**
  * Deactivate a SPI chipselect.
  * This function is provided by the board code when using a driver
  * that can't control its chipselects automatically (e.g.
  
  
  
@@ -201,18 +202,18 @@
  */
 void spi_cs_deactivate(struct spi_slave *slave);
  
-/*-----------------------------------------------------------------------
+/**
  * Set transfer speed.
  * This sets a new speed to be applied for next spi_xfer().
- *   slave:	The SPI slave
- *   hz:	The transfer speed
+ * @slave:	The SPI slave
+ * @hz:		The transfer speed
  */
 void spi_set_speed(struct spi_slave *slave, uint hz);
  
-/*-----------------------------------------------------------------------
+/**
  * Write 8 bits, then read 8 bits.
- *   slave:	The SPI slave we're communicating with
- *   byte:	Byte to be written
+ * @slave:	The SPI slave we're communicating with
+ * @byte:	Byte to be written
  *
  * Returns: The value that was read, or a negative value on error.
  *
...	...	@@ -29,10 +29,11 @@
29	29	#define SPI_XFER_END 0x02 /* Deassert CS after transfer */
30	30
31	31	/* Header byte that marks the start of the message */
32		-#define SPI_PREAMBLE_END_BYTE 0xec
	32	+#define SPI_PREAMBLE_END_BYTE 0xec
33	33
34		-/*-----------------------------------------------------------------------
35		- * Representation of a SPI slave, i.e. what we're communicating with.
	34	+/**
	35	+ * struct spi_slave: Representation of a SPI slave,
	36	+ * i.e. what we're communicating with.
36	37	*
37	38	* Drivers are expected to extend this with controller-specific data.
38	39	*
39	40
...	...	@@ -42,12 +43,12 @@
42	43	* be written at once, excluding command bytes.
43	44	*/
44	45	struct spi_slave {
45		- unsigned int bus;
46		- unsigned int cs;
	46	+ unsigned int bus;
	47	+ unsigned int cs;
47	48	unsigned int max_write_size;
48	49	};
49	50
50		-/*-----------------------------------------------------------------------
	51	+/**
51	52	* Initialization, must be called once on start up.
52	53	*
53	54	* TODO: I don't think we really need this.
...	...	@@ -60,10 +61,10 @@
60	61	* Allocate and zero all fields in the spi slave, and set the bus/chip
61	62	* select. Use the helper macro spi_alloc_slave() to call this.
62	63	*
63		- * @offset: Offset of struct spi_slave within slave structure
64		- * @size: Size of slave structure
65		- * @bus: Bus ID of the slave chip.
66		- * @cs: Chip select ID of the slave chip on the specified bus.
	64	+ * @offset: Offset of struct spi_slave within slave structure.
	65	+ * @size: Size of slave structure.
	66	+ * @bus: Bus ID of the slave chip.
	67	+ * @cs: Chip select ID of the slave chip on the specified bus.
67	68	*/
68	69	void *spi_do_alloc_slave(int offset, int size, unsigned int bus,
69	70	unsigned int cs);
...	...	@@ -74,10 +75,10 @@
74	75	* Allocate and zero all fields in the spi slave, and set the bus/chip
75	76	* select.
76	77	*
77		- * @_struct: Name of structure to allocate (e.g. struct tegra_spi). This
78		- * structure must contain a member 'struct spi_slave *slave'.
79		- * @bus: Bus ID of the slave chip.
80		- * @cs: Chip select ID of the slave chip on the specified bus.
	78	+ * @_struct: Name of structure to allocate (e.g. struct tegra_spi).
	79	+ * This structure must contain a member 'struct spi_slave *slave'.
	80	+ * @bus: Bus ID of the slave chip.
	81	+ * @cs: Chip select ID of the slave chip on the specified bus.
81	82	*/
82	83	#define spi_alloc_slave(_struct, bus, cs) \
83	84	spi_do_alloc_slave(offsetof(_struct, slave), \
84	85
...	...	@@ -89,13 +90,13 @@
89	90	* Allocate and zero all fields in the spi slave, and set the bus/chip
90	91	* select.
91	92	*
92		- * @bus: Bus ID of the slave chip.
93		- * @cs: Chip select ID of the slave chip on the specified bus.
	93	+ * @bus: Bus ID of the slave chip.
	94	+ * @cs: Chip select ID of the slave chip on the specified bus.
94	95	*/
95	96	#define spi_alloc_slave_base(bus, cs) \
96	97	spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs)
97	98
98		-/*-----------------------------------------------------------------------
	99	+/**
99	100	* Set up communications parameters for a SPI slave.
100	101	*
101	102	* This must be called once for each slave. Note that this function
...	...	@@ -103,10 +104,10 @@
103	104	* contents of spi_slave so that the hardware can be easily
104	105	* initialized later.
105	106	*
106		- * bus: Bus ID of the slave chip.
107		- * cs: Chip select ID of the slave chip on the specified bus.
108		- * max_hz: Maximum SCK rate in Hz.
109		- * mode: Clock polarity, clock phase and other parameters.
	107	+ * @bus: Bus ID of the slave chip.
	108	+ * @cs: Chip select ID of the slave chip on the specified bus.
	109	+ * @max_hz: Maximum SCK rate in Hz.
	110	+ * @mode: Clock polarity, clock phase and other parameters.
110	111	*
111	112	* Returns: A spi_slave reference that can be used in subsequent SPI
112	113	* calls, or NULL if one or more of the parameters are not supported.
113	114
114	115
...	...	@@ -114,14 +115,14 @@
114	115	struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
115	116	unsigned int max_hz, unsigned int mode);
116	117
117		-/*-----------------------------------------------------------------------
	118	+/**
118	119	* Free any memory associated with a SPI slave.
119	120	*
120		- * slave: The SPI slave
	121	+ * @slave: The SPI slave
121	122	*/
122	123	void spi_free_slave(struct spi_slave *slave);
123	124
124		-/*-----------------------------------------------------------------------
	125	+/**
125	126	* Claim the bus and prepare it for communication with a given slave.
126	127	*
127	128	* This must be called before doing any transfers with a SPI slave. It
128	129
129	130
130	131
...	...	@@ -130,25 +131,25 @@
130	131	* allowed to claim the same bus for several slaves without releasing
131	132	* the bus in between.
132	133	*
133		- * slave: The SPI slave
	134	+ * @slave: The SPI slave
134	135	*
135	136	* Returns: 0 if the bus was claimed successfully, or a negative value
136	137	* if it wasn't.
137	138	*/
138	139	int spi_claim_bus(struct spi_slave *slave);
139	140
140		-/*-----------------------------------------------------------------------
	141	+/**
141	142	* Release the SPI bus
142	143	*
143	144	* This must be called once for every call to spi_claim_bus() after
144	145	* all transfers have finished. It may disable any SPI hardware as
145	146	* appropriate.
146	147	*
147		- * slave: The SPI slave
	148	+ * @slave: The SPI slave
148	149	*/
149	150	void spi_release_bus(struct spi_slave *slave);
150	151
151		-/*-----------------------------------------------------------------------
	152	+/**
152	153	* SPI transfer
153	154	*
154	155	* This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
155	156
156	157
157	158
...	...	@@ -161,19 +162,19 @@
161	162	* temporary variables, this is OK).
162	163	*
163	164	* spi_xfer() interface:
164		- * slave: The SPI slave which will be sending/receiving the data.
165		- * bitlen: How many bits to write and read.
166		- * dout: Pointer to a string of bits to send out. The bits are
	165	+ * @slave: The SPI slave which will be sending/receiving the data.
	166	+ * @bitlen: How many bits to write and read.
	167	+ * @dout: Pointer to a string of bits to send out. The bits are
167	168	* held in a byte array and are sent MSB first.
168		- * din: Pointer to a string of bits that will be filled in.
169		- * flags: A bitwise combination of SPI_XFER_* flags.
	169	+ * @din: Pointer to a string of bits that will be filled in.
	170	+ * @flags: A bitwise combination of SPI_XFER_* flags.
170	171	*
171		- * Returns: 0 on success, not 0 on failure
	172	+ * Returns: 0 on success, not 0 on failure
172	173	*/
173	174	int spi_xfer(struct spi_slave slave, unsigned int bitlen, const void dout,
174	175	void *din, unsigned long flags);
175	176
176		-/*-----------------------------------------------------------------------
	177	+/**
177	178	* Determine if a SPI chipselect is valid.
178	179	* This function is provided by the board if the low-level SPI driver
179	180	* needs it to determine if a given chipselect is actually valid.
...	...	@@ -183,7 +184,7 @@
183	184	*/
184	185	int spi_cs_is_valid(unsigned int bus, unsigned int cs);
185	186
186		-/*-----------------------------------------------------------------------
	187	+/**
187	188	* Activate a SPI chipselect.
188	189	* This function is provided by the board code when using a driver
189	190	* that can't control its chipselects automatically (e.g.
...	...	@@ -192,7 +193,7 @@
192	193	*/
193	194	void spi_cs_activate(struct spi_slave *slave);
194	195
195		-/*-----------------------------------------------------------------------
	196	+/**
196	197	* Deactivate a SPI chipselect.
197	198	* This function is provided by the board code when using a driver
198	199	* that can't control its chipselects automatically (e.g.
199	200
200	201
201	202
...	...	@@ -201,18 +202,18 @@
201	202	*/
202	203	void spi_cs_deactivate(struct spi_slave *slave);
203	204
204		-/*-----------------------------------------------------------------------
	205	+/**
205	206	* Set transfer speed.
206	207	* This sets a new speed to be applied for next spi_xfer().
207		- * slave: The SPI slave
208		- * hz: The transfer speed
	208	+ * @slave: The SPI slave
	209	+ * @hz: The transfer speed
209	210	*/
210	211	void spi_set_speed(struct spi_slave *slave, uint hz);
211	212
212		-/*-----------------------------------------------------------------------
	213	+/**
213	214	* Write 8 bits, then read 8 bits.
214		- * slave: The SPI slave we're communicating with
215		- * byte: Byte to be written
	215	+ * @slave: The SPI slave we're communicating with
	216	+ * @byte: Byte to be written
216	217	*
217	218	* Returns: The value that was read, or a negative value on error.
218	219	*