From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from relay.hostedemail.com (smtprelay0014.hostedemail.com [216.40.44.14]) by sourceware.org (Postfix) with ESMTPS id 38D353857739 for ; Tue, 23 Jan 2024 21:05:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 38D353857739 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=systematicsw.ab.ca Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=systematicsw.ab.ca ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 38D353857739 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=216.40.44.14 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1706043923; cv=none; b=d4a9H/3EjYxaTauz7vz4vFjMi9FwpLSNJpVNZ6TOF0489+qqcEO92BzraB+karnIhRz4NoV9VUP/PIjq9/XIW3HmauE0Xc3axC375pHfaU00yzf9Cp4sHJ6HRDZz6vyAOagRBPMg/0NGqzsIRNRiPzC56YkxyJRznzkyUAqxCh4= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1706043923; c=relaxed/simple; bh=4w9WgzYDd2Wv8Y5bB+kKD8g5rQ7dnARoHWp8wdXjCaY=; h=Message-ID:Date:MIME-Version:From:Subject:To; b=K4uvQQz+yDLpTAEwcB0lJCzN74WbBw/gNiSpjTEsG8PxtKvf8qsajt9o89S+zZz+5vK3xcw8cfGQ2AfWtXcyZ6SV2lM0kXOY69M1Ix+14cVpKn4NnC4TBWUkaiSVgda/6tqgzfyrzhZcEQkKS9q5Ca4wNtplvwujs+NkYL7fUJI= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from omf15.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id 8D0A91401A4 for ; Tue, 23 Jan 2024 21:05:19 +0000 (UTC) Received: from [HIDDEN] (Authenticated sender: Brian.Inglis@SystematicSW.ab.ca) by omf15.hostedemail.com (Postfix) with ESMTPA id 151661A for ; Tue, 23 Jan 2024 21:05:17 +0000 (UTC) Message-ID: <98c7546a-2caf-4492-b5e8-882f5d867262@systematicsw.ab.ca> Date: Tue, 23 Jan 2024 14:05:17 -0700 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird From: brian.inglis@systematicsw.ab.ca Reply-To: newlib@sourceware.org Subject: Re: FW: [PATCH] [RFC] newlib: libc: start manual appendix to hold various ABI constants Content-Language: en-CA To: newlib@sourceware.org References: <20231227072512.17179-1-vapier@gentoo.org> Autocrypt: addr=brian.inglis@systematicsw.ab.ca; keydata= xjMEXopx8xYJKwYBBAHaRw8BAQdAnCK0qv/xwUCCZQoA9BHRYpstERrspfT0NkUWQVuoePbN LkJyaWFuIEluZ2xpcyA8QnJpYW4uSW5nbGlzQFN5c3RlbWF0aWNTdy5hYi5jYT7ClgQTFggA PhYhBMM5/lbU970GBS2bZB62lxu92I8YBQJeinHzAhsDBQkJZgGABQsJCAcCBhUKCQgLAgQW AgMBAh4BAheAAAoJEB62lxu92I8Y0ioBAI8xrggNxziAVmr+Xm6nnyjoujMqWcq3oEhlYGAO WacZAQDFtdDx2koSVSoOmfaOyRTbIWSf9/Cjai29060fsmdsDM44BF6KcfMSCisGAQQBl1UB BQEBB0Awv8kHI2PaEgViDqzbnoe8B9KMHoBZLS92HdC7ZPh8HQMBCAfCfgQYFggAJhYhBMM5 /lbU970GBS2bZB62lxu92I8YBQJeinHzAhsMBQkJZgGAAAoJEB62lxu92I8YZwUBAJw/74rF IyaSsGI7ewCdCy88Lce/kdwX7zGwid+f8NZ3AQC/ezTFFi5obXnyMxZJN464nPXiggtT9gN5 RSyTY8X+AQ== Organization: Systematic Software In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-Stat-Signature: im3bn1poatxsnqsjzua3qpx4emyg9rqe X-Rspamd-Server: rspamout03 X-Spam-Status: No, score=-2.3 required=5.0 tests=BAYES_00,KAM_DMARC_STATUS,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_PASS,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.6 X-Rspamd-Queue-Id: 151661A X-Session-Marker: 427269616E2E496E676C69734053797374656D6174696353572E61622E6361 X-Session-ID: U2FsdGVkX19KN9rzXfX48C0VEhwQL5G97PDJg65GpeM= X-HE-Tag: 1706043917-149635 X-HE-Meta: U2FsdGVkX1+sZEaYwW2InOXVNsuS3JtIimGonkqFBvsXS+GV3L/jPXZ9w5zZK4FT5+JniCEPk/2Wf+y243scjQS4gLx1Tbfw/nPm+nLFOnNm/MMm1ECmRbCObrmHRHht9ghxVxplFNDhawbdFHN3I9UUKodC3UlsO/ASE0AGZrjGb0qhI8NrmHbV0mre2HtBmJ/er/TII6RGWAumZvoxzxQANcrto6jB83dqYzyG321HLLNFLqhUIs9HJU5sf3omsZ+QvPWNUlbp5+qgguG/zuxRtZbhiqFo3P1ObYofS8mtfCxrLai4wYw77LxVE1n5Wszlh9KgFY2sgQ+lmi08LAtD+ThrnKFIjbXNX68HNL1XF7wvek5yfOX9tjxwAi+l2vJApDk/ItxT1X87RlGLPFL9h4yoI1pmoofWKC6caIiM+lER2KKznn4OWZqcZ/SlbM5TTxSXyL0UMt9PebFayg== X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: On 2023-12-29 22:03, Mike Frysinger wrote: > On 29 Dec 2023 20:17, C Howland wrote: >> I won't comment on whether adding this is a good idea or not as I >> don't meet any of the stated use cases. But here are a few thoughts on the >> details of it assuming others like the addition. > > if you only use newlib, it could be helpful. consider how common it is for > people to write error messages like: > printf("error %i\n", errno); > so your log contains "error 13". how do you find out what errno 13 is ? > even Linux's `man errno` doesn't list the raw numbers. having online access > to the name<->number mappings for these is helpful in a pinch in my experience. moreutils errno? https://joeyh.name/code/moreutils/ https://repology.org/project/moreutils/versions - perhaps with creative use of "locales" (or patches) for different library sources and board support? >> Given the stated purpose it sounds like mapping files might want to be >> made for some of the scenarios mentioned. For something like that I'd >> think most people would want to start with the source code (as opposed to >> copying from the manual). With this in mind, adding the Newlib source file >> path as supplementary information to the values in the manual might make >> sense as an additional aid. > > the GNU sim script can already extract the code and turn it into structured > data (e.g. JSON). it can also turn that into a C file for the generated table. > i would expect the export-to-JSON to be part of the script for merging into > newlib so that the people who need access to the ABI in source form can easily > get it and convert it to whatever format they need. so the sim would switch to > running the newlib script to get the JSON, but it would keep the output-to-C > logic since that's sim-specific. > >> Thinking a step beyond the stated purpose of making the values >> available in the manual for mapping purposes, in a bigger-picture view (it >> is a manual) would it make sense to preserve the descriptive comments in >> the source, copying them to the manual, too? (Without seeing the script >> mechanism being used I can't tell how easy or hard that might be to add.) > > the script is written in Python and uses a preprocessor (e.g. gcc) to dump > the constants. gcc has a -CC option to include line-level comments, so this > is a possibility. it would require the source be structured in a way where > the comments are inline which it mostly already is. > >> It might be better to enhance the wording here a little. > > i half-assed this content to show the general structure. i'm sure the hand > written descriptions could use improvement. i'll take your feedback in once > i get a signal from the newlib maintainers on this in general. > >> Given today's reality of no printed (vs. electronic) manuals (maybe a rare >> person that might print a copy), is it worth bothering to present both name >> and number sorted lists? (People will just electronically search, making >> the multiple presentation of essentially no added value.) Just choose 1 >> and do that only? (The cost of doing it is low, and choosing numeric or >> name might be tricky to decide. But dropping to 1 would reduce electronic >> search clutter of having the same thing found twice per subsection. >> Already will be a little bit distracting to have the common/cris/spu >> sections, twice as bad if each lists both values twice.) > > *shrug* it was easy enough to generate. i find sorted-by-name helpful when > i want to see if a specific name is available, perhaps under a slight name > variant (when i can't remember exactly how it's been abbreviated), and i find > sorted-by-number helpful when looking up an error number from log output. > if we only have sorted-by-name, searching for a single digit number is a bit > of a pita because it'll match numbers in the constant name, in the comment, > and in the multi-digit errno values. it's not uncommon for the user agent > to support only case-insensitive substrings (e.g. Chrome), and needing regex > just to construct an exact match seems a bit too much for a general manual. > > for example: > $ gcc -E -P -dD -CC - <<<'#include ' | grep 2 > <35 errno matches> > > but it's not something i'm strongly tied to, so if the newlib maintainers > want to use one or the other, i don't care enough to fight. > -mike -- Take care. Thanks, Brian Inglis Calgary, Alberta, Canada La perfection est atteinte Perfection is achieved non pas lorsqu'il n'y a plus rien à ajouter not when there is no more to add mais lorsqu'il n'y a plus rien à retirer but when there is no more to cut -- Antoine de Saint-Exupéry