Skip to content

Commit 57089ca

Browse files
glikelyglikely
committed
Editorial and typesetting fixes on chapters 1-3
Lots of minor changes made after proofreading the document Signed-off-by: Grant Likely <[email protected]>
1 parent cd46253 commit 57089ca

File tree

3 files changed

+94
-93
lines changed

3 files changed

+94
-93
lines changed

‎source/devicenodes.rst‎

Lines changed: 73 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -124,9 +124,10 @@ taking any action associated with a change in storage attributes, the
124124
client program can safely access all memory (including memory covered by
125125
memory reservations) as WIMG = 0b001x. That is:
126126

127-
- not Write Through Required not Caching Inhibited Memory Coherence
128-
129-
- Required either not Guarded or Guarded (i.e., WIMG = 0b001x)
127+
* not Write Through Required
128+
* not Caching Inhibited
129+
* Memory Coherence
130+
* Required either not Guarded or Guarded
130131

131132
If the VLE storage attribute is supported, with VLE=0.
132133

@@ -155,16 +156,15 @@ If the VLE storage attribute is supported, with VLE=0.
155156
:ref:`sect-standard-properties`) are allowed but are optional.
156157

157158

158-
**Example**
159+
**Examples**
159160

160161
Given a 64-bit Power system with the following physical memory layout:
161162

162-
- RAM: starting address 0x0, length 0x80000000 (2GB)
163-
164-
- RAM: starting address 0x100000000, length 0x100000000 (4GB)
163+
* RAM: starting address 0x0, length 0x80000000 (2GB)
164+
* RAM: starting address 0x100000000, length 0x100000000 (4GB)
165165

166-
Memory nodes could be defined as follows, assuming an ``#address-cells`` == 2
167-
and ``#size-cells`` == 2:
166+
Memory nodes could be defined as follows, assuming ``#address-cells = <2>``
167+
and ``#size-cells = <2>``.
168168

169169
**Example #1**
170170

@@ -202,8 +202,6 @@ The ``/chosen`` node does not represent a real device in the system but
202202
describes parameters chosen or specified by the system firmware at run
203203
time. It shall be a child of the root node.
204204

205-
The node name (see :ref:`sect-node-names`) shall be ``/chosen``.
206-
207205
.. tabularcolumns:: | l c l J |
208206
.. table:: ``/chosen`` Node Properties
209207

@@ -255,8 +253,6 @@ A cpus node is required for all device trees. It does not represent a
255253
real device in the system, but acts as a container for child cpu nodes
256254
which represent the systems CPUs.
257255

258-
The node name (see :ref:`sect-node-names`) shall be cpus.
259-
260256
.. tabularcolumns:: | l c l J |
261257
.. table:: ``/cpus`` Node Properties
262258

@@ -305,8 +301,7 @@ CPU node, but if an expected property is not found then it should look
305301
at the parent cpus node. This results in a less verbose representation
306302
of properties which are identical across all CPUs.
307303

308-
The node name for every cpu node (see :ref:`sect-node-names`) should be
309-
cpu.
304+
The node name for every cpu node should be ``cpu``.
310305

311306
General Properties of ``/cpus/cpu*`` nodes
312307
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -315,73 +310,75 @@ The following table describes the general properties of CPU nodes. Some
315310
of the properties described in :numref:`table-cpu-node-props` are select
316311
standard properties with specific applicable detail.
317312

318-
.. tabularcolumns:: | p{2.5cm} p{1cm} p{2cm} p{8.5cm} |
313+
.. tabularcolumns:: | p{1.5cm} p{1cm} p{2.5cm} p{9.0cm} |
319314
.. _table-cpu-node-props:
320315
.. table:: ``/cpus/cpu*`` Node General Properties
321316
:class: longtable
322317

323318
============================ ===== ================ ===============================================
324319
Property Name Usage Value Type Definition
325320
============================ ===== ================ ===============================================
326-
``device_type`` R ``<string>`` Value shall be "cpu".
327-
``reg`` R array The value of ``reg`` is a ``<prop-encoded-array>``
321+
``device_type`` | R | ``<string>`` Value shall be ``"cpu"``.
322+
``reg`` R array The value of *reg* is a ``<prop-encoded-array>``
328323
that defines a unique CPU/thread id for the
329324
CPU/threads represented by the CPU node.
330325

