$ uname -a
FreeBSD vm-current 15.0-CURRENT FreeBSD 15.0-CURRENT #18 main-n266137-ede5d4ff5b39: Thu Oct 26 21:44:36 CEST 2023     root@vm-current:/usr/obj/usr/src/amd64.amd64/sys/GENERIC amd64
$ man 4 ice
No manual entry for ice

In D43093#982800, @fernape wrote:

I can't find ice(4). Where is it?

$ uname -a
FreeBSD vm-current 15.0-CURRENT FreeBSD 15.0-CURRENT #18 main-n266137-ede5d4ff5b39: Thu Oct 26 21:44:36 CEST 2023     root@vm-current:/usr/obj/usr/src/amd64.amd64/sys/GENERIC amd64
$ man 4 ice
No manual entry for ice

It doesn't exist yet; it's the next thing I'll add after this man page.

In D43093#982901, @erj wrote:
In D43093#982800, @fernape wrote:
I can't find ice(4). Where is it?
$ uname -a
FreeBSD vm-current 15.0-CURRENT FreeBSD 15.0-CURRENT #18 main-n266137-ede5d4ff5b39: Thu Oct 26 21:44:36 CEST 2023     root@vm-current:/usr/obj/usr/src/amd64.amd64/sys/GENERIC amd64
$ man 4 ice
No manual entry for ice
It doesn't exist yet; it's the next thing I'll add after this man page.

Does ice(4) reference iavf(4)? If not, it might be better to commit the ice(4) first.

erj mentioned this in D45270: Add man page for the ice network driver..May 20 2024, 5:44 PM

des added a subscriber: des.May 20 2024, 8:15 PM

des added inline comments.

share/man/man4/iavf.4
200	same below

Eric, do you want me to commandeer this?

In D43093#1033039, @des wrote:

Eric, do you want me to commandeer this?

Sure, go ahead!

des commandeered this revision.May 21 2024, 7:13 AM

des added a reviewer: erj.

clean up

Harbormaster completed remote builds in B57811: Diff 138832.May 21 2024, 8:20 AM

des edited reviewers, added: manpages; removed: docs.May 21 2024, 8:21 AM

The updates look good to me.

share/man/man4/iavf.4
338–348	I left out this section from the original man page when I uploaded my diff; is it worth keeping this information still in the man page? I also didn't check when the conversion happened; did it happen in 12.4?

des marked an inline comment as done.May 21 2024, 10:54 PM

des added inline comments.

share/man/man4/iavf.4
338–348	12.4 was the lowest-numbered FreeBSD release that shipped with `iavf` (although 13.1 was the _earliest_ such release, so maybe we should list both?)

correct history

Harbormaster completed remote builds in B57829: Diff 138872.May 21 2024, 10:55 PM

erj accepted this revision.May 21 2024, 11:17 PM

This revision is now accepted and ready to land.May 21 2024, 11:17 PM

Closed by commit rGba222f6fb4b2: iavf(4): Improve man page (authored by erj, committed by des). · Explain WhyMay 21 2024, 11:25 PM

This revision was automatically updated to reflect the committed changes.

des added a commit: rGba222f6fb4b2: iavf(4): Improve man page.

des added a commit: rG4c380c44c82f: iavf(4): Improve man page.May 23 2024, 2:42 AM

des added a commit: rGd823e80ef5a7: iavf(4): Improve man page.May 23 2024, 2:44 AM

des added a commit: rGf9b5ecd25790: iavf(4): Improve man page.May 23 2024, 2:48 AM

Revision Contents
Changeset List

Path

Size

share/

man/

man4/

iavf.4

348 lines

Diff 138873

View Options

share/man/man4/iavf.4

Show All 17 Lines

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

.\" SUCH DAMAGE.

.\"

.\" $FreeBSD$

.\"

.Dd August 25, 2006

.Dd December 15, 2021

.Dt ITHREAD 9

pauamma_gundo.comUnsubmitted

Done

Reminder (if needed) to bump on commit.

pauamma_gundo.com: Reminder (if needed) to bump on commit.

mhorneAuthorUnsubmitted

Done

Yes, will do.

mhorne: Yes, will do.

.Os

.Sh NAME

.Nm ithread_add_handler ,

.Nm intr_event_add_handler ,

.Nm ithread_create ,

.Nm intr_event_create ,

.Nm ithread_destroy ,

.Nm intr_event_destroy ,

.Nm ithread_priority ,

.Nm intr_event_remove_handler ,

.Nm ithread_remove_handler ,

.Nm intr_priority ,

.Nm ithread_schedule

.Nd "kernel interrupt threads"

.Nd kernel interrupt threads

.Sh SYNOPSIS

.In sys/param.h

.In sys/bus.h

.In sys/interrupt.h

.Ft int

.Fo ithread_add_handler

.Fo intr_event_add_handler

.Fa "struct ithd *ithread"

.Fa "struct intr_event *ie"

.Fa "const char *name"

.Fa "driver_filter_t filter"

