Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
Op 24-09-2020 om 16:21 schreef Karol Herbst: On Thu, Sep 24, 2020 at 3:06 PM Roy Spliet wrote: Op 23-09-2020 om 22:36 schreef Karol Herbst: On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: yeah, I think overall this file is a good idea and being able to get a quick overview over the driver is helpful. I think if we focus on the user facing things first, like the hwmon or other things users generally interact with would be helpful. I think if we start to document areas where there are many low hanging fruits, this could help random people to start with easier tasks and get more used to the driver overall, so I'd probably ignore most of the stuff which really requires a fundamental understanding on how things work and focus more on vbios parsing (which has annoying interfaces anyway and it might make sense to make it more consistent and nicer to use) and/or simple code interfacing with the mmio space. I'll admit to being motivated by entirely selfish reasons. I know practically nothing about nouveau and I'm the type of person who likes to keep notes about how things work together, both free form and structured in-line docs. All that to say, I think focusing on the "low-hanging fruit" stuff will be very beneficial and I'm happy to do that, but I'm also interested in documenting everything else I run across. yeah, that's fine. I was just giving a suggestion on where the initial focus should be on. Eg some users have problems with their fans as they are either always ramping up to max, or not running at all... GPUs temperature or power consumption is reporting incorrectly... all those things users hit regularly, but which isn't really important enough so it just falls under the table even if it gets reported. This does bring up an interesting point about organization and target audiences. Typically when I'm writing documentation I like to organize things by target audiences, so we could have a layout like: * General Introduction * User Guide - Overview of supported hardware/features/etc That's best to document in a wiki though. And we had plans to convert the existing old wiki over to gitlab. And maybe It think we really should do that and clean it up while we work on that. It's just a huge project but maybe just starting with whatever you want to do would be fine and after a while nothing is left. Anyway, I think we should discuss this more openly with the others as well. i don't like the current wiki anyway, as only approved developers can change things and with a gitlab wiki we could even take MRs on stuff. - Installation well.. I think this can be skipped ;) But still, also belongs more into a wiki. I think what we could cover here is to how to clean up remaining stuff from the blob driver as this is something which comes up quite a lot on IRC though. - Configuration (module parameters and such) - Troubleshooting that would be cool to have in the wiki as well. Just collecting the most common issue and document it there. Especially if it is on gitlab, users can just do that as well :) - Getting Involved (bug reporting, running tests, etc) yeah, and we have some stuff on that on the old wiki already, it's just very outdated and needs updating, which as said above can only be done by developers and developers sadly have other things to do :) * Developer Guide - Architecture Overview - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? - Internal APIs Right, those things I'd like to see in the kernel tree actually. - Debugging and Development Tools - Contribution Guide Those I think belong more into the wiki again. The latter is a bit hard to split as there are kernel guides, but also community and project guides. Mesa does things differently than let's say the kernel. And Nouveau is still in this limbo state being on the old infra, but also on the new one with mesa... I'm not sure how much stuff people want to keep on the nouveau.freedesktop.org wiki vs here. I think the first step actually is to set up a proper nouveau project on gitlab for dealing with issues and the wiki. I would be fine to do that and we can also move the code there late. But maybe let's start with the wiki :) Risking to turn this into a "let's fix everything in one go" project that ends up never getting finished, I just want to make sure that everybody is also aware of the documentation generated from Envytools [0]. Especially "architecture overview" (that is, if we're talking about hardware architecture and not driver/software architecture) might be better suited in envytools. As for module parameters, IMHO modinfo is supposed to be the source of information. It's sadly lacking any "sub-"option inside nouveau.config and nouveau.debug, which may be by design. Perhaps expanding the modin
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 8:18 PM Jeremy Cline wrote: > > On Thu, Sep 24, 2020 at 07:26:01PM +0200, Karol Herbst wrote: > > On Thu, Sep 24, 2020 at 6:03 PM Jeremy Cline wrote: > > > > > > On Wed, Sep 23, 2020 at 11:36:54PM +0200, Karol Herbst wrote: > > > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > > > > > > > > > > On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > > > > > > On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline > > > > > > wrote: > > > > > > > > > > > > > > > > > > > > > yeah, I think overall this file is a good idea and being able to > > > > > > get a > > > > > > quick overview over the driver is helpful. I think if we focus on > > > > > > the > > > > > > user facing things first, like the hwmon or other things users > > > > > > generally interact with would be helpful. I think if we start to > > > > > > document areas where there are many low hanging fruits, this could > > > > > > help random people to start with easier tasks and get more used to > > > > > > the > > > > > > driver overall, so I'd probably ignore most of the stuff which > > > > > > really > > > > > > requires a fundamental understanding on how things work and focus > > > > > > more > > > > > > on vbios parsing (which has annoying interfaces anyway and it might > > > > > > make sense to make it more consistent and nicer to use) and/or > > > > > > simple > > > > > > code interfacing with the mmio space. > > > > > > > > > > > > > > > > I'll admit to being motivated by entirely selfish reasons. I know > > > > > practically nothing about nouveau and I'm the type of person who likes > > > > > to keep notes about how things work together, both free form and > > > > > structured in-line docs. All that to say, I think focusing on the > > > > > "low-hanging fruit" stuff will be very beneficial and I'm happy to do > > > > > that, but I'm also interested in documenting everything else I run > > > > > across. > > > > > > > > > > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > > > focus should be on. > > > > > > > > > > Eg some users have problems with their fans as they are either > > > > > > always > > > > > > ramping up to max, or not running at all... GPUs temperature or > > > > > > power > > > > > > consumption is reporting incorrectly... all those things users hit > > > > > > regularly, but which isn't really important enough so it just falls > > > > > > under the table even if it gets reported. > > > > > > > > > > > > > > > > This does bring up an interesting point about organization and target > > > > > audiences. Typically when I'm writing documentation I like to organize > > > > > things by target audiences, so we could have a layout like: > > > > > > > > > > * General Introduction > > > > > > > > > > * User Guide > > > > > - Overview of supported hardware/features/etc > > > > > > > > That's best to document in a wiki though. And we had plans to convert > > > > the existing old wiki over to gitlab. And maybe It think we really > > > > should do that and clean it up while we work on that. It's just a huge > > > > project but maybe just starting with whatever you want to do would be > > > > fine and after a while nothing is left. Anyway, I think we should > > > > discuss this more openly with the others as well. i don't like the > > > > current wiki anyway, as only approved developers can change things and > > > > with a gitlab wiki we could even take MRs on stuff. > > > > > > > > > > Yeah, so I think there's going to be at least three separate locations > > > for documentation: Envytools (hardware), the nouveau wiki (user guide), > > > and in the kernel (developer-focused and only the kernel bits). I don't > > > know much about the userspace bits yet, so maybe there's going to be > > > more than three places. I think it'd be good to at least cross-reference > > > between the wiki and the kernel docs, so this "section" could really > > > just be a link to the nouveau wiki for folks who end up in the kernel > > > docs, but really just want to use things (and maybe new developers who > > > haven't historically been users, such as myself). > > > > > > > > - Installation > > > > > > > > well.. I think this can be skipped ;) But still, also belongs more > > > > into a wiki. I think what we could cover here is to how to clean up > > > > remaining stuff from the blob driver as this is something which comes > > > > up quite a lot on IRC though. > > > > > > > > > - Configuration (module parameters and such) > > > > > - Troubleshooting > > > > > > > > that would be cool to have in the wiki as well. Just collecting the > > > > most common issue and document it there. Especially if it is on > > > > gitlab, users can just do that as well :) > > > > > > > > > - Getting Involved (bug reporting, running tests, etc) > > > > > > > > yeah, and we have some stuff on that on the old wiki already, it's > > > > just very outdated and needs updating, which as said above
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 07:26:01PM +0200, Karol Herbst wrote: > On Thu, Sep 24, 2020 at 6:03 PM Jeremy Cline wrote: > > > > On Wed, Sep 23, 2020 at 11:36:54PM +0200, Karol Herbst wrote: > > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > > > > > > > > On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > > > > > On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline > > > > > wrote: > > > > > > > > > > > > > > > > > yeah, I think overall this file is a good idea and being able to get a > > > > > quick overview over the driver is helpful. I think if we focus on the > > > > > user facing things first, like the hwmon or other things users > > > > > generally interact with would be helpful. I think if we start to > > > > > document areas where there are many low hanging fruits, this could > > > > > help random people to start with easier tasks and get more used to the > > > > > driver overall, so I'd probably ignore most of the stuff which really > > > > > requires a fundamental understanding on how things work and focus more > > > > > on vbios parsing (which has annoying interfaces anyway and it might > > > > > make sense to make it more consistent and nicer to use) and/or simple > > > > > code interfacing with the mmio space. > > > > > > > > > > > > > I'll admit to being motivated by entirely selfish reasons. I know > > > > practically nothing about nouveau and I'm the type of person who likes > > > > to keep notes about how things work together, both free form and > > > > structured in-line docs. All that to say, I think focusing on the > > > > "low-hanging fruit" stuff will be very beneficial and I'm happy to do > > > > that, but I'm also interested in documenting everything else I run > > > > across. > > > > > > > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > > focus should be on. > > > > > > > > Eg some users have problems with their fans as they are either always > > > > > ramping up to max, or not running at all... GPUs temperature or power > > > > > consumption is reporting incorrectly... all those things users hit > > > > > regularly, but which isn't really important enough so it just falls > > > > > under the table even if it gets reported. > > > > > > > > > > > > > This does bring up an interesting point about organization and target > > > > audiences. Typically when I'm writing documentation I like to organize > > > > things by target audiences, so we could have a layout like: > > > > > > > > * General Introduction > > > > > > > > * User Guide > > > > - Overview of supported hardware/features/etc > > > > > > That's best to document in a wiki though. And we had plans to convert > > > the existing old wiki over to gitlab. And maybe It think we really > > > should do that and clean it up while we work on that. It's just a huge > > > project but maybe just starting with whatever you want to do would be > > > fine and after a while nothing is left. Anyway, I think we should > > > discuss this more openly with the others as well. i don't like the > > > current wiki anyway, as only approved developers can change things and > > > with a gitlab wiki we could even take MRs on stuff. > > > > > > > Yeah, so I think there's going to be at least three separate locations > > for documentation: Envytools (hardware), the nouveau wiki (user guide), > > and in the kernel (developer-focused and only the kernel bits). I don't > > know much about the userspace bits yet, so maybe there's going to be > > more than three places. I think it'd be good to at least cross-reference > > between the wiki and the kernel docs, so this "section" could really > > just be a link to the nouveau wiki for folks who end up in the kernel > > docs, but really just want to use things (and maybe new developers who > > haven't historically been users, such as myself). > > > > > > - Installation > > > > > > well.. I think this can be skipped ;) But still, also belongs more > > > into a wiki. I think what we could cover here is to how to clean up > > > remaining stuff from the blob driver as this is something which comes > > > up quite a lot on IRC though. > > > > > > > - Configuration (module parameters and such) > > > > - Troubleshooting > > > > > > that would be cool to have in the wiki as well. Just collecting the > > > most common issue and document it there. Especially if it is on > > > gitlab, users can just do that as well :) > > > > > > > - Getting Involved (bug reporting, running tests, etc) > > > > > > yeah, and we have some stuff on that on the old wiki already, it's > > > just very outdated and needs updating, which as said above can only be > > > done by developers and developers sadly have other things to do :) > > > > > > > > > > > * Developer Guide > > > > - Architecture Overview > > > > - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > > > > - Internal APIs > > > > > > Right, those things I'd like to see in the kernel tree actua
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 7:26 PM Karol Herbst wrote: > > On Thu, Sep 24, 2020 at 6:03 PM Jeremy Cline wrote: > > > > On Wed, Sep 23, 2020 at 11:36:54PM +0200, Karol Herbst wrote: > > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > > > > > > > > On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > > > > > On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline > > > > > wrote: > > > > > > > > > > > > > > > > > yeah, I think overall this file is a good idea and being able to get a > > > > > quick overview over the driver is helpful. I think if we focus on the > > > > > user facing things first, like the hwmon or other things users > > > > > generally interact with would be helpful. I think if we start to > > > > > document areas where there are many low hanging fruits, this could > > > > > help random people to start with easier tasks and get more used to the > > > > > driver overall, so I'd probably ignore most of the stuff which really > > > > > requires a fundamental understanding on how things work and focus more > > > > > on vbios parsing (which has annoying interfaces anyway and it might > > > > > make sense to make it more consistent and nicer to use) and/or simple > > > > > code interfacing with the mmio space. > > > > > > > > > > > > > I'll admit to being motivated by entirely selfish reasons. I know > > > > practically nothing about nouveau and I'm the type of person who likes > > > > to keep notes about how things work together, both free form and > > > > structured in-line docs. All that to say, I think focusing on the > > > > "low-hanging fruit" stuff will be very beneficial and I'm happy to do > > > > that, but I'm also interested in documenting everything else I run > > > > across. > > > > > > > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > > focus should be on. > > > > > > > > Eg some users have problems with their fans as they are either always > > > > > ramping up to max, or not running at all... GPUs temperature or power > > > > > consumption is reporting incorrectly... all those things users hit > > > > > regularly, but which isn't really important enough so it just falls > > > > > under the table even if it gets reported. > > > > > > > > > > > > > This does bring up an interesting point about organization and target > > > > audiences. Typically when I'm writing documentation I like to organize > > > > things by target audiences, so we could have a layout like: > > > > > > > > * General Introduction > > > > > > > > * User Guide > > > > - Overview of supported hardware/features/etc > > > > > > That's best to document in a wiki though. And we had plans to convert > > > the existing old wiki over to gitlab. And maybe It think we really > > > should do that and clean it up while we work on that. It's just a huge > > > project but maybe just starting with whatever you want to do would be > > > fine and after a while nothing is left. Anyway, I think we should > > > discuss this more openly with the others as well. i don't like the > > > current wiki anyway, as only approved developers can change things and > > > with a gitlab wiki we could even take MRs on stuff. > > > > > > > Yeah, so I think there's going to be at least three separate locations > > for documentation: Envytools (hardware), the nouveau wiki (user guide), > > and in the kernel (developer-focused and only the kernel bits). I don't > > know much about the userspace bits yet, so maybe there's going to be > > more than three places. I think it'd be good to at least cross-reference > > between the wiki and the kernel docs, so this "section" could really > > just be a link to the nouveau wiki for folks who end up in the kernel > > docs, but really just want to use things (and maybe new developers who > > haven't historically been users, such as myself). > > > > > > - Installation > > > > > > well.. I think this can be skipped ;) But still, also belongs more > > > into a wiki. I think what we could cover here is to how to clean up > > > remaining stuff from the blob driver as this is something which comes > > > up quite a lot on IRC though. > > > > > > > - Configuration (module parameters and such) > > > > - Troubleshooting > > > > > > that would be cool to have in the wiki as well. Just collecting the > > > most common issue and document it there. Especially if it is on > > > gitlab, users can just do that as well :) > > > > > > > - Getting Involved (bug reporting, running tests, etc) > > > > > > yeah, and we have some stuff on that on the old wiki already, it's > > > just very outdated and needs updating, which as said above can only be > > > done by developers and developers sadly have other things to do :) > > > > > > > > > > > * Developer Guide > > > > - Architecture Overview > > > > - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > > > > - Internal APIs > > > > > > Right, those things I'd like to see in the kernel tree actually. >
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 6:03 PM Jeremy Cline wrote: > > On Wed, Sep 23, 2020 at 11:36:54PM +0200, Karol Herbst wrote: > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > > > > > > On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > > > > On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: > > > > > > > > > > > > > yeah, I think overall this file is a good idea and being able to get a > > > > quick overview over the driver is helpful. I think if we focus on the > > > > user facing things first, like the hwmon or other things users > > > > generally interact with would be helpful. I think if we start to > > > > document areas where there are many low hanging fruits, this could > > > > help random people to start with easier tasks and get more used to the > > > > driver overall, so I'd probably ignore most of the stuff which really > > > > requires a fundamental understanding on how things work and focus more > > > > on vbios parsing (which has annoying interfaces anyway and it might > > > > make sense to make it more consistent and nicer to use) and/or simple > > > > code interfacing with the mmio space. > > > > > > > > > > I'll admit to being motivated by entirely selfish reasons. I know > > > practically nothing about nouveau and I'm the type of person who likes > > > to keep notes about how things work together, both free form and > > > structured in-line docs. All that to say, I think focusing on the > > > "low-hanging fruit" stuff will be very beneficial and I'm happy to do > > > that, but I'm also interested in documenting everything else I run > > > across. > > > > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > focus should be on. > > > > > > Eg some users have problems with their fans as they are either always > > > > ramping up to max, or not running at all... GPUs temperature or power > > > > consumption is reporting incorrectly... all those things users hit > > > > regularly, but which isn't really important enough so it just falls > > > > under the table even if it gets reported. > > > > > > > > > > This does bring up an interesting point about organization and target > > > audiences. Typically when I'm writing documentation I like to organize > > > things by target audiences, so we could have a layout like: > > > > > > * General Introduction > > > > > > * User Guide > > > - Overview of supported hardware/features/etc > > > > That's best to document in a wiki though. And we had plans to convert > > the existing old wiki over to gitlab. And maybe It think we really > > should do that and clean it up while we work on that. It's just a huge > > project but maybe just starting with whatever you want to do would be > > fine and after a while nothing is left. Anyway, I think we should > > discuss this more openly with the others as well. i don't like the > > current wiki anyway, as only approved developers can change things and > > with a gitlab wiki we could even take MRs on stuff. > > > > Yeah, so I think there's going to be at least three separate locations > for documentation: Envytools (hardware), the nouveau wiki (user guide), > and in the kernel (developer-focused and only the kernel bits). I don't > know much about the userspace bits yet, so maybe there's going to be > more than three places. I think it'd be good to at least cross-reference > between the wiki and the kernel docs, so this "section" could really > just be a link to the nouveau wiki for folks who end up in the kernel > docs, but really just want to use things (and maybe new developers who > haven't historically been users, such as myself). > > > > - Installation > > > > well.. I think this can be skipped ;) But still, also belongs more > > into a wiki. I think what we could cover here is to how to clean up > > remaining stuff from the blob driver as this is something which comes > > up quite a lot on IRC though. > > > > > - Configuration (module parameters and such) > > > - Troubleshooting > > > > that would be cool to have in the wiki as well. Just collecting the > > most common issue and document it there. Especially if it is on > > gitlab, users can just do that as well :) > > > > > - Getting Involved (bug reporting, running tests, etc) > > > > yeah, and we have some stuff on that on the old wiki already, it's > > just very outdated and needs updating, which as said above can only be > > done by developers and developers sadly have other things to do :) > > > > > > > > * Developer Guide > > > - Architecture Overview > > > - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > > > - Internal APIs > > > > Right, those things I'd like to see in the kernel tree actually. > > > > > - Debugging and Development Tools > > > - Contribution Guide > > > > > > > Those I think belong more into the wiki again. The latter is a bit > > hard to split as there are kernel guides, but also community and > > project guides. Mesa does thing
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Wed, Sep 23, 2020 at 11:36:54PM +0200, Karol Herbst wrote: > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > > > > On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > > > On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: > > > > > > > > > yeah, I think overall this file is a good idea and being able to get a > > > quick overview over the driver is helpful. I think if we focus on the > > > user facing things first, like the hwmon or other things users > > > generally interact with would be helpful. I think if we start to > > > document areas where there are many low hanging fruits, this could > > > help random people to start with easier tasks and get more used to the > > > driver overall, so I'd probably ignore most of the stuff which really > > > requires a fundamental understanding on how things work and focus more > > > on vbios parsing (which has annoying interfaces anyway and it might > > > make sense to make it more consistent and nicer to use) and/or simple > > > code interfacing with the mmio space. > > > > > > > I'll admit to being motivated by entirely selfish reasons. I know > > practically nothing about nouveau and I'm the type of person who likes > > to keep notes about how things work together, both free form and > > structured in-line docs. All that to say, I think focusing on the > > "low-hanging fruit" stuff will be very beneficial and I'm happy to do > > that, but I'm also interested in documenting everything else I run > > across. > > > > yeah, that's fine. I was just giving a suggestion on where the initial > focus should be on. > > > > Eg some users have problems with their fans as they are either always > > > ramping up to max, or not running at all... GPUs temperature or power > > > consumption is reporting incorrectly... all those things users hit > > > regularly, but which isn't really important enough so it just falls > > > under the table even if it gets reported. > > > > > > > This does bring up an interesting point about organization and target > > audiences. Typically when I'm writing documentation I like to organize > > things by target audiences, so we could have a layout like: > > > > * General Introduction > > > > * User Guide > > - Overview of supported hardware/features/etc > > That's best to document in a wiki though. And we had plans to convert > the existing old wiki over to gitlab. And maybe It think we really > should do that and clean it up while we work on that. It's just a huge > project but maybe just starting with whatever you want to do would be > fine and after a while nothing is left. Anyway, I think we should > discuss this more openly with the others as well. i don't like the > current wiki anyway, as only approved developers can change things and > with a gitlab wiki we could even take MRs on stuff. > Yeah, so I think there's going to be at least three separate locations for documentation: Envytools (hardware), the nouveau wiki (user guide), and in the kernel (developer-focused and only the kernel bits). I don't know much about the userspace bits yet, so maybe there's going to be more than three places. I think it'd be good to at least cross-reference between the wiki and the kernel docs, so this "section" could really just be a link to the nouveau wiki for folks who end up in the kernel docs, but really just want to use things (and maybe new developers who haven't historically been users, such as myself). > > - Installation > > well.. I think this can be skipped ;) But still, also belongs more > into a wiki. I think what we could cover here is to how to clean up > remaining stuff from the blob driver as this is something which comes > up quite a lot on IRC though. > > > - Configuration (module parameters and such) > > - Troubleshooting > > that would be cool to have in the wiki as well. Just collecting the > most common issue and document it there. Especially if it is on > gitlab, users can just do that as well :) > > > - Getting Involved (bug reporting, running tests, etc) > > yeah, and we have some stuff on that on the old wiki already, it's > just very outdated and needs updating, which as said above can only be > done by developers and developers sadly have other things to do :) > > > > > * Developer Guide > > - Architecture Overview > > - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > > - Internal APIs > > Right, those things I'd like to see in the kernel tree actually. > > > - Debugging and Development Tools > > - Contribution Guide > > > > Those I think belong more into the wiki again. The latter is a bit > hard to split as there are kernel guides, but also community and > project guides. Mesa does things differently than let's say the > kernel. And Nouveau is still in this limbo state being on the old > infra, but also on the new one with mesa... > > > I'm not sure how much stuff people want to keep on the > > nouveau.freedesktop.org wiki vs her
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 01:56:32PM +0100, Roy Spliet wrote: > > Op 23-09-2020 om 22:36 schreef Karol Herbst: > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > > > > > > On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > > > > On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: > > > > > > > > > > > > > yeah, I think overall this file is a good idea and being able to get a > > > > quick overview over the driver is helpful. I think if we focus on the > > > > user facing things first, like the hwmon or other things users > > > > generally interact with would be helpful. I think if we start to > > > > document areas where there are many low hanging fruits, this could > > > > help random people to start with easier tasks and get more used to the > > > > driver overall, so I'd probably ignore most of the stuff which really > > > > requires a fundamental understanding on how things work and focus more > > > > on vbios parsing (which has annoying interfaces anyway and it might > > > > make sense to make it more consistent and nicer to use) and/or simple > > > > code interfacing with the mmio space. > > > > > > > > > > I'll admit to being motivated by entirely selfish reasons. I know > > > practically nothing about nouveau and I'm the type of person who likes > > > to keep notes about how things work together, both free form and > > > structured in-line docs. All that to say, I think focusing on the > > > "low-hanging fruit" stuff will be very beneficial and I'm happy to do > > > that, but I'm also interested in documenting everything else I run > > > across. > > > > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > focus should be on. > > > > > > Eg some users have problems with their fans as they are either always > > > > ramping up to max, or not running at all... GPUs temperature or power > > > > consumption is reporting incorrectly... all those things users hit > > > > regularly, but which isn't really important enough so it just falls > > > > under the table even if it gets reported. > > > > > > > > > > This does bring up an interesting point about organization and target > > > audiences. Typically when I'm writing documentation I like to organize > > > things by target audiences, so we could have a layout like: > > > > > > * General Introduction > > > > > > * User Guide > > > - Overview of supported hardware/features/etc > > > > That's best to document in a wiki though. And we had plans to convert > > the existing old wiki over to gitlab. And maybe It think we really > > should do that and clean it up while we work on that. It's just a huge > > project but maybe just starting with whatever you want to do would be > > fine and after a while nothing is left. Anyway, I think we should > > discuss this more openly with the others as well. i don't like the > > current wiki anyway, as only approved developers can change things and > > with a gitlab wiki we could even take MRs on stuff. > > > > > - Installation > > > > well.. I think this can be skipped ;) But still, also belongs more > > into a wiki. I think what we could cover here is to how to clean up > > remaining stuff from the blob driver as this is something which comes > > up quite a lot on IRC though. > > > > > - Configuration (module parameters and such) > > > - Troubleshooting > > > > that would be cool to have in the wiki as well. Just collecting the > > most common issue and document it there. Especially if it is on > > gitlab, users can just do that as well :) > > > > > - Getting Involved (bug reporting, running tests, etc) > > > > yeah, and we have some stuff on that on the old wiki already, it's > > just very outdated and needs updating, which as said above can only be > > done by developers and developers sadly have other things to do :) > > > > > > > > * Developer Guide > > > - Architecture Overview > > > - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > > > - Internal APIs > > > > Right, those things I'd like to see in the kernel tree actually. > > > > > - Debugging and Development Tools > > > - Contribution Guide > > > > > > > Those I think belong more into the wiki again. The latter is a bit > > hard to split as there are kernel guides, but also community and > > project guides. Mesa does things differently than let's say the > > kernel. And Nouveau is still in this limbo state being on the old > > infra, but also on the new one with mesa... > > > > > I'm not sure how much stuff people want to keep on the > > > nouveau.freedesktop.org wiki vs here. > > > > > > > I think the first step actually is to set up a proper nouveau project > > on gitlab for dealing with issues and the wiki. I would be fine to do > > that and we can also move the code there late. But maybe let's start > > with the wiki :) > > Risking to turn this into a "let's fix everything in one go" project that > ends up never get
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 3:06 PM Roy Spliet wrote: > > > Op 23-09-2020 om 22:36 schreef Karol Herbst: > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > >> > >> On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > >>> On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: > >> > >> > >> > >>> yeah, I think overall this file is a good idea and being able to get a > >>> quick overview over the driver is helpful. I think if we focus on the > >>> user facing things first, like the hwmon or other things users > >>> generally interact with would be helpful. I think if we start to > >>> document areas where there are many low hanging fruits, this could > >>> help random people to start with easier tasks and get more used to the > >>> driver overall, so I'd probably ignore most of the stuff which really > >>> requires a fundamental understanding on how things work and focus more > >>> on vbios parsing (which has annoying interfaces anyway and it might > >>> make sense to make it more consistent and nicer to use) and/or simple > >>> code interfacing with the mmio space. > >>> > >> > >> I'll admit to being motivated by entirely selfish reasons. I know > >> practically nothing about nouveau and I'm the type of person who likes > >> to keep notes about how things work together, both free form and > >> structured in-line docs. All that to say, I think focusing on the > >> "low-hanging fruit" stuff will be very beneficial and I'm happy to do > >> that, but I'm also interested in documenting everything else I run > >> across. > >> > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > focus should be on. > > > >>> Eg some users have problems with their fans as they are either always > >>> ramping up to max, or not running at all... GPUs temperature or power > >>> consumption is reporting incorrectly... all those things users hit > >>> regularly, but which isn't really important enough so it just falls > >>> under the table even if it gets reported. > >>> > >> > >> This does bring up an interesting point about organization and target > >> audiences. Typically when I'm writing documentation I like to organize > >> things by target audiences, so we could have a layout like: > >> > >> * General Introduction > >> > >> * User Guide > >> - Overview of supported hardware/features/etc > > > > That's best to document in a wiki though. And we had plans to convert > > the existing old wiki over to gitlab. And maybe It think we really > > should do that and clean it up while we work on that. It's just a huge > > project but maybe just starting with whatever you want to do would be > > fine and after a while nothing is left. Anyway, I think we should > > discuss this more openly with the others as well. i don't like the > > current wiki anyway, as only approved developers can change things and > > with a gitlab wiki we could even take MRs on stuff. > > > >> - Installation > > > > well.. I think this can be skipped ;) But still, also belongs more > > into a wiki. I think what we could cover here is to how to clean up > > remaining stuff from the blob driver as this is something which comes > > up quite a lot on IRC though. > > > >> - Configuration (module parameters and such) > >> - Troubleshooting > > > > that would be cool to have in the wiki as well. Just collecting the > > most common issue and document it there. Especially if it is on > > gitlab, users can just do that as well :) > > > >> - Getting Involved (bug reporting, running tests, etc) > > > > yeah, and we have some stuff on that on the old wiki already, it's > > just very outdated and needs updating, which as said above can only be > > done by developers and developers sadly have other things to do :) > > > >> > >> * Developer Guide > >> - Architecture Overview > >> - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > >> - Internal APIs > > > > Right, those things I'd like to see in the kernel tree actually. > > > >> - Debugging and Development Tools > >> - Contribution Guide > >> > > > > Those I think belong more into the wiki again. The latter is a bit > > hard to split as there are kernel guides, but also community and > > project guides. Mesa does things differently than let's say the > > kernel. And Nouveau is still in this limbo state being on the old > > infra, but also on the new one with mesa... > > > >> I'm not sure how much stuff people want to keep on the > >> nouveau.freedesktop.org wiki vs here. > >> > > > > I think the first step actually is to set up a proper nouveau project > > on gitlab for dealing with issues and the wiki. I would be fine to do > > that and we can also move the code there late. But maybe let's start > > with the wiki :) > > Risking to turn this into a "let's fix everything in one go" project > that ends up never getting finished, I just want to make sure that > everybody is also aware of the documentation generated from Envyto
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
On Thu, Sep 24, 2020 at 9:06 AM Roy Spliet wrote: > > > Op 23-09-2020 om 22:36 schreef Karol Herbst: > > On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: > >> > >> On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: > >>> On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: > >> > >> > >> > >>> yeah, I think overall this file is a good idea and being able to get a > >>> quick overview over the driver is helpful. I think if we focus on the > >>> user facing things first, like the hwmon or other things users > >>> generally interact with would be helpful. I think if we start to > >>> document areas where there are many low hanging fruits, this could > >>> help random people to start with easier tasks and get more used to the > >>> driver overall, so I'd probably ignore most of the stuff which really > >>> requires a fundamental understanding on how things work and focus more > >>> on vbios parsing (which has annoying interfaces anyway and it might > >>> make sense to make it more consistent and nicer to use) and/or simple > >>> code interfacing with the mmio space. > >>> > >> > >> I'll admit to being motivated by entirely selfish reasons. I know > >> practically nothing about nouveau and I'm the type of person who likes > >> to keep notes about how things work together, both free form and > >> structured in-line docs. All that to say, I think focusing on the > >> "low-hanging fruit" stuff will be very beneficial and I'm happy to do > >> that, but I'm also interested in documenting everything else I run > >> across. > >> > > > > yeah, that's fine. I was just giving a suggestion on where the initial > > focus should be on. > > > >>> Eg some users have problems with their fans as they are either always > >>> ramping up to max, or not running at all... GPUs temperature or power > >>> consumption is reporting incorrectly... all those things users hit > >>> regularly, but which isn't really important enough so it just falls > >>> under the table even if it gets reported. > >>> > >> > >> This does bring up an interesting point about organization and target > >> audiences. Typically when I'm writing documentation I like to organize > >> things by target audiences, so we could have a layout like: > >> > >> * General Introduction > >> > >> * User Guide > >> - Overview of supported hardware/features/etc > > > > That's best to document in a wiki though. And we had plans to convert > > the existing old wiki over to gitlab. And maybe It think we really > > should do that and clean it up while we work on that. It's just a huge > > project but maybe just starting with whatever you want to do would be > > fine and after a while nothing is left. Anyway, I think we should > > discuss this more openly with the others as well. i don't like the > > current wiki anyway, as only approved developers can change things and > > with a gitlab wiki we could even take MRs on stuff. > > > >> - Installation > > > > well.. I think this can be skipped ;) But still, also belongs more > > into a wiki. I think what we could cover here is to how to clean up > > remaining stuff from the blob driver as this is something which comes > > up quite a lot on IRC though. > > > >> - Configuration (module parameters and such) > >> - Troubleshooting > > > > that would be cool to have in the wiki as well. Just collecting the > > most common issue and document it there. Especially if it is on > > gitlab, users can just do that as well :) > > > >> - Getting Involved (bug reporting, running tests, etc) > > > > yeah, and we have some stuff on that on the old wiki already, it's > > just very outdated and needs updating, which as said above can only be > > done by developers and developers sadly have other things to do :) > > > >> > >> * Developer Guide > >> - Architecture Overview > >> - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? > >> - Internal APIs > > > > Right, those things I'd like to see in the kernel tree actually. > > > >> - Debugging and Development Tools > >> - Contribution Guide > >> > > > > Those I think belong more into the wiki again. The latter is a bit > > hard to split as there are kernel guides, but also community and > > project guides. Mesa does things differently than let's say the > > kernel. And Nouveau is still in this limbo state being on the old > > infra, but also on the new one with mesa... > > > >> I'm not sure how much stuff people want to keep on the > >> nouveau.freedesktop.org wiki vs here. > >> > > > > I think the first step actually is to set up a proper nouveau project > > on gitlab for dealing with issues and the wiki. I would be fine to do > > that and we can also move the code there late. But maybe let's start > > with the wiki :) > > Risking to turn this into a "let's fix everything in one go" project > that ends up never getting finished, I just want to make sure that > everybody is also aware of the documentation generated from Envyto
Re: [Nouveau] [RFC] Documentation: nouveau: Introduce some nouveau documentation
Op 23-09-2020 om 22:36 schreef Karol Herbst: On Wed, Sep 23, 2020 at 10:39 PM Jeremy Cline wrote: On Wed, Sep 23, 2020 at 09:02:45PM +0200, Karol Herbst wrote: On Fri, Sep 11, 2020 at 6:21 PM Jeremy Cline wrote: yeah, I think overall this file is a good idea and being able to get a quick overview over the driver is helpful. I think if we focus on the user facing things first, like the hwmon or other things users generally interact with would be helpful. I think if we start to document areas where there are many low hanging fruits, this could help random people to start with easier tasks and get more used to the driver overall, so I'd probably ignore most of the stuff which really requires a fundamental understanding on how things work and focus more on vbios parsing (which has annoying interfaces anyway and it might make sense to make it more consistent and nicer to use) and/or simple code interfacing with the mmio space. I'll admit to being motivated by entirely selfish reasons. I know practically nothing about nouveau and I'm the type of person who likes to keep notes about how things work together, both free form and structured in-line docs. All that to say, I think focusing on the "low-hanging fruit" stuff will be very beneficial and I'm happy to do that, but I'm also interested in documenting everything else I run across. yeah, that's fine. I was just giving a suggestion on where the initial focus should be on. Eg some users have problems with their fans as they are either always ramping up to max, or not running at all... GPUs temperature or power consumption is reporting incorrectly... all those things users hit regularly, but which isn't really important enough so it just falls under the table even if it gets reported. This does bring up an interesting point about organization and target audiences. Typically when I'm writing documentation I like to organize things by target audiences, so we could have a layout like: * General Introduction * User Guide - Overview of supported hardware/features/etc That's best to document in a wiki though. And we had plans to convert the existing old wiki over to gitlab. And maybe It think we really should do that and clean it up while we work on that. It's just a huge project but maybe just starting with whatever you want to do would be fine and after a while nothing is left. Anyway, I think we should discuss this more openly with the others as well. i don't like the current wiki anyway, as only approved developers can change things and with a gitlab wiki we could even take MRs on stuff. - Installation well.. I think this can be skipped ;) But still, also belongs more into a wiki. I think what we could cover here is to how to clean up remaining stuff from the blob driver as this is something which comes up quite a lot on IRC though. - Configuration (module parameters and such) - Troubleshooting that would be cool to have in the wiki as well. Just collecting the most common issue and document it there. Especially if it is on gitlab, users can just do that as well :) - Getting Involved (bug reporting, running tests, etc) yeah, and we have some stuff on that on the old wiki already, it's just very outdated and needs updating, which as said above can only be done by developers and developers sadly have other things to do :) * Developer Guide - Architecture Overview - External APIs (include/uapi/drm/nouveau_drm.h, any sysfs stuff)? - Internal APIs Right, those things I'd like to see in the kernel tree actually. - Debugging and Development Tools - Contribution Guide Those I think belong more into the wiki again. The latter is a bit hard to split as there are kernel guides, but also community and project guides. Mesa does things differently than let's say the kernel. And Nouveau is still in this limbo state being on the old infra, but also on the new one with mesa... I'm not sure how much stuff people want to keep on the nouveau.freedesktop.org wiki vs here. I think the first step actually is to set up a proper nouveau project on gitlab for dealing with issues and the wiki. I would be fine to do that and we can also move the code there late. But maybe let's start with the wiki :) Risking to turn this into a "let's fix everything in one go" project that ends up never getting finished, I just want to make sure that everybody is also aware of the documentation generated from Envytools [0]. Especially "architecture overview" (that is, if we're talking about hardware architecture and not driver/software architecture) might be better suited in envytools. As for module parameters, IMHO modinfo is supposed to be the source of information. It's sadly lacking any "sub-"option inside nouveau.config and nouveau.debug, which may be by design. Perhaps expanding the modinfo explanations can help cover at least all the other options in a way that never gets out of sync wi
Re: [Nouveau] [PATCH 0/6] drm/nouveau: Support sync FDs and sync objects
On Thu, Sep 24, 2020 at 12:05 PM Thierry Reding wrote: > > On Wed, Sep 23, 2020 at 05:21:24PM +0200, Daniel Vetter wrote: > > On Wed, Sep 23, 2020 at 11:18:53AM +0200, Thierry Reding wrote: > > > On Fri, Aug 28, 2020 at 12:40:10PM +0200, Thierry Reding wrote: > > > > From: Thierry Reding > > > > > > > > Hi, > > > > > > > > This series implements a new IOCTL to submit push buffers that can > > > > optionally return a sync FD or sync object to userspace. This is useful > > > > in cases where userspace wants to synchronize operations between the GPU > > > > and another driver (such as KMS for display). Among other things this > > > > allows extensions such as eglDupNativeFenceFDANDROID to be implemented. > > > > > > > > Note that patch 4 modifies the ABI introduced in patch 3 by allowing DRM > > > > sync objects to be passed rather than only sync FDs. It also allows any > > > > number of sync FDs/objects to be passed in or emitted. I think those are > > > > useful features, but I left them in a separate patch in case everybody > > > > else thinks that this won't be needed. If we decide to merge the new ABI > > > > then patch 4 should be squashed into patch 3. > > > > > > > > The corresponding userspace changes can be found here: > > > > > > > > libdrm: > > > > https://gitlab.freedesktop.org/tagr/drm/-/commits/nouveau-sync-fd-v2/ > > > > mesa: > > > > https://gitlab.freedesktop.org/tagr/mesa/-/commits/nouveau-sync-fd/ > > > > > > > > I've verified that this works with kmscube's --atomic mode and Weston. > > > > > > Hi Ben, > > > > > > any thoughts on this series? I realize that this is somewhat suboptimal > > > because we're effectively adding a duplicate of the existing IOCTL with > > > only the "minor" extension of adding sync FDs/objects, but at the same > > > time I don't have any good ideas on what else to add to make this more > > > appealing or if you have any plans of your own to address this in the > > > future. > > > > drm core automatically zero-extends ioctl structs both ways, so if all you > > do is add more stuff to the top level ioctl struct at the bottom, there's > > no need to duplicate any code. At least as long as you guarantee that 0 == > > old behaviour for both in and out parameters. > > But that only works if the structure size remains fixed, right? In this > case, however, we have to extend the structure with additional fields, > so the size is going to change and therefore the IOCTL number will also > change. Nope, drm_ioctl() is pretty much magic, and will zero-extend size mismatches in both ways. Which means you can run userspace compile against old kernels (so user_sz > kernel_sz) and you can run old userspace on new kernels (so user_sz < kernel_sz) and it will all work correctly. No need to allocate new ioctl numbers for this case, just extend at the bottom. We're doing this pretty much all the time. You might still want a getparam (or explicit flag, if all versions of that ioctl validated the flags correctly) since doing since a dummy pushbuf on an old kernel won't result in anything getting rejected. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch ___ Nouveau mailing list Nouveau@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/nouveau
Re: [Nouveau] [PATCH 0/6] drm/nouveau: Support sync FDs and sync objects
On Wed, Sep 23, 2020 at 05:21:24PM +0200, Daniel Vetter wrote: > On Wed, Sep 23, 2020 at 11:18:53AM +0200, Thierry Reding wrote: > > On Fri, Aug 28, 2020 at 12:40:10PM +0200, Thierry Reding wrote: > > > From: Thierry Reding > > > > > > Hi, > > > > > > This series implements a new IOCTL to submit push buffers that can > > > optionally return a sync FD or sync object to userspace. This is useful > > > in cases where userspace wants to synchronize operations between the GPU > > > and another driver (such as KMS for display). Among other things this > > > allows extensions such as eglDupNativeFenceFDANDROID to be implemented. > > > > > > Note that patch 4 modifies the ABI introduced in patch 3 by allowing DRM > > > sync objects to be passed rather than only sync FDs. It also allows any > > > number of sync FDs/objects to be passed in or emitted. I think those are > > > useful features, but I left them in a separate patch in case everybody > > > else thinks that this won't be needed. If we decide to merge the new ABI > > > then patch 4 should be squashed into patch 3. > > > > > > The corresponding userspace changes can be found here: > > > > > > libdrm: > > > https://gitlab.freedesktop.org/tagr/drm/-/commits/nouveau-sync-fd-v2/ > > > mesa: > > > https://gitlab.freedesktop.org/tagr/mesa/-/commits/nouveau-sync-fd/ > > > > > > I've verified that this works with kmscube's --atomic mode and Weston. > > > > Hi Ben, > > > > any thoughts on this series? I realize that this is somewhat suboptimal > > because we're effectively adding a duplicate of the existing IOCTL with > > only the "minor" extension of adding sync FDs/objects, but at the same > > time I don't have any good ideas on what else to add to make this more > > appealing or if you have any plans of your own to address this in the > > future. > > drm core automatically zero-extends ioctl structs both ways, so if all you > do is add more stuff to the top level ioctl struct at the bottom, there's > no need to duplicate any code. At least as long as you guarantee that 0 == > old behaviour for both in and out parameters. But that only works if the structure size remains fixed, right? In this case, however, we have to extend the structure with additional fields, so the size is going to change and therefore the IOCTL number will also change. Thierry signature.asc Description: PGP signature ___ Nouveau mailing list Nouveau@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/nouveau
