Opened on 12/21/16 at 13:49:53
Last modified on 08/29/18 at 05:47:59
#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
comment:2 Changed on 08/14/17 at 00:55:55 by Chris Johns
Milestone: | 5.0 → 4.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.0 → Indefinite |
---|
comment:4 Changed on 10/10/17 at 06:06:29 by Sebastian Huber
Component: | Documentation → doc |
---|
comment:5 Changed on 10/25/17 at 13:03:22 by Sebastian Huber
Owner: | set to Sebastian Huber |
---|---|
Status: | new → assigned |
comment:6 Changed on 06/26/18 at 09:21:34 by Sebastian Huber <sebastian.huber@…>
comment:8 Changed on 08/29/18 at 05:47:59 by Sebastian Huber <sebastian.huber@…>
Note: See
TracTickets for help on using
tickets.
I think grouping all READMEs together does not work, it forces a lowest common denominator. We should consider each type separately. I see:
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.