January 2021 - U-Boot

Subject: [PATCH v2 4/4] board/km: add support for seli8 design based on nxp ls102x
by Aleksandar Gerasimovski 02 Feb '21

02 Feb '21

The SELI8 design is a new tdm service unit card for Hitachi-Powergrids XMC and FOX product lines. It is based on NXP LS1021 SoC and it provides following interfaces: - IFC interface for NOR, NAND and external FPGA's - 1 x RGMII ETH for debug purposes - 2 x SGMII ETH for management communication via back-plane - 1 x uQE HDLC for management communication via back-plane - 1 x I2C for peripheral devices - 1 x SPI for peripheral devices - 1 x UART for debug logging It is foreseen that the design will be later re-used for another XMC and FOX service cards with similar SoC requirements. Signed-off-by: Rainer Boschung <rainer.boschung(a)hitachi-powergrids.com> Signed-off-by: Matteo Ghidoni <matteo.ghidoni(a)hitachi-powergrids.com> Signed-off-by: Aleksandar Gerasimovski <aleksandar.gerasimovski(a)hitachi-powergrids.com> --- Changes for v2: - fix patch subject to 60 characters --- arch/arm/Kconfig | 19 ++ arch/arm/dts/Makefile | 2 + arch/arm/dts/ls1021a-pg-wcom-seli8.dts | 111 +++++++++ board/keymile/Kconfig | 23 +- board/keymile/common/ivm.c | 19 +- board/keymile/pg-wcom-ls102xa/Kconfig | 19 ++ board/keymile/pg-wcom-ls102xa/MAINTAINERS | 10 + board/keymile/pg-wcom-ls102xa/Makefile | 11 + board/keymile/pg-wcom-ls102xa/ddr.c | 90 +++++++ board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c | 160 ++++++++++++ configs/pg_wcom_seli8_defconfig | 63 +++++ include/configs/km/pg-wcom-ls102xa.h | 309 ++++++++++++++++++++++++ include/configs/pg-wcom-seli8.h | 45 ++++ 13 files changed, 870 insertions(+), 11 deletions(-) create mode 100644 arch/arm/dts/ls1021a-pg-wcom-seli8.dts create mode 100644 board/keymile/pg-wcom-ls102xa/Kconfig create mode 100644 board/keymile/pg-wcom-ls102xa/MAINTAINERS create mode 100644 board/keymile/pg-wcom-ls102xa/Makefile create mode 100644 board/keymile/pg-wcom-ls102xa/ddr.c create mode 100644 board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c create mode 100644 configs/pg_wcom_seli8_defconfig create mode 100644 include/configs/km/pg-wcom-ls102xa.h create mode 100644 include/configs/pg-wcom-seli8.h diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig index fbe9087..13fdf3c 100644 --- a/arch/arm/Kconfig +++ b/arch/arm/Kconfig @@ -1515,6 +1515,24 @@ config TARGET_LS1021ATWR select DM_SPI_FLASH if FSL_DSPI || FSL_QSPI imply SCSI +config TARGET_PG_WCOM_SELI8 + bool "Support Hitachi-Powergrids SELI8 service unit card" + select ARCH_LS1021A + select ARCH_SUPPORT_PSCI + select BOARD_EARLY_INIT_F + select BOARD_LATE_INIT + select CPU_V7A + select CPU_V7_HAS_NONSEC + select CPU_V7_HAS_VIRT + select SYS_FSL_DDR + select FSL_DDR_INTERACTIVE + select VENDOR_KM + imply SCSI + help + Support for Hitachi-Powergrids SELI8 service unit card. + SELI8 is a QorIQ LS1021a based service unit card used + in XMC20 and FOX615 product families. + config TARGET_LS1021ATSN bool "Support ls1021atsn" select ARCH_LS1021A @@ -2034,6 +2052,7 @@ source "board/variscite/dart_6ul/Kconfig" source "board/vscom/baltos/Kconfig" source "board/phytium/durian/Kconfig" source "board/xen/xenguest_arm64/Kconfig" +source "board/keymile/Kconfig" source "arch/arm/Kconfig.debug" diff --git a/arch/arm/dts/Makefile b/arch/arm/dts/Makefile index fd47e40..ec93f93 100644 --- a/arch/arm/dts/Makefile +++ b/arch/arm/dts/Makefile @@ -393,6 +393,8 @@ dtb-$(CONFIG_ARCH_LS1021A) += ls1021a-qds-duart.dtb \ ls1021a-qds-lpuart.dtb \ ls1021a-twr-duart.dtb ls1021a-twr-lpuart.dtb \ ls1021a-iot-duart.dtb ls1021a-tsn.dtb +dtb-$(CONFIG_TARGET_PG_WCOM_SELI8) += ls1021a-pg-wcom-seli8.dtb + dtb-$(CONFIG_FSL_LSCH3) += fsl-ls2080a-qds.dtb \ fsl-ls2080a-qds-42-x.dtb \ fsl-ls2080a-rdb.dtb \ diff --git a/arch/arm/dts/ls1021a-pg-wcom-seli8.dts b/arch/arm/dts/ls1021a-pg-wcom-seli8.dts new file mode 100644 index 0000000..e335188 --- /dev/null +++ b/arch/arm/dts/ls1021a-pg-wcom-seli8.dts @@ -0,0 +1,111 @@ +// SPDX-License-Identifier: GPL-2.0+ +/* + * Copyright 2013-2015 Freescale Semiconductor, Inc. + * Copyright 2020 Hitachi Power Grids. All rights reserved. + */ + +/dts-v1/; +#include "ls1021a.dtsi" + +/ { + model = "Hitachi-Powergrids SELI8 Service Unit for XMC and FOX"; + + chosen { + stdout-path = &uart0; + }; +}; + +&enet0 { + status = "okay"; + tbi-handle = <&tbi0>; + phy-connection-type = "sgmii"; + fixed-link { + speed = <1000>; + full-duplex; + }; +}; + +&enet1 { + status = "okay"; + tbi-handle = <&tbi1>; + phy-connection-type = "sgmii"; + fixed-link { + speed = <1000>; + full-duplex; + }; +}; + +&enet2 { + phy-handle = <&debug_phy>; + phy-connection-type = "rgmii-id"; + status = "okay"; +}; + +&i2c0 { + status = "okay"; +}; + +&ifc { + #address-cells = <2>; + #size-cells = <1>; + /* NOR Flash on board */ + ranges = <0x0 0x0 0x60000000 0x04000000>; + status = "okay"; + + nor@0,0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "cfi-flash"; + reg = <0x0 0x0 0x4000000>; + bank-width = <2>; + device-width = <1>; + + partition@0 { + label = "rcw"; + reg = <0x0 0x20000>; + read-only; + }; + partition@20000 { + label = "qe"; + reg = <0x20000 0x20000>; + }; + partition@40000 { + label = "envred"; + reg = <0x40000 0x20000>; + }; + partition@60000 { + label = "env"; + reg = <0x60000 0x20000>; + }; + partition@100000 { + label = "u-boot"; + reg = <0x100000 0x100000>; + }; + partition@200000 { + label = "ubi0"; + reg = <0x200000 0x3E00000>; + }; + }; +}; + +&mdio0 { + debug_phy: ethernet-phy@11 { + reg = <0x11>; + }; + + tbi0: tbi-phy@0xb { + reg = <0xb>; + device_type = "tbi-phy"; + }; +}; + +&mdio1 { + tbi1: tbi-phy@0xd { + reg = <0xd>; + device_type = "tbi-phy"; + }; +}; + +&uart0 { + status = "okay"; +}; diff --git a/board/keymile/Kconfig b/board/keymile/Kconfig index e590690..965a537 100644 --- a/board/keymile/Kconfig +++ b/board/keymile/Kconfig @@ -20,8 +20,8 @@ config KM_PNVRAM config KM_PHRAM hex "Physical RAM" - default 0x17F000 if ARM - default 0x100000 if PPC + default 0x17F000 if ARM && !ARCH_LS1021A + default 0x100000 if PPC || ARCH_LS1021A depends on !ARCH_SOCFPGA help Start address of the physical RAM, which is the mounted /var folder. @@ -30,13 +30,14 @@ config KM_RESERVED_PRAM hex "Reserved RAM" default 0x801000 if ARCH_KIRKWOOD default 0x0 if MPC83xx - default 0x1000 if MPC85xx + default 0x1000 if MPC85xx || ARCH_LS1021A depends on !ARCH_SOCFPGA help Reserved physical RAM area at the end of memory for special purposes. config KM_CRAMFS_ADDR hex "CRAMFS Address" + default 0x83000000 if ARCH_LS1021A default 0x3000000 depends on !ARCH_SOCFPGA help @@ -44,16 +45,25 @@ config KM_CRAMFS_ADDR config KM_KERNEL_ADDR hex "Kernel Load Address" + default 0x82000000 if ARCH_LS1021A default 0x2000000 help Address where to load Linux kernel in RAM. config KM_FDT_ADDR hex "FDT Load Address" + default 0x82FC0000 if ARCH_LS1021A default 0x2FC0000 help Address where to load flattened device tree in RAM. +config SYS_PAX_BASE + hex "PAX IFC Base Address" + default 0x78000000 + depends on ARCH_LS1021A + help + IFC Base Address for PAXx FPGA. + config KM_CONSOLE_TTY string "KM Console" default "ttyS0" @@ -69,9 +79,9 @@ config KM_DEF_NETDEV config KM_COMMON_ETH_INIT bool "Common Ethernet Initialization" default y if ARCH_KIRKWOOD || MPC83xx - default n if MPC85xx || ARCH_SOCFPGA + default n if MPC85xx || ARCH_SOCFPGA || ARCH_LS1021A help - Use the Ethernet initialization implemented in common code, which + Use the Ethernet initialization implemented in common code that detects if a Piggy board is present. config PIGGY_MAC_ADDRESS_OFFSET @@ -90,7 +100,7 @@ config KM_MVEXTSW_ADDR config KM_IVM_BUS int "IVM I2C Bus" default 0 if ARCH_SOCFPGA - default 1 if ARCH_KIRKWOOD || MPC85xx + default 1 if ARCH_KIRKWOOD || MPC85xx || ARCH_LS1021A default 2 if MPC83xx help Identifier number of I2C bus, where the inventory EEPROM is connected to. @@ -116,6 +126,7 @@ config SYS_IVM_EEPROM_PAGE_LEN source "board/keymile/km83xx/Kconfig" source "board/keymile/kmp204x/Kconfig" source "board/keymile/km_arm/Kconfig" +source "board/keymile/pg-wcom-ls102xa/Kconfig" endmenu diff --git a/board/keymile/common/ivm.c b/board/keymile/common/ivm.c index e989bf6..48817cb 100644 --- a/board/keymile/common/ivm.c +++ b/board/keymile/common/ivm.c @@ -306,11 +306,7 @@ static int ivm_populate_env(unsigned char *buf, int len, int mac_address_offset) return 0; page2 = &buf[CONFIG_SYS_IVM_EEPROM_PAGE_LEN * 2]; - if (!IS_ENABLED(CONFIG_KMTEGR1)) { - /* if an offset is defined, add it */ - process_mac(valbuf, page2, mac_address_offset, true); - env_set((char *)"ethaddr", (char *)valbuf); - } else { + if (IS_ENABLED(CONFIG_KMTEGR1)) { /* KMTEGR1 has a special setup. eth0 has no connection to the * outside and gets an locally administred MAC address, eth1 is * the debug interface and gets the official MAC address from @@ -320,6 +316,19 @@ static int ivm_populate_env(unsigned char *buf, int len, int mac_address_offset) env_set((char *)"ethaddr", (char *)valbuf); process_mac(valbuf, page2, mac_address_offset, true); env_set((char *)"eth1addr", (char *)valbuf); + } else if (IS_ENABLED(CONFIG_ARCH_LS1021A)) { + /* LS102xA has 1xRGMII for debug connection and + * 2xSGMII for back-plane mgmt connection + */ + process_mac(valbuf, page2, 1, true); + env_set((char *)"ethaddr", (char *)valbuf); + process_mac(valbuf, page2, 2, true); + env_set((char *)"eth1addr", (char *)valbuf); + process_mac(valbuf, page2, mac_address_offset, true); + env_set((char *)"eth2addr", (char *)valbuf); + } else { + process_mac(valbuf, page2, mac_address_offset, true); + env_set((char *)"ethaddr", (char *)valbuf); } return 0; diff --git a/board/keymile/pg-wcom-ls102xa/Kconfig b/board/keymile/pg-wcom-ls102xa/Kconfig new file mode 100644 index 0000000..15c009d --- /dev/null +++ b/board/keymile/pg-wcom-ls102xa/Kconfig @@ -0,0 +1,19 @@ +if TARGET_PG_WCOM_SELI8 + +config SYS_BOARD + default "pg-wcom-ls102xa" + +config SYS_VENDOR + default "keymile" + +config SYS_SOC + default "ls102xa" + +config SYS_CONFIG_NAME + default "pg-wcom-seli8" + +config BOARD_SPECIFIC_OPTIONS + def_bool y + imply FS_CRAMFS + +endif diff --git a/board/keymile/pg-wcom-ls102xa/MAINTAINERS b/board/keymile/pg-wcom-ls102xa/MAINTAINERS new file mode 100644 index 0000000..e1bc90a --- /dev/null +++ b/board/keymile/pg-wcom-ls102xa/MAINTAINERS @@ -0,0 +1,10 @@ +Hitachi Power Grids LS102XA BOARD +M: Aleksandar Gerasimovski <aleksandar.gerasimovski(a)hitachi-powergrids.com> +M: Rainer Boschung <rainer.boschung(a)hitachi-powergrids.com> +M: Matteo Ghidoni <matteo.ghidoni(a)hitachi-powergrids.com> +S: Maintained +F: board/keymile/pg-wcom-ls102xa/ +F: include/configs/km/pg-wcom-ls102xa.h +F: include/configs/pg-wcom-seli8.h +F: configs/pg_wcom_seli8_defconfig +F: arch/arm/dts/ls1021a-pg-wcom-seli8.dts diff --git a/board/keymile/pg-wcom-ls102xa/Makefile b/board/keymile/pg-wcom-ls102xa/Makefile new file mode 100644 index 0000000..229b0c2 --- /dev/null +++ b/board/keymile/pg-wcom-ls102xa/Makefile @@ -0,0 +1,11 @@ +# +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright 2021 Hitachi Power Grids. All rights reserved. +# + +obj-y += pg-wcom-ls102xa.o ddr.o +obj-y += ../common/common.o ../common/ivm.o ../common/qrio.o +obj-$(CONFIG_LAYERSCAPE_NS_ACCESS) += ../../freescale/common/ns_access.o +obj-$(CONFIG_LS102XA_STREAM_ID) += ../../freescale/common/ls102xa_stream_id.o +obj-$(CONFIG_ID_EEPROM) += ../../freescale/common/sys_eeprom.o diff --git a/board/keymile/pg-wcom-ls102xa/ddr.c b/board/keymile/pg-wcom-ls102xa/ddr.c new file mode 100644 index 0000000..6023573 --- /dev/null +++ b/board/keymile/pg-wcom-ls102xa/ddr.c @@ -0,0 +1,90 @@ +// SPDX-License-Identifier: GPL-2.0+ +/* + * Copyright 2014 Freescale Semiconductor, Inc. + * Copyright 2020 Hitachi Power Grids. All rights reserved. + */ + +#include <common.h> +#include <fsl_ddr_sdram.h> +#include <fsl_ddr_dimm_params.h> +#include <asm/io.h> +#include <asm/arch/clock.h> +#include <asm/arch/ls102xa_soc.h> + +DECLARE_GLOBAL_DATA_PTR; + +void fsl_ddr_board_options(memctl_options_t *popts, + dimm_params_t *pdimm, + unsigned int ctrl_num) +{ + if (ctrl_num > 1) { + printf("Not supported controller number %d\n", ctrl_num); + return; + } + + // 1/2 DRAM cycle (should be increased in case of ADDR/CMD heavily loaded than the clock) + popts->clk_adjust = 0x4; + popts->write_data_delay = 0x4; + // wr leveling start value for lane 0 + popts->wrlvl_start = 0x5; + // wr leveling start values for lanes 1-3 (lane 4 not there) + popts->wrlvl_ctl_2 = 0x05050500; + // 32-bit DRAM, no need to set start values for lanes we do not have (5-8) + popts->wrlvl_ctl_3 = 0x0; + popts->cpo_override = 0x1f; + + /* force DDR bus width to 32 bits */ + popts->data_bus_width = 1; + popts->otf_burst_chop_en = 0; + popts->burst_length = DDR_BL8; + + /* + * Factors to consider for half-strength driver enable: + * - number of DIMMs installed + */ + popts->half_strength_driver_enable = 1; + /* + * Write leveling override + */ + popts->wrlvl_override = 1; + popts->wrlvl_sample = 0xf; + + /* + * Rtt and Rtt_WR override + */ + popts->rtt_override = 0; + + /* Enable ZQ calibration */ + popts->zq_en = 1; + + popts->cswl_override = DDR_CSWL_CS0; + + /* optimize cpo for erratum A-009942 */ + popts->cpo_sample = 0x58; + + /* DHC_EN =1, ODT = 75 Ohm */ + popts->ddr_cdr1 = DDR_CDR1_DHC_EN | DDR_CDR1_ODT(DDR_CDR_ODT_75ohm); + popts->ddr_cdr2 = DDR_CDR2_ODT(DDR_CDR_ODT_75ohm); +} + +int fsl_initdram(void) +{ + phys_size_t dram_size; + + puts("Initializing DDR....using SPD\n"); + dram_size = fsl_ddr_sdram(); + + erratum_a008850_post(); + + gd->ram_size = dram_size; + + return 0; +} + +int dram_init_banksize(void) +{ + gd->bd->bi_dram[0].start = CONFIG_SYS_SDRAM_BASE; + gd->bd->bi_dram[0].size = gd->ram_size; + + return 0; +} diff --git a/board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c b/board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c new file mode 100644 index 0000000..6b0e963 --- /dev/null +++ b/board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c @@ -0,0 +1,160 @@ +// SPDX-License-Identifier: GPL-2.0+ +/* + * Copyright 2020 Hitachi Power Grids. All rights reserved. + */ + +#include <common.h> +#include <i2c.h> +#include <asm/io.h> +#include <asm/arch/immap_ls102xa.h> +#include <asm/arch/clock.h> +#include <asm/arch/fsl_serdes.h> +#include <asm/arch/ls102xa_devdis.h> +#include <asm/arch/ls102xa_soc.h> +#include <hwconfig.h> +#include <mmc.h> +#include <fsl_csu.h> +#include <fsl_esdhc.h> +#include <fsl_ifc.h> +#include <fsl_immap.h> +#include <netdev.h> +#include <fsl_mdio.h> +#include <tsec.h> +#include <fsl_sec.h> +#include <fsl_devdis.h> +#include <fsl_ddr.h> +#include <spl.h> +#include <fdt_support.h> +#include <fsl_qe.h> +#include <fsl_validate.h> + +#include "../common/common.h" +#include "../common/qrio.h" + +DECLARE_GLOBAL_DATA_PTR; + +static uchar ivm_content[CONFIG_SYS_IVM_EEPROM_MAX_LEN]; + +int checkboard(void) +{ + show_qrio(); + + return 0; +} + +int dram_init(void) +{ + return fsl_initdram(); +} + +int board_early_init_f(void) +{ + struct ccsr_scfg *scfg = (struct ccsr_scfg *)CONFIG_SYS_FSL_SCFG_ADDR; + struct ccsr_gur __iomem *gur = (void *)CONFIG_SYS_FSL_GUTS_ADDR; + struct fsl_ifc ifc = {(void *)CONFIG_SYS_IFC_ADDR, (void *)NULL}; + + /* Disable unused MCK1 */ + setbits_be32(&gur->ddrclkdr, 2); + + /* IFC Global Configuration */ + setbits_be32(&ifc.gregs->ifc_gcr, 12 << IFC_GCR_TBCTL_TRN_TIME_SHIFT); + setbits_be32(&ifc.gregs->ifc_ccr, IFC_CCR_CLK_DIV(3) | + IFC_CCR_INV_CLK_EN); + + /* clear BD & FR bits for BE BD's and frame data */ + clrbits_be32(&scfg->etsecdmamcr, SCFG_ETSECDMAMCR_LE_BD_FR); + out_be32(&scfg->etsecmcr, SCFG_ETSECCMCR_GE2_CLK125); + + init_early_memctl_regs(); + + /* QRIO Configuration */ + qrio_uprstreq(UPREQ_CORE_RST); + + if (IS_ENABLED(CONFIG_TARGET_PG_WCOM_SELI8)) { + qrio_prstcfg(KM_LIU_RST, PRSTCFG_POWUP_UNIT_RST); + qrio_wdmask(KM_LIU_RST, true); + + qrio_prstcfg(KM_PAXK_RST, PRSTCFG_POWUP_UNIT_RST); + qrio_wdmask(KM_PAXK_RST, true); + + qrio_prstcfg(KM_DBG_ETH_RST, PRSTCFG_POWUP_UNIT_CORE_RST); + qrio_prst(KM_DBG_ETH_RST, false, false); + } + + i2c_deblock_gpio_cfg(); + + arch_soc_init(); + + return 0; +} + +int board_init(void) +{ + if (IS_ENABLED(CONFIG_SYS_FSL_ERRATUM_A010315)) + erratum_a010315(); + + fsl_serdes_init(); + + ls102xa_smmu_stream_id_init(); + + u_qe_init(); + + return 0; +} + +int board_late_init(void) +{ + return 0; +} + +int misc_init_r(void) +{ + if (IS_ENABLED(CONFIG_FSL_DEVICE_DISABLE)) + device_disable(devdis_tbl, ARRAY_SIZE(devdis_tbl)); + + ivm_read_eeprom(ivm_content, CONFIG_SYS_IVM_EEPROM_MAX_LEN, + CONFIG_PIGGY_MAC_ADDRESS_OFFSET); + + return 0; +} + +int ft_board_setup(void *blob, struct bd_info *bd) +{ + ft_cpu_setup(blob, bd); + + if (IS_ENABLED(CONFIG_PCI)) + ft_pci_setup(blob, bd); + + return 0; +} + +u8 flash_read8(void *addr) +{ + return __raw_readb(addr + 1); +} + +void flash_write16(u16 val, void *addr) +{ + u16 shftval = (((val >> 8) & 0xff) | ((val << 8) & 0xff00)); + + __raw_writew(shftval, addr); +} + +u16 flash_read16(void *addr) +{ + u16 val = __raw_readw(addr); + + return (((val) >> 8) & 0x00ff) | (((val) << 8) & 0xff00); +} + +int hush_init_var(void) +{ + ivm_analyze_eeprom(ivm_content, CONFIG_SYS_IVM_EEPROM_MAX_LEN); + return 0; +} + +int last_stage_init(void) +{ + set_km_env(); + return 0; +} diff --git a/configs/pg_wcom_seli8_defconfig b/configs/pg_wcom_seli8_defconfig new file mode 100644 index 0000000..2d58fa0 --- /dev/null +++ b/configs/pg_wcom_seli8_defconfig @@ -0,0 +1,63 @@ +CONFIG_ARM=y +CONFIG_TARGET_PG_WCOM_SELI8=y +CONFIG_SYS_TEXT_BASE=0x60100000 +CONFIG_NR_DRAM_BANKS=1 +CONFIG_KM_DEF_NETDEV="eth2" +CONFIG_KM_COMMON_ETH_INIT=y +CONFIG_PIGGY_MAC_ADDRESS_OFFSET=3 +CONFIG_SYS_MEMTEST_START=0x80000000 +CONFIG_SYS_MEMTEST_END=0x9fffffff +CONFIG_ENV_SIZE=0x4000 +CONFIG_ENV_SECT_SIZE=0x20000 +CONFIG_BOOTCOUNT_BOOTLIMIT=3 +CONFIG_SYS_BOOTCOUNT_ADDR=0x70000020 +CONFIG_DEFAULT_DEVICE_TREE="ls1021a-pg-wcom-seli8" +CONFIG_AHCI=y +CONFIG_DISTRO_DEFAULTS=y +CONFIG_FIT=y +CONFIG_FIT_VERBOSE=y +CONFIG_OF_BOARD_SETUP=y +CONFIG_OF_STDOUT_VIA_ALIAS=y +CONFIG_BOOTDELAY=3 +CONFIG_USE_BOOTARGS=y +CONFIG_BOOTARGS="console=ttyS0,115200 root=/dev/ram0" +CONFIG_SILENT_CONSOLE=y +CONFIG_MISC_INIT_R=y +CONFIG_LAST_STAGE_INIT=y +CONFIG_CMD_IMLS=y +CONFIG_CMD_GREPENV=y +CONFIG_CMD_MEMINFO=y +CONFIG_CMD_MEMTEST=y +CONFIG_CMD_GPT=y +CONFIG_CMD_I2C=y +CONFIG_CMD_NAND=y +CONFIG_CMD_NAND_TRIMFFS=y +CONFIG_CMD_CRAMFS=y +CONFIG_CMD_MTDPARTS=y +CONFIG_MTDIDS_DEFAULT="nor0=60000000.nor,nand0=68000000.flash" +CONFIG_MTDPARTS_DEFAULT="mtdparts=60000000.nor:128k(rcw),128k(qe),128k(envred),128k(env),512k(res),1m(u-boot),-(ubi0);68000000.flash:-(ubi1)" +CONFIG_CMD_UBI=y +CONFIG_OF_CONTROL=y +CONFIG_ENV_IS_IN_FLASH=y +CONFIG_ENV_ADDR=0x60060000 +CONFIG_DM=y +CONFIG_BOOTCOUNT_LIMIT=y +CONFIG_SYS_FSL_DDR3=y +# CONFIG_MMC is not set +CONFIG_MTD=y +CONFIG_MTD_NOR_FLASH=y +CONFIG_FLASH_CFI_DRIVER=y +CONFIG_SYS_FLASH_USE_BUFFER_WRITE=y +CONFIG_FLASH_CFI_MTD=y +CONFIG_SYS_FLASH_CFI=y +CONFIG_MTD_RAW_NAND=y +CONFIG_PHY_MARVELL=y +CONFIG_PHY_FIXED=y +CONFIG_DM_ETH=y +CONFIG_DM_MDIO=y +CONFIG_PHY_GIGE=y +CONFIG_MII=y +CONFIG_TSEC_ENET=y +CONFIG_SPECIFY_CONSOLE_INDEX=y +CONFIG_DM_SERIAL=y +CONFIG_SYS_NS16550=y diff --git a/include/configs/km/pg-wcom-ls102xa.h b/include/configs/km/pg-wcom-ls102xa.h new file mode 100644 index 0000000..55fb909 --- /dev/null +++ b/include/configs/km/pg-wcom-ls102xa.h @@ -0,0 +1,309 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ +/* + * Copyright 2020 Hitachi Power Grids. All rights reserved. + */ + +#ifndef __CONFIG_PG_WCOM_LS102XA_H +#define __CONFIG_PG_WCOM_LS102XA_H + +#define CONFIG_SYS_FSL_CLK + +#define CONFIG_SKIP_LOWLEVEL_INIT + +/* include common defines/options for all Keymile boards */ +#include "keymile-common.h" + +/* + * Size of malloc() pool + */ +#define CONFIG_SYS_MALLOC_LEN (CONFIG_ENV_SIZE + 16 * 1024 * 1024) + +#define CONFIG_SYS_INIT_RAM_ADDR OCRAM_BASE_ADDR +#define CONFIG_SYS_INIT_RAM_SIZE OCRAM_SIZE + +#define CONFIG_SYS_CLK_FREQ 66666666 +/* + * Take into account default implementation where DDR_FDBK_MULTI is consider as + * configured for DDR_PLL = 2*MEM_PLL_RAT. + * In our case DDR_FDBK_MULTI is 2, means DDR_PLL = MEM_PLL_RAT. + */ +#define CONFIG_DDR_CLK_FREQ (100000000 >> 1) + +#define PHYS_SDRAM 0x80000000 +#define PHYS_SDRAM_SIZE (1u * 1024 * 1024 * 1024) + +#define CONFIG_SYS_DDR_SDRAM_BASE 0x80000000UL +#define CONFIG_SYS_SDRAM_BASE CONFIG_SYS_DDR_SDRAM_BASE + +#define CONFIG_DIMM_SLOTS_PER_CTLR 1 +#define CONFIG_CHIP_SELECTS_PER_CTRL 4 + +#define CONFIG_DDR_SPD + +#define CONFIG_SYS_SPD_BUS_NUM 0 +#define SPD_EEPROM_ADDRESS 0x54 + +/* + * IFC Definitions + */ +/* NOR Flash Definitions */ +#define CONFIG_FSL_IFC +#define CONFIG_SYS_FLASH_BASE 0x60000000 +#define CONFIG_SYS_FLASH_BASE_PHYS CONFIG_SYS_FLASH_BASE + +#define CONFIG_SYS_NOR0_CSPR_EXT (0x0) +#define CONFIG_SYS_NOR0_CSPR (CSPR_PHYS_ADDR(CONFIG_SYS_FLASH_BASE_PHYS) | \ + CSPR_PORT_SIZE_16 | \ + CSPR_TE | \ + CSPR_MSEL_NOR | \ + CSPR_V) +#define CONFIG_SYS_NOR_AMASK IFC_AMASK(64 * 1024 * 1024) + +#define CONFIG_SYS_NOR_CSOR (CSOR_NOR_AVD_TGL_PGM_EN | \ + CSOR_NOR_ADM_SHIFT(0x4) | \ + CSOR_NOR_NOR_MODE_AYSNC_NOR | \ + CSOR_NOR_TRHZ_20 | \ + CSOR_NOR_BCTLD) +#define CONFIG_SYS_NOR_FTIM0 (FTIM0_NOR_TACSE(0x1) | \ + FTIM0_NOR_TEADC(0x7) | \ + FTIM0_NOR_TAVDS(0x0) | \ + FTIM0_NOR_TEAHC(0x1)) +#define CONFIG_SYS_NOR_FTIM1 (FTIM1_NOR_TACO(0x1) | \ + FTIM1_NOR_TRAD_NOR(0x21) | \ + FTIM1_NOR_TSEQRAD_NOR(0x21)) +#define CONFIG_SYS_NOR_FTIM2 (FTIM2_NOR_TCS(0x1) | \ + FTIM2_NOR_TCH(0x1) | \ + FTIM2_NOR_TWPH(0x6) | \ + FTIM2_NOR_TWP(0xb)) +#define CONFIG_SYS_NOR_FTIM3 0 + +#define CONFIG_SYS_FLASH_QUIET_TEST +#define CONFIG_FLASH_SHOW_PROGRESS 45 /* count down from 45/5: 9..1 */ + +#define CONFIG_SYS_MAX_FLASH_BANKS 1 /* number of banks */ +#define CONFIG_SYS_MAX_FLASH_SECT 512 /* sectors per device */ +#define CONFIG_SYS_FLASH_ERASE_TOUT 60000 /* Flash Erase Timeout (ms) */ +#define CONFIG_SYS_FLASH_WRITE_TOUT 500 /* Flash Write Timeout (ms) */ + +#define CONFIG_SYS_FLASH_EMPTY_INFO +#define CONFIG_SYS_FLASH_BANKS_LIST { CONFIG_SYS_FLASH_BASE_PHYS } + +#define CONFIG_CFI_FLASH_USE_WEAK_ACCESSORS +#define CONFIG_SYS_WRITE_SWAPPED_DATA + +#define CONFIG_SYS_CSPR0_EXT CONFIG_SYS_NOR0_CSPR_EXT +#define CONFIG_SYS_CSPR0 CONFIG_SYS_NOR0_CSPR +#define CONFIG_SYS_AMASK0 CONFIG_SYS_NOR_AMASK +#define CONFIG_SYS_CSOR0 CONFIG_SYS_NOR_CSOR +#define CONFIG_SYS_CS0_FTIM0 CONFIG_SYS_NOR_FTIM0 +#define CONFIG_SYS_CS0_FTIM1 CONFIG_SYS_NOR_FTIM1 +#define CONFIG_SYS_CS0_FTIM2 CONFIG_SYS_NOR_FTIM2 +#define CONFIG_SYS_CS0_FTIM3 CONFIG_SYS_NOR_FTIM3 + +/* NAND Flash Definitions */ +#define CONFIG_NAND_FSL_IFC +#define CONFIG_SYS_NAND_BASE 0x68000000 +#define CONFIG_SYS_NAND_BASE_PHYS CONFIG_SYS_NAND_BASE + +#define CONFIG_SYS_NAND_CSPR_EXT (0x0) +#define CONFIG_SYS_NAND_CSPR (CSPR_PHYS_ADDR(CONFIG_SYS_NAND_BASE) | \ + CSPR_PORT_SIZE_8 | \ + CSPR_TE | \ + CSPR_MSEL_NAND | \ + CSPR_V) +#define CONFIG_SYS_NAND_AMASK IFC_AMASK(64 * 1024) +#define CONFIG_SYS_NAND_CSOR (CSOR_NAND_ECC_ENC_EN \ + | CSOR_NAND_ECC_DEC_EN \ + | CSOR_NAND_ECC_MODE_4 \ + | CSOR_NAND_RAL_3 \ + | CSOR_NAND_PGS_2K \ + | CSOR_NAND_SPRZ_64 \ + | CSOR_NAND_PB(64) \ + | CSOR_NAND_TRHZ_40 \ + | CSOR_NAND_BCTLD) + +#define CONFIG_SYS_NAND_ONFI_DETECTION + +#define CONFIG_SYS_NAND_FTIM0 (FTIM0_NAND_TCCST(0x3) | \ + FTIM0_NAND_TWP(0x8) | \ + FTIM0_NAND_TWCHT(0x3) | \ + FTIM0_NAND_TWH(0x5)) +#define CONFIG_SYS_NAND_FTIM1 (FTIM1_NAND_TADLE(0x1e) | \ + FTIM1_NAND_TWBE(0x1e) | \ + FTIM1_NAND_TRR(0x6) | \ + FTIM1_NAND_TRP(0x8)) +#define CONFIG_SYS_NAND_FTIM2 (FTIM2_NAND_TRAD(0x9) | \ + FTIM2_NAND_TREH(0x5) | \ + FTIM2_NAND_TWHRE(0x3c)) +#define CONFIG_SYS_NAND_FTIM3 (FTIM3_NAND_TWW(0x1e)) + +#define CONFIG_SYS_CSPR1_EXT CONFIG_SYS_NAND_CSPR_EXT +#define CONFIG_SYS_CSPR1 CONFIG_SYS_NAND_CSPR +#define CONFIG_SYS_AMASK1 CONFIG_SYS_NAND_AMASK +#define CONFIG_SYS_CSOR1 CONFIG_SYS_NAND_CSOR +#define CONFIG_SYS_CS1_FTIM0 CONFIG_SYS_NAND_FTIM0 +#define CONFIG_SYS_CS1_FTIM1 CONFIG_SYS_NAND_FTIM1 +#define CONFIG_SYS_CS1_FTIM2 CONFIG_SYS_NAND_FTIM2 +#define CONFIG_SYS_CS1_FTIM3 CONFIG_SYS_NAND_FTIM3 + +#define CONFIG_SYS_MAX_NAND_DEVICE 1 +#define CONFIG_SYS_NAND_BASE_LIST { CONFIG_SYS_NAND_BASE } +#define CONFIG_SYS_NAND_BLOCK_SIZE (128 * 1024) + +/* QRIO FPGA Definitions */ +#define CONFIG_SYS_QRIO_BASE 0x70000000 +#define CONFIG_SYS_QRIO_BASE_PHYS CONFIG_SYS_QRIO_BASE + +#define CONFIG_SYS_CSPR2_EXT (0x00) +#define CONFIG_SYS_CSPR2 (CSPR_PHYS_ADDR(CONFIG_SYS_QRIO_BASE) | \ + CSPR_PORT_SIZE_8 | \ + CSPR_TE | \ + CSPR_MSEL_GPCM | \ + CSPR_V) +#define CONFIG_SYS_AMASK2 IFC_AMASK(64 * 1024) +#define CONFIG_SYS_CSOR2 (CSOR_GPCM_ADM_SHIFT(0x4) | \ + CSOR_GPCM_TRHZ_20 | \ + CSOR_GPCM_BCTLD) +#define CONFIG_SYS_CS2_FTIM0 (FTIM0_GPCM_TACSE(0x2) | \ + FTIM0_GPCM_TEADC(0x8) | \ + FTIM0_GPCM_TEAHC(0x2)) +#define CONFIG_SYS_CS2_FTIM1 (FTIM1_GPCM_TACO(0x2) | \ + FTIM1_GPCM_TRAD(0x6)) +#define CONFIG_SYS_CS2_FTIM2 (FTIM2_GPCM_TCS(0x1) | \ + FTIM2_GPCM_TCH(0x1) | \ + FTIM2_GPCM_TWP(0x7)) +#define CONFIG_SYS_CS2_FTIM3 0x04000000 + +/* + * Serial Port + */ +#define CONFIG_SYS_NS16550_SERIAL +#define CONFIG_SYS_NS16550_CLK get_serial_clock() + +/* + * I2C + */ +#define CONFIG_SYS_I2C +#define CONFIG_SYS_I2C_INIT_BOARD +#define CONFIG_SYS_I2C_SPEED 100000 +#define CONFIG_SYS_I2C_MXC +#define CONFIG_SYS_I2C_MXC_I2C1 /* enable I2C bus 1 */ +#define CONFIG_SYS_I2C_MXC_I2C2 /* enable I2C bus 2 */ +#define CONFIG_SYS_I2C_MXC_I2C3 /* enable I2C bus 3 */ + +#define CONFIG_I2C_MULTI_BUS +#define CONFIG_SYS_I2C_MAX_HOPS 1 +#define CONFIG_SYS_NUM_I2C_BUSES 3 +#define I2C_MUX_PCA_ADDR 0x70 +#define I2C_MUX_CH_DEFAULT 0x0 +#define CONFIG_SYS_I2C_BUSES { {0, {I2C_NULL_HOP} }, \ + {0, {{I2C_MUX_PCA9547, 0x70, 1 } } }, \ + {1, {I2C_NULL_HOP} }, \ + } + +#ifndef __ASSEMBLY__ +void set_sda(int state); +void set_scl(int state); +int get_sda(void); +int get_scl(void); +#endif + +/* + * eTSEC + */ +#ifdef CONFIG_TSEC_ENET +#define CONFIG_ETHPRIME "ethernet@2d90000" +#endif + +#define CONFIG_CMDLINE_TAG + +#define CONFIG_LAYERSCAPE_NS_ACCESS +#define CONFIG_SMP_PEN_ADDR 0x01ee0200 +#define COUNTER_FREQUENCY 12500000 + +#define CONFIG_HWCONFIG +#define HWCONFIG_BUFFER_SIZE 256 +#define CONFIG_FSL_DEVICE_DISABLE + +/* + * Miscellaneous configurable options + */ + +#define CONFIG_SYS_LOAD_ADDR 0x82000000 + +#define CONFIG_LS102XA_STREAM_ID + +#define CONFIG_SYS_INIT_SP_OFFSET \ + (CONFIG_SYS_INIT_RAM_SIZE - GENERATED_GBL_DATA_SIZE) +#define CONFIG_SYS_INIT_SP_ADDR \ + (CONFIG_SYS_INIT_RAM_ADDR + CONFIG_SYS_INIT_SP_OFFSET) + +#define CONFIG_SYS_MONITOR_BASE CONFIG_SYS_TEXT_BASE /* start of monitor */ +#define CONFIG_SYS_MONITOR_LEN 0x100000 /* 1Mbyte */ +#define CONFIG_SYS_QE_FW_ADDR 0x60020000 + +#define CONFIG_SYS_BOOTCOUNT_BE + +/* + * Environment + */ + +#define CONFIG_SYS_REDUNDAND_ENVIRONMENT +#define CONFIG_ENV_ADDR_REDUND (CONFIG_ENV_ADDR - CONFIG_ENV_SECT_SIZE) + +#define CONFIG_ENV_TOTAL_SIZE 0x40000 +#define ENV_DEL_ADDR 0x60040000 /* direct for newenv */ + +#define CONFIG_ENV_OVERWRITE +#ifndef CONFIG_KM_DEF_ENV /* if not set by keymile-common.h */ +#define CONFIG_KM_DEF_ENV +#endif + +#ifndef CONFIG_KM_DEF_BOOT_ARGS_CPU +#define CONFIG_KM_DEF_BOOT_ARGS_CPU "" +#endif + +#define CONFIG_KM_DEF_ENV_CPU \ + "boot=bootm ${load_addr_r} - ${fdt_addr_r}\0" \ + "cramfsloadfdt=" \ + "cramfsload ${fdt_addr_r} " \ + "fdt_0x${IVM_BoardId}_0x${IVM_HWKey}.dtb\0" \ + "u-boot=" CONFIG_HOSTNAME "/u-boot.bin\0" \ + "update=protect off " __stringify(CONFIG_SYS_MONITOR_BASE) \ + " +${filesize} && " \ + "erase " __stringify(CONFIG_SYS_MONITOR_BASE) \ + " +${filesize} && " \ + "cp.b ${load_addr_r} " \ + __stringify(CONFIG_SYS_MONITOR_BASE) " ${filesize} && " \ + "protect on " __stringify(CONFIG_SYS_MONITOR_BASE) \ + " +${filesize}\0" \ + "update-nor=protect off " __stringify(CONFIG_SYS_FLASH_BASE) \ + " +${filesize} && " \ + "erase " __stringify(CONFIG_SYS_FLASH_BASE) \ + " +${filesize} && " \ + "cp.b ${load_addr_r} " \ + __stringify(CONFIG_SYS_FLASH_BASE) " ${filesize} && " \ + "protect on " __stringify(CONFIG_SYS_MONITOR_BASE) \ + " +" __stringify(CONFIG_SYS_MONITOR_LEN)"\0" \ + "set_fdthigh=true\0" \ + "checkfdt=true\0" \ + "" + +#define CONFIG_KM_NEW_ENV \ + "newenv=protect off " __stringify(ENV_DEL_ADDR) \ + " +" __stringify(CONFIG_ENV_TOTAL_SIZE) " && " \ + "erase " __stringify(ENV_DEL_ADDR) \ + " +" __stringify(CONFIG_ENV_TOTAL_SIZE) " && " \ + "protect on " __stringify(ENV_DEL_ADDR) \ + " +" __stringify(CONFIG_ENV_TOTAL_SIZE) "\0" + +#define CONFIG_EXTRA_ENV_SETTINGS \ + CONFIG_KM_NEW_ENV \ + CONFIG_KM_DEF_ENV \ + "EEprom_ivm=pca9547:70:9\0" \ + "" + +#define CONFIG_SYS_BOOTM_LEN (64 << 20) /* Increase max gunzip size */ +#define CONFIG_SYS_BOOTMAPSZ (256 << 20) /* Increase map for Linux */ + +#endif diff --git a/include/configs/pg-wcom-seli8.h b/include/configs/pg-wcom-seli8.h new file mode 100644 index 0000000..9a7669c --- /dev/null +++ b/include/configs/pg-wcom-seli8.h @@ -0,0 +1,45 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ +/* + * Copyright 2020 Hitachi Power Grids. All rights reserved. + */ + +#ifndef __CONFIG_PG_WCOM_SELI8_H +#define __CONFIG_PG_WCOM_SELI8_H + +#define CONFIG_HOSTNAME "SELI8" + +#define CONFIG_KM_UBI_PARTITION_NAME_BOOT "ubi0" +#define CONFIG_KM_UBI_PARTITION_NAME_APP "ubi1" + +/* PAXK FPGA Definitions */ +#define CONFIG_SYS_CSPR3_EXT (0x00) +#define CONFIG_SYS_CSPR3 (CSPR_PHYS_ADDR(CONFIG_SYS_PAX_BASE) | \ + CSPR_PORT_SIZE_8 | \ + CSPR_MSEL_GPCM | \ + CSPR_V) +#define CONFIG_SYS_AMASK3 IFC_AMASK(64 * 1024) +#define CONFIG_SYS_CSOR3 (CSOR_GPCM_ADM_SHIFT(0x4) | \ + CSOR_GPCM_TRHZ_40) +#define CONFIG_SYS_CS3_FTIM0 (FTIM0_GPCM_TACSE(0x6) | \ + FTIM0_GPCM_TEADC(0x7) | \ + FTIM0_GPCM_TEAHC(0x2)) +#define CONFIG_SYS_CS3_FTIM1 (FTIM1_GPCM_TACO(0x2) | \ + FTIM1_GPCM_TRAD(0x12)) +#define CONFIG_SYS_CS3_FTIM2 (FTIM2_GPCM_TCS(0x3) | \ + FTIM2_GPCM_TCH(0x1) | \ + FTIM2_GPCM_TWP(0x12)) +#define CONFIG_SYS_CS3_FTIM3 0x04000000 + +/* PRST */ +#define KM_LIU_RST 0 +#define KM_PAXK_RST 1 +#define KM_DBG_ETH_RST 15 + +/* QRIO GPIOs used for deblocking */ +#define KM_I2C_DEBLOCK_PORT QRIO_GPIO_A +#define KM_I2C_DEBLOCK_SCL 20 +#define KM_I2C_DEBLOCK_SDA 21 + +#include "km/pg-wcom-ls102xa.h" + +#endif /* __CONFIG_PG_WCOM_SELI8_H */ -- 1.8.3.1 -----Original Message----- From: Priyanka Jain (OSS) <priyanka.jain(a)oss.nxp.com> Sent: Dienstag, 19. Januar 2021 07:56 To: Aleksandar Gerasimovski <aleksandar.gerasimovski(a)hitachi-powergrids.com>; u-boot(a)lists.denx.de Cc: Valentin Longchamp <valentin.longchamp(a)hitachi-powergrids.com>; Holger Brunck <holger.brunck(a)hitachi-powergrids.com>; Rainer Boschung <rainer.boschung(a)hitachi-powergrids.com>; Matteo Ghidoni <matteo.ghidoni(a)hitachi-powergrids.com> Subject: RE: [PATCH 4/4] board: keymile: add support for seli8 design based on nxp ls102x soc CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe. >-----Original Message----- >From: U-Boot <u-boot-bounces(a)lists.denx.de> On Behalf Of Aleksandar >Gerasimovski >Sent: Wednesday, January 13, 2021 9:51 PM >To: u-boot(a)lists.denx.de >Cc: Valentin Longchamp <valentin.longchamp(a)hitachi-powergrids.com>; >Holger Brunck <holger.brunck(a)hitachi-powergrids.com>; Rainer Boschung ><rainer.boschung(a)hitachi-powergrids.com>; Matteo Ghidoni ><matteo.ghidoni(a)hitachi-powergrids.com> >Subject: [PATCH 4/4] board: keymile: add support for seli8 design based >on nxp ls102x soc > Please trim subject to 60 characters >The SELI8 design is a new tdm service unit card for Hitachi-Powergrids >XMC and FOX product lines. > >It is based on NXP LS1021 SoC and it provides following interfaces: > - IFC interface for NOR, NAND and external FPGA's > - 1 x RGMII ETH for debug purposes > - 2 x SGMII ETH for management communication via back-plane > - 1 x uQE HDLC for management communication via back-plane > - 1 x I2C for peripheral devices > - 1 x SPI for peripheral devices > - 1 x UART for debug logging > >It is foreseen that the design will be later re-used for another XMC >and FOX service cards with similar SoC requirements. > >Signed-off-by: Rainer Boschung <rainer.boschung(a)hitachi-powergrids.com> >Signed-off-by: Matteo Ghidoni <matteo.ghidoni(a)hitachi-powergrids.com> >Signed-off-by: Aleksandar Gerasimovski ><aleksandar.gerasimovski@hitachi- powergrids.com> >--- > arch/arm/Kconfig | 19 ++ > arch/arm/dts/Makefile | 2 + > arch/arm/dts/ls1021a-pg-wcom-seli8.dts | 111 +++++++++ > board/keymile/Kconfig | 23 +- > board/keymile/common/ivm.c | 19 +- > board/keymile/pg-wcom-ls102xa/Kconfig | 19 ++ > board/keymile/pg-wcom-ls102xa/MAINTAINERS | 10 + > board/keymile/pg-wcom-ls102xa/Makefile | 11 + > board/keymile/pg-wcom-ls102xa/ddr.c | 90 +++++++ > board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c | 160 ++++++++++++ > configs/pg_wcom_seli8_defconfig | 63 +++++ > include/configs/km/pg-wcom-ls102xa.h | 309 >++++++++++++++++++++++++ > include/configs/pg-wcom-seli8.h | 45 ++++ > 13 files changed, 870 insertions(+), 11 deletions(-) create mode >100644 arch/arm/dts/ls1021a-pg-wcom-seli8.dts > create mode 100644 board/keymile/pg-wcom-ls102xa/Kconfig > create mode 100644 board/keymile/pg-wcom-ls102xa/MAINTAINERS > create mode 100644 board/keymile/pg-wcom-ls102xa/Makefile > create mode 100644 board/keymile/pg-wcom-ls102xa/ddr.c > create mode 100644 board/keymile/pg-wcom-ls102xa/pg-wcom-ls102xa.c > create mode 100644 configs/pg_wcom_seli8_defconfig create mode 100644 >include/configs/km/pg-wcom-ls102xa.h > create mode 100644 include/configs/pg-wcom-seli8.h > <snip> Regards Priyank

