Re: [PATCH v6 02/25] rtrs: public interface header to establish RDMA connections

[Jinpu Wang <jinpu.wang@cloud.ionos.com>]

On Mon, Dec 30, 2019 at 8:25 PM Bart Van Assche <bvanassche@acm.org> wrote:
>
> On 2019-12-30 02:29, Jack Wang wrote:
> > +/*
> > + * Here goes RTRS client API
> > + */
>
> A comment that explains what the abbreviation "RTRS" stands for would be
> welcome here. Additionally, I think that "Here goes" can be left out.
will do.
>
> > +/**
> > + * rtrs_clt_open() - Open a session to an RTRS server
> > + * @priv: User supplied private data.
> > + * @link_ev: Event notification for connection state changes
>
> Please mention that @link_ev is a callback function.
Ok.
>
> > + *   @priv: User supplied data that was passed to rtrs_clt_open()
> > + *   @ev: Occurred event
>
> Is this patch series W=1 clean? @link_ev arguments should be documented
> above the link_clt_ev_fn typedef.
We will make sure it's W=1 clean in next round.
>
> > + * @path_cnt: Number of elemnts in the @paths array
>
> elemnts -> elements?
will fix.
>
> > + * Starts session establishment with the rtrs_server. The function can block
> > + * up to ~2000ms until it returns.
>
> until -> before?
will fix
>
> > +struct rtrs_clt *rtrs_clt_open(void *priv, link_clt_ev_fn *link_ev,
> > +                              const char *sessname,
> > +                              const struct rtrs_addr *paths,
> > +                              size_t path_cnt, short port,
> > +                              size_t pdu_sz, u8 reconnect_delay_sec,
> > +                              u16 max_segments,
> > +                              s16 max_reconnect_attempts);
>
> Since the range for port numbers is 1..65535, please change "short port"
> into "u16 port".
ok.
>
> > +/**
> > + * enum rtrs_clt_con_type() type of ib connection to use with a given permit
>
> What is a "permit"?
Does use rtrs_permit sound better?
>
> > + * @vec:     Message that is send to server together with the request.
>
> send -> sent?
right.
>
> > + *           Sum of len of all @vec elements limited to <= IO_MSG_SIZE.
> > + *           Since the msg is copied internally it can be allocated on stack.
> > + * @nr:              Number of elements in @vec.
> > + * @len:     length of data send to/from server
>
> send -> sent?
right.
>
> > +/**
> > + * link_ev_fn():     Events about connective state changes
>
> connective -> connection?
connectivity I think, will fix.
>
> > +/**
> > + * rtrs_srv_open() - open RTRS server context
> > + * @ops:             callback functions
> > + *
> > + * Creates server context with specified callbacks.
> > + *
> > + * Return a valid pointer on success otherwise PTR_ERR.
> > + */
> > +struct rtrs_srv_ctx *rtrs_srv_open(rdma_ev_fn *rdma_ev, link_ev_fn *link_ev,
> > +                                  unsigned int port);
>
> Is this patch series W=1 clean? The documented argument does not match
> the actual argument list.
As replied above we will make sure it's W=1 clean when sending next round.
>
> Bart.
Thanks, Bart