On 18-12-23, 13:58, Pierre-Louis Bossart wrote: > > >> Documentation/driver-api/soundwire/bra.rst | 478 ++++++++++++++++++ > > > > Can we split the cadence parts of this to bra-cadence.rst that way this > > file documents the core parts only > > Yes, we can split the Cadence parts out. Great > > > >> +Error handling > >> +~~~~~~~~~~~~~~ > >> + > >> +The expected response to a 'bra_message' and follow-up behavior may > >> +vary: > >> + > >> + (1) A Peripheral driver may want to receive an immediate -EBUSY > >> + response if the BRA protocol is not available at a given time. > >> + > >> + (2) A Peripheral driver may want to wait until a timeout for the > >> + on-going transfer to be handled > >> + > >> + (3) A Peripheral driver may want to wait until existing BRA > >> + transfers complete or deal with BRA as a background task when > >> + audio transfers stop. In this case, there would be no timeout, > >> + and the operation may not happen if the platform is suspended. > > > > Is this runtime suspend or S3/S4 case? > > System suspend (which can also mean S0i1). > > I don't think we can have a case where a peripheral driver waits on > something without having done a pm_runtime_get_sync() to prevent > runtime_pm suspend. > > > > >> +BTP/BRA API available to peripheral drivers > >> +------------------------------------------- > >> + > >> +ASoC Peripheral drivers may use > >> + > >> + - sdw_bpt_stream_open(mode) > >> + > >> + This function verifies that the BPT protocol with the > >> + 'mode'. For now only BRA is accepted as a mode. This function > >> + allocates a work buffer internally. This buffer is not exposed > >> + to the caller. > >> + > >> + errors: > >> + -ENODEV: BPT/BRA is not supported by the Manager. > >> + > >> + -EBUSY: another agent is already using the audio payload for > >> + audio transfers. There is no way to predict when the audio > >> + streams might stop, this will require the Peripheral driver > >> + to fall back to the regular (slow) command channel. > >> + > >> + -EAGAIN: another agent is already transferring data using the > >> + BPT/BRA protocol. Since the transfers will typically last > >> + 10s or 100s of ms, the Peripheral driver may wait and retry > >> + later. > >> + > >> + - sdw_bpt_message_send_async(bpt_message) > > > > why not have a single API that does both? First check if it is supported > > and then allocate buffers and do the transfer.. What are the advantages > > of using this two step process > > Symmetry is the only thing that comes to my mind. Open - close and send > - wait are natural matches, aren't they? Why have symmetry to DAI apis, why not symmetry to regmap write APIs..? This is data transfer, so I am not sure why would we model it as a DAI. (Internal implementation may rely on that but from API design, i dont think that should be a concern) > > We do need a wait(), so bundling open() and send() would be odd. > > But you have a point that the open() is not generic in that it also > prepares the DMA buffers for transmission. Maybe it's more natural to > follow the traditional open(), hw_params(), hw_free, close() from ALSA. -- ~Vinod
