Skip to content

Commit e1c3683

Browse files
iriark01iriark01
committed
Splitting I/O to Drivers and I/O
1 parent f124008 commit e1c3683

File tree

4 files changed

+107
-64
lines changed

4 files changed

+107
-64
lines changed

‎docs.json

Lines changed: 54 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -203,112 +203,125 @@
203203
]
204204
},
205205
{
206-
"title": "Input/Output (I/O)",
206+
"title": "Drivers",
207207
"intro": {
208208
"path": "docs/api/io/drivers.md"
209209
},
210210
"sub_chapters": [{
211-
"title": "I/O options and config",
211+
"title": "Drvier options and config",
212212
"intro": {
213213
"path": "docs/api/io/io-config.md"
214214
},
215215
"sources": []
216216
},
217217
{
218-
"title": "I/O APIs",
219-
"sources": [{
220-
"path": "docs/api/io/AnalogIn.md"
221-
},
218+
"title": "Driver APIs",
219+
"sources": [
222220
{
223-
"path": "docs/api/io/AnalogOut.md"
221+
"path": "docs/api/io/Ticker.md"
224222
},
225223
{
226-
"path": "docs/api/io/DigitalIn.md"
224+
"path": "docs/api/io/TimeOut.md"
227225
},
228226
{
229-
"path": "docs/api/io/DigitalOut.md"
227+
"path": "docs/api/io/Timer.md"
230228
},
231229
{
232-
"path": "docs/api/io/DigitalInOut.md"
230+
"path": "docs/api/io/Watchdog.md"
233231
},
234232
{
235-
"path": "docs/api/io/BusIn.md"
233+
"path": "docs/api/io/ResetReason.md"
236234
},
237235
{
238-
"path": "docs/api/io/BusOut.md"
236+
"path": "docs/api/io/FlashIAP.md"
239237
},
240238
{
241-
"path": "docs/api/io/BusInOut.md"
239+
"path": "docs/api/io/BufferedSerial.md"
242240
},
243241
{
244-
"path": "docs/api/io/PortIn.md"
242+
"path": "docs/api/io/UnbufferedSerial.md"
245243
},
246244
{
247-
"path": "docs/api/io/PortOut.md"
245+
"path": "docs/api/io/SPI.md"
248246
},
249247
{
250-
"path": "docs/api/io/PortInOut.md"
248+
"path": "docs/api/io/SPISlave.md"
251249
},
252250
{
253-
"path": "docs/api/io/PwmOut.md"
251+
"path": "docs/api/io/QuadSPI.md"
254252
},
255253
{
256-
"path": "docs/api/io/InterruptIn.md"
254+
"path": "docs/api/io/I2C.md"
257255
},
258256
{
259-
"path": "docs/api/io/Ticker.md"
257+
"path": "docs/api/io/I2CSlave.md"
260258
},
261259
{
262-
"path": "docs/api/io/TimeOut.md"
260+
"path": "docs/api/io/CAN.md"
263261
},
264262
{
265-
"path": "docs/api/io/Timer.md"
263+
"path": "docs/api/io/MbedCRC.md"
264+
}
265+
]
266+
},
267+
{
268+
"title": "Drivers tutorials",
269+
"sources": [{
270+
"path": "docs/api/io/flow_control.md"
266271
},
267272
{
268-
"path": "docs/api/io/Watchdog.md"
273+
"path": "docs/api/io/alarm-tutorial.md"
274+
}
275+
]
276+
}
277+
]
278+
},
279+
{
280+
"title": "Input/Output (I/O)",
281+
"intro": {
282+
"path": "docs/api/io/io_intro.md"
283+
},
284+
"sub_chapters": [
285+
{
286+
"title": "I/O APIs",
287+
"sources": [{
288+
"path": "docs/api/io/AnalogIn.md"
269289
},
270290
{
271-
"path": "docs/api/io/ResetReason.md"
291+
"path": "docs/api/io/AnalogOut.md"
272292
},
273293
{
274-
"path": "docs/api/io/FlashIAP.md"
294+
"path": "docs/api/io/DigitalIn.md"
275295
},
276296
{
277-
"path": "docs/api/io/BufferedSerial.md"
297+
"path": "docs/api/io/DigitalOut.md"
278298
},
279299
{
280-
"path": "docs/api/io/UnbufferedSerial.md"
300+
"path": "docs/api/io/DigitalInOut.md"
281301
},
282302
{
283-
"path": "docs/api/io/SPI.md"
303+
"path": "docs/api/io/BusIn.md"
284304
},
285305
{
286-
"path": "docs/api/io/SPISlave.md"
306+
"path": "docs/api/io/BusOut.md"
287307
},
288308
{
289-
"path": "docs/api/io/QuadSPI.md"
309+
"path": "docs/api/io/BusInOut.md"
290310
},
291311
{
292-
"path": "docs/api/io/I2C.md"
312+
"path": "docs/api/io/PortIn.md"
293313
},
294314
{
295-
"path": "docs/api/io/I2CSlave.md"
315+
"path": "docs/api/io/PortOut.md"
296316
},
297317
{
298-
"path": "docs/api/io/CAN.md"
318+
"path": "docs/api/io/PortInOut.md"
299319
},
300320
{
301-
"path": "docs/api/io/MbedCRC.md"
302-
}
303-
]
304-
},
305-
{
306-
"title": "I/O tutorials",
307-
"sources": [{
308-
"path": "docs/api/io/flow_control.md"
321+
"path": "docs/api/io/PwmOut.md"
309322
},
310323
{
311-
"path": "docs/api/io/alarm-tutorial.md"
324+
"path": "docs/api/io/InterruptIn.md"
312325
}
313326
]
314327
}

‎docs/api/api.md

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,36 @@ The Mbed OS RTOS capabilities include managing objects such as threads, synchron
2929
</tbody>
3030
</table>
3131

32+
## Drivers
33+
34+
The drivers are digital interfaces that allow your board to interface with a computer or external devices.
35+
36+
<table>
37+
<tbody>
38+
<tr>
39+
<td><a href="ticker.html">Ticker</a></td>
40+
<td><a href="timeout.html">Timeout</a></td>
41+
<td><a href="timer.html">Timer</a></td>
42+
<td><a href="watchdog.html">Watchdog</a></td>
43+
<td><a href="resetreason.html">ResetReason</a></td>
44+
</tr>
45+
<tr>
46+
<td><a href="flash-iap.html">Flash IAP</a></td>
47+
<td><a href="bufferedserial.html">BufferedSerial</a></td>
48+
<td><a href="unbufferedserial.html">UnbufferedSerial</a></td>
49+
<td><a href="spi.html">SPI</a></td>
50+
<td><a href="spislave.html">SPISlave</a></td>
51+
</tr>
52+
<tr>
53+
<td><a href="quadspi-qspi.html">QuadSPI (QSPI)</a></td>
54+
<td><a href="i2c.html">I2C</a></td>
55+
<td><a href="i2cslave.html">I2CSlave</a></td>
56+
<td><a href="can.html">CAN</a></td>
57+
<td><a href="mbedcrc.html">MbedCRC</a></td>
58+
</tr>
59+
</tbody>
60+
</table>
61+
3262
## Input/Output
3363

3464
Input/Output APIs include analog and digital inputs and outputs on development boards, as well as digital interfaces, which allow your board to interface with a computer or external devices.
@@ -53,27 +83,6 @@ Input/Output APIs include analog and digital inputs and outputs on development b
5383
<td><a href="portinout.html">PortInOut</a></td>
5484
<td><a href="pwmout.html">PwmOut</a></td>
5585
<td><a href="interruptin.html">InterruptIn</a></td>
56-
<td><a href="ticker.html">Ticker</a></td>
57-
<td><a href="timeout.html">Timeout</a></td>
58-
</tr>
59-
<tr>
60-
<td><a href="timer.html">Timer</a></td>
61-
<td><a href="watchdog.html">Watchdog</a></td>
62-
<td><a href="resetreason.html">ResetReason</a></td>
63-
<td><a href="flash-iap.html">Flash IAP</a></td>
64-
<td><a href="bufferedserial.html">BufferedSerial</a></td>
65-
</tr>
66-
<tr>
67-
<td><a href="unbufferedserial.html">UnbufferedSerial</a></td>
68-
<td><a href="spi.html">SPI</a></td>
69-
<td><a href="spislave.html">SPISlave</a></td>
70-
<td><a href="quadspi-qspi.html">QuadSPI (QSPI)</a></td>
71-
<td><a href="i2c.html">I2C</a></td>
72-
</tr>
73-
<tr>
74-
<td><a href="i2cslave.html">I2CSlave</a></td>
75-
<td><a href="can.html">CAN</a></td>
76-
<td><a href="mbedcrc.html">MbedCRC</a></td>
7786
</tr>
7887
</tbody>
7988
</table>

‎docs/api/io/drivers.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@ In some cases, the drivers provide nonblocking APIs. These APIs configure hardwa
1616

1717
In Mbed OS, the standard API for asynchronous events is the attach function. You can use the attach function to attach a callback function. Drivers call the attached callback function during specific events. You can use this to learn when the state of a nonblocking operation changes or whether other asynchronous events occur.
1818

19-
For example, you can attach a callback function on a [Serial](serial.html) object, which the Serial object calls when the serial line receives a packet on the RX line.
20-
2119
One important thing to note is that when you attach callbacks with this function, the driver calls them in interrupt context. Interrupt context runs at a higher priority than any thread, which means that any code called from the attach callback must be interrupt safe. This excludes any blocking APIs such as blocking drivers, malloc, and mutexes. Or you risk preventing other high-priority interrupts from running, which may break other parts of the OS.
2220

2321
When you need to call code that’s not interrupt safe from interrupt context, you must first defer from the interrupt context to a thread. The easiest way to defer to a thread is to signal a waiting thread through a [Semaphore](semaphore.html). In more complex use cases, you can use an [EventQueue](eventqueue.html) to manage multiple events at once.

‎docs/api/io/io_intro.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# I/O overview
2+
3+
Input/Ouput APIs are a subset drivers.
4+
5+
Drivers provide access to general purpose microcontroller hardware. Drivers typically access a microcontroller's hardware peripherals directly, and may form the lowest lever of a protocol or network stack.
6+
7+
The Mbed OS driver APIs include analog and digital inputs and outputs on development boards, as well as digital interfaces, which allow your board to interface with a computer or external devices. With these drivers, you can read or set the voltage of analog pins, control digital pins individually or grouped into a bus and trigger an event when more data is available on the bus. You can also control the frequency and mark to space ratio, or duty cycle, of a Pulse Width Modulated (PWM) digital output.
8+
9+
## Blocking nature
10+
11+
By default, all Mbed OS driver APIs are blocking. In the drivers, blocking APIs cause the current thread to wait until the hardware operation completes. Blocking APIs simplify control flow, allow for linearly structured programs and make debugging intuitive. We suggest using blocking APIs as a starting point. You should only consider more complex APIs if the blocking APIs do not satisfy your requirements.
12+
13+
Mbed OS is built around an RTOS, and to complement this, the drivers are thread safe. This means that if you use multiple drivers in a blocking manner, as long as the drivers are in separate threads, their operations can still be carried out in parallel. When a driver blocks a thread, the RTOS either switches to any nonblocked threads or sleeps. This means that in most cases, an application using blocking APIs has the same advantages as one using nonblocking APIs.
14+
15+
In some cases, the drivers provide nonblocking APIs. These APIs configure hardware to run in the background of the processor, without blocking a thread. Nonblocking drivers signal through the attach function once the background operation is complete.
16+
17+
## Attaching callbacks to drivers
18+
19+
In Mbed OS, the standard API for asynchronous events is the attach function. You can use the attach function to attach a callback function. Drivers call the attached callback function during specific events. You can use this to learn when the state of a nonblocking operation changes or whether other asynchronous events occur.
20+
21+
One important thing to note is that when you attach callbacks with this function, the driver calls them in interrupt context. Interrupt context runs at a higher priority than any thread, which means that any code called from the attach callback must be interrupt safe. This excludes any blocking APIs such as blocking drivers, malloc, and mutexes. Or you risk preventing other high-priority interrupts from running, which may break other parts of the OS.
22+
23+
When you need to call code that’s not interrupt safe from interrupt context, you must first defer from the interrupt context to a thread. The easiest way to defer to a thread is to signal a waiting thread through a [Semaphore](semaphore.html). In more complex use cases, you can use an [EventQueue](eventqueue.html) to manage multiple events at once.

0 commit comments

Comments
 (0)