2 1

Intermittent failure with test_efi_selftest_text_input
by Simon Glass 02 Feb '21

02 Feb '21

Hi Heinrich, I am seeing a failure in gitlab every now and then. Here is an example of a build that failed and then succeeded on retry: https://gitlab.denx.de/u-boot/custodians/u-boot-dm/-/jobs/149201 Here's the failing trace: https://pastebin.com/bdu6jmVy Do you have any ideas? Regards, Simon

3 4

[PATCH 1/1] sandbox: host bind must close file descriptor
by Heinrich Schuchardt 01 Feb '21

01 Feb '21

Each invocation of the 'host bind' command with a file name argument opens a file descriptor. The next invocation of the 'host bind' command destroys the block device but the file descriptor remains open. The same holds true for the 'unbind blk' command. Close the file descriptor when unbinding the host block device. Signed-off-by: Heinrich Schuchardt <xypron.glpk(a)gmx.de> --- drivers/block/sandbox.c | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/drivers/block/sandbox.c b/drivers/block/sandbox.c index f57f690d3c..02992ac34f 100644 --- a/drivers/block/sandbox.c +++ b/drivers/block/sandbox.c @@ -230,6 +230,25 @@ int host_get_dev_err(int devnum, struct blk_desc **blk_devp) } #ifdef CONFIG_BLK + +int sandbox_host_unbind(struct udevice *dev) +{ + struct host_block_dev *host_dev; + + host_dev = dev_get_plat(dev); + if (host_dev) { + if (host_dev->fd) { + os_close(host_dev->fd); + host_dev->fd = 0; + } else { + log_err("missing file descriptor\n"); + } + } else { + log_err("missing platform data\n"); + } + return 0; +} + static const struct blk_ops sandbox_host_blk_ops = { .read = host_block_read, .write = host_block_write, @@ -239,6 +258,7 @@ U_BOOT_DRIVER(sandbox_host_blk) = { .name = "sandbox_host_blk", .id = UCLASS_BLK, .ops = &sandbox_host_blk_ops, + .unbind = sandbox_host_unbind, .plat_auto = sizeof(struct host_block_dev), }; #else -- 2.29.2

