diff options
| -rw-r--r-- | share/man/man9/g_access.9 | 62 | ||||
| -rw-r--r-- | share/man/man9/g_attach.9 | 28 | ||||
| -rw-r--r-- | share/man/man9/g_bio.9 | 52 | ||||
| -rw-r--r-- | share/man/man9/g_consumer.9 | 22 | ||||
| -rw-r--r-- | share/man/man9/g_data.9 | 37 | ||||
| -rw-r--r-- | share/man/man9/g_event.9 | 51 | ||||
| -rw-r--r-- | share/man/man9/g_provider.9 | 44 | ||||
| -rw-r--r-- | share/man/man9/g_provider_by_name.9 | 4 | ||||
| -rw-r--r-- | share/man/man9/g_wither_geom.9 | 20 |
9 files changed, 171 insertions, 149 deletions
diff --git a/share/man/man9/g_access.9 b/share/man/man9/g_access.9 index a14d2f4..1b4bf61 100644 --- a/share/man/man9/g_access.9 +++ b/share/man/man9/g_access.9 @@ -29,7 +29,7 @@ .Os .Sh NAME .Nm g_access -.Nd "control access count between given consumer and its provider" +.Nd "control access to GEOM consumers and their providers" .Sh SYNOPSIS .In geom/geom.h .Ft int @@ -37,26 +37,29 @@ .Sh DESCRIPTION The .Fn g_access -function allows to open/change access to/close the provider which is -attached to the given consumer +function allows to open, close, and generally change access to the provider +which is attached to the given consumer .Fa cp . -Arguments +The arguments .Fa dcr , .Fa dcw , +and .Fa dce -stand for read, write and exclusive access count change. -Read and write access are self explanatory. -Exclusive access count prevents others write access. -Provider's access count is the sum of all attached consumers counts. -After attaching to the provider with -.Fn g_attach -function, one have to use +represent relative read, write, and exclusive access count changes. +Read and write access counts are self explanatory, and +exclusive access counts deny write access to other interested parties. +A provider's access count is the sum of the access counts of all +attached consumers. +.Pp +After attaching a consumer to a provider with +.Fn g_attach , +the .Fn g_access -function before starting I/O requests. +function has to be called on the consumer before starting I/O requests. .Sh RESTRICTIONS/CONDITIONS -The consumer must be attached. +The consumer has to be attached to a provider. .Pp -Change cannot result in negative access count. +The intended change must not result in a negative access count. .Pp No\-operation is not permitted .Fa ( dcr @@ -67,17 +70,18 @@ No\-operation is not permitted = .Va 0 ) . .Pp -Access method for provider's geom have to be defined (eg. gp->access). +The provider's geom must have an access method defined (eg. gp->access). .Pp -The topology lock must be held. +The topology lock has to be held. .Sh RETURN VALUES -.Fn g_attach -returns the value 0 if successful; otherwise an error code is returned. -Note, that +The .Fn g_access -function cannot failed when arguments +function returns 0 if successful; otherwise an error code is returned. +Note that +.Fn g_access +cannot fail when the arguments .Fa dcr , -.Fa dcw +.Fa dcw , and .Fa dce are less than or equal to 0. @@ -85,17 +89,17 @@ are less than or equal to 0. Possible errors: .Bl -tag -width Er .It Bq Er EPERM -The function is trying to open with exclusive access count, but provider -is already open for writting. +The function is trying to open a provider with an exclusive access count, but +it is already open for writing. .It Bq Er EPERM -The function is trying to open for write, but provider is already exclusively -open. +The function is trying to open a provider for writing, but it is already +exclusively open. .El .Pp -Any other error, than can be returned by provider's access method. +Any other error that can be returned by the provider's access method. .Sh EXAMPLES -Create consumer, attach it to given provider, gain read access and read first -sector. +Create a consumer, attach it to a given provider, gain read access and +read first sector. .Bd -literal -offset indent void some_function(struct g_geom *mygeom, struct g_provider *pp) @@ -123,7 +127,7 @@ some_function(struct g_geom *mygeom, struct g_provider *pp) } /* - * Don't hold toplogy lock while reading. + * Don't hold topology lock while reading. */ g_topology_unlock(); ptr = g_read_data(cp, 0, pp->sectorsize, &error); diff --git a/share/man/man9/g_attach.9 b/share/man/man9/g_attach.9 index 6fcaf58..d3ac053 100644 --- a/share/man/man9/g_attach.9 +++ b/share/man/man9/g_attach.9 @@ -30,7 +30,7 @@ .Sh NAME .Nm g_attach , .Nm g_detach -.Nd "attach/detach consumer to/from provider" +.Nd "attach/detach GEOM consumers to/from providers" .Sh SYNOPSIS .In geom/geom.h .Ft int @@ -40,23 +40,26 @@ .Sh DESCRIPTION The .Fn g_attach -function attaches given consumer to given provider. -For real provider access (ie. I/O operations), one still need to call the -.Fn g_access -function on consumer to gain access to attached provider. +function attaches given consumer +.Fa cp +to given provider +.Fa pp , +thus establishing a communication channel between the consumer and the +provider that allows to change access counts or perform I/O operations. .Pp The .Fn g_detach -function detaches the given consumer from the corresponding provider. -This function is used when we do not want to communicate with the -provider anymore. +function detaches given consumer +.Fa cp +from its corresponding provider, tearing down the communication channel +between them. .Sh RESTRICTIONS/CONDITIONS .Fn g_attach : .Bl -item -offset indent .It -The consumer can not be attached already. +The consumer must not be attached to a provider. .It -The operation should not create a topology loop. +The operation must not create a topology loop. .It The topology lock has to be held. .El @@ -73,8 +76,9 @@ There must be no active requests. The topology lock has to be held. .El .Sh RETURN VALUES +The .Fn g_attach -returns the value 0 if successful; otherwise an error code is returned. +function returns 0 if successful; otherwise an error code is returned. .Sh ERRORS Possible errors: .Bl -tag -width Er @@ -82,7 +86,7 @@ Possible errors: The operation creates a topology loop. .El .Sh EXAMPLES -Create consumer, attach it to given provider, gain read access and clean up. +Create a consumer, attach it to a given provider, gain read access and clean up. .Bd -literal -offset indent void some_function(struct g_geom *mygeom, struct g_provider *pp) diff --git a/share/man/man9/g_bio.9 b/share/man/man9/g_bio.9 index 42236c5..898ad76 100644 --- a/share/man/man9/g_bio.9 +++ b/share/man/man9/g_bio.9 @@ -32,7 +32,7 @@ .Nm g_clone_bio , .Nm g_destroy_bio , .Nm g_print_bio -.Nd "bio controlling functions" +.Nd "GEOM bio controlling functions" .Sh SYNOPSIS .In sys/bio.h .In geom/geom.h @@ -45,30 +45,28 @@ .Ft void .Fn g_print_bio "struct bio *bp" .Sh DESCRIPTION -The -.Fa bio -structure is used by GEOM to describe I/O requests. -Most important fields of +A .Fa struct bio -are described below: +is used by GEOM to describe I/O requests, its +most important fields are described below: .Bl -tag -width ".Va bio_attribute" .It Va bio_cmd -I/O request number. +I/O request command. There are four I/O requests available in GEOM: .Bl -tag -width BIO_GETATTR .It Dv BIO_READ -Self explanatory. +A read request. .It Dv BIO_WRITE -Self explanatory. +A write request. .It Dv BIO_DELETE -Delete indicates that a certain range of data is no longer used and that +Indicates that a certain range of data is no longer used and that it can be erased or freed as the underlying technology supports. Technologies like flash adaptation layers can arrange to erase the relevant blocks before they will become reassigned and cryptographic devices may want to fill random bits into the range to reduce the amount of data available for attack. .It Dv BIO_GETATTR -Get attribute supports inspection and manipulation of out\-of\-band +Inspect and manipulate out\-of\-band attributes on a particular provider or path. Attributes are named by ascii strings and are stored in the .Va bio_attribute @@ -83,8 +81,8 @@ Available flags: .Bl -tag -width BIO_GETATTR .It Dv BIO_ERROR Request failed (error value is stored in -.Va bio_error ) -field. +.Va bio_error +field). .It Dv BIO_DONE Request finished. .It Dv BIO_FLAG1 @@ -95,7 +93,7 @@ Avaliable for private use. .It Va bio_error Error value when BIO_ERROR is set. .It Va bio_done -Pointer to function which will be called on request finish. +Pointer to function which will be called when the request is finished. .It Va bio_driver1 Private use by the callee (ie: the provider). .It Va bio_driver2 @@ -135,9 +133,9 @@ The .Fn g_clone_bio function allocates a new .Vt bio -structure and copies those fields from the +structure and copies the following fields from the .Vt bio -structure given as an argument to clone: +given as an argument to clone: .Va bio_cmd , .Va bio_length , .Va bio_offset , @@ -145,11 +143,13 @@ structure given as an argument to clone: .Va bio_attribute . The field .Va bio_parent -in clone is set to source +in the clone points to the passed .Vt bio and the field .Va bio_children -in parent is increased. +in the passed +.Vt bio +is incremented. .Pp This function should be used for every request which enters through the provider of a particular geom and needs to be scheduled down. @@ -157,7 +157,7 @@ Proper order is: .Pp .Bl -enum -compact .It -Clone +Clone the received .Vt "struct bio" . .It Modify the clone. @@ -167,15 +167,23 @@ Schedule the clone on its own consumer. .Pp The .Fn g_destroy_bio -function kills the given +function deallocates and destroys the given .Vt bio structure. .Pp The .Fn g_print_bio -function prints informations about given +function prints information about the given .Vt bio -structure. +structure (for debugging purposes). +.Sh RETURN VALUES +The +.Fn g_new_bio +and +.Fn g_clone_bio +functions return a pointer to the allocated +.Vt bio , +or NULL if an error occurred. .Sh EXAMPLES Implementation of .Dq Dv NULL Ns \-transformation , diff --git a/share/man/man9/g_consumer.9 b/share/man/man9/g_consumer.9 index f0b5b1c..7e94191 100644 --- a/share/man/man9/g_consumer.9 +++ b/share/man/man9/g_consumer.9 @@ -38,34 +38,34 @@ .Ft void .Fn g_destroy_consumer "struct g_consumer *cp" .Sh DESCRIPTION -The GEOM consumer is the backdoor through which a geom connects to +A GEOM consumer is the backdoor through which a geom connects to another GEOM provider and through which I/O requests are sent. .Pp The .Fn g_new_consumer -function creates a new consumer releated to geom +function creates a new consumer on geom .Fa gp . -The consumer is unusable prior attaching to a provider and gaining access -to it. -To serve its purpose, the consumer has to be attached to a provider -with the +Before using the new consumer, it has to be attached to a provider with .Xr g_attach 9 -function. +and opened with +.Xr g_access 9 . .Pp The .Fn g_destroy_consumer -function destroys given consumer and cancels all related pending events. +function destroys the given consumer and cancels all related pending events. This function is the last stage of killing an unwanted consumer. .Pp .Sh RESTRICTIONS/CONDITIONS .Fn g_new_consumer : .Bl -item -offset indent .It -The geom related to the created consumer must have the +The geom +.Fa gp +has to have .Fa start and .Fa access -fields defined. +methods defined. .It The topology lock has to be held. .El @@ -73,7 +73,7 @@ The topology lock has to be held. .Fn g_destroy_consumer : .Bl -item -offset indent .It -The consumer can not be attached. +The consumer must not be attached to a provider. .It The access count has to be 0. .It diff --git a/share/man/man9/g_data.9 b/share/man/man9/g_data.9 index ebacf05..7bc7882 100644 --- a/share/man/man9/g_data.9 +++ b/share/man/man9/g_data.9 @@ -30,7 +30,7 @@ .Sh NAME .Nm g_read_data , .Nm g_write_data -.Nd "read/write data through consumer" +.Nd "read/write data from/to GEOM consumer" .Sh SYNOPSIS .In geom/geom.h .Ft "void *" @@ -40,19 +40,19 @@ .Sh DESCRIPTION The .Fn g_read_data -reads +function reads .Fa length -bytes of data from a provider through attached consumer -.Fa cp +bytes of data from the provider attached to consumer +.Fa cp , starting at offset .Fa offset . -Memory for data is allocated inside +The buffer returned from .Fn g_read_data -with +is allocated with .Fn g_malloc , -and should therefor be freed by the caller with the +so it should be freed by the caller with .Fn g_free -function after use. +after use. If the operation fails, an error value will be stored in the .Fa error argument if it is not @@ -60,16 +60,17 @@ argument if it is not .Pp The .Fn g_write_data -writes +function writes .Fa length -bytes of data from address +bytes of data from the buffer pointed to by .Fa ptr +to the provider attached to consumer +.Fa cp , starting at offset -.Fa offset -to a provider through the attached consumer -.Fa cp . +.Fa offset . .Sh RESTRICTIONS/CONDITIONS -Length of data should be a multiple of the sectorsize for the provider +.Fa length +should be a multiple of the provider's sectorsize and less than or equal to .Dv DFLTPHYS .Dv ( DFLTPHYS is defined in @@ -77,17 +78,19 @@ and less than or equal to .Pp The topology lock must not be held. .Sh RETURN VALUES +The .Fn g_read_data -returns a pointer to the read data or +function returns a pointer to a data buffer or .Dv NULL if an error occured. In that case an error value is stored in the .Fa error -argument unsless it is +argument unless it is .Dv NULL . .Pp +The .Fn g_write_data -returns the value 0 if successful; otherwise an error code is returned. +function returns 0 if successful; otherwise an error code is returned. .Sh ERRORS Possible errors: .Bl -tag -width Er diff --git a/share/man/man9/g_event.9 b/share/man/man9/g_event.9 index 7585b4c..f0a512c 100644 --- a/share/man/man9/g_event.9 +++ b/share/man/man9/g_event.9 @@ -31,7 +31,7 @@ .Nm g_post_event , .Nm g_waitfor_event , .Nm g_cancel_event -.Nd "events management" +.Nd "GEOM events management" .Sh SYNOPSIS .In geom/geom.h .Ft int @@ -41,34 +41,33 @@ .Ft void .Fn g_cancel_event "void *ref" .Sh DESCRIPTION -The GEOM has its own event queue to inform classes about important things. -The event queue can be also used by classes, mostly for running away -from I/O path. -Sleeping, heavy weight tasks, etc. are not permitted on I/O path and -events are the cure to avoid such situations. +The GEOM framework has its own event queue to inform classes about important +events. +The event queue can be also used by GEOM classes themselves, for example +to work around some restrictions in the I/O path, where sleeping, heavy weight +tasks, etc. are not permitted. .Pp The .Fn g_post_event -function tells GEOM to call function +function tells the GEOM framework to call function .Fa func with argument .Fa arg from the event queue. The .Fa flag -argument is a flag for +argument is passed to .Xr malloc 9 -that should be used by GEOM. -Only the flags +for memory allocations inside of +.Fn g_post_event . +The only allowed flags are .Dv M_WAITOK -or -.Dv M_NOWAIT -can be used. -The rest of the arguments are used as references. -An event can be canceled by using any of given references as an -argument to the -.Fn g_cancel_event -function. +and +.Dv M_NOWAIT . +The rest of the arguments are used as references to identify the event. +An event can be canceled by using any of the given references as an +argument to +.Fn g_cancel_event . The list of references has to end with a .Dv NULL value. @@ -82,7 +81,7 @@ It waits until the event is finished or canceled and then returns. .Pp The .Fn g_cancel_event -function cancels event(s) identified by +function cancels all event(s) identified by .Fa ref . Cancellation is equivalent to calling the requested function with requested arguments and argument @@ -128,24 +127,28 @@ in a deadlock. .Fn g_post_event and .Fn g_waitfor_event -returns the value 0 if successful; otherwise an error code is returned. +return 0 if successful; otherwise an error code is returned. .Sh ERRORS -Possible errors for +Possible errors for the .Fn g_post_event function: .Bl -tag -width Er .It Bq Er ENOMEM -There was insufficient memory. +The +.Fa flag +argument was set to M_NOWAIT and there was insufficient memory. .El .Pp -Possible errors for +Possible errors for the .Fn g_waitfor_event function: .Bl -tag -width Er .It Bq Er EAGAIN The event was canceled. .It Bq Er ENOMEM -There was insufficient memory. +The +.Fa flag +argument was set to M_NOWAIT and there was insufficient memory. .El .Sh EXAMPLES Example of a function called from the event queue. diff --git a/share/man/man9/g_provider.9 b/share/man/man9/g_provider.9 index 5cda1ec..40b2e04 100644 --- a/share/man/man9/g_provider.9 +++ b/share/man/man9/g_provider.9 @@ -41,7 +41,7 @@ .Ft void .Fn g_error_provider "struct g_provider *pp" "int error" .Sh DESCRIPTION -The GEOM provider is the front gate at which a geom offers service. +A GEOM provider is the front gate at which a geom offers service. A provider is .Dq a disk\-like thing which appears in Pa /dev \- a logical disk in other words. @@ -49,33 +49,30 @@ All providers have three main properties: name, sectorsize and size. .Pp The .Fn g_new_providerf -function creates a new provider and attaches it to geom +function creates a new provider on given geom .Fa gp . -The provider name is created in a printf\-like way from the rest of +The name of the provider, which will appear as device in devfs, is created +in a printf\-like way from the rest of the arguments. -After creation, the provider is unusable, because -.Fn g_new_providerf -sets its error to -.Er ENXIO . -The function -.Fn g_error_provider -should be used to reset this error, but before it is called, two -fields should be set in the provider structure: +After creation, the caller has to set the provider's .Va mediasize and -.Va sectorsize -as well as other initialization things should be done first. +.Va sectorsize , +as well as other desired initializations, and then call +.Fn g_error_provider +to reset the provider's error, which is initially set to +.Er ENXIO . .Pp The .Fn g_destroy_provider function destroys the given provider, cancels all related pending events and -removes corresponding devfs entry. +removes the corresponding devfs entry. .Pp The .Fn g_error_provider -function is used to set a provider error value. -If it set to a nonzero value, all I/O requests will be denied, -increasing its access count will not be possible (error +function is used to set the provider's error value. +If set to a nonzero, all I/O requests will be denied, +as well as increasing its access count will not be possible (error .Fa error will be returned). .Sh RESTRICTIONS/CONDITIONS @@ -84,11 +81,13 @@ will be returned). .It The provider name should be unique, but this is not enforced by GEOM. If the name is not unique, one will end up with two (or more) files -with the same name, which is programmer error. +with the same name, which is a programmer error. .It -The geom related to the created provider must have +The geom +.Fa gp +has to have a .Fa start -field defined. +method defined. .It The topology lock has to be held. .El @@ -96,15 +95,16 @@ The topology lock has to be held. .Fn g_destroy_provider : .Bl -item -offset indent .It -No consumers have to be attached. +The provider must not have consumers attached. .It The access count has to be 0. .It The topology lock has to be held. .El .Sh RETURN VALUES +The .Fn g_new_providerf -returns a pointer to the newly created provider. +function returns a pointer to the newly created provider. .Sh EXAMPLES Create an example provider, set its parameters and make it usable. .Bd -literal -offset indent diff --git a/share/man/man9/g_provider_by_name.9 b/share/man/man9/g_provider_by_name.9 index 4756949..bb59f29 100644 --- a/share/man/man9/g_provider_by_name.9 +++ b/share/man/man9/g_provider_by_name.9 @@ -29,7 +29,7 @@ .Os .Sh NAME .Nm g_provider_by_name -.Nd "find provider with given name" +.Nd "find GEOM provider with given name" .Sh SYNOPSIS .In geom/geom.h .Ft "struct g_provider *" @@ -37,7 +37,7 @@ .Sh DESCRIPTION The .Fn g_provider_by_name -searches for a provider called +function searches for a provider called .Fa name and returns the structure .Fa g_provider diff --git a/share/man/man9/g_wither_geom.9 b/share/man/man9/g_wither_geom.9 index 1e5258a..b4ceff0 100644 --- a/share/man/man9/g_wither_geom.9 +++ b/share/man/man9/g_wither_geom.9 @@ -29,7 +29,7 @@ .Os .Sh NAME .Nm g_wither_geom -.Nd "destroy geom and releated providers and consumers when you get a chance" +.Nd "destroy geom and related providers and consumers when you get a chance" .Sh SYNOPSIS .In geom/geom.h .Ft void @@ -40,12 +40,12 @@ The function tells GEOM that geom .Fa gp is to be destroyed. -GEOM sets an error for every provider related to the given geom (in -orphan process) and waits for a chance to destroy the geom. -If access count of any possessed consumer goes to 0, consumer will be +GEOM sets an error on each provider of the given geom (in the +orphaning process) and waits for a chance to destroy the geom. +If the access count of any possessed consumer goes to 0, the consumer will be detached and destroyed automatically. -If last consumer attached to any possesed provider will be detached, -provider will be destroyed. +If the last consumer attached to any possessed provider will be detached, +the provider will be destroyed. If there are no more providers nor consumers, the geom will be destroyed. .Pp @@ -58,10 +58,10 @@ should be disposed off and set to .Dv NULL . Note that the .Fn g_wither_geom -function gives no guarantee that geom will be immediately destroyed, mostly -because access counts of corresponding consumers and providers may not be 0. -That is why calling this function for every geom from given class is not enough -to be sure that class can be unloaded. +function gives no guarantee that the geom will be immediately destroyed, mostly +because the access counts of the geom's consumers and providers may not be 0. +That is why calling this function for every geom from a given class is not enough +to be sure that the class can be unloaded. .Sh RESTRICTIONS/CONDITIONS The argument .Fa error |