.Fa "driver_intr_t handler"

.Fa "void *arg"

.Fa "u_char pri"

.Fa "enum intr_type flags"

.Fa "void **cookiep"

.Fc

.Ft int

.Fo ithread_create

.Fo intr_event_create

.Fa "struct ithd **ithread"

.Fa "struct intr_event **event"

.Fa "int vector"

.Fa "void *source"

.Fa "int flags"

.Fa "void (*disable)(int)"

.Fa "int irq"

.Fa "void (*enable)(int)"

.Fa "void (*pre_ithread)(void *)"

.Fa "void (*post_ithread)(void *)"

.Fa "void (*post_filter)(void *)"

.Fa "int (*assign_cpu)(void *, int)"

.Fa "const char *fmt"

.Fa "..."

.Fc

.Ft int

.Fn ithread_destroy "struct ithd *ithread"

.Fn intr_event_destroy "struct intr_event *ie"

.Ft u_char

.Fn ithread_priority "enum intr_type flags"

.Ft int

.Fn ithread_remove_handler "void *cookie"

.Fn intr_event_remove_handler "void *cookie"

.Ft int

.Ft u_char

.Fn ithread_schedule "struct ithd *ithread" "int do_switch"

.Fn intr_priority "enum intr_type flags"

.Sh DESCRIPTION

Interrupt threads are kernel threads that run a list of handlers when

triggered by either a hardware or software interrupt.

Each interrupt handler has a name, handler function, handler argument,

priority, and various flags.

Each interrupt thread maintains a list of handlers sorted by priority.

This results in higher priority handlers being executed prior to lower

priority handlers.

Each thread assumes the priority of its highest priority handler for its

process priority, or

.Dv PRIO_MAX

if it has no handlers.

Interrupt threads are also associated with a single interrupt source,

represented as a vector number.

.Pp

The

.Fn ithread_create

.Fn intr_event_create

function creates a new interrupt thread.

The

.Fa ithread

.Fa source

argument points to an

argument points to a

.Vt struct ithd

.Vt struct entr_event event

pauamma_gundo.comUnsubmitted

Not Done

Is "entr" a typo for "intr"?

pauamma_gundo.com: Is "entr" a typo for "intr"?

pointer that will point to the newly created thread upon success.

The

.Fa vector

argument specifies the interrupt source to associate this thread with.

The

.Fa flags

argument is a mask of properties of this thread.

The only valid flag currently for

.Fn ithread_create

.Fn intr_event_create

.Dv IT_SOFT

.Dv IE_SOFT

to specify that this interrupt thread is a software interrupt.

The

.Fa enable

and

argument specify optional functions used to enable this

pauamma_gundo.comUnsubmitted

Done

.Fa enable

- argument specify optional functions used to enable this

+ argument specifies optional functions used to enable this

interrupt thread's interrupt source.

pauamma_gundo.com:

.Fa disable

arguments specify optional functions used to enable and disable this

interrupt thread's interrupt source.

The functions receive the vector corresponding to the thread's interrupt

source as their only argument.

The remaining arguments form a

.Xr printf 9

argument list that is used to build the base name of the new ithread.

argument list that is used to build the base name of the new interrupt thread.

The full name of an interrupt thread is formed by concatenating the base

name of an interrupt thread with the names of all of its interrupt handlers.

pauamma_gundo.comUnsubmitted

Done

Since you're touching that area, "an interrupt thread" should be "the interrupt thread" here, if you're referring to the same one mentioned on the previous line.

pauamma_gundo.com: Since you're touching that area, "an interrupt thread" should be "the interrupt thread" here…

.Pp

The

.Fn ithread_destroy

.Fn intr_event_destroy

function destroys a previously created interrupt thread by releasing its

resources and arranging for the backing kernel thread to terminate.

An interrupt thread can only be destroyed if it has no handlers remaining.

.Pp

The

.Fn ithread_add_handler

.Fn intr_event_add_handler

function adds a new handler to an existing interrupt thread specified by

.Fa ithread .

The

.Fa name

argument specifies a name for this handler.

The

.Fa handler

and

Show All 12 Lines

.Fa cookiep

is not

.Dv NULL ,

then it will be assigned a cookie that can be used later to remove this

handler.

.Pp

The

.Fn ithread_remove_handler

.Fn intr_event_remove_handler

removes a handler from an interrupt thread.

The

.Fa cookie

argument specifies the handler to remove from its thread.

.Pp

The

.Fn ithread_schedule

function schedules an interrupt thread to run.

If the

.Fa do_switch

argument is non-zero and the interrupt thread is idle, then a context switch

will be forced after putting the interrupt thread on the run queue.

.Pp

The

.Fn ithread_priority

function translates the

.Dv INTR_TYPE_*

interrupt flags into interrupt handler priorities.

.Pp

The interrupt flags not related to the type of a particular interrupt

.Pq Dv INTR_TYPE_*

can be used to specify additional properties of both hardware and software

interrupt handlers.

The

.Dv INTR_EXCL

