docs: use flexible array members, not zero-length
Subsystems (6)
PATCH 1/1 docs: use flexible array members, not zero-length
Update the docs throughout to remove zero-length arrays, replacing them with C99 flexible array members. GCC will then ensure that the arrays are always the last element in the struct.
--- Documentation/bpf/btf.rst | 2 +- Documentation/digsig.txt | 4 ++-- Documentation/driver-api/connector.rst | 2 +- Documentation/driver-api/usb/URB.rst | 2 +- .../filesystems/autofs-mount-control.txt | 2 +- Documentation/filesystems/autofs.txt | 2 +- Documentation/filesystems/fiemap.txt | 2 +- Documentation/hwspinlock.txt | 2 +- Documentation/networking/can.rst | 2 +- Documentation/networking/rxrpc.txt | 2 +- Documentation/remoteproc.txt | 4 ++-- Documentation/virt/kvm/api.txt | 24 +++++++++---------- Documentation/x86/boot.rst | 4 ++-- 13 files changed, 27 insertions(+), 27 deletions(-)
Documentation/bpf/btf.rst +1 -1
@@ -670,7 +670,7 @@ func_info for each specific ELF section.:: __u32 sec_name_off; /* offset to section name */ __u32 num_info; /* Followed by num_info * record_size number of bytes */ - __u8 data[0]; + __u8 data[]; }; Here, num_info must be greater than 0.
Documentation/digsig.txt +2 -2
@@ -31,7 +31,7 @@ Public key and signature consist of header and MPIs:: time_t timestamp; /* key made, always 0 for now */ uint8_t algo; uint8_t nmpi; - char mpi[0]; + char mpi[]; } __packed; struct signature_hdr {
@@ -41,7 +41,7 @@ Public key and signature consist of header and MPIs:: uint8_t hash; uint8_t keyid[8]; uint8_t nmpi; - char mpi[0]; + char mpi[]; } __packed; keyid equals to SHA1[12-19] over the total key content.
Documentation/driver-api/connector.rst +1 -1
@@ -49,7 +49,7 @@ be dereferenced to `struct cn_msg *`:: __u32 ack; __u32 len; /* Length of the following data */ - __u8 data[0]; + __u8 data[]; }; Connector interfaces
Documentation/driver-api/usb/URB.rst +1 -1
@@ -82,7 +82,7 @@ Some of the fields in struct :c:type:`urb` are:: // ISO only: packets are only "best effort"; each can have errors int error_count; // number of errors - struct usb_iso_packet_descriptor iso_frame_desc[0]; + struct usb_iso_packet_descriptor iso_frame_desc[]; }; Your driver must create the "pipe" value using values from the appropriate
Documentation/filesystems/autofs-mount-control.txt +1 -1
@@ -194,7 +194,7 @@ struct autofs_dev_ioctl { struct args_ismountpoint ismountpoint; }; - char path[0]; + char path[]; }; The ioctlfd field is a mount point file descriptor of an autofs mount
Documentation/filesystems/autofs.txt +1 -1
@@ -455,7 +455,7 @@ Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure: struct args_ismountpoint ismountpoint; }; - char path[0]; + char path[]; }; For the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target
Documentation/filesystems/fiemap.txt +1 -1
@@ -22,7 +22,7 @@ struct fiemap { * mapped (out) */ __u32 fm_extent_count; /* size of fm_extents array (in) */ __u32 fm_reserved; - struct fiemap_extent fm_extents[0]; /* array of mapped extents (out) */ + struct fiemap_extent fm_extents[]; /* array of mapped extents (out) */ };
Documentation/hwspinlock.txt +1 -1
@@ -439,7 +439,7 @@ implementation using the hwspin_lock_register() API. const struct hwspinlock_ops *ops; int base_id; int num_locks; - struct hwspinlock lock[0]; + struct hwspinlock lock[]; }; struct hwspinlock_device contains an array of hwspinlock structs, each
Documentation/networking/can.rst +1 -1
@@ -705,7 +705,7 @@ The broadcast manager sends responses to user space in the same form: struct timeval ival1, ival2; /* count and subsequent interval */ canid_t can_id; /* unique can_id for task */ __u32 nframes; /* number of can_frames following */ - struct can_frame frames[0]; + struct can_frame frames[]; }; The aligned payload 'frames' uses the same basic CAN frame structure defined
Documentation/networking/rxrpc.txt +1 -1
@@ -518,7 +518,7 @@ form: uint8_t kvno; /* key version number */ uint8_t __pad[3]; uint8_t session_key[8]; /* DES session key */ - uint8_t ticket[0]; /* the encrypted ticket */ + uint8_t ticket[]; /* the encrypted ticket */ }; Where the ticket blob is just appended to the above structure.
Documentation/remoteproc.txt +2 -2
@@ -274,7 +274,7 @@ The resource table begins with this header:: u32 ver; u32 num; u32 reserved[2]; - u32 offset[0]; + u32 offset[]; } __packed; Immediately following this header are the resource entries themselves,
@@ -291,7 +291,7 @@ each of which begins with the following resource entry header:: */ struct fw_rsc_hdr { u32 type; - u8 data[0]; + u8 data[]; } __packed; Some resources entries are mere announcements, where the host is informed
Documentation/virt/kvm/api.txt +12 -12
@@ -192,7 +192,7 @@ Errors: struct kvm_msr_list { __u32 nmsrs; /* number of msrs in entries */ - __u32 indices[0]; + __u32 indices[]; }; The user fills in the size of the indices array in nmsrs, and in return
@@ -566,7 +566,7 @@ struct kvm_msrs { __u32 nmsrs; /* number of msrs in entries */ __u32 pad; - struct kvm_msr_entry entries[0]; + struct kvm_msr_entry entries[]; }; struct kvm_msr_entry {
@@ -626,7 +626,7 @@ struct kvm_cpuid_entry { struct kvm_cpuid { __u32 nent; __u32 padding; - struct kvm_cpuid_entry entries[0]; + struct kvm_cpuid_entry entries[]; };
@@ -649,7 +649,7 @@ signal mask. /* for KVM_SET_SIGNAL_MASK */ struct kvm_signal_mask { __u32 len; - __u8 sigset[0]; + __u8 sigset[]; };
@@ -1403,7 +1403,7 @@ Returns: 0 on success, -1 on error struct kvm_cpuid2 { __u32 nent; __u32 padding; - struct kvm_cpuid_entry2 entries[0]; + struct kvm_cpuid_entry2 entries[]; }; #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
@@ -1516,7 +1516,7 @@ On arm/arm64, GSI routing has the following limitation: struct kvm_irq_routing { __u32 nr; __u32 flags; - struct kvm_irq_routing_entry entries[0]; + struct kvm_irq_routing_entry entries[]; }; No flags are specified so far, the corresponding field must be set to zero.
@@ -2868,7 +2868,7 @@ Errors: struct kvm_reg_list { __u64 n; /* number of registers in reg[] */ - __u64 reg[0]; + __u64 reg[]; }; This ioctl returns the guest registers that are supported for the
@@ -2997,7 +2997,7 @@ Returns: 0 on success, -1 on error struct kvm_cpuid2 { __u32 nent; __u32 flags; - struct kvm_cpuid_entry2 entries[0]; + struct kvm_cpuid_entry2 entries[]; }; The member 'flags' is used for passing flags from userspace.
@@ -3889,8 +3889,8 @@ struct kvm_nested_state { } hdr; union { - struct kvm_vmx_nested_state_data vmx[0]; - struct kvm_svm_nested_state_data svm[0]; + struct kvm_vmx_nested_state_data vmx[]; + struct kvm_svm_nested_state_data svm[]; } data; };
@@ -4016,7 +4016,7 @@ Returns: 0 on success, -1 on error struct kvm_cpuid2 { __u32 nent; __u32 padding; - struct kvm_cpuid_entry2 entries[0]; + struct kvm_cpuid_entry2 entries[]; }; struct kvm_cpuid_entry2 {
@@ -4110,7 +4110,7 @@ struct kvm_pmu_event_filter { __u32 fixed_counter_bitmap; __u32 flags; __u32 pad[4]; - __u64 events[0]; + __u64 events[]; }; This ioctl restricts the set of PMU events that the guest can program.
Documentation/x86/boot.rst +2 -2
@@ -790,13 +790,13 @@ Protocol: 2.09+ The 64-bit physical pointer to NULL terminated single linked list of struct setup_data. This is used to define a more extensible boot parameters passing mechanism. The definition of struct setup_data is - as follow:: + as follows:: struct setup_data { u64 next; u32 type; u32 len; - u8 data[0]; + u8 data[]; }; Where, the next is a 64-bit physical pointer to the next node of
Signature · 1 line
2.20.1
Jonathan Corbet
maintainerQuoted 3 lines · On Fri, 27 Sep 2019 16:29:27 +0200 Stephen Kitt <[email protected]> wrote:
Update the docs throughout to remove zero-length arrays, replacing them with C99 flexible array members. GCC will then ensure that the arrays are always the last element in the struct.
I appreciate the thought but...
Documentation/bpf/btf.rst func_info for each specific ELF section.:: · line 674
Quoted 11 lines
Documentation/bpf/btf.rst +1
-1@@ -670,7 +670,7 @@ func_info for each specific ELF section.:: __u32 sec_name_off; /* offset to section name */ __u32 num_info; /* Followed by num_info * record_size number of bytes */ - __u8 data[0]; + __u8 data[]; };
I only checked this one, but found what I had expected: the actual definition of this structure (found in tools/lib/bpf/libbpf_internal.h) says "data[0]". We can't really make the documentation read the way we *wish* the source would be, we need to document reality.
I'm pretty sure that most of the other examples will be the same.
If you really want to fix these, the right solution is to fix the offending structures — one patch per structure — in the source, then update the documentation to match the new reality.
Thanks,
jon
Quoted 19 lines · Jonathan Corbet
Documentation/bpf/btf.rst func_info for each specific ELF section.:: · line 674
Quoted 11 lines · On Fri, 27 Sep 2019 16:29:27 +0200 Stephen Kitt <[email protected]> wrote:
Documentation/bpf/btf.rst +1
-1@@ -670,7 +670,7 @@ func_info for each specific ELF section.:: __u32 sec_name_off; /* offset to section name */ __u32 num_info; /* Followed by num_info * record_size number of bytes */ - __u8 data[0]; + __u8 data[]; };I only checked this one, but found what I had expected: the actual definition of this structure (found in
tools/lib/bpf/libbpf_internal.h) says "data[0]". We can't really make the documentation read the way we *wish* the source would be, we need to document reality.
Quoted 1 line
I'm pretty sure that most of the other examples will be the same.
Aargh, yes, of course, thanks for checking! I was locked in a “prescriptive” documentation mode, but this type of documentation has to be descriptive since it’s documenting shared structures, not structures which developers have to write.
Quoted 3 lines
If you really want to fix these, the right solution is to fix the offending structures — one patch per structure — in the source, then update the documentation to match the new reality.
Yes. I have a Coccinelle script which takes care of the code, but it doesn’t work for docs ;-).
Wouldn’t it be better to update the docs simultaneously in each patch which fixes a structure? Or is that unworkable with current development practices?
Regards,
Stephen
Jonathan Corbet
maintainerQuoted 2 lines · On Sat, 28 Sep 2019 10:55:57 +0200 Stephen Kitt <[email protected]> wrote:
Wouldn’t it be better to update the docs simultaneously in each patch which fixes a structure? Or is that unworkable with current development practices?
Definitely update the two together. The doc fix should just go through the appropriate maintainer with the code change.
Thanks,
jon