2 3

[PATCH 1/1] doc: dm: describe end of life of plat_auto
by Heinrich Schuchardt 01 Feb '21

01 Feb '21

Describe when plat_auto is freed. Fix a typo. Signed-off-by: Heinrich Schuchardt <xypron.glpk(a)gmx.de> --- doc/driver-model/design.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst index ffed7d5f79..1f00f437a8 100644 --- a/doc/driver-model/design.rst +++ b/doc/driver-model/design.rst @@ -725,7 +725,7 @@ The steps are: 2. If plat_auto is non-zero, then the platform data space is allocated. This is only useful for device tree operation, since - otherwise you would have to specific the platform data in the + otherwise you would have to specify the platform data in the U_BOOT_DRVINFO() declaration. The space is allocated for the device and zeroed. It will be accessible as dev->plat. @@ -861,8 +861,8 @@ remove it. This performs the probe steps in reverse: be dynamically allocated, and thus needs to be deallocated during the remove() method, either: - - if the plat_auto is non-zero, the deallocation - happens automatically within the driver model core; or + - if the plat_auto is non-zero, the deallocation happens automatically + within the driver model core in the unbind stage; or - when plat_auto is 0, both the allocation (in probe() or preferably of_to_plat()) and the deallocation in remove() -- 2.29.2