331326
If a CPU supports more than one thread (i.e.
332-
multiple streams of execution) the ``reg``
327+
multiple streams of execution) the *reg*
333328
property is an array with 1 element per
334-
thread. The ``#address-cells`` on the ``/cpus`` node
329+
thread. The *#address-cells* on the ``/cpus`` node
335330
specifies how many cells each element of the
336331
array takes. Software can determine the number
337-
of threads by dividing the size of ``reg`` by
338-
the parent node’s ``#address-cells``.
332+
of threads by dividing the size of *reg* by
333+
the parent node's *#address-cells*.
339334

340335
If a CPU/thread can be the target of an
341-
external interrupt the "reg" property value
336+
external interrupt the *reg* property value
342337
must be a unique CPU/thread id that is
343338
addressable by the interrupt controller.
344339

345340
If a CPU/thread cannot be the target of an
346-
external interrupt, then "reg" must be unique
341+
external interrupt, then *reg* must be unique
347342
and out of bounds of the range addressed by
348343
the interrupt controller
349344

350-
If a CPU/thread’s PIR is modifiable, a client
351-
program should modify PIR to match the "reg"
345+
If a CPU/thread's PIR is modifiable, a client
346+
program should modify PIR to match the *reg*
352347
property value. If PIR cannot be modified and
353348
the PIR value is distinct from the interrupt
354349
controller numberspace, the CPUs binding may
355350
define a binding-specific representation of
356351
PIR values if desired.
357-
``clock-frequency`` | array Specifies the current clock speed of the CPU
358-
| R in Hertz. The value is a <prop-encoded-array>
352+
``clock-frequency`` | R | array Specifies the current clock speed of the CPU
353+
in Hertz. The value is a ``<prop-encoded-array>``
359354
in one of two forms:
360355

361-
A 32-bit integer consisting of one ``<u32>``
362-
specifying the frequency.
356+
* A 32-bit integer consisting of one ``<u32>``
357+
specifying the frequency.
358+
* A 64-bit integer represented as a ``<u64>``
359+
specifying the frequency.
363360

364-
A 64-bit integer represented as a ``<u64>``
365-
specifying the frequency.
366-
``timebase-frequency`` | array Specifies the current frequency at which the
367-
| R timebase and decrementer registers are updated
361+
``timebase-frequency`` | R | array Specifies the current frequency at which the
362+
timebase and decrementer registers are updated
368363
(in Hertz). The value is a
369364
<prop-encoded-array> in one of two forms:
370365

371-
A 32-bit integer consisting of one ``<u32>``
372-
specifying the frequency.
366+
* A 32-bit integer consisting of one ``<u32>``
367+
specifying the frequency.
368+
* A 64-bit integer represented as a ``<u64>``.
373369

374-
A 64-bit integer represented as a ``<u64>``.
375370
``status`` SD ``<string>`` A standard property describing the state of a
376371
CPU. This property shall be present for nodes
377372
representing CPUs in a symmetric
378373
multiprocessing (SMP) configuration. For a CPU
379-
node the meaning of the “okay” and “disabled”
380-
values are as follows:
374+
node the meaning of the ``"okay"`` and
375+
``"disabled"`` values are as follows:
381376

382-
``"okay"``. The CPU is running.
377+
``"okay"`` :
378+
The CPU is running.
383379

384-
``"disabled"``. The CPU is in a quiescent state.
380+
``"disabled"`` :
381+
The CPU is in a quiescent state.
385382

386383
A quiescent CPU is in a state where it cannot
387384
interfere with the normal operation of other
@@ -399,34 +396,35 @@ standard properties with specific applicable detail.
399396
loop, held in reset, and electrically isolated
400397
from the system bus or in another
401398
implementation dependent state.
402-
``enable-method`` SD ``<stringlist>`` Describes the method by which a CPU in a
399+
``enable-method`` | SD ``<stringlist>`` Describes the method by which a CPU in a
403400
disabled state is enabled. This property is
404401
required for CPUs with a status property with
405-
a value of “disabled”. The value consists of
402+
a value of ``"disabled"``. The value consists of
406403
one or more strings that define the method to
407404
release this CPU. If a client program
408405
recognizes any of the methods, it may use it.
409406
The value shall be one of the following:
410407

411-
"spin-table" The CPU is enabled with the
412-
spin table method defined in the |spec|.
408+
``"spin-table"`` :
409+
The CPU is enabled with the
410+
spin table method defined in the |spec|.
413411

