[PATCH] D63327: [docs][llvm-nm] Improve symbol code documentation

[Fangrui Song via Phabricator via llvm-commits]

MaskRay added inline comments.


================
Comment at: docs/CommandGuide/llvm-nm.rst:51
+
+n
+
----------------
jhenderson wrote:
> jhenderson wrote:
> > MaskRay wrote:
> > > I think the semantics (GNU nm behavior) of `n` are similar to what the reverted rL359312 did, but unfortunately I cannot find a reasonable use case to write a test, nor can I find useful tests in the binutils-gdb repository.
> > > 
> > > I don't know if relocations into non-SHF_ALLOC sections other than .debug* are reasonable.
> > > I don't know if relocations into non-SHF_ALLOC sections other than .debug* are reasonable.
> > 
> > We use them in Sony-specific sections at least. I think they are reasonable for additional metadata that needs to refer to the actual code in some way.
> > 
> > I'm okay with the semantics of 'n' changing in the future (this is just one example where the code doesn't necessarily make sense). I'd just like to document what we currently do now - we can document what the behaviour is when we change the code.
> > We use them in Sony-specific sections at least. I think they are reasonable for additional metadata that needs to refer to the actual code in some way.
> 
> I misread your comment. I don't know about relocations into non-alloc sections, but it's certainly possible to produce local symbols in them at least.
Sent out D63588. The new behavior should match what I observed from GNU nm.

> ELF: .note or .comment section symbol, or local symbol from non-alloc section.

This should just be: local symbol from non-alloc section if D63588 is accepted. (You can add non-writable if that matters.. though I can't find a use case of a writable non-alloc section)

Note sections are usually SHF_ALLOC. `.comment` sections do not have relocations. I don't know why the original code was written that way...


================
Comment at: docs/CommandGuide/llvm-nm.rst:81
+
+ Named object is referenced but undefined in this file.
+
----------------
It doesn't have to be "referenced".

```
as /dev/null -o a.o
ld.bfd a.o -u foo -o a  # or gold; but ld.lld doesn't have this behavior
nm a => U foo
```

though `foo` is not referenced...


================
Comment at: docs/CommandGuide/llvm-nm.rst:89
+
+ ELF: Weak object definition. Multiple definitions link together into zero or one definitions.
+
----------------
> Multiple definitions link together into zero or one definitions.

This sentence makes me puzzled. You may delete it if no better description can be found.



Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D63327/new/

https://reviews.llvm.org/D63327