Add /proc/mempool to display mempool usage
Subsystems (10)
PATCH RESEND 1/1 Add /proc/mempool to display mempool usage
This patch add a new /proc/mempool file in order to display mempool usage.
The feature can be disabled with CONFIG_PROC_MEMPOOL=N during kernel configuration.
Patch againt 2.6.28-rc6.
---
Add /proc/mempool to display mempool usage.
Can be disabled with CONFIG_PROC_MEMPOOL=N
Resend #1 : cosmetic cleaning.
block/blk-core.c | 2 +- drivers/block/pktcdvd.c | 4 ++-- drivers/block/virtio_blk.c | 2 +- drivers/md/dm-crypt.c | 4 ++-- drivers/md/dm-io.c | 2 +- drivers/md/dm-raid1.c | 2 +- drivers/md/dm-region-hash.c | 2 +- drivers/md/multipath.c | 2 +- drivers/md/raid1.c | 7 +++---- drivers/md/raid10.c | 5 +++-- fs/bio.c | 2 +- fs/proc/Kconfig | 6 ++++++ fs/proc/Makefile | 1 + include/linux/mempool.h | 40 +++++++++++++++++++++++++++++++--------- mm/bounce.c | 4 ++-- mm/mempool.c | 42 +++++++++++++++++++++++++++++++++++++++--- 16 files changed, 96 insertions(+), 31 deletions(-)
block/blk-core.c +1 -1
@@ -483,7 +483,7 @@ static int blk_init_free_list(struct reqinit_waitqueue_head (&rl->wait[WRITE ]); rl->rq_pool =mempool_create_node (BLKDEV_MIN_RQ , mempool_alloc_slab, - mempool_free_slab, request_cachep, q->node); + mempool_free_slab, request_cachep, q->node,"blk_rq" ,MEMPOOL_SLAB );if (!rl->rq_pool)return -ENOMEM ;
drivers/block/pktcdvd.c +2 -2
@@ -2879,7 +2879,7 @@ static int pkt_setup_dev(dev_t dev, dev_ goto out_mutex; pd->rb_pool =mempool_create_kmalloc_pool (PKT_RB_POOL_SIZE , -sizeof (struct pkt_rb_node )); +sizeof (struct pkt_rb_node ),"pkt_rb" );if (!pd->rb_pool) goto out_mem;
@@ -3070,7 +3070,7 @@ static int __init pkt_init(void)mutex_init (&ctl_mutex); psd_pool =mempool_create_kmalloc_pool (PSD_POOL_SIZE , -sizeof (struct packet_stacked_data )); +sizeof (struct packet_stacked_data ),"pkt_psd" );if (!psd_pool)return -ENOMEM ;
drivers/block/virtio_blk.c +1 -1
@@ -230,7 +230,7 @@ static int virtblk_probe(struct virtio_d goto out_free_vblk; } - vblk->pool =mempool_create_kmalloc_pool (1 ,sizeof (struct virtblk_req )); + vblk->pool =mempool_create_kmalloc_pool (1 ,sizeof (struct virtblk_req ),"vblk" );if (!vblk->pool) { err = -ENOMEM ; goto out_free_vq;
drivers/md/dm-crypt.c +2 -2
@@ -1047,14 +1047,14 @@ static int crypt_ctr(struct dm_target *t ~(crypto_tfm_ctx_alignment () -1 ); cc->req_pool =mempool_create_kmalloc_pool (MIN_IOS , cc->dmreq_start + -sizeof (struct dm_crypt_request ) + cc->iv_size); +sizeof (struct dm_crypt_request ) + cc->iv_size,"dm-crypt_req" );if (!cc->req_pool) { ti->error ="Cannot allocate crypt request mempool" ; goto bad_req_pool; } cc->req =NULL ; - cc->page_pool =mempool_create_page_pool (MIN_POOL_PAGES ,0 ); + cc->page_pool =mempool_create_page_pool (MIN_POOL_PAGES ,0 ,"dm-crypt_page" );if (!cc->page_pool) { ti->error ="Cannot allocate page mempool" ; goto bad_page_pool;
drivers/md/dm-io.c +1 -1
@@ -52,7 +52,7 @@ struct dm_io_client *dm_io_client_createif (!client)return ERR_PTR (-ENOMEM ); - client->pool =mempool_create_kmalloc_pool (ios,sizeof (struct io )); + client->pool =mempool_create_kmalloc_pool (ios,sizeof (struct io ),"dm-io_client" );if (!client->pool) goto bad;
drivers/md/dm-raid1.c +1 -1
@@ -766,7 +766,7 @@ static struct mirror_set *alloc_context( len =sizeof (struct dm_raid1_read_record ); ms->read_record_pool =mempool_create_kmalloc_pool (MIN_READ_RECORDS , - len); + len,"dm-raid read record" );if (!ms->read_record_pool) { ti->error ="Error creating mirror read_record_pool" ;kfree (ms);
drivers/md/dm-region-hash.c +1 -1
@@ -214,7 +214,7 @@ struct dm_region_hash *dm_region_hash_crINIT_LIST_HEAD (&rh->failed_recovered_regions); rh->region_pool =mempool_create_kmalloc_pool (MIN_REGIONS , -sizeof (struct dm_region )); +sizeof (struct dm_region ),"md-region-hash" );if (!rh->region_pool) {vfree (rh->buckets);kfree (rh);
drivers/md/multipath.c +1 -1
@@ -475,7 +475,7 @@ static int multipath_run (mddev_t *mddev mddev->degraded = conf->raid_disks - conf->working_disks; conf->pool =mempool_create_kzalloc_pool (NR_RESERVED_BUFS , -sizeof (struct multipath_bh )); +sizeof (struct multipath_bh ),"multipath_bh" );if (conf->pool ==NULL ) { printk(KERN_ERR "multipath: couldn't allocate memory for %s\n",
drivers/md/raid10.c +3 -2
@@ -1636,7 +1636,8 @@ static int init_resync(conf_t *conf) buffs =RESYNC_WINDOW /RESYNC_BLOCK_SIZE ;BUG_ON (conf->r10buf_pool); - conf->r10buf_pool =mempool_create (buffs, r10buf_pool_alloc, r10buf_pool_free, conf); + conf->r10buf_pool =mempool_create (buffs, r10buf_pool_alloc, r10buf_pool_free, conf, +"md_r10buf" ,MEMPOOL_PRIVATE );if (!conf->r10buf_pool)return -ENOMEM ; conf->next_resync =0 ;
@@ -2097,7 +2098,7 @@ static int run(mddev_t *mddev) conf->stride = stride << conf->chunk_shift; conf->r10bio_pool =mempool_create (NR_RAID10_BIOS , r10bio_pool_alloc, - r10bio_pool_free, conf); + r10bio_pool_free, conf,"md_r10bio" ,MEMPOOL_PRIVATE );if (!conf->r10bio_pool) {printk (KERN_ERR "raid10: couldn't allocate memory for %s\n" ,mdname (mddev));
drivers/md/raid1.c +3 -4
@@ -1678,7 +1678,7 @@ static int init_resync(conf_t *conf) buffs =RESYNC_WINDOW /RESYNC_BLOCK_SIZE ;BUG_ON (conf->r1buf_pool); conf->r1buf_pool =mempool_create (buffs, r1buf_pool_alloc, r1buf_pool_free, - conf->poolinfo); + conf->poolinfo,"md_r1buf" ,MEMPOOL_PRIVATE );if (!conf->r1buf_pool)return -ENOMEM ; conf->next_resync =0 ;
@@ -1955,8 +1955,7 @@ static int run(mddev_t *mddev) conf->poolinfo->mddev = mddev; conf->poolinfo->raid_disks = mddev->raid_disks; conf->r1bio_pool =mempool_create (NR_RAID1_BIOS , r1bio_pool_alloc, - r1bio_pool_free, - conf->poolinfo); + r1bio_pool_free, conf->poolinfo,"md_r1bio" ,MEMPOOL_PRIVATE );if (!conf->r1bio_pool) goto out_no_mem;
@@ -2170,7 +2169,7 @@ static int raid1_reshape(mddev_t *mddev) newpoolinfo->raid_disks = raid_disks; newpool =mempool_create (NR_RAID1_BIOS , r1bio_pool_alloc, - r1bio_pool_free, newpoolinfo); + r1bio_pool_free, newpoolinfo,"md_raid1" ,MEMPOOL_PRIVATE );if (!newpool) {kfree (newpoolinfo);return -ENOMEM ;
fs/bio.c +1 -1
@@ -1428,7 +1428,7 @@ static int __init init_bio(void)panic ("bio: can't allocate bios\n" ); bio_split_pool =mempool_create_kmalloc_pool (BIO_SPLIT_ENTRIES , -sizeof (struct bio_pair )); +sizeof (struct bio_pair ),"bio_pair" );if (!bio_split_pool)panic ("bio: can't create split pool\n" );
fs/proc/Kconfig +6 -0
@@ -67,3 +67,9 @@ config PROC_PAGE_MONITOR /proc/pid/smaps, /proc/pid/clear_refs, /proc/pid/pagemap, /proc/kpagecount, and /proc/kpageflags. Disabling these interfaces will reduce the size of the kernel by approximately 4kb. + +config PROC_MEMPOOL + default y + bool "Enable /proc mempool" + help + Display mempool created and usage
fs/proc/Makefile +1 -0
@@ -26,3 +26,4 @@ proc-$(CONFIG_PROC_VMCORE) += vmcore.o proc-$(CONFIG_PROC_DEVICETREE) += proc_devtree.o proc-$(CONFIG_PRINTK) += kmsg.o proc-$(CONFIG_PROC_PAGE_MONITOR) += page.o +proc-$(CONFIG_PROC_MEMPOOL) += mempool.o
include/linux/mempool.h +31 -9
@@ -18,15 +18,33 @@ typedef struct mempool_s {void **elements;void *pool_data; +struct list_head list; +char * name; +unsigned int size; +unsigned short type;mempool_alloc_t *alloc;mempool_free_t *free;wait_queue_head_t wait; } mempool_t; +extern struct list_head mempool_list; +extern rwlock_t mempool_lock; + +enum MEMPOOL_TYPE { +MEMPOOL_SLAB , +MEMPOOL_KMALLOC , +MEMPOOL_KZALLOC , +MEMPOOL_PAGE , +MEMPOOL_PRIVATE ,/* For private or default usage */ +MEMPOOL_NR_TYPES +}; +extern mempool_t *mempool_create (int min_nr,mempool_alloc_t *alloc_fn, -mempool_free_t *free_fn,void *pool_data); +mempool_free_t *free_fn,void *pool_data,const char *name, +unsigned short type);extern mempool_t *mempool_create_node (int min_nr,mempool_alloc_t *alloc_fn, -mempool_free_t *free_fn,void *pool_data,int nid); +mempool_free_t *free_fn,void *pool_data,int nid,const char *name, +unsigned short type);extern int mempool_resize (mempool_t *pool,int new_min_nr,gfp_t gfp_mask);extern void mempool_destroy (mempool_t *pool);
@@ -42,8 +60,9 @@ void mempool_free_slab(void *element, vostatic inline mempool_t *mempool_create_slab_pool (int min_nr,struct kmem_cache *kc) { +const char *name =kmem_cache_name (kc);return mempool_create (min_nr, mempool_alloc_slab, mempool_free_slab, - (void *) kc); + (void *) kc, name,MEMPOOL_SLAB ); }/*
@@ -53,15 +72,17 @@ mempool_create_slab_pool(int min_nr, strvoid *mempool_kmalloc (gfp_t gfp_mask,void *pool_data);void *mempool_kzalloc (gfp_t gfp_mask,void *pool_data);void mempool_kfree (void *element,void *pool_data); -static inline mempool_t *mempool_create_kmalloc_pool (int min_nr,size_t size) +static inline mempool_t *mempool_create_kmalloc_pool (int min_nr,size_t size, +const char * name) {return mempool_create (min_nr, mempool_kmalloc, mempool_kfree, - (void *) size); + (void *) size, name,MEMPOOL_KMALLOC ); } -static inline mempool_t *mempool_create_kzalloc_pool (int min_nr,size_t size) +static inline mempool_t *mempool_create_kzalloc_pool (int min_nr,size_t size, +const char * name) {return mempool_create (min_nr, mempool_kzalloc, mempool_kfree, - (void *) size); + (void *) size, name,MEMPOOL_KMALLOC ); }/*
@@ -70,10 +91,11 @@ static inline mempool_t *mempool_create_*/ void *mempool_alloc_pages (gfp_t gfp_mask,void *pool_data);void mempool_free_pages (void *element,void *pool_data); -static inline mempool_t *mempool_create_page_pool (int min_nr,int order) +static inline mempool_t *mempool_create_page_pool (int min_nr,int order, +const char * name) {return mempool_create (min_nr, mempool_alloc_pages, mempool_free_pages, - (void *)(long )order); + (void *)(long )order, name,MEMPOOL_PAGE ); }#endif /* _LINUX_MEMPOOL_H */
mm/bounce.c +2 -2
@@ -31,7 +31,7 @@ static __init int init_emergency_pool(voif (!i.totalhigh)return 0 ; - page_pool =mempool_create_page_pool (POOL_SIZE ,0 ); + page_pool =mempool_create_page_pool (POOL_SIZE ,0 ,"highmem_bounce" );BUG_ON (!page_pool);printk ("highmem bounce pool size: %d pages\n" ,POOL_SIZE );
@@ -80,7 +80,7 @@ int init_emergency_isa_pool(void)return 0 ; isa_page_pool =mempool_create (ISA_POOL_SIZE , mempool_alloc_pages_isa, - mempool_free_pages, (void *)0 ); + mempool_free_pages, (void *)0 ,"isa_page_pool" ,MEMPOOL_PAGE );BUG_ON (!isa_page_pool);printk ("isa bounce pool size: %d pages\n" ,ISA_POOL_SIZE );
mm/mempool.c +39 -3
71 lines not on this page · raw message
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.
We're NOT adding config option per proc file.
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
Quoted 10 lines · Alexey Dobriyan
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.We're NOT adding config option per proc file.
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
debugfs has been open for random stuff since the day it was added to the tree :)
Feel free to put this kind of thing there instead of proc.
thanks,
greg k-h
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 9 lines · Greg KH
Quoted 8 lines · Alexey Dobriyan
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.We're NOT adding config option per proc file.
Quoted 8 lines
Quoted 2 lines
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
debugfs has been open for random stuff since the day it was added to the tree :)
Feel free to put this kind of thing there instead of proc.
Acknowledged,
Quoted 3 lines
thanks,
greg k-h
Thanks,
Remi
Quoted 9 lines · On Sat, 29 Nov 2008 15:49:07 -0800 Greg KH wrote:
Quoted 8 lines · Alexey Dobriyan
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.We're NOT adding config option per proc file.
Quoted 7 lines
Quoted 2 lines
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
debugfs has been open for random stuff since the day it was added to the tree :)
Feel free to put this kind of thing there instead of proc.
Do distros ship with debugfs enabled?
The problem with using debugfs is that it is very optional IMO.
---
~Randy
Quoted 14 lines · Randy Dunlap
Quoted 12 lines · On Sat, 29 Nov 2008 15:49:07 -0800 Greg KH wrote:
Quoted 10 lines · Alexey Dobriyan
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.We're NOT adding config option per proc file.
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
Quoted 7 lines
Quoted 4 lines
debugfs has been open for random stuff since the day it was added to the tree :)
Feel free to put this kind of thing there instead of proc.
Do distros ship with debugfs enabled?
The problem with using debugfs is that it is very optional IMO.
The problem with debugfs is that it claims to not be an ABI but it is lying. Distributions ship tools that depend on portions of debugfs. And they also ship debugfs in their kernel. So it is effectively the same as /proc, except with the 1.0-era everything-goes attitude rather than the 2.6-era we-should-really-think-about-this one.
Pushing stuff from procfs to debugfs is thus just setting us up for pain down the road. Don't do it. In five years, we'll discover we can't turn debugfs off or even clean it up because too much relies on it.
If you think that debugfs is NOT an ABI, then I'm sure you'll be happy to ack my patch entitled 'gratuitously break usbmon to remind folks that debugfs is not an ABI'.
Signature · 1 line
Mathematics is the supreme nostalgia of our time.
Andrew Morton
maintainerQuoted 29 lines · On Mon, 01 Dec 2008 13:13:31 -0600 Matt Mackall…
Quoted 14 lines · Randy Dunlap
Quoted 12 lines · On Sat, 29 Nov 2008 15:49:07 -0800 Greg KH wrote:
Quoted 10 lines · Alexey Dobriyan
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.We're NOT adding config option per proc file.
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
Quoted 7 lines
Quoted 4 lines
debugfs has been open for random stuff since the day it was added to the tree :)
Feel free to put this kind of thing there instead of proc.
Do distros ship with debugfs enabled?
The problem with using debugfs is that it is very optional IMO.The problem with debugfs is that it claims to not be an ABI but it is lying. Distributions ship tools that depend on portions of debugfs. And they also ship debugfs in their kernel. So it is effectively the same as /proc, except with the 1.0-era everything-goes attitude rather than the 2.6-era we-should-really-think-about-this one.
Quoted 7 lines
Pushing stuff from procfs to debugfs is thus just setting us up for pain down the road. Don't do it. In five years, we'll discover we can't turn debugfs off or even clean it up because too much relies on it.
If you think that debugfs is NOT an ABI, then I'm sure you'll be happy to ack my patch entitled 'gratuitously break usbmon to remind folks that debugfs is not an ABI'.
^^ yup.
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 36 lines · Andrew Morton
Quoted 33 lines · On Mon, 01 Dec 2008 13:13:31 -0600 Matt Mackall <[email protected]> wrote:
Quoted 14 lines · Randy Dunlap
Quoted 12 lines · On Sat, 29 Nov 2008 15:49:07 -0800 Greg KH wrote:
Quoted 10 lines · Alexey Dobriyan
Quoted 4 lines · Remi Colinet
This patch add a new
/proc/mempoolfile in order to display mempool usage.The feature can be disabled with
CONFIG_PROC_MEMPOOL=Nduring kernel configuration.We're NOT adding config option per proc file.
And can we, please, freeze /proc for not per-process stuff and open debugfs for random stuff, please?
Quoted 7 lines
Quoted 4 lines
debugfs has been open for random stuff since the day it was added to the tree :)
Feel free to put this kind of thing there instead of proc.
Do distros ship with debugfs enabled?
The problem with using debugfs is that it is very optional IMO.The problem with debugfs is that it claims to not be an ABI but it is lying. Distributions ship tools that depend on portions of debugfs. And they also ship debugfs in their kernel. So it is effectively the same as /proc, except with the 1.0-era everything-goes attitude rather than the 2.6-era we-should-really-think-about-this one.
Pushing stuff from procfs to debugfs is thus just setting us up for pain down the road. Don't do it. In five years, we'll discover we can't turn debugfs off or even clean it up because too much relies on it.
Quoted 5 lines
Quoted 3 lines
If you think that debugfs is NOT an ABI, then I'm sure you'll be happy to ack my patch entitled 'gratuitously break usbmon to remind folks that debugfs is not an ABI'.
^^ yup.
Hmm, I thought Documentation/ABI/ was supposed to tell us what's an ABI you can depend on and what's not. I mean, you shouldn't be depending on anything but the interfaces documented in Documentation/ABI/stable/, no?
Quoted 5 lines · Pekka Enberg
Hmm, I thought
Documentation/ABI/was supposed to tell us what's an ABI you can depend on and what's not. I mean, you shouldn't be depending on anything but the interfaces documented inDocumentation/ABI/stable/, no?
Who is the f*cking MORON that thinks that "documentation" has any meaning what-so-ever?
The fact that something is documented (whether correctly or not) has absolutely _zero_ impact on anything at all. What makes something an ABI is that it's useful and available. The only way something isn't an ABI is by _explicitly_ making sure that it's not available even by mistake in a stable form for binary use.
Example: kernel internal data structures and function calls. We make sure that you simply _cannot_ make a binary that works across kernel versions. That is the only way for an ABI to not form.
Linus
Quoted 6 lines · Linus Torvalds
The fact that something is documented (whether correctly or not) has absolutely _zero_ impact on anything at all. What makes something an ABI is that it's useful and available. The only way something isn't an ABI is by _explicitly_ making sure that it's not available even by mistake in a stable form for binary use.
Of course, the alternate form is to make it so _useless_ that people won't use it even if it's available, and I guess we do have those kinds of interfaces too. But we generally don't need to worry about unused and useless interfaces very much, so it doesn't tend to matter much.
Linus
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Linus,
Quoted 4 lines · Pekka Enberg
Quoted 4 lines
Hmm, I thought
Documentation/ABI/was supposed to tell us what's an ABI you can depend on and what's not. I mean, you shouldn't be depending on anything but the interfaces documented inDocumentation/ABI/stable/, no?
Quoted 2 lines · Linus Torvalds
Who is the f*cking MORON that thinks that "documentation" has any meaning what-so-ever?
Me, I suppose. At least that's the impression I got when being asked to document any new kmemtrace debugfs files, for example.
Quoted 5 lines · Linus Torvalds
The fact that something is documented (whether correctly or not) has absolutely _zero_ impact on anything at all. What makes something an ABI is that it's useful and available. The only way something isn't an ABI is by _explicitly_ making sure that it's not available even by mistake in a stable form for binary use.
OK, but why do we have those different ABI "stages" in Documentation/ABI then? The README file there seems to contradict what you say. Or maybe I'm reading it wrong...
Pekka
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 24 lines · Pekka Enberg
Hi Linus,
Quoted 4 lines · Pekka Enberg
Quoted 4 lines
Hmm, I thought
Documentation/ABI/was supposed to tell us what's an ABI you can depend on and what's not. I mean, you shouldn't be depending on anything but the interfaces documented inDocumentation/ABI/stable/, no?Quoted 2 lines · Linus Torvalds
Who is the f*cking MORON that thinks that "documentation" has any meaning what-so-ever?
Me, I suppose. At least that's the impression I got when being asked to document any new kmemtrace debugfs files, for example.
Quoted 5 lines · Linus Torvalds
The fact that something is documented (whether correctly or not) has absolutely _zero_ impact on anything at all. What makes something an ABI is that it's useful and available. The only way something isn't an ABI is by _explicitly_ making sure that it's not available even by mistake in a stable form for binary use.
Quoted 3 lines
OK, but why do we have those different ABI "stages" in
Documentation/ABIthen? The README file there seems to contradict what you say. Or maybe I'm reading it wrong...
If the terrain and the map do not agree, follow the terrain. – Swedish army manual.
If code uses a public interface and we break that interface, we will get unhappy users. Putting stuff in debugfs/ in a released kernel makes it public. That's the terrain.
Signature · 6 lines
Mathematics is the supreme nostalgia of our time. -- To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 4 lines · Pekka Enberg
OK, but why do we have those different ABI "stages" in
Documentation/ABIthen? The README file there seems to contradict what you say. Or maybe I'm reading it wrong...
I think that whole Documentation/ABI stuff is utter tosh, and should just be thrown out, whenever it talks about interfaces that are _not_ ABI's.
IOW, it's fine to document things that are actually supposed to be stable, but:
- assuming that non-documentation means that it's not an ABI is bogus and wrong.
- explicitly documenting something as "not an ABI" is wrongheaded and stupid, because it's meaningless and only sets people up for being disappointed later.
So yeah, I think we might as well remove the "testing" one. Right now it can act in two ways:
- as documentation on how to use it (ie as "stable").
This is fine, but then it shouldn't be called "testing", should it?
- as an excuse for whining later when it _did_ get used, and people break exported ABI's, and we need to revert the breakage.
And this is the one that I don't think is valid. No amount of documentation will ever make something less stable.
So as far as I'm concerned, "testing" should either go away (as a way to discourage people from even _knowing_ about the things, and hoping that they never get used), or it should be moved to "stable".
And in the end, nothing is ever totally black-and-white or quite that simple, but that's the mindset you should have.
Finally, when it comes to documentation as a bigger issue:
- wrong documentation is irrelevant. It doesn't matter if the documentation says "X", when the code does "Y".
If people rely on "Y", then pointing at the docs and saying "but you should never have relied on it, because teh docs say X" is totally and utterly bogus. The _documentation_ was wrong. Don't ever use incorrect documentation as an excuse.
Too many people seem to think that documentation is the "final" argument. It's not. Not even close. It's a hint and a help, but it's _secondary_ to code. Anybody who doesn't understand that should never be allowed to write code (or documentation, for that matte).
[ The same is true of assert()'s in code too - I've seen too many damn
asserts that were simply _wrong_, and then when they triggered, people would always blindly assume that the assert() was right, and try to change the code to suit. For some reason people have a hard time asking themselves whether perhaps the bug was in the assertion itself. ]
Linus
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 8 lines · Linus Torvalds
Quoted 4 lines · Pekka Enberg
OK, but why do we have those different ABI "stages" in
Documentation/ABIthen? The README file there seems to contradict what you say. Or maybe I'm reading it wrong...
Quoted 8 lines
I think that whole
Documentation/ABIstuff is utter tosh, and should just be thrown out, whenever it talks about interfaces that are _not_ ABI's.IOW, it's fine to document things that are actually supposed to be stable, but:
- assuming that non-documentation means that it's not an ABI is bogus and wrong.
Agreed. (When so much is much is undocumented anyway, there is no way that lack of documentation can be used to signal "this is not an ABI.)
Quoted 3 lines
- explicitly documenting something as "not an ABI" is wrongheaded and stupid, because it's meaningless and only sets people up for being disappointed later.
Agreed.
[...]
Quoted 9 lines
Finally, when it comes to documentation as a bigger issue:
- wrong documentation is irrelevant. It doesn't matter if the documentation says "X", when the code does "Y".
If people rely on "Y", then pointing at the docs and saying "but you should never have relied on it, because teh docs say X" is totally and utterly bogus. The _documentation_ was wrong. Don't ever use incorrect documentation as an excuse.
Agreed.
Quoted 4 lines
Too many people seem to think that documentation is the "final" argument. It's not. Not even close. It's a hint and a help, but it's _secondary_ to code. Anybody who doesn't understand that should never be allowed to write code (or documentation, for that matte).
While clearly documentation is not the final answer, I think you undervalue it somewhat, and I think it's worth mentioning two specific points. Documentation may be secondary to code, but it can help a lot, especially if:
* The documentation is done at the same time as the code (by the developer, or by someone working with the developer). This typically makes the developer think more about the code they are writing. It also gives others to more quickly understand the code with the aim of reviewing the code and/or API design, and perhaps testing it. There simply isn't enough review and testing going on, and documentation can make a real difference there, IMO.
* While the "but you should never have relied on it, because the docs say X" argument may not hold, there is one important way that I think documentation can still help: explicitly saying that "the behavior is unspecified around point X, and other code should not rely on a specific behavior". This legitimately allows developers to change the behavior around point X in the future. (I made the point at LPC, if you force users to read the code behind an API, then you end up creating a "tight spec", since they will do exactly what the code permits. In this sense, documentation can be used to "loosen" the spec.)
Cheers,
Michael
Signature · 9 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html