414-
``"[vendor],[method]"`` An
415-
implementation-dependent string that
416-
describes the method by which a CPU is
417-
released from a "disabled" state. The
418-
required format is: "vendor,method" where
419-
vendor is a string describing the name of
420-
the manufacturer and method is a string
421-
describing the vendorspecific mechanism.
412+
``"[vendor],[method]"`` :
413+
Implementation dependent string that
414+
describes the method by which a CPU is
415+
released from a ``"disabled"`` state. The
416+
required format is: ``"[vendor],[method]"``,
417+
where vendor is a string describing the name of
418+
the manufacturer and method is a string
419+
describing the vendorspecific mechanism.
422420

423421
Example: ``"fsl,MPC8572DS"``
424422

425-
Note: Other methods may be added to later
426-
revisions of the |spec| specification.
427-
``cpu-release-addr`` | ``<u64>`` The cpu-release-addr property is required for
428-
| SD cpu nodes that have an enable-method property
429-
value of "spin-table". The value specifies the
423+
.. note:: Other methods may be added to later
424+
revisions of the |spec| specification.
425+
``cpu-release-addr`` | SD | ``<u64>`` The cpu-release-addr property is required for
426+
cpu nodes that have an enable-method property
427+
value of ``"spin-table"``. The value specifies the
430428
physical address of a spin table entry that
431429
releases a secondary CPU from its spin loop.
432430
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
@@ -436,19 +434,19 @@ standard properties with specific applicable detail.
436434
:ref:`sect-standard-properties`) are allowed but are optional.
437435

438436

439-
.. tabularcolumns:: | p{2.5cm} p{1cm} p{2cm} p{9.5cm} |
437+
.. tabularcolumns:: | p{1.5cm} p{1cm} p{2.5cm} p{9.0cm} |
440438
.. table:: ``/cpus/cpu*`` Node Power ISA Properties
441439
:class: longtable
442440

443441
============================ ===== ====================== ===============================================
444442
Property Name Usage Value Type Definition
445443
============================ ===== ====================== ===============================================
446-
``power-isa-version`` | ``<string>`` A string that specifies the numerical portion
447-
| O of the Power ISA version string. For example,
444+
``power-isa-version`` | O | ``<string>`` A string that specifies the numerical portion
445+
of the Power ISA version string. For example,
448446
for an implementation complying with Power ISA
449447
Version 2.06, the value of this property would
450448
be "2.06".
451-
``power-isa-*`` O ``<empty>`` If the power-isa-version property exists, then
449+
``power-isa-*`` | O | ``<empty>`` If the power-isa-version property exists, then
452450
for each category from the Categories section
453451
of Book I of the Power ISA version indicated,
454452
the existence of a property named
@@ -464,25 +462,25 @@ standard properties with specific applicable detail.
464462
implementation supports
465463
[Category:Embedded.Hypervisor] as defined in
466464
Power ISA Version 2.06.
467-
``cache-op-block-size`` | ``<u32>`` Specifies the block size in bytes upon which
468-
| SD cache block instructions operate (e.g., dcbz).
465+
``cache-op-block-size`` | SD | ``<u32>`` Specifies the block size in bytes upon which
466+
cache block instructions operate (e.g., dcbz).
469467
Required if different than the L1 cache block
470468
size.
471-
``reservation-granule-size`` | | Specifies the reservation granule size
472-
| SD | ``<u32>`` supported by this processor in bytes.
469+
``reservation-granule-size`` | SD | ``<u32>`` Specifies the reservation granule size
470+
supported by this processor in bytes.
473471
``mmu-type`` O ``<string>`` Specifies the CPU’s MMU type.
474472

475473
Valid values are shown below:
476474

477-
"mpc8xx"
478-
"ppc40x"
479-
"ppc440"
480-
"ppc476"
481-
"power-embedded"
482-
"powerpc-classic"
483-
"power-server-stab"
484-
"power-server-slb"
485-
"none"
475+
* ``"mpc8xx"``
476+
* ``"ppc40x"``
477+
* ``"ppc440"``
478+
* ``"ppc476"``
479+
* ``"power-embedded"``
480+
* ``"powerpc-classic"``
481+
* ``"power-server-stab"``
482+
* ``"power-server-slb"``
483+
* ``"none"``
486484
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
487485
=========================================================================================================
488486

0 commit comments

Comments
 (0)