2 1

[PATCH 1/1] fs: fat: usage basename in file_fat_write_at, fat_mkdir
by Heinrich Schuchardt 01 Feb '21

01 Feb '21

This patch involves no functional change. It is just about code readability. Both in file_fat_write_at() and fat_mkdir() the incoming file or directory path are split into two parts: the parent directory and the base name. In file_fat_write_at() the value of the variable basename is assigned to the filename parameter and afterwards the variable filename is used instead of basename. It is more readable to use the variable basename and leave filename unchanged. In fat_mkdir() the base name variable is called directory. This is confusing. Call it basename like in file_fat_write_at(). This allows to rename parameter new_directory to directory in the implementation of fat_mkdir() to match the function declaration. Signed-off-by: Heinrich Schuchardt <xypron.glpk(a)gmx.de> --- fs/fat/fat_write.c | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/fs/fat/fat_write.c b/fs/fat/fat_write.c index b43a27b205..a9b9fa5d68 100644 --- a/fs/fat/fat_write.c +++ b/fs/fat/fat_write.c @@ -1299,9 +1299,8 @@ int file_fat_write_at(const char *filename, loff_t pos, void *buffer, goto exit; } - filename = basename; - if (normalize_longname(l_filename, filename)) { - printf("FAT: illegal filename (%s)\n", filename); + if (normalize_longname(l_filename, basename)) { + printf("FAT: illegal filename (%s)\n", basename); ret = -EINVAL; goto exit; } @@ -1365,7 +1364,7 @@ int file_fat_write_at(const char *filename, loff_t pos, void *buffer, } /* Check if long name is needed */ - ndent = set_name(itr, filename, shortname); + ndent = set_name(itr, basename, shortname); if (ndent < 0) { ret = ndent; goto exit; @@ -1375,7 +1374,7 @@ int file_fat_write_at(const char *filename, loff_t pos, void *buffer, goto exit; if (ndent > 1) { /* Set long name entries */ - ret = fill_dir_slot(itr, filename, shortname); + ret = fill_dir_slot(itr, basename, shortname); if (ret) goto exit; } @@ -1611,31 +1610,31 @@ exit: return ret; } -int fat_mkdir(const char *new_dirname) +int fat_mkdir(const char *dirname) { dir_entry *retdent; fsdata datablock = { .fatbuf = NULL, }; fsdata *mydata = &datablock; fat_itr *itr = NULL; - char *dirname_copy, *parent, *dirname; + char *dirname_copy, *parent, *basename; char l_dirname[VFAT_MAXLEN_BYTES]; int ret = -1; loff_t actwrite; unsigned int bytesperclust; dir_entry *dotdent = NULL; - dirname_copy = strdup(new_dirname); + dirname_copy = strdup(dirname); if (!dirname_copy) goto exit; - split_filename(dirname_copy, &parent, &dirname); - if (!strlen(dirname)) { + split_filename(dirname_copy, &parent, &basename); + if (!strlen(basename)) { ret = -EINVAL; goto exit; } - if (normalize_longname(l_dirname, dirname)) { - printf("FAT: illegal filename (%s)\n", dirname); + if (normalize_longname(l_dirname, basename)) { + printf("FAT: illegal filename (%s)\n", basename); ret = -EINVAL; goto exit; } @@ -1678,7 +1677,7 @@ int fat_mkdir(const char *new_dirname) } /* Check if long name is needed */ - ndent = set_name(itr, dirname, shortname); + ndent = set_name(itr, basename, shortname); if (ndent < 0) { ret = ndent; goto exit; @@ -1688,7 +1687,7 @@ int fat_mkdir(const char *new_dirname) goto exit; if (ndent > 1) { /* Set long name entries */ - ret = fill_dir_slot(itr, dirname, shortname); + ret = fill_dir_slot(itr, basename, shortname); if (ret) goto exit; } -- 2.29.2

2 1

[PATCH 0/2] power: remove non-DM max8997/8 files
by Jaehoon Chung 01 Feb '21

01 Feb '21

Remove non-DM files about max8997 and max8998. There are already max8997/8 pmic driver to support driver-model. But i didn't remove them because there was one place to use them. Now, it's time to remove non-DM max8997/8 files after converting to DM in samsung/common/misc.c Jaehoon Chung (2): board: samsung: covert to driver model about power_key_pressed power: pmic: remove pmic_max8997/8 files board/samsung/common/misc.c | 27 ++++---- drivers/power/pmic/Makefile | 2 - drivers/power/pmic/pmic_max8997.c | 107 ------------------------------ drivers/power/pmic/pmic_max8998.c | 32 --------- 4 files changed, 14 insertions(+), 154 deletions(-) delete mode 100644 drivers/power/pmic/pmic_max8997.c delete mode 100644 drivers/power/pmic/pmic_max8998.c -- 2.29.0

2 4

[PATCH v4 0/6] Add support for ECDSA image signing (with test)
by Alexandru Gagniuc 01 Feb '21

01 Feb '21

## Purpose and intent The purpose of this series is to enable ECDSA as an alternative to RSA for FIT signing. As new chips have built-in support for ECDSA verified boot, it makes sense to stick to one signing algorithm, instead of resorting to RSA for u-boot images. The focus of this series is signing an existing FIT image: mkimage -F some-existing.fit --signing-key some/key.pem Signing while assembling a FIT is not a tested use case. # Implementation ## Code organization Unlike the RSA path, which mixes host and firmware code in the same, source files, this series keeps a very clear distinction. ecdsa-libcrypto.c is intended to be used for host code and only for host code. There is more opportunity for code reuse this way. ## Signing There is one major difference from the RSA path. The 'key-name-hint' property is ignored in the ECDSA path. There are two reasons: (1) The intent of 'key-name-hint' is not clear (2) Initial implementation is much easier to review There is an intentional side-effect. The RSA path takes 'key-name-hint' to decide which key file to read from disk. In the context of "which fdt node describes my signing key", this makes sense. On the other hand, 'key-name-hint' is also used as the basename of where the key is on the filesystem. This leads to some funny search paths, such as "some/dir/(null).key" So I am using the -K option to mkimage as the _full_ path to the key file. It doesn't have to be named .key, it doesn't have to be named .crt, and it doesn't have to exist in a particular directory (as is the case for the RSA path). I understand and recognize that this discrepancy must be resolved, but resolving it right now would make the initial implementation much harder and longer. # Testing test/py/tests/test_fit_ecdsa.py is implemented withe the goal to check that the signing is done correctly, and that the signature is encoded in the proper raw format. Verification is done with pyCryptodomex, so this test will catch both coding errors and openssl bugs. This is the only scope of testing proposed here. # Things not yet resolved: - is mkimage '-k' supposed to be a directory or file path I'm hoping I can postpone answering this question pending further discussion. Changes since v3: - Don't use 'log_msg_ret()', as it's not available host-side Changes since v1 and v2: - Added lots of function comments - Replaced hardcoded error numbers with more meaningful errno numbers - Changed some error paths to use 'return log_msg_ret' Alexandru Gagniuc (6): lib: Rename rsa-checksum.c to hash-checksum.c lib/rsa: Make fdt_add_bignum() available outside of RSA code lib: Add support for ECDSA image signing doc: signature.txt: Document devicetree format for ECDSA keys test/py: Add pycryptodomex to list of required pakages test/py: ecdsa: Add test for mkimage ECDSA signing common/image-fit-sig.c | 2 +- common/image-sig.c | 13 +- doc/uImage.FIT/signature.txt | 7 +- include/image.h | 5 +- include/u-boot/ecdsa.h | 94 ++++++ include/u-boot/fdt-libcrypto.h | 27 ++ .../{rsa-checksum.h => hash-checksum.h} | 0 lib/Makefile | 1 + lib/crypto/pkcs7_verify.c | 2 +- lib/crypto/x509_public_key.c | 2 +- lib/ecdsa/ecdsa-libcrypto.c | 306 ++++++++++++++++++ lib/fdt-libcrypto.c | 72 +++++ lib/{rsa/rsa-checksum.c => hash-checksum.c} | 3 +- lib/rsa/Makefile | 2 +- lib/rsa/rsa-sign.c | 65 +--- test/py/requirements.txt | 1 + test/py/tests/test_fit_ecdsa.py | 111 +++++++ tools/Makefile | 7 +- 18 files changed, 645 insertions(+), 75 deletions(-) create mode 100644 include/u-boot/ecdsa.h create mode 100644 include/u-boot/fdt-libcrypto.h rename include/u-boot/{rsa-checksum.h => hash-checksum.h} (100%) create mode 100644 lib/ecdsa/ecdsa-libcrypto.c create mode 100644 lib/fdt-libcrypto.c rename lib/{rsa/rsa-checksum.c => hash-checksum.c} (96%) create mode 100644 test/py/tests/test_fit_ecdsa.py -- 2.26.2

5 12

[PATCH v1 7/7] provide "sf protect check" command
by Bernhard Kirchen 01 Feb '21

01 Feb '21

this change exposes checking the protection mechanism of SPI NOR flash chips to the CLI. it expands what was already there to communicate not only the protection state of a particular region, but also whether or not the hardware write protection mechanism of the chip is enabled. the new command works for Micron (and compatible) SPI NOR flash chips as well as the SST26* series of SPI NOR flash chips. the changes were tested on proprietary boards using a M25P16 and a SST26VF016B. Signed-off-by: Bernhard Kirchen <bernhard.kirchen(a)mbconnectline.com> --- cmd/sf.c | 23 +++++++++++++++-- drivers/mtd/spi/spi-nor-core.c | 45 +++++++++++++++++++++++++--------- include/linux/mtd/spi-nor.h | 17 ++++++++++++- include/spi_flash.h | 8 ++++++ 4 files changed, 78 insertions(+), 15 deletions(-) diff --git a/cmd/sf.c b/cmd/sf.c index ecd2918cbc..664442813d 100644 --- a/cmd/sf.c +++ b/cmd/sf.c @@ -355,6 +355,7 @@ static int do_spi_protect(int argc, char *const argv[]) int ret = 0; loff_t start, len; bool prot = false; + struct lock_info info; if (argc != 4) return -1; @@ -369,6 +370,24 @@ static int do_spi_protect(int argc, char *const argv[]) return 1; } + if (strcmp(argv[1], "check") == 0) { + info.ofs = start; + info.len = len; + ret = spi_flash_is_protected(flash, &info); + if (ret != 0) { + printf("ERROR: operation failed (%d)\n", ret); + return 1; + } + + printf("region [0x%06x, 0x%06x] is %sfully write-protected\n", + info.ofs, (info.ofs + info.len - 1), + (info.is_locked ? "" : "NOT ")); + printf("hardware write protection is %sactive\n", + (info.hw_protection ? "" : "NOT ")); + + return 0; + } + if (strcmp(argv[1], "lock") == 0) prot = true; else if (strcmp(argv[1], "unlock") == 0) @@ -612,8 +631,8 @@ U_BOOT_CMD( "sf update addr offset|partition len - erase and write 'len' bytes from memory\n" " at 'addr' to flash at 'offset'\n" " or to start of mtd 'partition'\n" - "sf protect lock|unlock sector len - protect/unprotect 'len' bytes starting\n" - " at address 'sector'\n" + "sf protect lock|unlock|check offs len - (un)protect or check protection of 'len'\n" + " bytes starting at address 'offs'\n" #ifdef CONFIG_CMD_SF_TEST "sf test offset len - run a very basic destructive test\n" " ranging 'len' bytes from 'offset'\n" diff --git a/drivers/mtd/spi/spi-nor-core.c b/drivers/mtd/spi/spi-nor-core.c index 0b48e068be..f77f22684d 100644 --- a/drivers/mtd/spi/spi-nor-core.c +++ b/drivers/mtd/spi/spi-nor-core.c @@ -869,18 +869,25 @@ static int stm_unlock(struct spi_nor *nor, loff_t ofs, uint64_t len) * Check if a region of the flash is (completely) locked. See stm_lock() for * more info. * - * Returns 1 if entire region is locked, 0 if any portion is unlocked, and - * negative on errors. + * Updates struct lock_info in-place to reflect protection state. */ -static int stm_is_locked(struct spi_nor *nor, loff_t ofs, uint64_t len) +static int stm_is_locked(struct spi_nor *nor, struct lock_info *info) { - int status; + int status, ret; status = read_sr(nor); if (status < 0) return status; - return stm_is_locked_sr(nor, ofs, len, status); + info->hw_protection = ((status & SR_SRWD) > 0); + + ret = stm_is_locked_sr(nor, info->ofs, info->len, status); + if (ret < 0) + return ret; + + info->is_locked = (ret > 0); + + return 0; } #endif /* CONFIG_SPI_FLASH_STMICRO */ @@ -1208,18 +1215,32 @@ static int sst26_lock(struct spi_nor *nor, loff_t ofs, uint64_t len) return sst26_lock_ctl(nor, ofs, len, SST26_CTL_LOCK); } -static int sst26_is_locked(struct spi_nor *nor, loff_t ofs, uint64_t len) +static int sst26_is_locked(struct spi_nor *nor, struct lock_info *info) { + int ret; + /* * is_locked function is used for check before reading or erasing flash - * region, so offset and length might be not 64k allighned, so adjust - * them to be 64k allighned as sst26_lock_ctl works only with 64k - * allighned regions. + * region, so offset and length might be not 64k aligned, so adjust + * them to be 64k aligned as sst26_lock_ctl works only with 64k + * aligned regions. */ - ofs -= ofs & (SZ_64K - 1); - len = len & (SZ_64K - 1) ? (len & ~(SZ_64K - 1)) + SZ_64K : len; + info->ofs -= info->ofs & (SZ_64K - 1); + info->len = info->len & (SZ_64K - 1) ? (info->len & ~(SZ_64K - 1)) + SZ_64K : info->len; - return sst26_lock_ctl(nor, ofs, len, SST26_CTL_CHECK); + ret = sst26_lock_ctl(nor, info->ofs, info->len, SST26_CTL_CHECK); + if (ret < 0) + return ret; + + info->is_locked = (ret == 0); + + ret = read_cr(nor); + if (ret < 0) + return ret; + + info->hw_protection = ((ret & (CR_WPEN | CR_QUAD_EN_SPAN)) == CR_WPEN); + + return 0; } static int sst_write_byteprogram(struct spi_nor *nor, loff_t to, size_t len, diff --git a/include/linux/mtd/spi-nor.h b/include/linux/mtd/spi-nor.h index ee5a59cf0a..bfd503b1b2 100644 --- a/include/linux/mtd/spi-nor.h +++ b/include/linux/mtd/spi-nor.h @@ -256,6 +256,21 @@ enum spi_nor_option_flags { */ struct flash_info; +/** + * struct lock_info - structure describing flash protection + * @ofs: start address of region + * @len: length of region + * @is_locked: true if the region is write-protected (locked) + * @hw_protection: true if the write-protection is backed by hardware, e.g., + * the lock can only be removed by setting WP# pin high + */ +struct lock_info { + u32 ofs; + u32 len; + bool is_locked; + bool hw_protection; +}; + /* * TODO: Remove, once all users of spi_flash interface are moved to MTD * @@ -344,7 +359,7 @@ struct spi_nor { int (*flash_lock)(struct spi_nor *nor, loff_t ofs, uint64_t len); int (*flash_unlock)(struct spi_nor *nor, loff_t ofs, uint64_t len); - int (*flash_is_locked)(struct spi_nor *nor, loff_t ofs, uint64_t len); + int (*flash_is_locked)(struct spi_nor *nor, struct lock_info *lock); int (*quad_enable)(struct spi_nor *nor); void *priv; diff --git a/include/spi_flash.h b/include/spi_flash.h index 85cae32cc7..09a4fdad1c 100644 --- a/include/spi_flash.h +++ b/include/spi_flash.h @@ -179,4 +179,12 @@ static inline int spi_flash_protect(struct spi_flash *flash, u32 ofs, u32 len, return flash->flash_unlock(flash, ofs, len); } +static inline int spi_flash_is_protected(struct spi_flash *flash, struct lock_info *info) +{ + if (!flash->flash_is_locked) + return -EOPNOTSUPP; + + return flash->flash_is_locked(flash, info); +} + #endif /* _SPI_FLASH_H_ */ -- 2.29.2

2 1

[PATCH v1 1/7] command sf: help text format
by Bernhard Kirchen 01 Feb '21

01 Feb '21

properly indent the help text and use single quotes consistently to mark variable parameters. Signed-off-by: Bernhard Kirchen <bernhard.kirchen(a)mbconnectline.com> --- cmd/sf.c | 48 ++++++++++++++++++++++-------------------------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/cmd/sf.c b/cmd/sf.c index c0d6a8f8a0..a991ae0d03 100644 --- a/cmd/sf.c +++ b/cmd/sf.c @@ -564,7 +564,7 @@ static int do_spi_flash(struct cmd_tbl *cmdtp, int flag, int argc, /* The remaining commands require a selected device */ if (!flash) { - puts("No SPI flash selected. Please run `sf probe'\n"); + puts("No SPI flash selected. Please run 'sf probe'\n"); return 1; } @@ -590,31 +590,27 @@ usage: return CMD_RET_USAGE; } -#ifdef CONFIG_CMD_SF_TEST -#define SF_TEST_HELP "\nsf test offset len " \ - "- run a very basic destructive test" -#else -#define SF_TEST_HELP -#endif - U_BOOT_CMD( - sf, 5, 1, do_spi_flash, + sf, 5, 1, do_spi_flash, "SPI flash sub-system", - "probe [[bus:]cs] [hz] [mode] - init flash device on given SPI bus\n" - " and chip select\n" - "sf read addr offset|partition len - read `len' bytes starting at\n" - " `offset' or from start of mtd\n" - " `partition'to memory at `addr'\n" - "sf write addr offset|partition len - write `len' bytes from memory\n" - " at `addr' to flash at `offset'\n" - " or to start of mtd `partition'\n" - "sf erase offset|partition [+]len - erase `len' bytes from `offset'\n" - " or from start of mtd `partition'\n" - " `+len' round up `len' to block size\n" - "sf update addr offset|partition len - erase and write `len' bytes from memory\n" - " at `addr' to flash at `offset'\n" - " or to start of mtd `partition'\n" - "sf protect lock/unlock sector len - protect/unprotect 'len' bytes starting\n" - " at address 'sector'\n" - SF_TEST_HELP + "probe [[bus:]cs] [hz] [mode] - init flash device on given SPI bus\n" + " and chip select\n" + "sf read addr offset|partition len - read 'len' bytes starting at\n" + " 'offset' or from start of mtd\n" + " 'partition' to memory at 'addr'\n" + "sf write addr offset|partition len - write 'len' bytes from memory\n" + " at 'addr' to flash at 'offset'\n" + " or to start of mtd 'partition'\n" + "sf erase offset|partition [+]len - erase 'len' bytes from 'offset'\n" + " or from start of mtd 'partition'.\n" + " '+len' round up 'len' to block size\n" + "sf update addr offset|partition len - erase and write 'len' bytes from memory\n" + " at 'addr' to flash at 'offset'\n" + " or to start of mtd 'partition'\n" + "sf protect lock|unlock sector len - protect/unprotect 'len' bytes starting\n" + " at address 'sector'\n" +#ifdef CONFIG_CMD_SF_TEST + "sf test offset len - run a very basic destructive test\n" + " ranging 'len' bytes from 'offset'\n" +#endif ); -- 2.29.2

2 1

[PATCH 1/1] doc: update Kernel documentation build system
by Heinrich Schuchardt 01 Feb '21

01 Feb '21

Update the docomentation build system according to Linux v5.11-rc1. With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3. Signed-off-by: Heinrich Schuchardt <xypron.glpk(a)gmx.de> --- Except for doc/develop/logging.rst I have already sent patches for erroneous pages that did not build with Sphinx 3. --- doc/conf.py | 141 ++++++++-- doc/sphinx/automarkup.py | 290 +++++++++++++++++++ doc/sphinx/cdomain.py | 93 +++++- doc/sphinx/kernel_abi.py | 194 +++++++++++++ doc/sphinx/kernel_feat.py | 169 +++++++++++ doc/sphinx/kerneldoc.py | 15 +- doc/sphinx/kernellog.py | 6 +- doc/sphinx/kfigure.py | 6 +- doc/sphinx/load_config.py | 27 +- doc/sphinx/maintainers_include.py | 197 +++++++++++++ doc/sphinx/parallel-wrapper.sh | 33 +++ doc/sphinx/parse-headers.pl | 6 +- doc/sphinx/requirements.txt | 5 +- scripts/kernel-doc | 450 ++++++++++++++++++++++-------- 14 files changed, 1476 insertions(+), 156 deletions(-) create mode 100644 doc/sphinx/automarkup.py create mode 100644 doc/sphinx/kernel_abi.py create mode 100644 doc/sphinx/kernel_feat.py create mode 100755 doc/sphinx/maintainers_include.py create mode 100644 doc/sphinx/parallel-wrapper.sh diff --git a/doc/conf.py b/doc/conf.py index ee7f201724..1b9f3591d5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -16,6 +16,8 @@ import sys import os import sphinx +from subprocess import check_output + # Get Sphinx version major, minor, patch = sphinx.version_info[:3] @@ -31,39 +33,98 @@ from load_config import loadConfig # If your documentation needs a minimal Sphinx version, state it here. needs_sphinx = '1.3' -latex_engine = 'xelatex' - # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', + 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', + 'maintainers_include', 'sphinx.ext.autosectionlabel', + 'kernel_abi', 'kernel_feat'] # -# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* -# of the docs correctly, but not all. +# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* +# of the docs correctly, but not all. Scream bloody murder but allow +# the process to proceed; hopefully somebody will fix this properly soon. # if major >= 3: + sys.stderr.write('''WARNING: The kernel documentation build process + support for Sphinx v3.0 and above is brand new. Be prepared for + possible issues in the generated output. + ''') if (major > 3) or (minor > 0 or patch >= 2): - sys.stderr.write('''The build process with Sphinx 3+ is broken. -You will have to remove -W in doc/Makefile. -''') # Sphinx c function parser is more pedantic with regards to type # checking. Due to that, having macros at c:function cause problems. - # Those needed to be escaped by using c_id_attributes[] array + # Those needed to be scaped by using c_id_attributes[] array c_id_attributes = [ - - # include/linux/compiler.h + # GCC Compiler types not parsed by Sphinx: + "__restrict__", + + # include/linux/compiler_types.h: + "__iomem", + "__kernel", + "noinstr", + "notrace", + "__percpu", + "__rcu", + "__user", + + # include/linux/compiler_attributes.h: + "__alias", + "__aligned", + "__aligned_largest", + "__always_inline", + "__assume_aligned", + "__cold", + "__attribute_const__", + "__copy", + "__pure", + "__designated_init", + "__visible", + "__printf", + "__scanf", + "__gnu_inline", + "__malloc", + "__mode", + "__no_caller_saved_registers", + "__noclone", + "__nonstring", + "__noreturn", + "__packed", + "__pure", + "__section", + "__always_unused", "__maybe_unused", + "__used", + "__weak", + "noinline", # include/efi.h "EFIAPI", # include/efi_loader.h "__efi_runtime", + + # include/linux/memblock.h: + "__init_memblock", + "__meminit", + + # include/linux/init.h: + "__init", + "__ref", + + # include/linux/linkage.h: + "asmlinkage", ] else: extensions.append('cdomain') + if major == 1 and minor < 7: + sys.stderr.write('WARNING: Sphinx 1.7 or greater will be required as of ' + 'the v2021.04 release\n') + +# Ensure that autosectionlabel will produce unique names +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 2 # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): @@ -86,9 +147,9 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'Das U-Boot' -copyright = 'The U-Boot development community' -author = 'The U-Boot development community' +project = 'The Linux Kernel' +copyright = 'The kernel development community' +author = 'The kernel development community' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -199,7 +260,7 @@ except ImportError: # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '../tools/logos/u-boot_logo.svg' +#html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -229,7 +290,7 @@ html_context = { # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +html_use_smartypants = False # Custom sidebar templates, maps document names to template names. #html_sidebars = {} @@ -279,7 +340,7 @@ html_context = { #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'TheUBootdoc' +htmlhelp_basename = 'TheLinuxKerneldoc' # -- Options for LaTeX output --------------------------------------------- @@ -288,7 +349,7 @@ latex_elements = { 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -'pointsize': '8pt', +'pointsize': '11pt', # Latex figure (float) alignment #'figure_align': 'htbp', @@ -301,13 +362,24 @@ latex_elements = { 'preamble': ''' % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} - \\setsansfont{DejaVu Serif} - \\setromanfont{DejaVu Sans} + \\setsansfont{DejaVu Sans} + \\setromanfont{DejaVu Serif} \\setmonofont{DejaVu Sans Mono} - ''' } +# At least one book (translations) may have Asian characters +# with are only displayed if xeCJK is used + +cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore') +if cjk_cmd.find("Noto Sans CJK SC") >= 0: + print ("enabling CJK for LaTeX builder") + latex_elements['preamble'] += ''' + % This is needed for translations + \\usepackage{xeCJK} + \\setCJKmainfont{Noto Sans CJK SC} + ''' + # Fix reference escape troubles with Sphinx 1.4.x if major == 1 and minor > 3: latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n' @@ -398,10 +470,23 @@ if major == 1 and minor < 6: # author, documentclass [howto, manual, or own class]). # Sorted in alphabetical order latex_documents = [ - ('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual', - 'The U-Boot development community', 'manual'), ] +# Add all other index files from Documentation/ subdirectories +for fn in os.listdir('.'): + doc = os.path.join(fn, "index") + if os.path.exists(doc + ".rst"): + has = False + for l in latex_documents: + if l[0] == doc: + has = True + break + if not has: + latex_documents.append((doc, fn + '.tex', + 'Linux %s Documentation' % fn.capitalize(), + 'The kernel development community', + 'manual')) + # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None @@ -428,7 +513,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'dasuboot', 'The U-Boot Documentation', + (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', [author], 1) ] @@ -442,8 +527,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'DasUBoot', 'The U-Boot Documentation', - author, 'DasUBoot', 'One line description of project.', + (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', + author, 'TheLinuxKernel', 'One line description of project.', 'Miscellaneous'), ] @@ -535,13 +620,13 @@ epub_exclude_files = ['search.html'] # Grouping the document tree into PDF files. List of tuples # (source start file, target name, title, author, options). # -# See the Sphinx chapter of http://ralsina.me/static/manual.pdf +# See the Sphinx chapter of https://ralsina.me/static/manual.pdf # # FIXME: Do not add the index file here; the result will be too big. Adding # multiple PDF files here actually tries to get the cross-referencing right # *between* PDF files. pdf_documents = [ - ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'), + ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), ] # kernel-doc extension configuration for running Sphinx directly (e.g. by Read diff --git a/doc/sphinx/automarkup.py b/doc/sphinx/automarkup.py new file mode 100644 index 0000000000..953b24b6e2 --- /dev/null +++ b/doc/sphinx/automarkup.py @@ -0,0 +1,290 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright 2019 Jonathan Corbet <corbet(a)lwn.net> +# +# Apply kernel-specific tweaks after the initial document processing +# has been done. +# +from docutils import nodes +import sphinx +from sphinx import addnodes +if sphinx.version_info[0] < 2 or \ + sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1: + from sphinx.environment import NoUri +else: + from sphinx.errors import NoUri +import re +from itertools import chain + +# +# Python 2 lacks re.ASCII... +# +try: + ascii_p3 = re.ASCII +except AttributeError: + ascii_p3 = 0 + +# +# Regex nastiness. Of course. +# Try to identify "function()" that's not already marked up some +# other way. Sphinx doesn't like a lot of stuff right after a +# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last +# bit tries to restrict matches to things that won't create trouble. +# +RE_function = re.compile(r'\b(([a-zA-Z_]\w+))', flags=ascii_p3) + +# +# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef +# +RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)', + flags=ascii_p3) + +# +# Sphinx 3 uses a different C role for each one of struct, union, enum and +# typedef +# +RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3) + +# +# Detects a reference to a documentation page of the form Documentation/... with +# an optional extension +# +RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*') + +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') + +# +# Reserved C words that we should skip when cross-referencing +# +Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ] + + +# +# Many places in the docs refer to common system calls. It is +# pointless to try to cross-reference them and, as has been known +# to happen, somebody defining a function by these names can lead +# to the creation of incorrect and confusing cross references. So +# just don't even try with these names. +# +Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', + 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', + 'socket' ] + +c_namespace = '' + +def markup_refs(docname, app, node): + t = node.astext() + done = 0 + repl = [ ] + # + # Associate each regex with the function that will markup its matches + # + markup_func_sphinx2 = {RE_doc: markup_doc_ref, + RE_function: markup_c_ref, + RE_generic_type: markup_c_ref} + + markup_func_sphinx3 = {RE_doc: markup_doc_ref, + RE_function: markup_func_ref_sphinx3, + RE_struct: markup_c_ref, + RE_union: markup_c_ref, + RE_enum: markup_c_ref, + RE_typedef: markup_c_ref} + + if sphinx.version_info[0] >= 3: + markup_func = markup_func_sphinx3 + else: + markup_func = markup_func_sphinx2 + + match_iterators = [regex.finditer(t) for regex in markup_func] + # + # Sort all references by the starting position in text + # + sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start()) + for m in sorted_matches: + # + # Include any text prior to match as a normal text node. + # + if m.start() > done: + repl.append(nodes.Text(t[done:m.start()])) + + # + # Call the function associated with the regex that matched this text and + # append its return to the text + # + repl.append(markup_func[m.re](docname, app, m)) + + done = m.end() + if done < len(t): + repl.append(nodes.Text(t[done:])) + return repl + +# +# In sphinx3 we can cross-reference to C macro and function, each one with its +# own C role, but both match the same regex, so we try both. +# +def markup_func_ref_sphinx3(docname, app, match): + class_str = ['c-func', 'c-macro'] + reftype_str = ['function', 'macro'] + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + base_target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + possible_targets = [base_target] + # Check if this document has a namespace, and if so, try + # cross-referencing inside it first. + if c_namespace: + possible_targets.insert(0, c_namespace + "." + base_target) + + if base_target not in Skipnames: + for target in possible_targets: + if target not in Skipfuncs: + for class_s, reftype_s in zip(class_str, reftype_str): + lit_text = nodes.literal(classes=['xref', 'c', class_s]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_s, + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_s, target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + + return target_text + +def markup_c_ref(docname, app, match): + class_str = {# Sphinx 2 only + RE_function: 'c-func', + RE_generic_type: 'c-type', + # Sphinx 3+ only + RE_struct: 'c-struct', + RE_union: 'c-union', + RE_enum: 'c-enum', + RE_typedef: 'c-type', + } + reftype_str = {# Sphinx 2 only + RE_function: 'function', + RE_generic_type: 'type', + # Sphinx 3+ only + RE_struct: 'struct', + RE_union: 'union', + RE_enum: 'enum', + RE_typedef: 'type', + } + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + base_target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + possible_targets = [base_target] + # Check if this document has a namespace, and if so, try + # cross-referencing inside it first. + if c_namespace: + possible_targets.insert(0, c_namespace + "." + base_target) + + if base_target not in Skipnames: + for target in possible_targets: + if not (match.re == RE_function and target in Skipfuncs): + lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_str[match.re], + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_str[match.re], target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + + return target_text + +# +# Try to replace a documentation reference of the form Documentation/... with a +# cross reference to that page +# +def markup_doc_ref(docname, app, match): + stddom = app.env.domains['std'] + # + # Go through the dance of getting an xref out of the std domain + # + target = match.group(1) + xref = None + pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc', + reftarget = target, modname = None, + classname = None, refexplicit = False) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc', + target, pxref, None) + except NoUri: + xref = None + # + # Return the xref if we got it; otherwise just return the plain text. + # + if xref: + return xref + else: + return nodes.Text(match.group(0)) + +def get_c_namespace(app, docname): + source = app.env.doc2path(docname) + with open(source) as f: + for l in f: + match = RE_namespace.search(l) + if match: + return match.group(1) + return '' + +def auto_markup(app, doctree, name): + global c_namespace + c_namespace = get_c_namespace(app, name) + # + # This loop could eventually be improved on. Someday maybe we + # want a proper tree traversal with a lot of awareness of which + # kinds of nodes to prune. But this works well for now. + # + # The nodes.literal test catches ``literal text``, its purpose is to + # avoid adding cross-references to functions that have been explicitly + # marked with cc:func:. + # + for para in doctree.traverse(nodes.paragraph): + for node in para.traverse(nodes.Text): + if not isinstance(node.parent, nodes.literal): + node.parent.replace(node, markup_refs(name, app, node)) + +def setup(app): + app.connect('doctree-resolved', auto_markup) + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc/sphinx/cdomain.py b/doc/sphinx/cdomain.py index cbac8e608d..014a5229e5 100644 --- a/doc/sphinx/cdomain.py +++ b/doc/sphinx/cdomain.py @@ -40,14 +40,94 @@ from sphinx import addnodes from sphinx.domains.c import c_funcptr_sig_re, c_sig_re from sphinx.domains.c import CObject as Base_CObject from sphinx.domains.c import CDomain as Base_CDomain +from itertools import chain +import re -__version__ = '1.0' +__version__ = '1.1' # Get Sphinx version major, minor, patch = sphinx.version_info[:3] +# Namespace to be prepended to the full name +namespace = None + +# +# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags +# - Store the namespace if ".. c:namespace::" tag is found +# +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') + +def markup_namespace(match): + global namespace + + namespace = match.group(1) + + return "" + +# +# Handle c:macro for function-style declaration +# +RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$') +def markup_macro(match): + return ".. c:function:: " + match.group(1) + ' ' + match.group(2) + +# +# Handle newer c domain tags that are evaluated as .. c:type: for +# backward-compatibility with Sphinx < 3.0 +# +RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$') + +def markup_ctype(match): + return ".. c:type:: " + match.group(2) + +# +# Handle newer c domain tags that are evaluated as :c:type: for +# backward-compatibility with Sphinx < 3.0 +# +RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`') +def markup_ctype_refs(match): + return ":c:type:`" + match.group(2) + '`' + +# +# Simply convert :c:expr: and :c:texpr: into a literal block. +# +RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') +def markup_c_expr(match): + return '\ ``' + match.group(2) + '``\ ' + +# +# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones +# +def c_markups(app, docname, source): + result = "" + markup_func = { + RE_namespace: markup_namespace, + RE_expr: markup_c_expr, + RE_macro: markup_macro, + RE_ctype: markup_ctype, + RE_ctype_refs: markup_ctype_refs, + } + + lines = iter(source[0].splitlines(True)) + for n in lines: + match_iterators = [regex.finditer(n) for regex in markup_func] + matches = sorted(chain(*match_iterators), key=lambda m: m.start()) + for m in matches: + n = n[:m.start()] + markup_func[m.re](m) + n[m.end():] + + result = result + n + + source[0] = result + +# +# Now implements support for the cdomain namespacing logic +# + def setup(app): + # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace:: + app.connect('source-read', c_markups) + if (major == 1 and minor < 8): app.override_domain(CDomain) else: @@ -75,6 +155,8 @@ class CObject(Base_CObject): function-like macro, the name of the macro is returned. Otherwise ``False`` is returned. """ + global namespace + if not self.objtype == 'function': return False @@ -107,11 +189,16 @@ class CObject(Base_CObject): param += nodes.emphasis(argname, argname) paramlist += param + if namespace: + fullname = namespace + "." + fullname + return fullname def handle_signature(self, sig, signode): """Transform a C signature into RST nodes.""" + global namespace + fullname = self.handle_func_like_macro(sig, signode) if not fullname: fullname = super(CObject, self).handle_signature(sig, signode) @@ -122,6 +209,10 @@ class CObject(Base_CObject): else: # FIXME: handle :name: value of other declaration types? pass + else: + if namespace: + fullname = namespace + "." + fullname + return fullname def add_target_and_index(self, name, sig, signode): diff --git a/doc/sphinx/kernel_abi.py b/doc/sphinx/kernel_abi.py new file mode 100644 index 0000000000..f3da859c98 --- /dev/null +++ b/doc/sphinx/kernel_abi.py @@ -0,0 +1,194 @@ +# -*- coding: utf-8; mode: python -*- +# coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 +# +u""" + kernel-abi + ~~~~~~~~~~ + + Implementation of the ``kernel-abi`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :copyright: Copyright (C) 2016-2020 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <mchehab+huawei(a)kernel.org> + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the + scripts/get_abi.pl script to parse the Kernel ABI files. + + Overview of directive's argument and options. + + .. code-block:: rst + + .. kernel-abi:: <ABI directory location> + :debug: + + The argument ``<ABI directory location>`` is required. It contains the + location of the ABI files to be parsed. + + ``debug`` + Inserts a code-block with the *raw* reST. Sometimes it is helpful to see + what reST is generated. + +""" + +import codecs +import os +import subprocess +import sys +import re +import kernellog + +from os import path + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from docutils.utils.error_reporting import ErrorString + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +def setup(app): + + app.add_directive("kernel-abi", KernelCmd) + return dict( + version = __version__ + , parallel_read_safe = True + , parallel_write_safe = True + ) + +class KernelCmd(Directive): + + u"""KernelABI (``kernel-abi``) directive""" + + required_arguments = 1 + optional_arguments = 2 + has_content = False + final_argument_whitespace = True + + option_spec = { + "debug" : directives.flag, + "rst" : directives.unchanged + } + + def run(self): + + doc = self.state.document + if not doc.settings.file_insertion_enabled: + raise self.warning("docutils: file insertion disabled") + + env = doc.settings.env + cwd = path.dirname(doc.current_source) + cmd = "get_abi.pl rest --enable-lineno --dir " + cmd += self.arguments[0] + + if 'rst' in self.options: + cmd += " --rst-source" + + srctree = path.abspath(os.environ["srctree"]) + + fname = cmd + + # extend PATH with $(srctree)/scripts + path_env = os.pathsep.join([ + srctree + os.sep + "scripts", + os.environ["PATH"] + ]) + shell_env = os.environ.copy() + shell_env["PATH"] = path_env + shell_env["srctree"] = srctree + + lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + nodeList = self.nestedParse(lines, self.arguments[0]) + return nodeList + + def runCmd(self, cmd, **kwargs): + u"""Run command ``cmd`` and return it's stdout as unicode.""" + + try: + proc = subprocess.Popen( + cmd + , stdout = subprocess.PIPE + , stderr = subprocess.PIPE + , **kwargs + ) + out, err = proc.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if proc.returncode != 0: + raise self.severe( + u"command '%s' failed with return code %d" + % (cmd, proc.returncode) + ) + except OSError as exc: + raise self.severe(u"problems with '%s' directive: %s." + % (self.name, ErrorString(exc))) + return out + + def nestedParse(self, lines, fname): + content = ViewList() + node = nodes.section() + + if "debug" in self.options: + code_block = "\n\n.. code-block:: rst\n :linenos:\n" + for l in lines.split("\n"): + code_block += "\n " + l + lines = code_block + "\n\n" + + line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$") + ln = 0 + n = 0 + f = fname + + for line in lines.split("\n"): + n = n + 1 + match = line_regex.search(line) + if match: + new_f = match.group(1) + + # Sphinx parser is lazy: it stops parsing contents in the + # middle, if it is too big. So, handle it per input file + if new_f != f and content: + self.do_parse(content, node) + content = ViewList() + + f = new_f + + # sphinx counts lines from 0 + ln = int(match.group(2)) - 1 + else: + content.append(line, f, ln) + + kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n)) + + if content: + self.do_parse(content, node) + + return node.children + + def do_parse(self, content, node): + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf diff --git a/doc/sphinx/kernel_feat.py b/doc/sphinx/kernel_feat.py new file mode 100644 index 0000000000..2fee04f1de --- /dev/null +++ b/doc/sphinx/kernel_feat.py @@ -0,0 +1,169 @@ +# coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 +# +u""" + kernel-feat + ~~~~~~~~~~~ + + Implementation of the ``kernel-feat`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <mchehab+samsung(a)kernel.org> + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the + scripts/get_feat.pl script to parse the Kernel ABI files. + + Overview of directive's argument and options. + + .. code-block:: rst + + .. kernel-feat:: <ABI directory location> + :debug: + + The argument ``<ABI directory location>`` is required. It contains the + location of the ABI files to be parsed. + + ``debug`` + Inserts a code-block with the *raw* reST. Sometimes it is helpful to see + what reST is generated. + +""" + +import codecs +import os +import subprocess +import sys + +from os import path + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from docutils.utils.error_reporting import ErrorString + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +def setup(app): + + app.add_directive("kernel-feat", KernelFeat) + return dict( + version = __version__ + , parallel_read_safe = True + , parallel_write_safe = True + ) + +class KernelFeat(Directive): + + u"""KernelFeat (``kernel-feat``) directive""" + + required_arguments = 1 + optional_arguments = 2 + has_content = False + final_argument_whitespace = True + + option_spec = { + "debug" : directives.flag + } + + def warn(self, message, **replace): + replace["fname"] = self.state.document.current_source + replace["line_no"] = replace.get("line_no", self.lineno) + message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace + self.state.document.settings.env.app.warn(message, prefix="") + + def run(self): + + doc = self.state.document + if not doc.settings.file_insertion_enabled: + raise self.warning("docutils: file insertion disabled") + + env = doc.settings.env + cwd = path.dirname(doc.current_source) + cmd = "get_feat.pl rest --dir " + cmd += self.arguments[0] + + if len(self.arguments) > 1: + cmd += " --arch " + self.arguments[1] + + srctree = path.abspath(os.environ["srctree"]) + + fname = cmd + + # extend PATH with $(srctree)/scripts + path_env = os.pathsep.join([ + srctree + os.sep + "scripts", + os.environ["PATH"] + ]) + shell_env = os.environ.copy() + shell_env["PATH"] = path_env + shell_env["srctree"] = srctree + + lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + nodeList = self.nestedParse(lines, fname) + return nodeList + + def runCmd(self, cmd, **kwargs): + u"""Run command ``cmd`` and return it's stdout as unicode.""" + + try: + proc = subprocess.Popen( + cmd + , stdout = subprocess.PIPE + , stderr = subprocess.PIPE + , **kwargs + ) + out, err = proc.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if proc.returncode != 0: + raise self.severe( + u"command '%s' failed with return code %d" + % (cmd, proc.returncode) + ) + except OSError as exc: + raise self.severe(u"problems with '%s' directive: %s." + % (self.name, ErrorString(exc))) + return out + + def nestedParse(self, lines, fname): + content = ViewList() + node = nodes.section() + + if "debug" in self.options: + code_block = "\n\n.. code-block:: rst\n :linenos:\n" + for l in lines.split("\n"): + code_block += "\n " + l + lines = code_block + "\n\n" + + for c, l in enumerate(lines.split("\n")): + content.append(l, fname, c) + + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children diff --git a/doc/sphinx/kerneldoc.py b/doc/sphinx/kerneldoc.py index 4bcbd6ae01..e9857ab904 100644 --- a/doc/sphinx/kerneldoc.py +++ b/doc/sphinx/kerneldoc.py @@ -62,6 +62,7 @@ class KernelDocDirective(Directive): 'export': directives.unchanged, 'internal': directives.unchanged, 'identifiers': directives.unchanged, + 'no-identifiers': directives.unchanged, 'functions': directives.unchanged, } has_content = False @@ -70,6 +71,11 @@ class KernelDocDirective(Directive): env = self.state.document.settings.env cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + # Pass the version string to kernel-doc, as it needs to use a different + # dialect, depending what the C domain supports for each specific + # Sphinx versions + cmd += ['-sphinx-version', sphinx.__version__] + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = [] @@ -99,6 +105,12 @@ class KernelDocDirective(Directive): else: cmd += ['-no-doc-sections'] + if 'no-identifiers' in self.options: + no_identifiers = self.options.get('no-identifiers').split() + if no_identifiers: + for i in no_identifiers: + cmd += ['-nosymbol', i] + for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): env.note_dependency(os.path.abspath(f)) @@ -136,7 +148,8 @@ class KernelDocDirective(Directive): lineoffset = int(match.group(1)) - 1 # we must eat our comments since the upset the markup else: - result.append(line, filename, lineoffset) + doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno) + result.append(line, doc + ": " + filename, lineoffset) lineoffset += 1 node = nodes.section() diff --git a/doc/sphinx/kernellog.py b/doc/sphinx/kernellog.py index af924f51a7..8ac7d274f5 100644 --- a/doc/sphinx/kernellog.py +++ b/doc/sphinx/kernellog.py @@ -25,4 +25,8 @@ def verbose(app, message): else: app.verbose(message) - +def info(app, message): + if UseLogging: + logger.info(message) + else: + app.info(message) diff --git a/doc/sphinx/kfigure.py b/doc/sphinx/kfigure.py index fbfe6693bb..788704886e 100644 --- a/doc/sphinx/kfigure.py +++ b/doc/sphinx/kfigure.py @@ -29,7 +29,7 @@ u""" Used tools: - * ``dot(1)``: Graphviz (http://www.graphviz.org). If Graphviz is not + * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not available, the DOT language is inserted as literal-block. * SVG to PDF: To generate PDF, you need at least one of this tools: @@ -41,7 +41,7 @@ u""" * generate PDF from SVG / used by PDF (LaTeX) builder * generate SVG (html-builder) and PDF (latex-builder) from DOT files. - DOT: see http://www.graphviz.org/content/dot-language + DOT: see https://www.graphviz.org/content/dot-language """ @@ -182,7 +182,7 @@ def setupTools(app): kernellog.verbose(app, "use dot(1) from: " + dot_cmd) else: kernellog.warn(app, "dot(1) not found, for better output quality install " - "graphviz from http://www.graphviz.org") + "graphviz from https://www.graphviz.org") if convert_cmd: kernellog.verbose(app, "use convert(1) from: " + convert_cmd) else: diff --git a/doc/sphinx/load_config.py b/doc/sphinx/load_config.py index 301a21aa4f..eeb394b39e 100644 --- a/doc/sphinx/load_config.py +++ b/doc/sphinx/load_config.py @@ -21,6 +21,29 @@ def loadConfig(namespace): and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): config_file = os.path.abspath(config_file) + # Let's avoid one conf.py file just due to latex_documents + start = config_file.find('Documentation/') + if start >= 0: + start = config_file.find('/', start + 1) + + end = config_file.rfind('/') + if start >= 0 and end > 0: + dir = config_file[start + 1:end] + + print("source directory: %s" % dir) + new_latex_docs = [] + latex_documents = namespace['latex_documents'] + + for l in latex_documents: + if l[0].find(dir + '/') == 0: + has = True + fn = l[0][len(dir) + 1:] + new_latex_docs.append((fn, l[1], l[2], l[3], l[4])) + break + + namespace['latex_documents'] = new_latex_docs + + # If there is an extra conf.py file, load it if os.path.isfile(config_file): sys.stdout.write("load additional sphinx-config: %s\n" % config_file) config = namespace.copy() @@ -29,4 +52,6 @@ def loadConfig(namespace): del config['__file__'] namespace.update(config) else: - sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file) + config = namespace.copy() + config['tags'].add("subproject") + namespace.update(config) diff --git a/doc/sphinx/maintainers_include.py b/doc/sphinx/maintainers_include.py new file mode 100755 index 0000000000..dc8fed48d3 --- /dev/null +++ b/doc/sphinx/maintainers_include.py @@ -0,0 +1,197 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +u""" + maintainers-include + ~~~~~~~~~~~~~~~~~~~ + + Implementation of the ``maintainers-include`` reST-directive. + + :copyright: Copyright (C) 2019 Kees Cook <keescook(a)chromium.org> + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``maintainers-include`` reST-directive performs extensive parsing + specific to the Linux kernel's standard "MAINTAINERS" file, in an + effort to avoid needing to heavily mark up the original plain text. +""" + +import sys +import re +import os.path + +from docutils import statemachine +from docutils.utils.error_reporting import ErrorString +from docutils.parsers.rst import Directive +from docutils.parsers.rst.directives.misc import Include + +__version__ = '1.0' + +def setup(app): + app.add_directive("maintainers-include", MaintainersInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class MaintainersInclude(Include): + u"""MaintainersInclude (``maintainers-include``) directive""" + required_arguments = 0 + + def parse_maintainers(self, path): + """Parse all the MAINTAINERS lines into ReST for human-readability""" + + result = list() + result.append(".. _maintainers:") + result.append("") + + # Poor man's state machine. + descriptions = False + maintainers = False + subsystems = False + + # Field letter to field name mapping. + field_letter = None + fields = dict() + + prev = None + field_prev = "" + field_content = "" + + for line in open(path): + if sys.version_info.major == 2: + line = unicode(line, 'utf-8') + # Have we reached the end of the preformatted Descriptions text? + if descriptions and line.startswith('Maintainers'): + descriptions = False + # Ensure a blank line following the last "|"-prefixed line. + result.append("") + + # Start subsystem processing? This is to skip processing the text + # between the Maintainers heading and the first subsystem name. + if maintainers and not subsystems: + if re.search('^[A-Z0-9]', line): + subsystems = True + + # Drop needless input whitespace. + line = line.rstrip() + + # Linkify all non-wildcard refs to ReST files in Documentation/. + pat = '(Documentation/([^\s\?\*]*)\.rst)' + m = re.search(pat, line) + if m: + # maintainers.rst is in a subdirectory, so include "../". + line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) + + # Check state machine for output rendering behavior. + output = None + if descriptions: + # Escape the escapes in preformatted text. + output = "| %s" % (line.replace("\\", "\\\\")) + # Look for and record field letter to field name mappings: + # R: Designated *reviewer*: FullName <address@domain> + m = re.search("\s(\S):\s", line) + if m: + field_letter = m.group(1) + if field_letter and not field_letter in fields: + m = re.search("\*([^\*]+)\*", line) + if m: + fields[field_letter] = m.group(1) + elif subsystems: + # Skip empty lines: subsystem parser adds them as needed. + if len(line) == 0: + continue + # Subsystem fields are batched into "field_content" + if line[1] != ':': + # Render a subsystem entry as: + # SUBSYSTEM NAME + # ~~~~~~~~~~~~~~ + + # Flush pending field content. + output = field_content + "\n\n" + field_content = "" + + # Collapse whitespace in subsystem name. + heading = re.sub("\s+", " ", line) + output = output + "%s\n%s" % (heading, "~" * len(heading)) + field_prev = "" + else: + # Render a subsystem field as: + # :Field: entry + # entry... + field, details = line.split(':', 1) + details = details.strip() + + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if not ':doc:' in details: + details = '``%s``' % (details) + + # Comma separate email field continuations. + if field == field_prev and field_prev in ['M', 'R', 'L']: + field_content = field_content + "," + + # Do not repeat field names, so that field entries + # will be collapsed together. + if field != field_prev: + output = field_content + "\n" + field_content = ":%s:" % (fields.get(field, field)) + field_content = field_content + "\n\t%s" % (details) + field_prev = field + else: + output = line + + # Re-split on any added newlines in any above parsing. + if output != None: + for separated in output.split('\n'): + result.append(separated) + + # Update the state machine when we find heading separators. + if line.startswith('----------'): + if prev.startswith('Descriptions'): + descriptions = True + if prev.startswith('Maintainers'): + maintainers = True + + # Retain previous line for state machine transitions. + prev = line + + # Flush pending field contents. + if field_content != "": + for separated in field_content.split('\n'): + result.append(separated) + + output = "\n".join(result) + # For debugging the pre-rendered results... + #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) + + self.state_machine.insert_input( + statemachine.string2lines(output), path) + + def run(self): + """Include the MAINTAINERS file as part of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + # Walk up source path directories to find Documentation/../ + path = self.state_machine.document.attributes['source'] + path = os.path.realpath(path) + tail = path + while tail != "Documentation" and tail != "": + (path, tail) = os.path.split(path) + + # Append "MAINTAINERS" + path = os.path.join(path, "MAINTAINERS") + + try: + self.state.document.settings.record_dependencies.add(path) + lines = self.parse_maintainers(path) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] diff --git a/doc/sphinx/parallel-wrapper.sh b/doc/sphinx/parallel-wrapper.sh new file mode 100644 index 0000000000..e54c44ce11 --- /dev/null +++ b/doc/sphinx/parallel-wrapper.sh @@ -0,0 +1,33 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0+ +# +# Figure out if we should follow a specific parallelism from the make +# environment (as exported by scripts/jobserver-exec), or fall back to +# the "auto" parallelism when "-jN" is not specified at the top-level +# "make" invocation. + +sphinx="$1" +shift || true + +parallel="$PARALLELISM" +if [ -z "$parallel" ] ; then + # If no parallelism is specified at the top-level make, then + # fall back to the expected "-jauto" mode that the "htmldocs" + # target has had. + auto=$(perl -e 'open IN,"'"$sphinx"' --version 2>&1 |"; + while (<IN>) { + if (m/([\d\.]+)/) { + print "auto" if ($1 >= "1.7") + } + } + close IN') + if [ -n "$auto" ] ; then + parallel="$auto" + fi +fi +# Only if some parallelism has been determined do we add the -jN option. +if [ -n "$parallel" ] ; then + parallel="-j$parallel" +fi + +exec "$sphinx" $parallel "$@" diff --git a/doc/sphinx/parse-headers.pl b/doc/sphinx/parse-headers.pl index c518050ffc..b063f2f1cf 100755 --- a/doc/sphinx/parse-headers.pl +++ b/doc/sphinx/parse-headers.pl @@ -1,4 +1,4 @@ -#!/usr/bin/perl +#!/usr/bin/env perl use strict; use Text::Tabs; use Getopt::Long; @@ -110,7 +110,7 @@ while (<IN>) { ) { my $s = $1; - $structs{$s} = "struct :c:type:`$s`\\ "; + $structs{$s} = "struct $s\\ "; next; } } @@ -393,7 +393,7 @@ Report bugs to Mauro Carvalho Chehab <mchehab(a)kernel.org> Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung(a)kernel.org>. -License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. +License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 742be3e126..5030d346d2 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -1,3 +1,4 @@ -docutils==0.12 -Sphinx==1.4.9 +docutils +Sphinx==2.4.4 sphinx_rtd_theme +six diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 516cf1db32..6dda8cb51f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -56,6 +56,13 @@ Output format selection (mutually exclusive): -rst Output reStructuredText format. -none Do not output documentation, only warnings. +Output format selection modifier (affects only ReST output): + + -sphinx-version Use the ReST C domain dialect compatible with an + specific Sphinx Version. + If not specified, kernel-doc will auto-detect using + the sphinx-build version found on PATH. + Output selection (mutually exclusive): -export Only output documentation for symbols that have been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() @@ -66,9 +73,8 @@ Output selection (mutually exclusive): -function NAME Only output documentation for the given function(s) or DOC: section title(s). All other functions and DOC: sections are ignored. May be specified multiple times. - -nofunction NAME Do NOT output documentation for the given function(s); - only output documentation for the other functions and - DOC: sections. May be specified multiple times. + -nosymbol NAME Exclude the specified symbols from the output + documentation. May be specified multiple times. Output selection modifiers: -no-doc-sections Do not output DOC: sections. @@ -81,6 +87,7 @@ Output selection modifiers: Other parameters: -v Verbose output, more warnings and other information. -h Print this help. + -Werror Treat warnings as errors. EOF print $message; @@ -213,7 +220,9 @@ my $type_constant = '\b``([^\`]+)``\b'; my $type_constant2 = '\%([-_\w]+)'; my $type_func = '(\w+)'; my $type_param = '$a)(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; +my $type_param_ref = '([\!]?)\(a)(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\($'; # Special RST handling for func ptr params +my $type_fp_param2 = '\@(\w+->\S+)'; # Special RST handling for structs with func ptr params my $type_env = '(\$\w+)'; my $type_enum = '\&(enum\s*([_\w]+))'; my $type_struct = '\&(struct\s*([_\w]+))'; @@ -236,6 +245,7 @@ my @highlights_man = ( [$type_typedef, "\\\\fI\$1\\\\fP"], [$type_union, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"], + [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], [$type_fallback, "\\\\fI\$1\\\\fP"] ); @@ -249,14 +259,15 @@ my @highlights_rst = ( [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\$\\\$ <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\$\\\$**"], - [$type_func, "\\:c\\:func\\:`\$1()`"], + [$type_fp_param2, "**\$1\\\$\\\$**"], + [$type_func, "\$1()"], [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], # in rst this can refer to any type [$type_fallback, "\\:c\\:type\\:`\$1`"], - [$type_param, "**\$1**"] + [$type_param_ref, "**\$1\$2**"] ); my $blankline_rst = "\n"; @@ -266,9 +277,12 @@ if ($#ARGV == -1) { } my $kernelversion; +my ($sphinx_major, $sphinx_minor, $sphinx_patch); + my $dohighlight = ""; my $verbose = 0; +my $Werror = 0; my $output_mode = "rst"; my $output_preformatted = 0; my $no_doc_sections = 0; @@ -280,12 +294,11 @@ my $modulename = "Kernel API"; use constant { OUTPUT_ALL => 0, # output all symbols and doc sections OUTPUT_INCLUDE => 1, # output only specified symbols - OUTPUT_EXCLUDE => 2, # output everything except specified symbols - OUTPUT_EXPORTED => 3, # output exported symbols - OUTPUT_INTERNAL => 4, # output non-exported symbols + OUTPUT_EXPORTED => 2, # output exported symbols + OUTPUT_INTERNAL => 3, # output non-exported symbols }; my $output_selection = OUTPUT_ALL; -my $show_not_found = 0; +my $show_not_found = 0; # No longer used my @export_file_list; @@ -307,6 +320,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', # CAVEAT EMPTOR! Some of the others I localised may not want to be, which # could cause "use of undefined value" or other bugs. my ($function, %function_table, %parametertypes, $declaration_purpose); +my %nosymbol_table = (); my $declaration_start_line; my ($type, $declaration_name, $return_type); my ($newsection, $newcontents, $prototype, $brcount, %source_map); @@ -315,9 +329,21 @@ if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}"; } +if (defined($ENV{'KDOC_WERROR'})) { + $Werror = "$ENV{'KDOC_WERROR'}"; +} + +if (defined($ENV{'KCFLAGS'})) { + my $kcflags = "$ENV{'KCFLAGS'}"; + + if ($kcflags =~ /Werror/) { + $Werror = 1; + } +} + # Generated docbook code is inserted in a template at a point where # docbook v3.1 requires a non-zero sequence of RefEntry's; see: -# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html +# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.ht… # We keep track of number of generated entries and generate a dummy # if needs be to ensure the expanded template can be postprocessed # into html. @@ -327,13 +353,14 @@ my $lineprefix=""; # Parser states use constant { - STATE_NORMAL => 0, # normal code - STATE_NAME => 1, # looking for function name - STATE_BODY_MAYBE => 2, # body - or maybe more description - STATE_BODY => 3, # the body of the comment - STATE_PROTO => 4, # scanning prototype - STATE_DOCBLOCK => 5, # documentation block - STATE_INLINE => 6, # gathering documentation outside main block + STATE_NORMAL => 0, # normal code + STATE_NAME => 1, # looking for function name + STATE_BODY_MAYBE => 2, # body - or maybe more description + STATE_BODY => 3, # the body of the comment + STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line + STATE_PROTO => 5, # scanning prototype + STATE_DOCBLOCK => 6, # documentation block + STATE_INLINE => 7, # gathering doc outside main block }; my $state; my $in_doc_sect; @@ -413,10 +440,9 @@ while ($ARGV[0] =~ m/^--?(.*)/) { $output_selection = OUTPUT_INCLUDE; $function = shift @ARGV; $function_table{$function} = 1; - } elsif ($cmd eq "nofunction") { # output all except specific functions - $output_selection = OUTPUT_EXCLUDE; - $function = shift @ARGV; - $function_table{$function} = 1; + } elsif ($cmd eq "nosymbol") { # Exclude specific symbols + my $symbol = shift @ARGV; + $nosymbol_table{$symbol} = 1; } elsif ($cmd eq "export") { # only exported symbols $output_selection = OUTPUT_EXPORTED; %function_table = (); @@ -428,6 +454,8 @@ while ($ARGV[0] =~ m/^--?(.*)/) { push(@export_file_list, $file); } elsif ($cmd eq "v") { $verbose = 1; + } elsif ($cmd eq "Werror") { + $Werror = 1; } elsif (($cmd eq "h") || ($cmd eq "help")) { usage(); } elsif ($cmd eq 'no-doc-sections') { @@ -435,7 +463,24 @@ while ($ARGV[0] =~ m/^--?(.*)/) { } elsif ($cmd eq 'enable-lineno') { $enable_lineno = 1; } elsif ($cmd eq 'show-not-found') { - $show_not_found = 1; + $show_not_found = 1; # A no-op but don't fail + } elsif ($cmd eq "sphinx-version") { + my $ver_string = shift @ARGV; + if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) { + $sphinx_major = $1; + if (defined($2)) { + $sphinx_minor = substr($2,1); + } else { + $sphinx_minor = 0; + } + if (defined($3)) { + $sphinx_patch = substr($3,1) + } else { + $sphinx_patch = 0; + } + } else { + die "Sphinx version should either major.minor or major.minor.patch format\n"; + } } else { # Unknown argument usage(); @@ -444,6 +489,51 @@ while ($ARGV[0] =~ m/^--?(.*)/) { # continue execution near EOF; +# The C domain dialect changed on Sphinx 3. So, we need to check the +# version in order to produce the right tags. +sub findprog($) +{ + foreach(split(/:/, $ENV{PATH})) { + return "$_/$_[0]" if(-x "$_/$_[0]"); + } +} + +sub get_sphinx_version() +{ + my $ver; + + my $cmd = "sphinx-build"; + if (!findprog($cmd)) { + my $cmd = "sphinx-build3"; + if (!findprog($cmd)) { + $sphinx_major = 1; + $sphinx_minor = 2; + $sphinx_patch = 0; + printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n", + $sphinx_major, $sphinx_minor, $sphinx_patch; + return; + } + } + + open IN, "$cmd --version 2>&1 |"; + while (<IN>) { + if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) { + $sphinx_major = $1; + $sphinx_minor = $2; + $sphinx_patch = $3; + last; + } + # Sphinx 1.2.x uses a different format + if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) { + $sphinx_major = $1; + $sphinx_minor = $2; + $sphinx_patch = $3; + last; + } + } + close IN; +} + # get kernel version from env sub get_kernel_version() { my $version = 'unknown kernel version'; @@ -510,11 +600,11 @@ sub dump_doc_section { return; } + return if (defined($nosymbol_table{$name})); + if (($output_selection == OUTPUT_ALL) || - ($output_selection == OUTPUT_INCLUDE && - defined($function_table{$name})) || - ($output_selection == OUTPUT_EXCLUDE && - !defined($function_table{$name}))) + (($output_selection == OUTPUT_INCLUDE) && + defined($function_table{$name}))) { dump_section($file, $name, $contents); output_blockhead({'sectionlist' => \@sectionlist, @@ -597,10 +687,10 @@ sub output_function_man(%) { $type = $args{'parametertypes'}{$parameter}; if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) { # pointer-to-function - print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n"; + print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n"; } else { $type =~ s/([^\*])$/$1 /; - print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n"; + print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n"; } $count++; $parenth = ""; @@ -740,6 +830,8 @@ sub output_blockhead_rst(%) { my ($parameter, $section); foreach $section (@{$args{'sectionlist'}}) { + next if (defined($nosymbol_table{$section})); + if ($output_selection != OUTPUT_INCLUDE) { print "**$section**\n\n"; } @@ -825,16 +917,37 @@ sub output_function_rst(%) { my ($parameter, $section); my $oldprefix = $lineprefix; my $start = ""; - - if ($args{'typedef'}) { - print ".. c:type:: ". $args{'function'} . "\n\n"; - print_lineno($declaration_start_line); - print " **Typedef**: "; - $lineprefix = ""; - output_highlight_rst($args{'purpose'}); - $start = "\n\n**Syntax**\n\n ``"; + my $is_macro = 0; + + if ($sphinx_major < 3) { + if ($args{'typedef'}) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; + $is_macro = 1; + } else { + print ".. c:function:: "; + } } else { - print ".. c:function:: "; + if ($args{'typedef'} || $args{'functiontype'} eq "") { + $is_macro = 1; + print ".. c:macro:: ". $args{'function'} . "\n\n"; + } else { + print ".. c:function:: "; + } + + if ($args{'typedef'}) { + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; + } else { + print "``" if ($is_macro); + } } if ($args{'functiontype'} ne "") { $start .= $args{'functiontype'} . " " . $args{'function'} . " ("; @@ -853,15 +966,17 @@ sub output_function_rst(%) { if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) { # pointer-to-function - print $1 . $parameter . ") (" . $2; + print $1 . $parameter . ") (" . $2 . ")"; } else { - print $type . " " . $parameter; + print $type; } } - if ($args{'typedef'}) { - print ");``\n\n"; + if ($is_macro) { + print ")``\n\n"; } else { print ")\n\n"; + } + if (!$args{'typedef'}) { print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); @@ -876,7 +991,7 @@ sub output_function_rst(%) { $type = $args{'parametertypes'}{$parameter}; if ($type ne "") { - print "``$type $parameter``\n"; + print "``$type``\n"; } else { print "``$parameter``\n"; } @@ -917,9 +1032,14 @@ sub output_enum_rst(%) { my ($parameter); my $oldprefix = $lineprefix; my $count; - my $name = "enum " . $args{'enum'}; - print "\n\n.. c:type:: " . $name . "\n\n"; + if ($sphinx_major < 3) { + my $name = "enum " . $args{'enum'}; + print "\n\n.. c:type:: " . $name . "\n\n"; + } else { + my $name = $args{'enum'}; + print "\n\n.. c:enum:: " . $name . "\n\n"; + } print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); @@ -945,8 +1065,13 @@ sub output_typedef_rst(%) { my %args = %{$_[0]}; my ($parameter); my $oldprefix = $lineprefix; - my $name = "typedef " . $args{'typedef'}; + my $name; + if ($sphinx_major < 3) { + $name = "typedef " . $args{'typedef'}; + } else { + $name = $args{'typedef'}; + } print "\n\n.. c:type:: " . $name . "\n\n"; print_lineno($declaration_start_line); $lineprefix = " "; @@ -961,9 +1086,18 @@ sub output_struct_rst(%) { my %args = %{$_[0]}; my ($parameter); my $oldprefix = $lineprefix; - my $name = $args{'type'} . " " . $args{'struct'}; - print "\n\n.. c:type:: " . $name . "\n\n"; + if ($sphinx_major < 3) { + my $name = $args{'type'} . " " . $args{'struct'}; + print "\n\n.. c:type:: " . $name . "\n\n"; + } else { + my $name = $args{'struct'}; + if ($args{'type'} eq 'union') { + print "\n\n.. c:union:: " . $name . "\n\n"; + } else { + print "\n\n.. c:struct:: " . $name . "\n\n"; + } + } print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); @@ -1022,12 +1156,14 @@ sub output_declaration { my $name = shift; my $functype = shift; my $func = "output_${functype}_$output_mode"; + + return if (defined($nosymbol_table{$name})); + if (($output_selection == OUTPUT_ALL) || (($output_selection == OUTPUT_INCLUDE || $output_selection == OUTPUT_EXPORTED) && defined($function_table{$name})) || - (($output_selection == OUTPUT_EXCLUDE || - $output_selection == OUTPUT_INTERNAL) && + ($output_selection == OUTPUT_INTERNAL && !($functype eq "function" && defined($function_table{$name})))) { &$func(@_); @@ -1062,7 +1198,7 @@ sub dump_struct($$) { my $x = shift; my $file = shift; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*$\([a-z0-9,_\s\($]*\)\)))*/) { + if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*$\([a-z0-9,_\s\($]*\)\)))*/) { my $decl_type = $1; $declaration_name = $2; my $members = $3; @@ -1073,11 +1209,15 @@ sub dump_struct($$) { # strip comments: $members =~ s/\/\*.*?\*\///gos; # strip attributes - $members =~ s/\s*__attribute__\s*$\([a-z0-9,_\*\s\($]*\)\)//gi; - $members =~ s/\s*__aligned\s*$[^;]*$//gos; - $members =~ s/\s*__packed\s*//gos; - $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; + $members =~ s/\s*__attribute__\s*$\([a-z0-9,_\*\s\($]*\)\)/ /gi; + $members =~ s/\s*__aligned\s*$[^;]*$/ /gos; + $members =~ s/\s*__packed\s*/ /gos; + $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; + $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; + $members =~ s/\s*____cacheline_aligned/ /gos; + # replace DECLARE_BITMAP + $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*$([^$]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos; $members =~ s/DECLARE_BITMAP\s*$([^,)]+),\s*([^,)]+)$/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; # replace DECLARE_HASHTABLE $members =~ s/DECLARE_HASHTABLE\s*$([^,)]+),\s*([^,)]+)$/unsigned long $1\[1 << (($2) - 1)\]/gos; @@ -1204,6 +1344,8 @@ sub show_warnings($$) { my $functype = shift; my $name = shift; + return 0 if (defined($nosymbol_table{$name})); + return 1 if ($output_selection == OUTPUT_ALL); if ($output_selection == OUTPUT_EXPORTED) { @@ -1227,27 +1369,28 @@ sub show_warnings($$) { return 0; } } - if ($output_selection == OUTPUT_EXCLUDE) { - if (!defined($function_table{$name})) { - return 1; - } else { - return 0; - } - } die("Please add the new output type at show_warnings()"); } sub dump_enum($$) { my $x = shift; my $file = shift; + my $members; + $x =~ s@/\*.*?\*/@@gos; # strip comments. # strip #define macros inside enums $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; - if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) { + if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) { + $declaration_name = $2; + $members = $1; + } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) { $declaration_name = $1; - my $members = $2; + $members = $2; + } + + if ($members) { my %_members; $members =~ s/\s+$//; @@ -1282,27 +1425,31 @@ sub dump_enum($$) { 'sections' => \%sections, 'purpose' => $declaration_purpose }); - } - else { + } else { print STDERR "${file}:$.: error: Cannot parse enum!\n"; ++$errors; } } +my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x; +my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; +my $typedef_args = qr { \s*$(.*)$; }x; + +my $typedef1 = qr { typedef$typedef_type$$typedef_ident$$typedef_args }x; +my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x; + sub dump_typedef($$) { my $x = shift; my $file = shift; $x =~ s@/\*.*?\*/@@gos; # strip comments. - # Parse function prototypes - if ($x =~ /typedef\s+(\w+)\s*$\*\s*(\w\S+)\s*$\s*$(.*)$;/ || - $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*$(.*)$;/) { - - # Function typedefs + # Parse function typedef prototypes + if ($x =~ $typedef1 || $x =~ $typedef2) { $return_type = $1; $declaration_name = $2; my $args = $3; + $return_type =~ s/^\s+//; create_parameterlist($args, ',', $file, $declaration_name); @@ -1369,25 +1516,27 @@ sub create_parameterlist($$$$) { foreach my $arg (split($splitter, $args)) { # strip comments $arg =~ s/\/\*.*\*\///; + $arg =~ s/\s*EFIAPI\s*/ /g; # strip leading/trailing spaces $arg =~ s/^\s*//; $arg =~ s/\s*$//; $arg =~ s/\s+/ /; + if ($arg =~ /^#/) { # Treat preprocessor directive as a typeless variable just to fill # corresponding data structures "correctly". Catch it later in # output_* subs. - push_parameter($arg, "", $file); + push_parameter($arg, "", "", $file); } elsif ($arg =~ m/$.+$\s*$/) { # pointer-to-function $arg =~ tr/#/,/; - $arg =~ m/[^\(]+\([\w\s]*\*?\s*([\w\.]*)\s*$/; + $arg =~ m/[^$]+\(\s*\*?\s*([\w\.]*)\s*$/; $param = $1; $type = $arg; $type =~ s/([^\(]+\(\*?)\s*$param/$1/; save_struct_actual($param); - push_parameter($param, $type, $file, $declaration_name); + push_parameter($param, $type, $arg, $file, $declaration_name); } elsif ($arg) { $arg =~ s/\s*:\s*/:/g; $arg =~ s/\s*\[/\[/g; @@ -1412,26 +1561,28 @@ sub create_parameterlist($$$$) { foreach $param (@args) { if ($param =~ m/^(\*+)\s*(.*)/) { save_struct_actual($2); - push_parameter($2, "$type $1", $file, $declaration_name); + + push_parameter($2, "$type $1", $arg, $file, $declaration_name); } elsif ($param =~ m/(.*?):(\d+)/) { if ($type ne "") { # skip unnamed bit-fields save_struct_actual($1); - push_parameter($1, "$type:$2", $file, $declaration_name) + push_parameter($1, "$type:$2", $arg, $file, $declaration_name) } } else { save_struct_actual($param); - push_parameter($param, $type, $file, $declaration_name); + push_parameter($param, $type, $arg, $file, $declaration_name); } } } } } -sub push_parameter($$$$) { +sub push_parameter($$$$$) { my $param = shift; my $type = shift; + my $org_arg = shift; my $file = shift; my $declaration_name = shift; @@ -1449,6 +1600,10 @@ sub push_parameter($$$$) { # handles unnamed variable parameters $param = "..."; } + elsif ($param =~ /\w\.\.\.$/) { + # for named variable parameters of the form `x...`, remove the dots + $param =~ s/\.\.\.$//; + } if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } @@ -1491,8 +1646,8 @@ sub push_parameter($$$$) { # "[blah" in a parameter string; ###$param =~ s/\s*//g; push @parameterlist, $param; - $type =~ s/\s\s+/ /g; - $parametertypes{$param} = $type; + $org_arg =~ s/\s\s+/ /g; + $parametertypes{$param} = $org_arg; } sub check_sections($$$$$) { @@ -1566,6 +1721,8 @@ sub dump_function($$) { my $file = shift; my $noret = 0; + print_lineno($new_start_line); + $prototype =~ s/^static +//; $prototype =~ s/^extern +//; $prototype =~ s/^asmlinkage +//; @@ -1580,6 +1737,7 @@ sub dump_function($$) { $prototype =~ s/__must_check +//; $prototype =~ s/__weak +//; $prototype =~ s/__sched +//; + $prototype =~ s/__printf\s*$\s*\d*\s*,\s*\d*\s*$ +//; my $define = $prototype =~ s/^#\s*define\s+//; #ak added $prototype =~ s/__attribute__\s*\(\( (?: @@ -1640,30 +1798,48 @@ sub dump_function($$) { return; } - my $prms = join " ", @parameterlist; - check_sections($file, $declaration_name, "function", $sectcheck, $prms); + my $prms = join " ", @parameterlist; + check_sections($file, $declaration_name, "function", $sectcheck, $prms); - # This check emits a lot of warnings at the moment, because many - # functions don't have a 'Return' doc section. So until the number - # of warnings goes sufficiently down, the check is only performed in - # verbose mode. - # TODO: always perform the check. - if ($verbose && !$noret) { - check_return_section($file, $declaration_name, $return_type); - } + # This check emits a lot of warnings at the moment, because many + # functions don't have a 'Return' doc section. So until the number + # of warnings goes sufficiently down, the check is only performed in + # verbose mode. + # TODO: always perform the check. + if ($verbose && !$noret) { + check_return_section($file, $declaration_name, $return_type); + } - output_declaration($declaration_name, - 'function', - {'function' => $declaration_name, - 'module' => $modulename, - 'functiontype' => $return_type, - 'parameterlist' => \@parameterlist, - 'parameterdescs' => \%parameterdescs, - 'parametertypes' => \%parametertypes, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose - }); + # The function parser can be called with a typedef parameter. + # Handle it. + if ($return_type =~ /typedef/) { + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'typedef' => 1, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } else { + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } } sub reset_state { @@ -1758,6 +1934,11 @@ sub process_proto_function($$) { $prototype =~ s@/\*.*?\*/@@gos; # strip comments. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. $prototype =~ s@^\s+@@gos; # strip leading spaces + + # Handle prototypes for function pointers like: + # int (*pcs_config)(struct foo) + $prototype =~ s@^(\S+\s+)$\s*\*(\S+)$@$1$2@gos; + if ($prototype =~ /SYSCALL_DEFINE/) { syscall_munge(); } @@ -1836,6 +2017,7 @@ sub process_export_file($) { while (<IN>) { if (/$export_symbol/) { + next if (defined($nosymbol_table{$2})); $function_table{$2} = 1; } } @@ -1867,7 +2049,7 @@ sub process_name($$) { if (/$doc_block/o) { $state = STATE_DOCBLOCK; $contents = ""; - $new_start_line = $. + 1; + $new_start_line = $.; if ( $1 eq "" ) { $section = $section_intro; @@ -1935,6 +2117,25 @@ sub process_name($$) { sub process_body($$) { my $file = shift; + # Until all named variable macro parameters are + # documented using the bare name (`x`) rather than with + # dots (`x...`), strip the dots: + if ($section =~ /\w\.\.\.$/) { + $section =~ s/\.\.\.$//; + + if ($verbose) { + print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n"; + ++$warnings; + } + } + + if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) { + dump_section($file, $section, $contents); + $section = $section_default; + $new_start_line = $.; + $contents = ""; + } + if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; $newcontents = $2; @@ -1987,19 +2188,23 @@ sub process_body($$) { $prototype = ""; $state = STATE_PROTO; $brcount = 0; + $new_start_line = $. + 1; } elsif (/$doc_content/) { - # miguel-style comment kludge, look for blank lines after - # @parameter line to signify start of description if ($1 eq "") { - if ($section =~ m/^@/ || $section eq $section_context) { + if ($section eq $section_context) { dump_section($file, $section, $contents); $section = $section_default; $contents = ""; $new_start_line = $.; + $state = STATE_BODY; } else { + if ($section ne $section_default) { + $state = STATE_BODY_WITH_BLANK_LINE; + } else { + $state = STATE_BODY; + } $contents .= "\n"; } - $state = STATE_BODY; } elsif ($state == STATE_BODY_MAYBE) { # Continued declaration purpose chomp($declaration_purpose); @@ -2131,7 +2336,7 @@ sub process_file($) { $file = map_filename($orig_file); - if (!open(IN,"<$file")) { + if (!open(IN_FILE,"<$file")) { print STDERR "Error: Cannot open file $file\n"; ++$errors; return; @@ -2140,9 +2345,9 @@ sub process_file($) { $. = 1; $section_counter = 0; - while (<IN>) { + while (<IN_FILE>) { while (s/\\\s*$//) { - $_ .= <IN>; + $_ .= <IN_FILE>; } # Replace tabs by spaces while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; @@ -2151,7 +2356,8 @@ sub process_file($) { process_normal(); } elsif ($state == STATE_NAME) { process_name($file, $_); - } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { + } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE || + $state == STATE_BODY_WITH_BLANK_LINE) { process_body($file, $_); } elsif ($state == STATE_INLINE) { # scanning for inline parameters process_inline($file, $_); @@ -2163,17 +2369,24 @@ sub process_file($) { } # Make sure we got something interesting. - if ($initial_section_counter == $section_counter) { - if ($output_mode ne "none") { - print STDERR "${file}:1: warning: no structured comments found\n"; + if ($initial_section_counter == $section_counter && $ + output_mode ne "none") { + if ($output_selection == OUTPUT_INCLUDE) { + print STDERR "${file}:1: warning: '$_' not found\n" + for keys %function_table; } - if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) { - print STDERR " Was looking for '$_'.\n" for keys %function_table; + else { + print STDERR "${file}:1: warning: no structured comments found\n"; } } + close IN_FILE; } +if ($output_mode eq "rst") { + get_sphinx_version() if (!$sphinx_major); +} + $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information @@ -2220,4 +2433,9 @@ if ($verbose && $warnings) { print STDERR "$warnings warnings\n"; } -exit($output_mode eq "none" ? 0 : $errors); +if ($Werror && $warnings) { + print STDERR "$warnings warnings as Errors\n"; + exit($warnings); +} else { + exit($output_mode eq "none" ? 0 : $errors) +} -- 2.29.2

4 12