Newer
Older
<p>
The file <code>include/nuttx/arch.h</code> identifies by prototype all of the APIs that must
be provided by the architecture specific logic.
The internal OS APIs that architecture-specific logic must
interface with also also identified in <code>include/nuttx/arch.h</code> or in
other header files.
</p>
<h2><a name="imports">4.1 APIs Exported by Architecture-Specific Logic to NuttX</a></h2>
<h3><a name="upinitialize">4.1.1 <code>up_initialize()</code></a></h3>
<p><b>Prototype</b>: <code>void up_initialize(void);</code></p>
<p><b>Description</b>.
<code>up_initialize()</code> will be called once during OS
initialization after the basic OS services have been
initialized. The architecture specific details of
initializing the OS will be handled here. Such things as
setting up interrupt service routines, starting the
clock, and registering <a href="#DeviceDrivers">device drivers</a> are some of the
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
things that are different for each processor and hardware
platform.
</p>
<p>
<code>up_initialize()</code> is called after the OS initialized but
before the init process has been started and before the
libraries have been initialized. OS services and driver
services are available.
</p>
<h3><a name="upidle">4.1.2 <code>up_idle()</code></a></h3>
<p><b>Prototype</b>: <code>void up_idle(void);</code></p>
<p><b>Description</b>.
<code>up_idle()</code> is the logic that will be executed
when their is no other ready-to-run task. This is processor
idle time and will continue until some interrupt occurs to
cause a context switch from the idle task.
</p>
<p>
Processing in this state may be processor-specific. e.g.,
this is where power management operations might be performed.
</p>
<h3><a name="upinitialstate">4.1.3 <code>up_initial_state()</code></a></h3>
<p><b>Prototype</b>: <code>void up_initial_state(FAR _TCB *tcb);</code></p>
<p><b>Description</b>.
A new thread is being started and a new TCB
has been created. This function is called to initialize
the processor specific portions of the new TCB.
</p>
<p>
This function must setup the intial architecture registers
and/or stack so that execution will begin at tcb->start
on the next context switch.
</p>
<h3><a name="upcreatestack">4.1.4 <code>up_create_stack()</code></a></h3>
<p><b>Prototype</b>: <code>STATUS up_create_stack(FAR _TCB *tcb, size_t stack_size);</code></p>
<p><b>Description</b>.
Allocate a stack for a new thread and setup
up stack-related information in the TCB.
</p>
<p>
The following TCB fields must be initialized:
</p>
<ul>
<li><code>adj_stack_size</code>: Stack size after adjustment for hardware,
processor, etc. This value is retained only for debug
purposes.</li>
<li><code>stack_alloc_ptr</code>: Pointer to allocated stack</li>
<li><code>adj_stack_ptr</code>: Adjusted <code>stack_alloc_ptr</code> for HW. The
initial value of the stack pointer.
</ul>
<p>
This API is <i>NOT</i> required if <code>CONFIG_CUSTOM_STACK</code>
is defined.
</p>
<p><b>Inputs</b>:</p?
<ul>
<li>
<code>tcb</code>: The TCB of new task.
</li>
<li>
<code>stack_size</code>: The requested stack size. At least this much
must be allocated.
</li>
</ul>
<h3><a name="upusestack">4.1.5 <code>up_use_stack()</code></a></h3>
<p><b>Prototype</b>:
<code>STATUS up_use_stack(FAR _TCB *tcb, FAR void *stack, size_t stack_size);</code>
</p>
<p><b>Description</b>.
Setup up stack-related information in the TCB
using pre-allocated stack memory.
</p>
<p>
The following TCB fields must be initialized:
</p>
<ul>
<li><code>adj_stack_size</code>: Stack size after adjustment for hardware,
processor, etc. This value is retained only for debug
purposes.</li>
<li><code>stack_alloc_ptr</code>: Pointer to allocated stack</li>
<li><code>adj_stack_ptr</code>: Adjusted <code>stack_alloc_ptr</code> for HW. The
initial value of the stack pointer.
</ul>
<p>
This API is <i>NOT</i> required if <code>CONFIG_CUSTOM_STACK</code>
is defined.
</p>
<p><b>Inputs:</b></p>
<ul>
<li>
<code>tcb</code>: The TCB of new task.
</li>
<li>
<code>stack_size</code>: The allocated stack size.
</li>
</ul>
<h3><a name="upreleasestack">4.1.6 <code>up_release_stack()</code></a></h3>
<p><b>Prototype</b>: <code>void up_release_stack(FAR _TCB *dtcb);</code></p>
<p><b>Description</b>.
A task has been stopped. Free all stack
related resources retained int the defunct TCB.
</p>
<p>
This API is <i>NOT</i> required if <code>CONFIG_CUSTOM_STACK</code>
is defined.
</p>
<h3><a name="upunblocktask">4.1.7 <code>up_unblock_task()</code></a></h3>
<p><b>Prototype</b>: <code>void up_unblock_task(FAR _TCB *tcb);</code></p>
<p><b>Description</b>.
A task is currently in an inactive task list
but has been prepped to execute. Move the TCB to the
ready-to-run list, restore its context, and start execution.
</p>
<p>
This function is called only from the NuttX scheduling
logic. Interrupts will always be disabled when this
function is called.
</p>
<p><b>Inputs</b>:
<ul>
<li><code>tcb</code>: Refers to the tcb to be unblocked. This tcb is
in one of the waiting tasks lists. It must be moved to
the ready-to-run list and, if it is the highest priority
ready to run taks, executed.
</li>
</ul>
<h3><a name="upblocktask">4.1.8 <code>up_block_task()</code></a></h3>
<p><b>Prototype</b>: <code>void up_block_task(FAR _TCB *tcb, tstate_t task_state);</code></p>
<p><b>Description</b>.
The currently executing task at the head of
the ready to run list must be stopped. Save its context
and move it to the inactive list specified by task_state.
This function is called only from the NuttX scheduling
logic. Interrupts will always be disabled when this
function is called.
<p><b>Inputs:</b></p>
<ul>
<li><code>tcb</code>: Refers to a task in the ready-to-run list (normally
the task at the head of the list). It most be
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
stopped, its context saved and moved into one of the
waiting task lists. It it was the task at the head
of the ready-to-run list, then a context to the new
ready to run task must be performed.
</li>
<li><code>task_state</code>: Specifies which waiting task list should be
hold the blocked task TCB.
</li>
</ul>
<h3><a name="upreleasepending">4.1.9 <code>up_release_pending()</code></a></h3>
<p><b>Prototype</b>: <code>void up_release_pending(void);</code></p>
<p><b>Description</b>.
When tasks become ready-to-run but cannot run because pre-emption
is disabled, they are placed into a pending task list.
This function releases and makes ready-to-run all of the tasks that have
collected in the pending task list. This can cause a
context switch if a new task is placed at the head of
the ready to run list.
</p>
<p>
This function is called only from the NuttX scheduling logic when
pre-emption is re-enabled. Interrupts will always be disabled when this
function is called.
</p>
<h3><a name="upreprioritizertr">4.1.10 <code>up_reprioritize_rtr()</code></a></h3>
<p><b>Prototype</b>: <code>void up_reprioritize_rtr(FAR _TCB *tcb, ubyte priority);</code></p>
<p><b>Description</b>.
Called when the priority of a running or
ready-to-run task changes and the reprioritization will
cause a context switch. Two cases:
</p>
<ol>
<li>
The priority of the currently running task drops and the next
task in the ready to run list has priority.
</li>
<li>
An idle, ready to run task's priority has been raised above the
the priority of the current, running task and it now has the
priority.
</li>
</ol>
<p>
This function is called only from the NuttX scheduling
logic. Interrupts will always be disabled when this
function is called.
</p>
<p><b>Inputs:</b></p>
<ul>
<li>
<code>tcb</code>: The TCB of the task that has been reprioritized
</li>
<li>
<code>priority</code>: The new task priority
</li>
</ul>
<h3><a name="_exit">4.1.11 <code>_exit()</code></a></h3>
<p><b>Prototype</b>: <code>void _exit(int status) noreturn_function;</code></p>
<p><b>Description</b>.
This function causes the currently executing task to cease
to exist. This is a special case of task_delete().
</p>
<p>
Unlike other UP APIs, this function may be called
directly from user programs in various states. The
implementation of this function should diable interrupts
before performing scheduling operations.
</p>
<h3><a name="upassert">4.1.12 <code>up_assert()</code></a></h3>
<p><b>Prototype</b>:<br>
<code>void up_assert(FAR const ubyte *filename, int linenum);</code></br>
<code>void up_assert_code(FAR const ubyte *filename, int linenum, int error_code);</code></br>
</p>
<p><b>Description</b>.
Assertions may be handled in an architecture-specific
way.
</p>
<h3><a name="upschedulesigaction">4.1.13 <code>up_schedule_sigaction()</code></a></h3>
<p><b>Prototype</b>:
<code>void up_schedule_sigaction(FAR _TCB *tcb, sig_deliver_t sigdeliver);</code>
</p>
<p><b>Description</b>.
This function is called by the OS when one or more
signal handling actions have been queued for execution.
The architecture specific code must configure things so
that the 'igdeliver' callback is executed on the thread
specified by 'tcb' as soon as possible.
</p>
<p>
This function may be called from interrupt handling logic.
</p>
<p>
This operation should not cause the task to be unblocked
nor should it cause any immediate execution of sigdeliver.
Typically, a few cases need to be considered:
</p>
<ol>
<li>
This function may be called from an interrupt handler
During interrupt processing, all xcptcontext structures
should be valid for all tasks. That structure should
be modified to invoke sigdeliver() either on return
from (this) interrupt or on some subsequent context
switch to the recipient task.
</li>
<li>
If not in an interrupt handler and the tcb is NOT
the currently executing task, then again just modify
the saved xcptcontext structure for the recipient
task so it will invoke sigdeliver when that task is
later resumed.
</li>
<li>
If not in an interrupt handler and the tcb IS the
currently executing task -- just call the signal
handler now.
</li>
</ol>
<p>
This API is <i>NOT</i> required if <code>CONFIG_DISABLE_SIGNALS</code>
is defined.
</p>
<h3><a name="upallocateheap">4.1.14 <code>up_allocate_heap()</code></a></h3>
<p><b>Prototype</b>: <code>void up_allocate_heap(FAR void **heap_start, size_t *heap_size);</code></p>
<p><b>Description</b>.
The heap may be statically allocated by
defining CONFIG_HEAP_BASE and CONFIG_HEAP_SIZE. If these
are not defined, then this function will be called to
dynamically set aside the heap region.
</p>
<p>
This API is <i>NOT</i> required if <code>CONFIG_HEAP_BASE</code>
is defined.
</p>
<h3><a name="upinterruptcontext">4.1.15 <code>up_interrupt_context()</code></a></h3>
<p><b>Prototype</b>: <code>boolean up_interrupt_context(void)</code></p>
<p><b>Description</b>.
Return TRUE is we are currently executing in
the interrupt handler context.
</p>
<h3><a name="updisableirq">4.1.16 <code>up_disable_irq()</code></a></h3>
<p><b>Prototype</b>:</p>
<ul><pre>
#ifndef CONFIG_ARCH_NOINTC
void up_disable_irq(int irq);
#endf
</pre></ul>
On many architectures, there are three levels of interrupt enabling: (1)
at the global level, (2) at the level of the interrupt controller,
and (3) at the device level. In order to receive interrupts, they
must be enabled at all three levels.
</p>
<p>
This function implements enabling of the device specified by 'irq'
at the interrupt controller level if supported by the architecture
(irqsave() supports the global level, the device level is hardware
specific).
<p>
If the architecture does not support <code>up_disable_irq</code>,
<code>CONFIG_ARCH_NOINTC</code> should be defined in the NuttX configuration file.
Since this API cannot be supported on all architectures, it should be
avoided in common implementations where possible.
</p>
<h3><a name="upenableirq">4.1.17 <code>up_enable_irq()</code></a></h3>
<p><b>Prototype</b>:</p>
<ul><pre>
#ifndef CONFIG_ARCH_NOINTC
void up_enable_irq(int irq);
#endf
</pre></ul>
<p><b>Description</b>.
This function implements disabling of the device specified by 'irq'
at the interrupt controller level if supported by the architecture
(irqrestore() supports the global level, the device level is hardware
specific).
</p>
<p>
If the architecture does not support <code>up_disable_irq</code>,
<code>CONFIG_ARCH_NOINTC</code> should be defined in the NuttX configuration file.
Since this API cannot be supported on all architectures, it should be
avoided in common implementations where possible.
</p>
<h3><a name="upprioritizeirq">4.1.18 <code>up_prioritize_irq()</code></a></h3>
<p><b>Prototype</b>:</p>
<ul><pre>
#ifdef CONFIG_ARCH_IRQPRIO
void up_enable_irq(int irq);
#endf
</pre></ul>
Set the priority of an IRQ.
</p>
<p>
If the architecture supports <code>up_enable_irq</code>,
<code>CONFIG_ARCH_IRQPRIO</code> should be defined in the NuttX configuration file.
Since this API cannot be supported on all architectures, it should be
avoided in common implementations where possible.
<h3><a name="upputc">4.1.19 <code>up_putc()</code></a></h3>
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
<p><b>Prototype</b>: <code>int up_putc(int ch);</code></p>
<p><b>Description</b>.
This is a debug interface exported by the architecture-specific logic.
Output one character on the console
</p>
<h2><a name="exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></h2>
<p>
These are standard interfaces that are exported by the OS
for use by the architecture specific logic.
</p>
<h3><a name="osstart">4.2.1 <code>os_start()</code></a></h3>
<p>
<b><i>To be provided</i></b>
</p>
<h3><a name="listmgmt">4.2.2 OS List Management APIs</a></h3></h3>
<p>
<b><i>To be provided</i></b>
</p>
<h3><a name="schedprocesstimer">4.2.3 <code>sched_process_timer()</code></a></h3>
<p><b>Prototype</b>: <code>void sched_process_timer(void);</code></p>
<p><b>Description</b>.
This function handles system timer events.
The timer interrupt logic itself is implemented in the
architecture specific code, but must call the following OS
function periodically -- the calling interval must be
<code>MSEC_PER_TICK</code>.
</p>
<h3><a name="irqdispatch">4.2.4 <code>irq_dispatch()</code></a></h3>
<p><b>Prototype</b>: <code>void irq_dispatch(int irq, FAR void *context);</code></p>
<p><b>Description</b>.
This function must be called from the achitecture-
specific logic in order to dispaly an interrupt to
the appropriate, registered handling logic.
</p>
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
<h2><a name="ledsupport">4.3 LED Support</a></h2>
<p>
A board architecture may or may not have LEDs.
If the board does have LEDs, then most architectures provide similar LED support that is enabled when <code>CONFIG_ARCH_LEDS</code>
is selected in the NuttX configuration file.
This LED support is part of architecture-specific logic and is not managed by the core NuttX logic.
However, the support provided by each architecture is sufficiently similar that it can be documented here.
</p>
<h3><a name="ledheaders">4.3.1 Header Files</a></h3>
<p>
LED-related definitions are provided in two header files:
<ul>
<li>
LED definitions are provided for each board in the <code>board.h</code> that resides
in the <code><i><board-name></i>/include/board.h</code> file (which is also
linked to <code>include/arch/board/board.h</code> when the RTOS is configured).
Those definitions are discussed <a href="#leddefinitions">below</a>.
</li>
<li>
The board-specific logic provides unique instances of the LED interfaces.
This is because the implementation of LED support may be very different
on different boards.
Prototypes for these board-specific implementations are, however, provided
in architecture-common header files.
That header file is usually at <code><i><arch-name></i>/src/common/up_internal.h</code>,
but could be at other locations in particular architectures.
These prototypes are discussed <a href="#ledapis">below</a>.
</li>
</ul>
</p>
<h3><a name="leddefinitions">4.3.2 LED Definitions</a></h3>
<p>
The implementation of LED support is very specific to a board architecture.
Some boards have several LEDS, others have only one or two.
Some have none.
Others LED matrices and show alphnumeric data, etc.
The NuttX logic does not refer to specific LEDS, rather, it refers to an event to be shown on the LEDS
in whatever manner is appropriate for the board;
the way that this event is presented depends upon the hardware available on the board.
</p>
<p>
The model used by NuttX is that the board can show 8 events defined as follows in <code><i><board-name></i>/include/board.h</code>:
</p>
<ul><pre>
#define LED_STARTED ??
#define LED_HEAPALLOCATE ??
#define LED_IRQSENABLED ??
#define LED_STACKCREATED ??
#define LED_INIRQ ??
#define LED_SIGNAL ??
#define LED_ASSERTION ??
#define LED_PANIC ??
</pre></ul>
<p>
The specific value assigned to each pre-processor variable can be whatever makes the implementation easiest for the board logic.
The <i>meaning</i> associated with each definition is as follows:
</p>
<ul>
<li>
<code>LED_STARTED</code> is the value that describes the setting of the LEDs when the LED logic is first initialized.
This LED value is set but never cleared.
</li>
<li>
<code>LED_HEAPALLOCATE</code> indicates that the NuttX heap has been configured.
This is an important place in the boot sequence because if the memory is configured wrong, it will probably crash leaving this LED setting.
This LED value is set but never cleared.
</li>
<li>
<code>LED_IRQSENABLED</code> indicates that interrupts have been enabled.
Again, during bring-up (or if there are hardware problems), it is very likely that the system may crash just when interrupts are enabled, leaving this setting on the LEDs.
This LED value is set but never cleared.
</li>
<li>
<code>LED_STACKCREATED</code> is set each time a new stack is created.
If set, it means that the system attempted to start at least one new thread.
This LED value is set but never cleared.
</li>
<li>
<code>LED_INIRQ</code> is set and cleared on entry and exit from each interrupt.
If interrupts are working okay, this LED will have a dull glow.
</li>
<li>
<code>LED_SIGNAL</code> is set and cleared on entry and exit from a signal handler.
Signal handlers are tricky so this is especially useful during bring-up or a new architecture.
</li>
<li>
<code>LED_ASSERTION</code> is set if an assertion occurs.
</li>
<li>
<code>LED_PANIC</code> will blink at around 1Hz if the system panics and hangs.
</li>
</ul>
<h3><a name="ledapis">4.3.3 Common LED interfaces</a></h3>
<p>
The <code><i><arch-name></i>/src/common/up_internal.h</code> probably has definitions
like:
</p>
<ul><pre>
/* Defined in board/up_leds.c */
#ifdef CONFIG_ARCH_LEDS
extern void up_ledinit(void);
extern void up_ledon(int led);
extern void up_ledoff(int led);
#else
# define up_ledinit()
# define up_ledon(led)
# define up_ledoff(led)
#endif
</pre></ul>
<p>
Where:
<p>
<ul>
<li>
<code>void up_ledinit(void)</code> is called early in power-up initialization to initialize the LED hardware.
</li>
<li>
<code>up_ledon(int led)</code> is called to instantiate the LED presentation of the event.
The <code>led</code> argument is one of the definitions provided in <code><i><board-name></i>/include/board.h</code>.
</li>
<li>
<code>up_ledoff(int led</code>is called to terminate the LED presentation of the event.
The <code>led</code> argument is one of the definitions provided in <code><i><board-name></i>/include/board.h</code>.
Note that only <code>LED_INIRQ</code>, <code>LED_SIGNAL</code>, <code>LED_ASSERTION</code>, and <code>LED_PANIC</code>
indications are terminated.
</li>
</ul>
<table width ="100%">
<tr bgcolor="#e4e4e4">
<td>
<h1><a name="NxFileSystem">5.0 NuttX File System</a></h1>
</td>
</tr>
</table>
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
<p><b>Overview</b>.
NuttX includes an optional, scalable file system.
This file-system may be omitted altogther; NuttX does not depend on the presence
of any file system.
</p>
<p><b>Pseudo Root File System</b>.
Or, a simple <i>in-memory</i>, <i>psuedo</i> file system can be enabled.
This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS
option to a non-zero value (see <a href="#apndxconfigs">Appendix A</a>).
This is an <i>in-memory</i> file system because it does not require any
storage medium or block driver support.
Rather, file system contents are generated on-the-fly as referenced via
standard file system operations (open, close, read, write, etc.).
In this sense, the file system is <i>psuedo</i> file system (in the
same sense that the Linux <code>/proc</code> file system is also
referred to as a psuedo file system).
</p>
<p>
Any user supplied data or logic can be accessed via the psuedo-file system.
Built in support is provided for character and block <a href="#DeviceDrivers">drivers</a> in the
<code>/dev</code> psuedo file system directory.
</p>
<p><b>Mounted File Systems</b>
The simple in-memory file system can be extended my mounting block
devices that provide access to true file systems backed up via some
mass storage device.
NuttX supports the standard <code>mount()</code> command that allows
a block driver to be bound to a mountpoint within the psuedo file system
At present, NuttX supports only the VFAT file system.
</p>
<p><b>Comparison to Linux</b>
From a programming perspective, the NuttX file system appears very similar
to a Linux file system.
However, there is a fundamental difference:
The NuttX root file system is a psuedo file system and true file systems may be
mounted in the psuedo file system.
In the typical Linux installation by comparison, the Linux root file system
is a true file system and psuedo file systems may be mounted in the true,
root file system.
The approach selected by NuttX is intended to support greater scalability
from the very tiny platform to the moderate platform.
</p>
<table width ="100%">
<tr bgcolor="#e4e4e4">
<td>
<h1><a name="DeviceDrivers">6.0 NuttX Device Drivers</a></h1>
</td>
</tr>
</table>
<p>
NuttX supports a variety of device drivers including:
<ul>
<li><i>Character</i> Device Drivers,</li>
<li><i>Block</i> Device Drivers, and</li>
<li>Other <i>Specialized</i> Drivers.</li>
</ul>
These different device driver types are discussed in the following paragraphs.
Note: device driver support requires that the <i>in-memory</i>, <i>psuedo</i> file system
is enabled by setting the CONFIG_NFILE_DESCRIPTORS in the NuttX configuration file to a
non-zero value.
</p>
<h2><a name="chardrivers">6.1 Character Device Drivers</a></h2>
<p>
Character device drivers have these properties:
</p>
<ul>
<li>
<b><code>include/nuttx/fs.h</code></b>.
All structures and APIs needed to work with character drivers are provided in this header file.
</li>
<li>
<b><code>struct file_operations</code></b>.
Each character device driver must implement an instance of <code>struct file_operations</code>.
That structure defines a call table with the following methods:
<ul>
<p><code>int open(FAR struct file *filp);</code><br>
<code>int close(FAR struct file *filp);</code><br>
<code>ssize_t read(FAR struct file *filp, FAR char *buffer, size_t buflen);</code><br>
<code>ssize_t write(FAR struct file *filp, FAR const char *buffer, size_t buflen);</code><br>
<code>off_t seek(FAR struct file *filp, off_t offset, int whence);</code><br>
<code>int ioctl(FAR struct file *filp, int cmd, unsigned long arg);</code><br>
<code>int poll(FAR struct file *filp, struct pollfd *fds, boolean setup);</code></p>
</ul>
</li>
<li>
<b><code>int register_driver(const char *path, const struct file_operations *fops, mode_t mode, void *priv);</code></b>.
Each character driver registers itself by calling <code>register_driver()</code>, passing it the
<code>path</code> where it will appear in the <a href="#NxFileSystem">pseudo-file-system</a> and it's
initialized instance of <code>struct file_operations</code>.
</li>
<li>
<b>User Access</b>.
After it has been registered, the character driver can be accessed by user code using the standard
<a href="NuttxUserGuide.html#driveroperations">driver operations</a> including
<code>open()</code>, <code>close()</code>, <code>read()</code>, <code>write()</code>, etc.
<code>drivers/dev_null.c</code>, <code>drivers/fifo.c</code>, <code>drivers/serial.c</code>, etc.
</li>
</ul>
<h2><a name="blockdrivers">6.2 Block Device Drivers</a></h2>
<p>
Block device drivers have these properties:
</p>
<ul>
<li>
<b><code>include/nuttx/fs.h</code></b>.
All structures and APIs needed to work with block drivers are provided in this header file.
</li>
<li>
<b><code>struct block_operations</code></b>.
Each block device driver must implement an instance of <code>struct block_operations</code>.
That structure defines a call table with the following methods:
<ul>
<p><code>int open(FAR struct inode *inode);</code><br>
<code>int close(FAR struct inode *inode);</code><br>
<code>ssize_t read(FAR struct inode *inode, FAR unsigned char *buffer, size_t start_sector, unsigned int nsectors);</code><br>
<code>ssize_t write(FAR struct inode *inode, FAR const unsigned char *buffer, size_t start_sector, unsigned int nsectors);</code><br>
<code>int geometry(FAR struct inode *inode, FAR struct geometry *geometry);</code><br>
<code>int ioctl(FAR struct inode *inode, int cmd, unsigned long arg);</code></p>
</ul>
</li>
<li>
<b><code>int register_blockdriver(const char *path, const struct block_operations *bops, mode_t mode, void *priv);</code></b>.
Each block driver registers itself by calling <code>register_blockdriver()</code>, passing it the
<code>path</code> where it will appear in the <a href="#NxFileSystem">pseudo-file-system</a> and it's
initialized instance of <code>struct block_operations</code>.
</li>
<li>
<b>User Access</b>.
Users do not normally access block drivers directly, rather, they access block drivers
indirectly through the <code>mount()</code> API.
The <code>mount()</code> API binds a block driver instance with a file system and with a mountpoint.
Then the user may use the block driver to access the file system on the underlying media.
<i>Example</i>: See the <code>cmd_mount()</code> implementation in <code>examples/nsh/nsh_fscmds.c</code>.
</li>
<li>
<b>Accessing a Character Driver as a Block Device</b>.
See the loop device at <code>drivers/loop.c</code>.
<i>Example</i>: See the <code>cmd_losetup()</code> implementation in <code>examples/nsh/nsh_fscmds.c</code>.
</li>
<li>
<b>Accessing a Block Driver as Character Device</b>.
See the Block-to-Character (BCH) conversion logic in <code>drivers/bch/</code>.
<i>Example</i>: See the <code>cmd_dd()</code> implementation in <code>examples/nsh/nsh_ddcmd.c</code>.
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
</li>
<li>
<b>Examples</b>.
<code>drivers/loop.c</code>, <code>drivers/mmcds/mmcsd_spi.c</code>, <code>drivers/ramdisk.c</code>, etc.
</li>
</ul>
<h2><a name="blockdrivers">6.3 Specialized Device Drivers</a></h2>
<h3><a name="ethdrivers">6.3.1 Ethernet Device Drivers</a></h3>
<ul>
<li>
<b><code>include/net/uip/uip-arch.h</code></b>.
All structures and APIs needed to work with Ethernet drivers are provided in this header file.
The structure <code>struct uip_driver_s</code> defines the interface and is passed to uIP via
<code>netdev_register()</code>.
</li>
<li>
<b><code>int netdev_register(FAR struct uip_driver_s *dev);</code></b>.
Each Eterhenet driver registers itself by calling <code>netdev_register()</code>.
</li>
<li>
<code>drivers/net/dm90x0.c</code>, <code>arch/drivers/arm/src/c5471/c5471_ethernet.c</code>, <code>arch/z80/src/ez80/ez80_emac.c</code>, etc.
</li>
</ul>
<h3><a name="spidrivers">6.3.2 SPI Device Drivers</a></h3>
<ul>
<li>
<b><code>include/nuttx/spi.h</code></b>.
All structures and APIs needed to work with SPI drivers are provided in this header file.
</li>
<li>
<b><code>struct spi_ops_s</code></b>.
Each SPI device driver must implement an instance of <code>struct spi_ops_s</code>.
That structure defines a call table with the following methods:
<ul>
<p><code>void select(FAR struct spi_dev_s *dev, enum spi_dev_e devid, boolean selected);</code><br>
<code>uint32 setfrequency(FAR struct spi_dev_s *dev, uint32 frequency);</code><br>
<code>void setmode(FAR struct spi_dev_s *dev, enum spi_mode_e mode);</code><br>
<code>void setbits(FAR struct spi_dev_s *dev, int nbits);</code><br>
<code>ubyte status(FAR struct spi_dev_s *dev, enum spi_dev_e devid);</code><br>
<code>uint16 send(FAR struct spi_dev_s *dev, uint16 wd);</code><br>
<code>void exchange(FAR struct spi_dev_s *dev, FAR const void *txbuffer, FAR void *rxbuffer, size_t nwords);</code><br>
<p><codei>nt registercallback(FAR struct spi_dev_s *dev, mediachange_t callback, void *arg);</code></p>
</ul>
<li>
<b>Binding SPI Drivers</b>.
SPI drivers are not normally directly accessed by user code, but are usually bound to another,
higher level device driver.
See for example, <code>int mmcsd_spislotinitialize(int minor, int slotno, FAR struct spi_dev_s *spi)</code> in <code>drivers/mmcsd/mmcsd_spi.c</code>.
</li>
<li>
<code>drivers/loop.c</code>, <code>drivers/mmcds/mmcsd_spi.c</code>, <code>drivers/ramdisk.c</code>, etc.
</li>
</ul>
<h3><a name="i2cdrivers">6.3.3 I2C Device Drivers</a></h3>
<ul>
<li>
<b><code>include/nuttx/i2c.h</code></b>.
All structures and APIs needed to work with I2C drivers are provided in this header file.
</li>
<li>
<b><code>struct i2c_ops_s</code></b>.
Each I2C device driver must implement an instance of <code>struct i2c_ops_s</code>.
That structure defines a call table with the following methods:
<ul>
<p><code>uint32 setfrequency(FAR struct i2c_dev_s *dev, uint32 frequency);</code><br>
<code>int setaddress(FAR struct i2c_dev_s *dev, int addr, int nbits);</code><br>
<code>int write(FAR struct i2c_dev_s *dev, const ubyte *buffer, int buflen);</code><br>
<code>int read(FAR struct i2c_dev_s *dev, ubyte *buffer, int buflen);</code></p>
</ul>
<li>
<b>Binding I2C Drivers</b>.
SPI drivers are not normally directly accessed by user code, but are usually bound to another,
higher level device driver.
</li>
<li>
<code>arch/z80/src/ez80/ez80_i2c.c</code>, <code>arch/z80/src/z8/z8_i2c.c</code>, etc.
</li>
</ul>
<h3><a name="serialdrivers">6.3.4 Serial Device Drivers</a></h3>
<ul>
<li>
<b><code>include/nuttx/serial.h</code></b>.
All structures and APIs needed to work with serial drivers are provided in this header file.
</li>
<li>
<b><code>struct uart_ops_s</code></b>.
Each serial device driver must implement an instance of <code>struct uart_ops_s</code>.
That structure defines a call table with the following methods:
<ul>
<p><code>int setup(FAR struct uart_dev_s *dev);</code><br>
<code>void shutdown(FAR struct uart_dev_s *dev);</code><br>
<code>int attach(FAR struct uart_dev_s *dev);</code><br>
<code>void detach(FAR struct uart_dev_s *dev);</code><br>
<code>int ioctl(FAR struct file *filep, int cmd, unsigned long arg);</code><br>
<code>int receive(FAR struct uart_dev_s *dev, unsigned int *status);</code><br>
<code>void rxint(FAR struct uart_dev_s *dev, boolean enable);</code><br>
<code>boolean rxavailable(FAR struct uart_dev_s *dev);</code><br>
<code>void send(FAR struct uart_dev_s *dev, int ch);</code><br>
<code>void txint(FAR struct uart_dev_s *dev, boolean enable);</code><br>
<code>boolean txready(FAR struct uart_dev_s *dev);</code><br>
<code>boolean txempty(FAR struct uart_dev_s *dev);</code></p>
</ul>
</li>
<li>
<b><code>int uart_register(FAR const char *path, FAR uart_dev_t *dev);</code></b>.
A serial driver may register itself by calling <code>uart_register()</code>, passing it the
<code>path</code> where it will appear in the <a href="#NxFileSystem">pseudo-file-system</a> and it's
initialized instance of <code>struct uart_ops_s</code>.
By convention, serial device drivers are registered at pathes like <code>/dev/ttyS0</code>, <code>/dev/ttyS1</code>, etc.
See the <code>uart_register()</code> implementation in <code>drivers/serial.c</code>.
</li>
<li>
<b>User Access</b>.
Serial drivers are, ultimately, normal <a href="#chardrivers">character drivers</a> and are accessed as other character drivers.
</li>
<li>
<code>arch/arm/src/chip/lm3s_serial.c</code>, <code>arch/arm/src/lpc214x/lpc214x_serial.c</code>, <code>arch/z16/src/z16f/z16f_serial.c</code>, etc.
</li>
</ul>
<table width ="100%">
<tr bgcolor="#e4e4e4">
<td>
<h1><a name="apndxconfigs">Appendix A: NuttX Configuration Settings</a></h1>
</td>
</tr>
</table>
<p>
The following variables are recognized by the build (you may
also include architecture-specific settings).
</p>
<h2>Architecture selection</h2>
<p>
The following configuration itemes select the architecture, chip, and
board configuration for the build.
</p>
<li><code>CONFIG_ARCH</code>:
Identifies the arch subdirectory</li>
<li><code>CONFIG_ARCH_name</code>:
For use in C code</li>
<li><code>CONFIG_ARCH_CHIP</code>:
Identifies the arch/*/chip subdirectory</li>
<li><code>CONFIG_ARCH_CHIP_name</code>:
For use in C code</li>
<li><code>CONFIG_ARCH_BOARD</code>:
Identifies the configs subdirectory and hence, the board that supports
the particular chip or SoC.</li>
<li><code>CONFIG_ARCH_BOARD_name</code>:
For use in C code</li>
<li><code>CONFIG_ENDIAN_BIG</code>:
Define if big endian (default is little endian).</li>
<li><code>CONFIG_ARCH_NOINTC</code>:
Define if the architecture does not support an interrupt controller
or otherwise cannot support APIs like up_enable_irq() and up_disable_irq().</li>
<li><code>CONFIG_ARCH_IRQPRIO</code>:
Define if the architecture suports prioritizaton of interrupts and the
up_prioritize_irq() API.</li>
Some architectures require a description of the RAM configuration:
</p>
<ul>
<li><code>CONFIG_DRAM_SIZE</code>:
Describes the installed DRAM.</li>
<li><code>CONFIG_DRAM_START</code>:
The start address of DRAM (physical)</li>
<li><code>CONFIG_DRAM_VSTART</code>:
The start address of DRAM (virtual)</li>
<p>
General build options:
</p>
<ul>
<li><code>CONFIG_RRLOAD_BINARY</code>:
Make the rrload binary format used with BSPs from <a href="www.ridgerun.com">ridgerun.com</a>
using the <code>tools/mkimage.sh</code> script.
</li>
<li><code>CONFIG_INTELHEX_BINARY</code>:
Make the Intel HEX binary format used with many different loaders using the GNU objcopy program
This option hould not be selected if you are not using the GNU toolchain.
</li>
<li><code>CONFIG_MOTOROLA_SREC</code>:
Make the Motorola S-Record binary format used with many different loaders using the GNU objcopy program
Should not be selected if you are not using the GNU toolchain.
</li>
mmke a raw binary format file used with many different loaders using the GNU objcopy program.
This option should not be selected if you are not using the GNU toolchain.
</li>
Toolchain supports libm.a
</li>
<li><code>CONFIG_HAVE_CXX</code>:
Toolchain supports C++ and <code>CXX</code>, <code>CXXFLAGS</code>, and <code>COMPILEXX</code>
have been defined in the configuratins <code>Make.defs</code> file.
</li>
<h2>General OS setup</h2>
<ul>
<li>
<code>CONFIG_EXAMPLE</code>: identifies the subdirectory in examples
that will be used in the build.
</li>
<li>
<code>CONFIG_DEBUG</code>: enables built-in debug options
</li>
<li>
<code>CONFIG_DEBUG_VERBOSE</code>: enables verbose debug output
</li>
<li>
<code>CONFIG_DEBUG_SCHED</code>: enable OS debug output (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_MM</code>: enable memory management debug output (disabld by default)
</li>
<li>
<code>CONFIG_DEBUG_NET</code>: enable network debug output (disabled by default)
<code>CONFIG_DEBUG_FS</code>: enable file system debug output (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_LIB</code>: enable C library debug output (disabled by default)
<code>CONFIG_ARCH_LOWPUTC</code>: architecture supports low-level, boot
time console output
</li>
<li>
<code>CONFIG_MM_REGIONS</code>: If the architecture includes multiple
regions of memory to allocate from, this specifies the
number of memory regions that the memory manager must
handle and enables the API mm_addregion(start, end);
</li>
<li>
<code>CONFIG_TICKS_PER_MSEC</code>: The default system timer is 100Hz