tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: networking: convert caif files to ReST
There are two text files for caif, plus one already converted
file.
Convert the two remaining ones to ReST, create a new index.rst
file for CAIF, adding it to the main networking documentation
index.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
authored by
Mauro Carvalho Chehab
and committed by
David S. Miller
da50d57a
790ab249
+281
-228
+37
-17
Documentation/networking/caif/Linux-CAIF.txt
Documentation/networking/caif/linux_caif.rst
+37
-17
Documentation/networking/caif/Linux-CAIF.txt
Documentation/networking/caif/linux_caif.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: <isonum.txt>
3
+
4
+
==========
1
5
Linux CAIF
2
-
===========
3
-
copyright (C) ST-Ericsson AB 2010
4
-
Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
5
-
License terms: GNU General Public License (GPL) version 2
6
+
==========
7
+
8
+
Copyright |copy| ST-Ericsson AB 2010
9
+
10
+
:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
11
+
:License terms: GNU General Public License (GPL) version 2
6
12
7
13
8
14
Introduction
9
-
------------
15
+
============
16
+
10
17
CAIF is a MUX protocol used by ST-Ericsson cellular modems for
11
18
communication between Modem and host. The host processes can open virtual AT
12
19
channels, initiate GPRS Data connections, Video channels and Utility Channels.
···
23
16
and host. Currently, UART and Loopback are available for Linux.
24
17
25
18
26
-
Architecture:
27
-
------------
19
+
Architecture
20
+
============
21
+
28
22
The implementation of CAIF is divided into:
23
+
29
24
* CAIF Socket Layer and GPRS IP Interface.
30
25
* CAIF Core Protocol Implementation
31
26
* CAIF Link Layer, implemented as NET devices.
32
27
28
+
::
33
29
34
30
RTNL
35
31
!
···
56
46
57
47
58
48
59
-
I M P L E M E N T A T I O N
60
-
===========================
49
+
Implementation
50
+
==============
61
51
62
52
63
53
CAIF Core Protocol Layer
64
-
=========================================
54
+
------------------------
65
55
66
56
CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
67
57
It implements the CAIF protocol stack in a layered approach, where
···
69
59
The architecture is inspired by the design patterns "Protocol Layer" and
70
60
"Protocol Packet".
71
61
72
-
== CAIF structure ==
62
+
CAIF structure
63
+
^^^^^^^^^^^^^^
64
+
73
65
The Core CAIF implementation contains:
66
+
74
67
- Simple implementation of CAIF.
75
68
- Layered architecture (a la Streams), each layer in the CAIF
76
69
specification is implemented in a separate c-file.
···
86
73
to the called function (except for framing layers' receive function)
87
74
88
75
Layered Architecture
89
-
--------------------
76
+
====================
77
+
90
78
The CAIF protocol can be divided into two parts: Support functions and Protocol
91
79
Implementation. The support functions include:
92
80
···
126
112
- CFSERL CAIF Serial layer. Handles concatenation/split of frames
127
113
into CAIF Frames with correct length.
128
114
129
-
115
+
::
130
116
131
117
+---------+
132
118
| Config |
···
157
143
158
144
159
145
In this layered approach the following "rules" apply.
146
+
160
147
- All layers embed the same structure "struct cflayer"
161
148
- A layer does not depend on any other layer's private data.
162
-
- Layers are stacked by setting the pointers
149
+
- Layers are stacked by setting the pointers::
150
+
163
151
layer->up , layer->dn
164
-
- In order to send data upwards, each layer should do
152
+
153
+
- In order to send data upwards, each layer should do::
154
+
165
155
layer->up->receive(layer->up, packet);
166
-
- In order to send data downwards, each layer should do
156
+
157
+
- In order to send data downwards, each layer should do::
158
+
167
159
layer->dn->transmit(layer->dn, packet);
168
160
169
161
170
162
CAIF Socket and IP interface
171
-
===========================
163
+
============================
172
164
173
165
The IP interface and CAIF socket API are implemented on top of the
174
166
CAIF Core protocol. The IP Interface and CAIF socket have an instance of
-2
Documentation/networking/caif/caif.rst
-2
Documentation/networking/caif/caif.rst
+13
Documentation/networking/caif/index.rst
+13
Documentation/networking/caif/index.rst
+229
Documentation/networking/caif/spi_porting.rst
+229
Documentation/networking/caif/spi_porting.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
================
4
+
CAIF SPI porting
5
+
================
6
+
7
+
CAIF SPI basics
8
+
===============
9
+
10
+
Running CAIF over SPI needs some extra setup, owing to the nature of SPI.
11
+
Two extra GPIOs have been added in order to negotiate the transfers
12
+
between the master and the slave. The minimum requirement for running
13
+
CAIF over SPI is a SPI slave chip and two GPIOs (more details below).
14
+
Please note that running as a slave implies that you need to keep up
15
+
with the master clock. An overrun or underrun event is fatal.
16
+
17
+
CAIF SPI framework
18
+
==================
19
+
20
+
To make porting as easy as possible, the CAIF SPI has been divided in
21
+
two parts. The first part (called the interface part) deals with all
22
+
generic functionality such as length framing, SPI frame negotiation
23
+
and SPI frame delivery and transmission. The other part is the CAIF
24
+
SPI slave device part, which is the module that you have to write if
25
+
you want to run SPI CAIF on a new hardware. This part takes care of
26
+
the physical hardware, both with regard to SPI and to GPIOs.
27
+
28
+
- Implementing a CAIF SPI device:
29
+
30
+
- Functionality provided by the CAIF SPI slave device:
31
+
32
+
In order to implement a SPI device you will, as a minimum,
33
+
need to implement the following
34
+
functions:
35
+
36
+
::
37
+
38
+
int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev):
39
+
40
+
This function is called by the CAIF SPI interface to give
41
+
you a chance to set up your hardware to be ready to receive
42
+
a stream of data from the master. The xfer structure contains
43
+
both physical and logical addresses, as well as the total length
44
+
of the transfer in both directions.The dev parameter can be used
45
+
to map to different CAIF SPI slave devices.
46
+
47
+
::
48
+
49
+
void (*sig_xfer) (bool xfer, struct cfspi_dev *dev):
50
+
51
+
This function is called by the CAIF SPI interface when the output
52
+
(SPI_INT) GPIO needs to change state. The boolean value of the xfer
53
+
variable indicates whether the GPIO should be asserted (HIGH) or
54
+
deasserted (LOW). The dev parameter can be used to map to different CAIF
55
+
SPI slave devices.
56
+
57
+
- Functionality provided by the CAIF SPI interface:
58
+
59
+
::
60
+
61
+
void (*ss_cb) (bool assert, struct cfspi_ifc *ifc);
62
+
63
+
This function is called by the CAIF SPI slave device in order to
64
+
signal a change of state of the input GPIO (SS) to the interface.
65
+
Only active edges are mandatory to be reported.
66
+
This function can be called from IRQ context (recommended in order
67
+
not to introduce latency). The ifc parameter should be the pointer
68
+
returned from the platform probe function in the SPI device structure.
69
+
70
+
::
71
+
72
+
void (*xfer_done_cb) (struct cfspi_ifc *ifc);
73
+
74
+
This function is called by the CAIF SPI slave device in order to
75
+
report that a transfer is completed. This function should only be
76
+
called once both the transmission and the reception are completed.
77
+
This function can be called from IRQ context (recommended in order
78
+
not to introduce latency). The ifc parameter should be the pointer
79
+
returned from the platform probe function in the SPI device structure.
80
+
81
+
- Connecting the bits and pieces:
82
+
83
+
- Filling in the SPI slave device structure:
84
+
85
+
Connect the necessary callback functions.
86
+
87
+
Indicate clock speed (used to calculate toggle delays).
88
+
89
+
Chose a suitable name (helps debugging if you use several CAIF
90
+
SPI slave devices).
91
+
92
+
Assign your private data (can be used to map to your
93
+
structure).
94
+
95
+
- Filling in the SPI slave platform device structure:
96
+
97
+
Add name of driver to connect to ("cfspi_sspi").
98
+
99
+
Assign the SPI slave device structure as platform data.
100
+
101
+
Padding
102
+
=======
103
+
104
+
In order to optimize throughput, a number of SPI padding options are provided.
105
+
Padding can be enabled independently for uplink and downlink transfers.
106
+
Padding can be enabled for the head, the tail and for the total frame size.
107
+
The padding needs to be correctly configured on both sides of the link.
108
+
The padding can be changed via module parameters in cfspi_sspi.c or via
109
+
the sysfs directory of the cfspi_sspi driver (before device registration).
110
+
111
+
- CAIF SPI device template::
112
+
113
+
/*
114
+
* Copyright (C) ST-Ericsson AB 2010
115
+
* Author: Daniel Martensson / Daniel.Martensson@stericsson.com
116
+
* License terms: GNU General Public License (GPL), version 2.
117
+
*
118
+
*/
119
+
120
+
#include <linux/init.h>
121
+
#include <linux/module.h>
122
+
#include <linux/device.h>
123
+
#include <linux/wait.h>
124
+
#include <linux/interrupt.h>
125
+
#include <linux/dma-mapping.h>
126
+
#include <net/caif/caif_spi.h>
127
+
128
+
MODULE_LICENSE("GPL");
129
+
130
+
struct sspi_struct {
131
+
struct cfspi_dev sdev;
132
+
struct cfspi_xfer *xfer;
133
+
};
134
+
135
+
static struct sspi_struct slave;
136
+
static struct platform_device slave_device;
137
+
138
+
static irqreturn_t sspi_irq(int irq, void *arg)
139
+
{
140
+
/* You only need to trigger on an edge to the active state of the
141
+
* SS signal. Once a edge is detected, the ss_cb() function should be
142
+
* called with the parameter assert set to true. It is OK
143
+
* (and even advised) to call the ss_cb() function in IRQ context in
144
+
* order not to add any delay. */
145
+
146
+
return IRQ_HANDLED;
147
+
}
148
+
149
+
static void sspi_complete(void *context)
150
+
{
151
+
/* Normally the DMA or the SPI framework will call you back
152
+
* in something similar to this. The only thing you need to
153
+
* do is to call the xfer_done_cb() function, providing the pointer
154
+
* to the CAIF SPI interface. It is OK to call this function
155
+
* from IRQ context. */
156
+
}
157
+
158
+
static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev)
159
+
{
160
+
/* Store transfer info. For a normal implementation you should
161
+
* set up your DMA here and make sure that you are ready to
162
+
* receive the data from the master SPI. */
163
+
164
+
struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
165
+
166
+
sspi->xfer = xfer;
167
+
168
+
return 0;
169
+
}
170
+
171
+
void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev)
172
+
{
173
+
/* If xfer is true then you should assert the SPI_INT to indicate to
174
+
* the master that you are ready to receive the data from the master
175
+
* SPI. If xfer is false then you should de-assert SPI_INT to indicate
176
+
* that the transfer is done.
177
+
*/
178
+
179
+
struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
180
+
}
181
+
182
+
static void sspi_release(struct device *dev)
183
+
{
184
+
/*
185
+
* Here you should release your SPI device resources.
186
+
*/
187
+
}
188
+
189
+
static int __init sspi_init(void)
190
+
{
191
+
/* Here you should initialize your SPI device by providing the
192
+
* necessary functions, clock speed, name and private data. Once
193
+
* done, you can register your device with the
194
+
* platform_device_register() function. This function will return
195
+
* with the CAIF SPI interface initialized. This is probably also
196
+
* the place where you should set up your GPIOs, interrupts and SPI
197
+
* resources. */
198
+
199
+
int res = 0;
200
+
201
+
/* Initialize slave device. */
202
+
slave.sdev.init_xfer = sspi_init_xfer;
203
+
slave.sdev.sig_xfer = sspi_sig_xfer;
204
+
slave.sdev.clk_mhz = 13;
205
+
slave.sdev.priv = &slave;
206
+
slave.sdev.name = "spi_sspi";
207
+
slave_device.dev.release = sspi_release;
208
+
209
+
/* Initialize platform device. */
210
+
slave_device.name = "cfspi_sspi";
211
+
slave_device.dev.platform_data = &slave.sdev;
212
+
213
+
/* Register platform device. */
214
+
res = platform_device_register(&slave_device);
215
+
if (res) {
216
+
printk(KERN_WARNING "sspi_init: failed to register dev.\n");
217
+
return -ENODEV;
218
+
}
219
+
220
+
return res;
221
+
}
222
+
223
+
static void __exit sspi_exit(void)
224
+
{
225
+
platform_device_del(&slave_device);
226
+
}
227
+
228
+
module_init(sspi_init);
229
+
module_exit(sspi_exit);
-208
Documentation/networking/caif/spi_porting.txt
-208
Documentation/networking/caif/spi_porting.txt
···
1
-
- CAIF SPI porting -
2
-
3
-
- CAIF SPI basics:
4
-
5
-
Running CAIF over SPI needs some extra setup, owing to the nature of SPI.
6
-
Two extra GPIOs have been added in order to negotiate the transfers
7
-
between the master and the slave. The minimum requirement for running
8
-
CAIF over SPI is a SPI slave chip and two GPIOs (more details below).
9
-
Please note that running as a slave implies that you need to keep up
10
-
with the master clock. An overrun or underrun event is fatal.
11
-
12
-
- CAIF SPI framework:
13
-
14
-
To make porting as easy as possible, the CAIF SPI has been divided in
15
-
two parts. The first part (called the interface part) deals with all
16
-
generic functionality such as length framing, SPI frame negotiation
17
-
and SPI frame delivery and transmission. The other part is the CAIF
18
-
SPI slave device part, which is the module that you have to write if
19
-
you want to run SPI CAIF on a new hardware. This part takes care of
20
-
the physical hardware, both with regard to SPI and to GPIOs.
21
-
22
-
- Implementing a CAIF SPI device:
23
-
24
-
- Functionality provided by the CAIF SPI slave device:
25
-
26
-
In order to implement a SPI device you will, as a minimum,
27
-
need to implement the following
28
-
functions:
29
-
30
-
int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev):
31
-
32
-
This function is called by the CAIF SPI interface to give
33
-
you a chance to set up your hardware to be ready to receive
34
-
a stream of data from the master. The xfer structure contains
35
-
both physical and logical addresses, as well as the total length
36
-
of the transfer in both directions.The dev parameter can be used
37
-
to map to different CAIF SPI slave devices.
38
-
39
-
void (*sig_xfer) (bool xfer, struct cfspi_dev *dev):
40
-
41
-
This function is called by the CAIF SPI interface when the output
42
-
(SPI_INT) GPIO needs to change state. The boolean value of the xfer
43
-
variable indicates whether the GPIO should be asserted (HIGH) or
44
-
deasserted (LOW). The dev parameter can be used to map to different CAIF
45
-
SPI slave devices.
46
-
47
-
- Functionality provided by the CAIF SPI interface:
48
-
49
-
void (*ss_cb) (bool assert, struct cfspi_ifc *ifc);
50
-
51
-
This function is called by the CAIF SPI slave device in order to
52
-
signal a change of state of the input GPIO (SS) to the interface.
53
-
Only active edges are mandatory to be reported.
54
-
This function can be called from IRQ context (recommended in order
55
-
not to introduce latency). The ifc parameter should be the pointer
56
-
returned from the platform probe function in the SPI device structure.
57
-
58
-
void (*xfer_done_cb) (struct cfspi_ifc *ifc);
59
-
60
-
This function is called by the CAIF SPI slave device in order to
61
-
report that a transfer is completed. This function should only be
62
-
called once both the transmission and the reception are completed.
63
-
This function can be called from IRQ context (recommended in order
64
-
not to introduce latency). The ifc parameter should be the pointer
65
-
returned from the platform probe function in the SPI device structure.
66
-
67
-
- Connecting the bits and pieces:
68
-
69
-
- Filling in the SPI slave device structure:
70
-
71
-
Connect the necessary callback functions.
72
-
Indicate clock speed (used to calculate toggle delays).
73
-
Chose a suitable name (helps debugging if you use several CAIF
74
-
SPI slave devices).
75
-
Assign your private data (can be used to map to your structure).
76
-
77
-
- Filling in the SPI slave platform device structure:
78
-
Add name of driver to connect to ("cfspi_sspi").
79
-
Assign the SPI slave device structure as platform data.
80
-
81
-
- Padding:
82
-
83
-
In order to optimize throughput, a number of SPI padding options are provided.
84
-
Padding can be enabled independently for uplink and downlink transfers.
85
-
Padding can be enabled for the head, the tail and for the total frame size.
86
-
The padding needs to be correctly configured on both sides of the link.
87
-
The padding can be changed via module parameters in cfspi_sspi.c or via
88
-
the sysfs directory of the cfspi_sspi driver (before device registration).
89
-
90
-
- CAIF SPI device template:
91
-
92
-
/*
93
-
* Copyright (C) ST-Ericsson AB 2010
94
-
* Author: Daniel Martensson / Daniel.Martensson@stericsson.com
95
-
* License terms: GNU General Public License (GPL), version 2.
96
-
*
97
-
*/
98
-
99
-
#include <linux/init.h>
100
-
#include <linux/module.h>
101
-
#include <linux/device.h>
102
-
#include <linux/wait.h>
103
-
#include <linux/interrupt.h>
104
-
#include <linux/dma-mapping.h>
105
-
#include <net/caif/caif_spi.h>
106
-
107
-
MODULE_LICENSE("GPL");
108
-
109
-
struct sspi_struct {
110
-
struct cfspi_dev sdev;
111
-
struct cfspi_xfer *xfer;
112
-
};
113
-
114
-
static struct sspi_struct slave;
115
-
static struct platform_device slave_device;
116
-
117
-
static irqreturn_t sspi_irq(int irq, void *arg)
118
-
{
119
-
/* You only need to trigger on an edge to the active state of the
120
-
* SS signal. Once a edge is detected, the ss_cb() function should be
121
-
* called with the parameter assert set to true. It is OK
122
-
* (and even advised) to call the ss_cb() function in IRQ context in
123
-
* order not to add any delay. */
124
-
125
-
return IRQ_HANDLED;
126
-
}
127
-
128
-
static void sspi_complete(void *context)
129
-
{
130
-
/* Normally the DMA or the SPI framework will call you back
131
-
* in something similar to this. The only thing you need to
132
-
* do is to call the xfer_done_cb() function, providing the pointer
133
-
* to the CAIF SPI interface. It is OK to call this function
134
-
* from IRQ context. */
135
-
}
136
-
137
-
static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev)
138
-
{
139
-
/* Store transfer info. For a normal implementation you should
140
-
* set up your DMA here and make sure that you are ready to
141
-
* receive the data from the master SPI. */
142
-
143
-
struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
144
-
145
-
sspi->xfer = xfer;
146
-
147
-
return 0;
148
-
}
149
-
150
-
void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev)
151
-
{
152
-
/* If xfer is true then you should assert the SPI_INT to indicate to
153
-
* the master that you are ready to receive the data from the master
154
-
* SPI. If xfer is false then you should de-assert SPI_INT to indicate
155
-
* that the transfer is done.
156
-
*/
157
-
158
-
struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
159
-
}
160
-
161
-
static void sspi_release(struct device *dev)
162
-
{
163
-
/*
164
-
* Here you should release your SPI device resources.
165
-
*/
166
-
}
167
-
168
-
static int __init sspi_init(void)
169
-
{
170
-
/* Here you should initialize your SPI device by providing the
171
-
* necessary functions, clock speed, name and private data. Once
172
-
* done, you can register your device with the
173
-
* platform_device_register() function. This function will return
174
-
* with the CAIF SPI interface initialized. This is probably also
175
-
* the place where you should set up your GPIOs, interrupts and SPI
176
-
* resources. */
177
-
178
-
int res = 0;
179
-
180
-
/* Initialize slave device. */
181
-
slave.sdev.init_xfer = sspi_init_xfer;
182
-
slave.sdev.sig_xfer = sspi_sig_xfer;
183
-
slave.sdev.clk_mhz = 13;
184
-
slave.sdev.priv = &slave;
185
-
slave.sdev.name = "spi_sspi";
186
-
slave_device.dev.release = sspi_release;
187
-
188
-
/* Initialize platform device. */
189
-
slave_device.name = "cfspi_sspi";
190
-
slave_device.dev.platform_data = &slave.sdev;
191
-
192
-
/* Register platform device. */
193
-
res = platform_device_register(&slave_device);
194
-
if (res) {
195
-
printk(KERN_WARNING "sspi_init: failed to register dev.\n");
196
-
return -ENODEV;
197
-
}
198
-
199
-
return res;
200
-
}
201
-
202
-
static void __exit sspi_exit(void)
203
-
{
204
-
platform_device_del(&slave_device);
205
-
}
206
-
207
-
module_init(sspi_init);
208
-
module_exit(sspi_exit);
+1
Documentation/networking/index.rst
+1
Documentation/networking/index.rst
+1
-1
drivers/net/caif/Kconfig
+1
-1
drivers/net/caif/Kconfig
···
28
28
The CAIF Link layer SPI Protocol driver for Slave SPI interface.
29
29
This driver implements a platform driver to accommodate for a
30
30
platform specific SPI device. A sample CAIF SPI Platform device is
31
-
provided in <file:Documentation/networking/caif/spi_porting.txt>.
31
+
provided in <file:Documentation/networking/caif/spi_porting.rst>.
32
32
33
33
config CAIF_SPI_SYNC
34
34
bool "Next command and length in start of frame"