flag specifies that this handler cannot share an interrupt thread with

another handler.

The

.Dv INTR_MPSAFE

flag specifies that this handler is MP safe in that it does not need the

Giant mutex to be held while it is executed.

The

.Dv INTR_ENTROPY

flag specifies that the interrupt source this handler is tied to is a good

source of entropy, and thus that entropy should be gathered when an interrupt

from the handler's source triggers.

Presently, the

.Dv INTR_ENTROPY

flag is not valid for software interrupt handlers.

.Pp

It is not permitted to sleep in an interrupt thread; hence, any memory

or zone allocations in an interrupt thread should be specified with the

.Dv M_NOWAIT

flag set.

Any allocation errors must be handled thereafter.

.Sh RETURN VALUES

The

.Fn ithread_add_handler ,

.Fn ithread_create ,

.Fn ithread_destroy ,

.Fn ithread_remove_handler ,

and

.Fn ithread_schedule

functions return zero on success and non-zero on failure.

The

.Fn ithread_priority

function returns a process priority corresponding to the passed in interrupt

flags.

.Sh EXAMPLES

The

.Fn swi_add

pauamma_gundo.comUnsubmitted

Not Done

While there, maybe change this to .Xr swi_add 9 to make it clearer it's not just an example and for easier comprehension of what the example does, not just how it does it? (I'm not part of the intended audience, so if you feel it's not needed, that's fine with me.)

pauamma_gundo.com: While there, maybe change this to .Xr swi_add 9 to make it clearer it's not just an example and…

mhorneAuthorUnsubmitted

Done

Sure, it will be done as part of D33476.

mhorne: Sure, it will be done as part of D33476.

function demonstrates the use of

.Fn ithread_create

.Fn intr_event_create

and

.Fn ithread_add_handler .

.Fn intr_event_add_handler .

.Bd -literal -offset indent

int

swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,

void *arg, int pri, enum intr_type flags, void **cookiep)

{

struct proc *p;

struct ithd *ithd;

int error;

Show All 16 Lines

if (ithdp != NULL)

*ithdp = ithd;

}

return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,

flags, cookiep));

}

.Ed

.Sh ERRORS

The

.Fn ithread_add_handler

.Fn intr_event_add_handler

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Any of the

The

.Fa ithread ,

.Fa ie

.Fa handler ,

.Fa name

arguments are

.Dv NULL .

.Dv NULL.

.It Bq Er EINVAL

The

.Dv INTR_EXCL

.Fa handler

and

.Fa filter

arguments are both

.Dv NULL.

.It Bq Er EINVAL

The

.Dv IH_EXCLUSIVE

flag is specified and the interrupt thread

.Fa ithread

.Fa ie

already has at least one handler, or the interrupt thread

.Fa ithread

.Fa ie

already has an exclusive handler.

.It Bq Er ENOMEM

Could not allocate needed memory for this handler.

.El

.Pp

The

.Fn ithread_create

.Fn intr_event_create

function will fail if:

.Bl -tag -width Er

.It Bq Er EAGAIN

The system-imposed limit on the total

number of processes under execution would be exceeded.

The limit is given by the

.Xr sysctl 3

MIB variable

.Dv KERN_MAXPROC .

.It Bq Er EINVAL

A flag other than

.Dv IT_SOFT

.Dv IE_SOFT

was specified in the

.Fa flags

parameter.

.It Bq Er ENOMEM

Could not allocate needed memory for this interrupt thread.

.El

.Pp

The

.Fn ithread_destroy

.Fn intr_event_destroy

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

The

.Fa ithread

.Fa ie

argument is

.Dv NULL .

.It Bq Er EINVAL

.It Bq Er EBUSY

The interrupt thread pointed to by

The interrupt event pointed to by

.Fa ithread

.Fa ie

has at least one handler.

has at least one handler which has not been removed with

.Fn intr_event_remove_handler .

.El

.Pp

The

.Fn ithread_remove_handler

.Fn intr_event_remove_handler

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

The

.Fa cookie

argument is

.Dv NULL .

.El

.Pp

The

.Fn ithread_schedule

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

The

.Fa ithread

argument is

.Dv NULL .

.It Bq Er EINVAL

The interrupt thread pointed to by

.Fa ithread

has no interrupt handlers.

.El

.Sh SEE ALSO

.Xr kthread 9 ,

.Xr malloc 9 ,

.Xr swi 9 ,

.Xr uma 9

.Sh HISTORY

Interrupt threads and their corresponding API first appeared in

.Fx 5.0 .

.Sh BUGS

Currently

.Vt struct ithd

represents both an interrupt source and an interrupt thread.

There should be a separate

.Vt struct isrc

that contains a vector number, enable and disable functions, etc.\& that

an ithread holds a reference to.

iavf(4): Improve man pageClosedPublicActions

Details

Diff Detail

Event Timeline

Revision ContentsChangeset List

Diff 138873

share/man/man4/iavf.4

iavf(4): Improve man page
ClosedPublic
Actions

Revision Contents
Changeset List