#2854 assigned enhancement

What to do with the README files in the RTEMS sources?

Reported by: Sebastian Huber Owned by: Sebastian Huber
Priority: normal Milestone: Indefinite
Component: doc Version: 5
Severity: normal Keywords:
Cc: Blocked By:
Blocking:

Description

There are several README files in the RTEMS sources:

find -iname '*readme*'
./cpukit/libcsupport/src/README
./cpukit/libi2c/README_libi2c
./cpukit/pppd/README
./cpukit/sapi/include/rtems/README
./cpukit/libfs/README
./cpukit/libfs/src/nfsclient/README
./cpukit/libpci/README
./cpukit/dtc/README.license
./cpukit/dtc/README
./cpukit/libmisc/stackchk/README
./cpukit/libmisc/xz/README
./cpukit/libmisc/monitor/README
./cpukit/libmisc/README
./cpukit/libmisc/serdbg/README
./cpukit/libmisc/utf8proc/README
./cpukit/libmisc/cpuuse/README
./cpukit/libmisc/uuid/README
./cpukit/libmisc/mouse/README
./cpukit/libmisc/untar/README
./cpukit/libmisc/fsmount/README
./cpukit/libmisc/capture/README
./cpukit/libmisc/shell/README
./cpukit/libblock/README
./cpukit/librpc/README_RTEMS
./cpukit/librpc/src/rpc/README
./cpukit/telnetd/README
./cpukit/posix/src/README.mqueue
./cpukit/libdrvmgr/README
./cpukit/libnetworking/README
./cpukit/libnetworking/lib/README
./cpukit/score/cpu/sparc/README
./cpukit/score/cpu/sparc64/README
./cpukit/zlib/README
./c/src/libchip/serial/README.xr88681
./c/src/libchip/serial/README.z85c30
./c/src/libchip/serial/README
./c/src/libchip/serial/README.ns16550
./c/src/libchip/serial/README.mc68681
./c/src/libchip/network/README.dec21140
./c/src/libchip/network/README.i82586
./c/src/libchip/network/README
./c/src/libchip/network/README.open_eth
./c/src/libchip/network/README.tulipclone
./c/src/libchip/network/README.sonic
./c/src/libchip/network/README.3com
./c/src/libchip/network/README.cs8900
./c/src/libchip/shmdr/README
./c/src/libchip/rtc/README.m48t08
./c/src/libchip/rtc/README.ds1643
./c/src/libchip/rtc/README.icm7170
./c/src/libchip/rtc/README.mc146818a
./c/src/libchip/rtc/README.m48t18
./c/src/README
./c/src/make/README
./c/src/ada-tests/tmtests/tmoverhd/README
./c/src/ada-tests/sptests/sp19/README
./c/src/ada-tests/sptests/sp04/README
./c/src/lib/libbsp/or1k/generic_or1k/README
./c/src/lib/libbsp/i386/pc386/README.dec21140
./c/src/lib/libbsp/i386/pc386/README
./c/src/lib/libbsp/i386/shared/smp/README
./c/src/lib/libbsp/sh/gensh4/README
./c/src/lib/libbsp/sh/shsim/README
./c/src/lib/libbsp/sh/gensh1/README
./c/src/lib/libbsp/sh/gensh2/README
./c/src/lib/libbsp/sh/gensh2/README.EVB7045F
./c/src/lib/libbsp/epiphany/epiphany_sim/README
./c/src/lib/libbsp/mips/hurricane/README
./c/src/lib/libbsp/mips/csb350/README
./c/src/lib/libbsp/mips/rbtx4938/README
./c/src/lib/libbsp/mips/rbtx4925/README
./c/src/lib/libbsp/mips/jmr3904/README
./c/src/lib/libbsp/mips/shared/gdbstub/README
./c/src/lib/libbsp/m68k/mcf5235/README
./c/src/lib/libbsp/m68k/gen68360/README
./c/src/lib/libbsp/m68k/mcf5329/README
./c/src/lib/libbsp/m68k/uC5282/README
./c/src/lib/libbsp/m68k/csb360/README
./c/src/lib/libbsp/m68k/mcf5206elite/README
./c/src/lib/libbsp/m68k/mvme167/README
./c/src/lib/libbsp/m68k/mvme147/README
./c/src/lib/libbsp/m68k/mrm332/README
./c/src/lib/libbsp/m68k/genmcf548x/README
./c/src/lib/libbsp/m68k/mcf5225x/README
./c/src/lib/libbsp/m68k/mvme147s/README
./c/src/lib/libbsp/m68k/mvme162/README.models
./c/src/lib/libbsp/m68k/mvme162/README
./c/src/lib/libbsp/m68k/mcf52235/README
./c/src/lib/libbsp/m68k/av5282/README
./c/src/lib/libbsp/m68k/gen68340/README
./c/src/lib/libbsp/lm32/lm32_evr/README
./c/src/lib/libbsp/lm32/milkymist/README
./c/src/lib/libbsp/lm32/shared/gdbstub/README
./c/src/lib/libbsp/m32c/m32cbsp/README
./c/src/lib/libbsp/sparc/leon2/README
./c/src/lib/libbsp/sparc/leon3/shmsupp/README
./c/src/lib/libbsp/sparc/leon3/README
./c/src/lib/libbsp/sparc/erc32/README
./c/src/lib/libbsp/sparc/shared/net/README
./c/src/lib/libbsp/nios2/README
./c/src/lib/libbsp/README
./c/src/lib/libbsp/no_cpu/no_bsp/README
./c/src/lib/libbsp/v850/gdbv850sim/README
./c/src/lib/libbsp/powerpc/virtex4/README
./c/src/lib/libbsp/powerpc/mvme5500/README.VME
./c/src/lib/libbsp/powerpc/mvme5500/README.booting
./c/src/lib/libbsp/powerpc/mvme5500/README
./c/src/lib/libbsp/powerpc/mvme5500/README.irq
./c/src/lib/libbsp/powerpc/beatnik/network/if_em/README
./c/src/lib/libbsp/powerpc/beatnik/network/porting/README
./c/src/lib/libbsp/powerpc/beatnik/README
./c/src/lib/libbsp/powerpc/mvme3100/README
./c/src/lib/libbsp/powerpc/gen83xx/README.mpc8349eamds
./c/src/lib/libbsp/powerpc/gen83xx/README.mpc8313erdb
./c/src/lib/libbsp/powerpc/gen5200/README
./c/src/lib/libbsp/powerpc/gen5200/README.IceCube
./c/src/lib/libbsp/powerpc/haleakala/README
./c/src/lib/libbsp/powerpc/qoriq/README
./c/src/lib/libbsp/powerpc/virtex5/README
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.mtx603e
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.dec21140
./c/src/lib/libbsp/powerpc/motorola_powerpc/README
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.MVME2300
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.OTHERBOARDS
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.MVME2400
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.qemu
./c/src/lib/libbsp/powerpc/motorola_powerpc/README.MVME2100
./c/src/lib/libbsp/powerpc/mpc55xxevb/README
./c/src/lib/libbsp/powerpc/ss555/README
./c/src/lib/libbsp/powerpc/psim/network/README
./c/src/lib/libbsp/powerpc/psim/shmsupp/README
./c/src/lib/libbsp/powerpc/psim/vectors/README
./c/src/lib/libbsp/powerpc/psim/README
./c/src/lib/libbsp/powerpc/virtex/README
./c/src/lib/libbsp/powerpc/tqm8xx/README
./c/src/lib/libbsp/powerpc/mpc8260ads/network/README
./c/src/lib/libbsp/powerpc/mpc8260ads/README
./c/src/lib/libbsp/powerpc/t32mppc/README
./c/src/lib/libbsp/powerpc/qemuppc/README
./c/src/lib/libbsp/powerpc/shared/vme/README
./c/src/lib/libbsp/powerpc/shared/bootloader/README
./c/src/lib/libbsp/bfin/bf537Stamp/README
./c/src/lib/libbsp/bfin/eZKit533/README
./c/src/lib/libbsp/bfin/TLL6527M/README
./c/src/lib/libbsp/arm/csb337/README.kit637_v6
./c/src/lib/libbsp/arm/csb337/README
./c/src/lib/libbsp/arm/rtl22xx/README
./c/src/lib/libbsp/arm/stm32f7x/hal/CMSIS/README.txt
./c/src/lib/libbsp/arm/smdk2410/README
./c/src/lib/libbsp/arm/atsam/README
./c/src/lib/libbsp/arm/csb336/README
./c/src/lib/libbsp/arm/stm32f4/README
./c/src/lib/libbsp/arm/tms570/README
./c/src/lib/libbsp/arm/realview-pbx-a9/README
./c/src/lib/libbsp/arm/gumstix/README
./c/src/lib/libbsp/arm/lpc24xx/README
./c/src/lib/libbsp/arm/beagle/pwm/README
./c/src/lib/libbsp/arm/beagle/README
./c/src/lib/libbsp/arm/beagle/README.JTAG
./c/src/lib/libbsp/arm/lpc176x/README
./c/src/lib/libbsp/arm/xilinx-zynq/README
./c/src/lib/libbsp/arm/altera-cyclone-v/README
./c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/README.txt
./c/src/lib/libbsp/arm/lpc32xx/README
./c/src/lib/libbsp/arm/lm3s69xx/README
./c/src/lib/libbsp/arm/raspberrypi/README
./c/src/lib/libbsp/arm/edb7312/README
./c/src/lib/libbsp/arm/stm32f4x/hal/CMSIS/README.txt
./c/src/lib/libbsp/arm/shared/CMSIS/README
./c/src/lib/libbsp/sparc64/usiii/README
./c/src/lib/libbsp/sparc64/niagara/README
./c/src/lib/libbsp/sparc64/shared/helenos/README
./c/src/lib/libbsp/shared/umon/README
./c/src/lib/libbsp/shared/vmeUniverse/README.porting
./c/src/lib/libbsp/shared/vmeUniverse/README.universe
./c/src/lib/libcpu/mips/mongoosev/README
./c/src/lib/libcpu/m68k/m68040/fpsp/README
./c/src/lib/libcpu/README
./c/src/lib/libcpu/powerpc/new-exceptions/bspsupport/README
./c/src/lib/libcpu/powerpc/mpc8xx/README
./c/src/lib/libcpu/powerpc/mpc8260/README
./c/src/lib/libcpu/powerpc/README
./c/src/lib/libcpu/powerpc/mpc5xx/README
./c/src/lib/libcpu/powerpc/mpc6xx/altivec/README
./c/src/lib/libcpu/powerpc/ppc403/vectors/README
./c/src/lib/libcpu/powerpc/ppc403/README
./c/src/lib/libcpu/bfin/README
./README
./testsuites/samples/pppd/README
./testsuites/samples/README
./testsuites/samples/loopback/README
./testsuites/mptests/README
./testsuites/README
./testsuites/tmtests/README
./testsuites/libtests/termios/README
./testsuites/libtests/README
./testsuites/libtests/POSIX/README
./testsuites/psxtmtests/README
./testsuites/smptests/README
./testsuites/sptests/README
./testsuites/rhealstone/README
./doc/README
./tools/cpu/nios2/README
./tools/build/README

