1*4882a593Smuzhiyun============ 2*4882a593SmuzhiyunIntroduction 3*4882a593Smuzhiyun============ 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunThe Linux DRM layer contains code intended to support the needs of 6*4882a593Smuzhiyuncomplex graphics devices, usually containing programmable pipelines well 7*4882a593Smuzhiyunsuited to 3D graphics acceleration. Graphics drivers in the kernel may 8*4882a593Smuzhiyunmake use of DRM functions to make tasks like memory management, 9*4882a593Smuzhiyuninterrupt handling and DMA easier, and provide a uniform interface to 10*4882a593Smuzhiyunapplications. 11*4882a593Smuzhiyun 12*4882a593SmuzhiyunA note on versions: this guide covers features found in the DRM tree, 13*4882a593Smuzhiyunincluding the TTM memory manager, output configuration and mode setting, 14*4882a593Smuzhiyunand the new vblank internals, in addition to all the regular features 15*4882a593Smuzhiyunfound in current kernels. 16*4882a593Smuzhiyun 17*4882a593Smuzhiyun[Insert diagram of typical DRM stack here] 18*4882a593Smuzhiyun 19*4882a593SmuzhiyunStyle Guidelines 20*4882a593Smuzhiyun================ 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunFor consistency this documentation uses American English. Abbreviations 23*4882a593Smuzhiyunare written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so 24*4882a593Smuzhiyunon. To aid in reading, documentations make full use of the markup 25*4882a593Smuzhiyuncharacters kerneldoc provides: @parameter for function parameters, 26*4882a593Smuzhiyun@member for structure members (within the same structure), &struct structure to 27*4882a593Smuzhiyunreference structures and function() for functions. These all get automatically 28*4882a593Smuzhiyunhyperlinked if kerneldoc for the referenced objects exists. When referencing 29*4882a593Smuzhiyunentries in function vtables (and structure members in general) please use 30*4882a593Smuzhiyun&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the 31*4882a593Smuzhiyunmember, only the structure. 32*4882a593Smuzhiyun 33*4882a593SmuzhiyunExcept in special situations (to separate locked from unlocked variants) 34*4882a593Smuzhiyunlocking requirements for functions aren't documented in the kerneldoc. 35*4882a593SmuzhiyunInstead locking should be check at runtime using e.g. 36*4882a593Smuzhiyun``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore 37*4882a593Smuzhiyundocumentation than runtime noise this provides more value. And on top of 38*4882a593Smuzhiyunthat runtime checks do need to be updated when the locking rules change, 39*4882a593Smuzhiyunincreasing the chances that they're correct. Within the documentation 40*4882a593Smuzhiyunthe locking rules should be explained in the relevant structures: Either 41*4882a593Smuzhiyunin the comment for the lock explaining what it protects, or data fields 42*4882a593Smuzhiyunneed a note about which lock protects them, or both. 43*4882a593Smuzhiyun 44*4882a593SmuzhiyunFunctions which have a non-\ ``void`` return value should have a section 45*4882a593Smuzhiyuncalled "Returns" explaining the expected return values in different 46*4882a593Smuzhiyuncases and their meanings. Currently there's no consensus whether that 47*4882a593Smuzhiyunsection name should be all upper-case or not, and whether it should end 48*4882a593Smuzhiyunin a colon or not. Go with the file-local style. Other common section 49*4882a593Smuzhiyunnames are "Notes" with information for dangerous or tricky corner cases, 50*4882a593Smuzhiyunand "FIXME" where the interface could be cleaned up. 51*4882a593Smuzhiyun 52*4882a593SmuzhiyunAlso read the :ref:`guidelines for the kernel documentation at large <doc_guide>`. 53*4882a593Smuzhiyun 54*4882a593SmuzhiyunDocumentation Requirements for kAPI 55*4882a593Smuzhiyun----------------------------------- 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunAll kernel APIs exported to other modules must be documented, including their 58*4882a593Smuzhiyundatastructures and at least a short introductory section explaining the overall 59*4882a593Smuzhiyunconcepts. Documentation should be put into the code itself as kerneldoc comments 60*4882a593Smuzhiyunas much as reasonable. 61*4882a593Smuzhiyun 62*4882a593SmuzhiyunDo not blindly document everything, but document only what's relevant for driver 63*4882a593Smuzhiyunauthors: Internal functions of drm.ko and definitely static functions should not 64*4882a593Smuzhiyunhave formal kerneldoc comments. Use normal C comments if you feel like a comment 65*4882a593Smuzhiyunis warranted. You may use kerneldoc syntax in the comment, but it shall not 66*4882a593Smuzhiyunstart with a /** kerneldoc marker. Similar for data structures, annotate 67*4882a593Smuzhiyunanything entirely private with ``/* private: */`` comments as per the 68*4882a593Smuzhiyundocumentation guide. 69*4882a593Smuzhiyun 70*4882a593SmuzhiyunGetting Started 71*4882a593Smuzhiyun=============== 72*4882a593Smuzhiyun 73*4882a593SmuzhiyunDevelopers interested in helping out with the DRM subsystem are very welcome. 74*4882a593SmuzhiyunOften people will resort to sending in patches for various issues reported by 75*4882a593Smuzhiyuncheckpatch or sparse. We welcome such contributions. 76*4882a593Smuzhiyun 77*4882a593SmuzhiyunAnyone looking to kick it up a notch can find a list of janitorial tasks on 78*4882a593Smuzhiyunthe :ref:`TODO list <todo>`. 79*4882a593Smuzhiyun 80*4882a593SmuzhiyunContribution Process 81*4882a593Smuzhiyun==================== 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunMostly the DRM subsystem works like any other kernel subsystem, see :ref:`the 84*4882a593Smuzhiyunmain process guidelines and documentation <process_index>` for how things work. 85*4882a593SmuzhiyunHere we just document some of the specialities of the GPU subsystem. 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunFeature Merge Deadlines 88*4882a593Smuzhiyun----------------------- 89*4882a593Smuzhiyun 90*4882a593SmuzhiyunAll feature work must be in the linux-next tree by the -rc6 release of the 91*4882a593Smuzhiyuncurrent release cycle, otherwise they must be postponed and can't reach the next 92*4882a593Smuzhiyunmerge window. All patches must have landed in the drm-next tree by latest -rc7, 93*4882a593Smuzhiyunbut if your branch is not in linux-next then this must have happened by -rc6 94*4882a593Smuzhiyunalready. 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunAfter that point only bugfixes (like after the upstream merge window has closed 97*4882a593Smuzhiyunwith the -rc1 release) are allowed. No new platform enabling or new drivers are 98*4882a593Smuzhiyunallowed. 99*4882a593Smuzhiyun 100*4882a593SmuzhiyunThis means that there's a blackout-period of about one month where feature work 101*4882a593Smuzhiyuncan't be merged. The recommended way to deal with that is having a -next tree 102*4882a593Smuzhiyunthat's always open, but making sure to not feed it into linux-next during the 103*4882a593Smuzhiyunblackout period. As an example, drm-misc works like that. 104*4882a593Smuzhiyun 105*4882a593SmuzhiyunCode of Conduct 106*4882a593Smuzhiyun--------------- 107*4882a593Smuzhiyun 108*4882a593SmuzhiyunAs a freedesktop.org project, dri-devel, and the DRM community, follows the 109*4882a593SmuzhiyunContributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct 110*4882a593Smuzhiyun 111*4882a593SmuzhiyunPlease conduct yourself in a respectful and civilised manner when 112*4882a593Smuzhiyuninteracting with community members on mailing lists, IRC, or bug 113*4882a593Smuzhiyuntrackers. The community represents the project as a whole, and abusive 114*4882a593Smuzhiyunor bullying behaviour is not tolerated by the project. 115