Should there be README files at all?

What should they contain?

How should they be formatted?

What is the relationship to the Wiki BSP pages: wiki:TBR/Website/Board_Support_Packages?

Change History (8)

comment:1 Changed on 12/21/16 at 23:24:33 by Chris Johns

I think grouping all READMEs together does not work, it forces a lowest common denominator. We should consider each type separately. I see:

  1. BSP
  2. Testsuite
  3. 3rd Party packages
  4. RTEMS kernel, ie the top level, c/src etc.

BSP

I think important information about a BSP needs to captured in rtems-docs.git. The documentation on a BSP forms an interface a user of the BSP can rely on and we need to make sure it is stable across releases. We also need to make changes clear to uses with specifics on how to migrate.

The wiki can contain transient and less formal documentation, for example how to use a specific debugger.

Testsuite

I do not know about these.

3rd Party packages

If a copy of the original package, leave.

RTEMS kernel

No idea. I suspect they will not be needed in a waf build system.

Wiki

TRB in the wiki means "To Be Reviewed" or "To Be Removed" depending on how you want to look at the pages. I feel the wiki needs be cleaned up, containing only relevant pages to be seriously considered a suitable place to add important documentation. Adding to the current pages means you need to know the history and importance to know how valid the pages are.

comment:2 Changed on 08/14/17 at 00:55:55 by Chris Johns

Milestone: 5.04.12.0

Please review and update the milestone. Thanks.

comment:3 Changed on 08/24/17 at 08:23:26 by Sebastian Huber

Milestone: 4.12.0Indefinite

comment:4 Changed on 10/10/17 at 06:06:29 by Sebastian Huber

Component: Documentationdoc

comment:5 Changed on 10/25/17 at 13:03:22 by Sebastian Huber

Owner: set to Sebastian Huber
Status: newassigned

comment:6 Changed on 06/26/18 at 09:21:34 by Sebastian Huber <sebastian.huber@…>

In 8e3de16/rtems-docs:

user: Add ARM BSPs chapter

Add NXP i.MX section as a BSP example.

Update #2854.

comment:7 Changed on 08/29/18 at 05:47:13 by Sebastian Huber <sebastian.huber@…>

In a6fca76/rtems:

bsp/qoriq: Remove README

Update #2854.

comment:8 Changed on 08/29/18 at 05:47:59 by Sebastian Huber <sebastian.huber@…>

In c476cce/rtems-docs:

user: Add qoriq BSP section

Update #2854.

Note: See TracTickets for help on using tickets.